Loading...
Searching...
No Matches
L4Re::Dataspace Class Reference

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 flexpage 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 *start_addr, l4_addr_t *end_addr)
| 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 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< 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 50 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.

References allocate(), copy_in(), and size().

Referenced by allocate().

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

## 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.

References clear(), and size().

Referenced by clear().

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

## 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.

References flags(), and size().

Referenced by allocate().

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

## flags()

Dataspace::Flags 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 111 of file dataspace_impl.h.

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

Referenced by L4vbus::Vbus::assign_dma_domain(), L4vbus::Vbus::assign_dma_domain(), copy_in(), info(), map(), and map_region().

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

References flags(), info(), L4_RPC, L4_RPC_NF, map(), and map_info().

Referenced by flags(), info(), and size().

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

## map()

long 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 flexpage 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 85 of file dataspace_impl.h.

References flags(), and L4_LOG2_PAGESIZE.

Referenced by info().

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

## map_info()

long L4Re::Dataspace::map_info | ( | l4_addr_t * | start_addr,
|  | l4_addr_t * | end_addr )

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 305 of file dataspace.

Referenced by info().

Here is the caller graph for this function:

## map_region()

long 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 flexpages 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 45 of file dataspace_impl.h.

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

Here is the call graph for this function:

## size()

Dataspace::Size Dataspace::size | ( |  | ) | const

noexcept

Get size of a dataspace.

Returns
  Size of the dataspace in bytes.

Definition at line 101 of file dataspace_impl.h.

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

Referenced by allocate(), clear(), and copy_in().

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

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

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