Interface for memory-like objects. More...

#include <dataspace>

Inheritance diagram for L4Re::Dataspace:

Collaboration diagram for L4Re::Dataspace:

Data Structures
struct	F
	Dataspace flags definitions. More...

struct	Stats
	Information about the dataspace. More...

Public Member Functions
long	map (Offset offset, Flags flags, Map_addr local_addr, Map_addr min_addr, Map_addr max_addr, L4::Cap< L4::Task > dst=L4::Cap< L4::Task >::Invalid) const noexcept
	Request a flex-page mapping from the dataspace.

long	map_region (Offset offset, Flags flags, Map_addr min_addr, Map_addr max_addr, L4::Cap< L4::Task > dst=L4::Cap< L4::Task >::Invalid) const noexcept
	Map a part of a dataspace into a local memory area.

long	clear (Offset offset, Size size)
	Clear parts of a dataspace.

long	allocate (Offset offset, Size size)
	Allocate a range in the dataspace.

long	copy_in (Offset dst_offs, L4::Ipc::Cap< Dataspace > src, Offset src_offs, Size size)
	Copy contents from another dataspace.

Size	size () const noexcept
	Get size of a dataspace.

Flags	flags () const noexcept
	Get flags of the dataspace.

long	info (Stats *stats)
	Get information on the dataspace.

long	map_info (l4_addr_t , l4_addr_t )
	Get mapping range of dataspace.

Public Member Functions inherited from L4::Kobject
l4_msgtag_t	dec_refcnt (l4_mword_t diff, l4_utcb_t *utcb=l4_utcb())
	Decrement the in kernel reference counter for the object.

Additional Inherited Members
Protected Types inherited from L4::Kobject_t< Dataspace, L4::Kobject, L4RE_PROTO_DATASPACE, L4::Type_info::Demand_t< 1 > >
typedef Dataspace	Class
	The target interface type (inheriting from Kobject_t)

typedef Typeid::Iface< PROTO, Dataspace >	__Iface
	The interface description for the derived class.

typedef Typeid::Merge_list< Typeid::Iface_list< __Iface >, typename Base::__Iface_list >	__Iface_list
	The list of all RPC interfaces provided directly or through inheritance.

Protected Member Functions inherited from L4::Kobject_t< Dataspace, L4::Kobject, L4RE_PROTO_DATASPACE, L4::Type_info::Demand_t< 1 > >
L4::Cap< Class >	c () const noexcept
	Get the capability to ourselves.

Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t	cap () const noexcept
	Return capability selector.

Static Protected Member Functions inherited from L4::Kobject_t< Dataspace, L4::Kobject, L4RE_PROTO_DATASPACE, L4::Type_info::Demand_t< 1 > >
static void	__check_protocols__ () noexcept
	Helper to check for protocol conflicts.

Detailed Description

Interface for memory-like objects.

Dataspaces are a central abstraction provided by L4Re. A dataspace is an abstraction for any thing that is available via usual memory access instructions. A dataspace can be a file, as well as the memory-mapped registers of a device, or anonymous memory, such as a heap.

The dataspace interface defines a set of methods that allow any kind of dataspace to be attached (mapped) to the virtual address space of an L4 task and then be accessed via memory-access instructions. The L4Re::Rm interface can be used to attach a dataspace to a virtual address space of a task paged by a certain instance of a region map.

Include File: #include <l4/re/dataspace>

dataspace
Dataspace interface.

Examples: examples/libs/l4re/c++/mem_alloc/ma+rm.cc, examples/libs/l4re/c++/shared_ds/ds_clnt.cc, and examples/libs/l4re/c++/shared_ds/ds_srv.cc.

Definition at line 61 of file dataspace.

Member Function Documentation

◆ allocate()

long L4Re::Dataspace::allocate	(	Offset	offset,
		Size	size
	)

Allocate a range in the dataspace.

Parameters

offset	Offset in the dataspace, in bytes.
size	Size of the range, in bytes.

Return values

L4_EOK	Success
-L4_ERANGE	Given range is outside the dataspace. (A dataspace provider may also silently ignore areas outside the dataspace.)
-L4_ENOMEM	Not enough memory available.
<0	IPC errors

On success, at least the given range is guaranteed to be allocated. The dataspace manager may also allocate more memory due to page granularity.

The memory is allocated with the same rights as the dataspace capability.

◆ clear()

long L4Re::Dataspace::clear	(	Offset	offset,
		Size	size
	)

Clear parts of a dataspace.

Parameters

offset	Offset within dataspace (in bytes).
size	Size of region to clear (in bytes).

Return values

>=0	Success.
-L4_ERANGE	Given range is outside the dataspace. (A dataspace provider may also silently ignore areas outside the dataspace.)
-L4_EACCESS	No L4_CAP_FPAGE_W right on dataspace capability.
<0	IPC errors

Zeroes out the memory. Depending on the type of memory the memory could also be deallocated and replaced by a shared zero-page.

◆ copy_in()

long L4Re::Dataspace::copy_in	(	Offset	dst_offs,
		L4::Ipc::Cap< Dataspace >	src,
		Offset	src_offs,
		Size	size
	)

Copy contents from another dataspace.

Parameters

dst_offs	Offset in destination dataspace.
src	Source dataspace to copy from.
src_offs	Offset in the source dataspace.
size	Size to copy (in bytes).

Return values

L4_EOK	Success
-L4_EACCESS	No L4_CAP_FPAGE_W right on the destination dataspace.
-L4_EINVAL	Invalid parameter supplied.
<0	IPC errors

The copy operation may use copy-on-write mechanisms. The operation may also fail if both dataspaces are not from the same dataspace manager or the dataspace managers do not cooperate.

◆ flags()

Dataspace::Flags L4Re::Dataspace::flags ( ) const

noexcept

Get flags of the dataspace.

Return values

>=0	Flags of the dataspace
<0	IPC errors

See also: L4Re::Dataspace::F::Flags

Definition at line 122 of file dataspace_impl.h.

References L4Re::Dataspace::Stats::flags, and info().

Referenced by L4vbus::Vbus::assign_dma_domain(), and L4vbus::Vbus::assign_dma_domain().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ info()

long L4Re::Dataspace::info ( Stats * stats )

Get information on the dataspace.

Parameters

[out] stats Dataspace information

Return values

0	Success
<0	IPC errors

Referenced by L4virtio::Svr::Driver_mem_region_t< DATA >::Driver_mem_region_t(), flags(), and size().

Here is the caller graph for this function:

◆ map()

long L4Re::Dataspace::map	(	Dataspace::Offset	offset,
		Dataspace::Flags	flags,
		Dataspace::Map_addr	local_addr,
		Dataspace::Map_addr	min_addr,
		Dataspace::Map_addr	max_addr,
		L4::Cap< L4::Task >	dst = `L4::Cap<L4::Task>::Invalid`
	)		const

noexcept

Request a flex-page mapping from the dataspace.

Parameters

offset	Offset to start within dataspace
flags	Dataspace flags, see L4Re::Dataspace::F::Flags.
local_addr	Local address to map to.
min_addr	Defines start of receive window. (Rounded down to page size.)
max_addr	Defines end of receive window. (Rounded up to page size.)
dst	Optional destination task of the mapping. If invalid, the callers task is implicitly the destination.

Return values

L4_EOK	Success
-L4_ERANGE	Invalid offset.
-L4_EPERM	Insufficient permission to map with requested rights.
<0	IPC errors

The map call will attempt to map the largest possible flexpage that covers the given local address and still fits into the region defined by min_addr and max_addr. If the given region is invalid or does not overlap the local address, the smallest valid page size is used.

Definition at line 96 of file dataspace_impl.h.

References L4_LOG2_PAGESIZE.

◆ map_info()

long L4Re::Dataspace::map_info	(	l4_addr_t *	,
		l4_addr_t *
	)

inline

Get mapping range of dataspace.

In case of a MMU-less system, the dataspace must be mapped at the correct address in the task because virtual and physical address must match. This method returns the start and end address of the physically contiguous buffer backing the dataspace.

On MMU-enabled system any page aligned address is permissible. On such systems the method is just a stub.

Parameters

[out]	start_addr	Start address of dataspace.
[out]	end_addr	End address (inclusive) of dataspace.

Return values

>0	Start/end address have been set and need to be obeyed.
0	No constraint of mapping address.
-L4_EPERM	Cannot infer mapping address. Dataspace not mappable.
<0	IPC errors.

Definition at line 315 of file dataspace.

◆ map_region()

long L4Re::Dataspace::map_region	(	Dataspace::Offset	offset,
		Dataspace::Flags	flags,
		Dataspace::Map_addr	min_addr,
		Dataspace::Map_addr	max_addr,
		L4::Cap< L4::Task >	dst = `L4::Cap<L4::Task>::Invalid`
	)		const

noexcept

Map a part of a dataspace into a local memory area.

Parameters

offset	Offset to start within dataspace.
flags	Dataspace flags, see L4Re::Dataspace::F::Flags.
min_addr	(Inclusive) start of the receive area.
max_addr	(Exclusive) end of receive area.
dst	Optional destination task of the mapping. If invalid, the callers task is implicitly the destination.

Return values

L4_EOK	Success
-L4_ERANGE	Invalid offset or receive area larger than the dataspace.
-L4_EPERM	Insufficient permission to map with requested rights.
<0	IPC errors

This is a convenience function which maps flex-pages consecutively into the given memory area in the local task. The area is expected to be filled completely. If the dataspace is not large enough to provide the mappings for the entire size of the area, then an error is returned. Mappings may or may not have been already established at that point.

offset and min_addr are rounded down to the next L4_PAGESIZE boundary when necessary. max_addr is rounded up to the page boundary. If the resulting maximum address is less or equal than the minimum address, then the function is a noop.

Definition at line 56 of file dataspace_impl.h.

References L4_LOG2_PAGESIZE, L4_UNLIKELY, L4::round_order(), and L4::trunc_order().

Here is the call graph for this function:

◆ size()

Dataspace::Size L4Re::Dataspace::size ( ) const

noexcept

Get size of a dataspace.

Returns: Size of the dataspace in bytes.

Definition at line 112 of file dataspace_impl.h.

References info(), and L4Re::Dataspace::Stats::size.

Here is the call graph for this function:

The documentation for this class was generated from the following files:

l4/re/dataspace
l4/re/impl/dataspace_impl.h

Data Structures

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ allocate()

◆ clear()

◆ copy_in()

◆ flags()

◆ info()

◆ map()

◆ map_info()

◆ map_region()

◆ size()