L4Re - L4 Runtime Environment
L4Re::Dataspace Class Reference

Interface for memory-like objects. More...

+ Inheritance diagram for L4Re::Dataspace:
+ Collaboration diagram for L4Re::Dataspace:

Data Structures

struct  Stats
 Information about the dataspace. More...
 

Public Types

enum  Map_flags {
  Map_ro = 0, Map_rw = 1, Map_normal = 0x00, Map_cacheable = Map_normal,
  Map_bufferable = 0x10, Map_uncacheable = 0x20, Map_caching_mask = 0x30, Map_caching_shift = 4
}
 Flags for map operations. More...
 

Public Member Functions

long map (l4_addr_t offset, unsigned long flags, l4_addr_t local_addr, l4_addr_t min_addr, l4_addr_t max_addr) const throw ()
 Request a flex-page mapping from the dataspace. More...
 
long map_region (l4_addr_t offset, unsigned long flags, l4_addr_t min_addr, l4_addr_t max_addr) const throw ()
 Map a part of a dataspace completely. More...
 
long clear (l4_addr_t offset, unsigned long size)
 Clear parts of a dataspace. More...
 
long allocate (l4_addr_t offset, l4_size_t size)
 Allocate a range in the dataspace. More...
 
long copy_in (l4_addr_t dst_offs, L4::Ipc::Cap< Dataspace > src, l4_addr_t src_offs, unsigned long size)
 Copy contents from another dataspace. More...
 
long phys (l4_addr_t offset, l4_addr_t &phys_addr, l4_size_t &phys_size)
 Get the physical addresses of a dataspace. More...
 
unsigned long size () const throw ()
 Get size of a dataspace. More...
 
long flags () const throw ()
 Get flags of the dataspace. More...
 
long info (Stats *stats)
 Get information on the dataspace. More...
 
- 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. More...
 

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 L4::Kobject ::__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< Classc () const
 Get the capability to ourselves.
 
- Protected Member Functions inherited from L4::Kobject
l4_cap_idx_t cap () const throw ()
 Return capability selector. More...
 
- 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__ ()
 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>
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 59 of file dataspace.

Member Enumeration Documentation

◆ Map_flags

Flags for map operations.

Enumerator
Map_ro 

Request read-only mapping.

Map_rw 

Request writable mapping.

Map_normal 

request normal memory mapping

Map_cacheable 

request normal memory mapping

Map_bufferable 

request bufferable (write buffered) mappings

Map_uncacheable 

request uncacheable memory mappings

Map_caching_mask 

mask for caching flags

Map_caching_shift 

shift value for caching flags

Definition at line 68 of file dataspace.

Member Function Documentation

◆ allocate()

long L4Re::Dataspace::allocate ( l4_addr_t  offset,
l4_size_t  size 
)

Allocate a range in the dataspace.

Parameters
offsetOffset in the dataspace, in bytes.
sizeSize of the range, in bytes.
Return values
L4_EOKSuccess
-L4_ERANGEGiven range is outside the dataspace. (A dataspace provider may also silently ignore areas outside the dataspace.)
-L4_ENOMEMNot enough memory available.
<0IPC 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 ( l4_addr_t  offset,
unsigned long  size 
)

Clear parts of a dataspace.

Parameters
offsetOffset within dataspace (in bytes).
sizeSize of region to clear (in bytes).
Return values
>=0Success.
-L4_ERANGEGiven range is outside the dataspace. (A dataspace provider may also silently ignore areas outside the dataspace.)
-L4_EACCESSDataspace is read-only.
<0IPC 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 ( l4_addr_t  dst_offs,
L4::Ipc::Cap< Dataspace src,
l4_addr_t  src_offs,
unsigned long  size 
)

Copy contents from another dataspace.

Parameters
dst_offsOffset in destination dataspace.
srcSource dataspace to copy from.
src_offsOffset in the source dataspace.
sizeSize to copy (in bytes).
Return values
L4_EOKSuccess
-L4_EACCESSDestination dataspace not writable.
-L4_EINVALInvalid parameter supplied.
<0IPC 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()

long L4Re::Dataspace::flags ( ) const
throw (
)

Get flags of the dataspace.

Return values
>=0Flags of the dataspace
<0IPC errors
See also
L4Re::Dataspace::Map_flags

Definition at line 116 of file dataspace_impl.h.

◆ info()

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

Get information on the dataspace.

Parameters
[out]statsDataspace information
Return values
0Success
<0IPC errors

◆ map()

long L4Re::Dataspace::map ( l4_addr_t  offset,
unsigned long  flags,
l4_addr_t  local_addr,
l4_addr_t  min_addr,
l4_addr_t  max_addr 
) const
throw (
)

Request a flex-page mapping from the dataspace.

Parameters
offsetOffset to start within dataspace
flagsmap flags, see Map_flags.
local_addrLocal address to map to.
min_addrDefines start of receive window. (Rounded down to page size.)
max_addrDefines end of receive window. (Rounded up to page size.)
Return values
L4_EOKSuccess
-L4_ERANGEInvalid offset.
-L4_EPERMInsufficient permission to map with requested rights.
<0IPC 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 92 of file dataspace_impl.h.

References l4_fpage_max_order(), L4_LOG2_PAGESIZE, l4_round_page(), and l4_trunc_page().

+ Here is the call graph for this function:

◆ map_region()

long L4Re::Dataspace::map_region ( l4_addr_t  offset,
unsigned long  flags,
l4_addr_t  min_addr,
l4_addr_t  max_addr 
) const
throw (
)

Map a part of a dataspace completely.

Parameters
offsetOffset to start within dataspace
flagsmap flags, see Map_flags.
min_addrDefines start of receive window. (Rounded down to page size.)
max_addrDefines end of receive window. (Rounded up to page size.)
Return values
L4_EOKSuccess
-L4_ERANGEInvalid offset.
-L4_EPERMInsufficient permission to map with requested rights.
<0IPC errors

Definition at line 55 of file dataspace_impl.h.

References l4_fpage_max_order(), L4_LOG2_PAGESIZE, l4_round_page(), l4_round_size(), l4_trunc_page(), l4_trunc_size(), and L4_UNLIKELY.

Referenced by L4Re::Rm::attach().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ phys()

long L4Re::Dataspace::phys ( l4_addr_t  offset,
l4_addr_t phys_addr,
l4_size_t phys_size 
)

Get the physical addresses of a dataspace.

Parameters
offsetOffset in dataspace
Return values
phys_addrPhysical address.
phys_sizeSize of largest physically contiguous region in the dataspace after phys_addr (in bytes).
L4_EOKSuccess
-L4_EINVALDataspace is not pinned.
<0IPC errors

This call will only succeed on pinned memory dataspaces.

Deprecated:
Use L4Re::Dma_space instead. This function will be removed in future releases.

◆ size()

unsigned long L4Re::Dataspace::size ( ) const
throw (
)

Get size of a dataspace.

Returns
Size of the dataspace in bytes.
Examples:
examples/libs/l4re/c++/shared_ds/ds_clnt.cc.

Definition at line 106 of file dataspace_impl.h.


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