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

Managed DMA Address Space. More...

`#include <dma_space>`

Collaboration diagram for L4Re::Dma_space:

## Public Types

enum | Direction { Bidirectional , To_device , From_device , None }
| Direction of the DMA transfers. More...
enum | Attribute { No_sync }
| Attributes used for the memory region during the transfer. More...
enum | Space_attrib { Coherent , Phys_space }
| Attributes assigned to the DMA space when associated with a specific device. More...
typedef l4_uint64_t | Dma_addr
| Data type for DMA addresses.
typedef L4::Types::Flags< Attribute > | Attributes
| Attributes for DMA mappings.
typedef L4::Types::Flags< Space_attrib > | Space_attribs
| Attributes used when configuring the DMA space.

## Public Member Functions

long | map (L4::Ipc::Cap< L4Re::Dataspace > src, L4Re::Dataspace::Offset offset, L4::Ipc::In_out< l4_size_t * > size, Attributes attrs, Direction dir, Dma_addr *dma_addr)
| Map the given part of this data space into the DMA address space.
long | unmap (Dma_addr dma_addr, l4_size_t size, Attributes attrs, Direction dir)
| Unmap the given part of this data space from the DMA address space.
long | associate (L4::Ipc::Opt< L4::Ipc::Cap< L4::Task > > dma_task, Space_attribs attr)
| Associate a (kernel) DMA space for a device to this Dma_space.
long | disassociate ()
| Disassociate the (kernel) DMA space from this Dma_space.

## Detailed Description

Managed DMA Address Space.

A managed Dma_space represents the L4Re abstraction of an DMA address space of one or several devices. Devices are assigned to a managed Dma_space by binding the Dma_space to the respective DMA domain (see L4vbus::Vbus::assign_dma_domain()), which might link the Dma_space with a kernel DMA space. Note that several DMA domains can be bound to the same Dma_space. Whenever a device needs direct access to parts of an L4Re::Dataspace, that part of the data space must be mapped to the managed Dma_space that is assigned to that device. Binding to DMA domains must happen before mapping. After the DMA accesses to the memory are finished the memory must be unmapped from the device's DMA address space.

Mapping to a managed DMA address space, using map(), makes the given parts of the data space visible to the associated device at the returned DMA address. As long as the memory is mapped into a DMA space it is 'pinned' and cannot be subject to dynamic memory management such as swapping. Additionally, map() is responsible for the necessary syncing operations before the DMA.

unmap() is the reverse operation to map() and unmaps the given data-space part for the DMA address space. unmap() is responsible for the necessary sync operations after the DMA.

Definition at line 52 of file dma_space.

## Member Typedef Documentation

## Attributes

typedef L4::Types::Flags<Attribute> L4Re::Dma_space::Attributes

Attributes for DMA mappings.

See also
  Attribute

Definition at line 97 of file dma_space.

## Member Enumeration Documentation

## Attribute

enum L4Re::Dma_space::Attribute

Attributes used for the memory region during the transfer.

See also
  Attributes

Enumerator

No_sync

Do not sync the memory hierarchy.

When this flag is not set (default) the memory region shall be made coherent to the point-of-coherency of the device associated with this Dma_space. When using this attribute the client is responsible for syncing the memory hierarchy for DMA. This can either be done using the cache API or by another map() or unmap() operation of the same part of the data space (without the No_sync attribute).

Definition at line 76 of file dma_space.

## Direction

enum L4Re::Dma_space::Direction

Direction of the DMA transfers.

Enumerator
Bidirectional | device reads and writes to the memory
To_device | device reads the memory
From_device | device writes to the memory
None | device is coherently connected to the memory

Definition at line 64 of file dma_space.

## Space_attrib

enum L4Re::Dma_space::Space_attrib

Attributes assigned to the DMA space when associated with a specific device.

See also
  Space_attribs

Enumerator
Coherent | The device is connected coherently with the cache. This means that the map() and unmap() do not need to sync CPU caches before and after DMA.
Phys_space | The DMA space has no DMA task assigned and uses the CPUs physical memory.

Definition at line 104 of file dma_space.

## Member Function Documentation

## associate()

long L4Re::Dma_space::associate | ( | L4::Ipc::Opt< L4::Ipc::Cap< L4::Task > > | dma_task,
|  | Space_attribs | attr )

Associate a (kernel) DMA space for a device to this Dma_space.

Parameters

  [in] | dma_task | The (kernel) DMA space used for the device that shall be associated with this DMA space. In case no IOMMU is present or configured, the dma_task might be an invalid capability when L4Re::Dma_space::Phys_space is set in attr, in this case the CPUs physical memory is used as DMA address space.
  [in] | attr | Attributes for this DMA space. See L4Re::Dma_space::Space_attrib.

Return values

  L4_EOK | Operation successful.
  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_EINVAL |
  -L4_ENOENT |

Precondition
  The invoked Dma_space capability must have the permission L4_CAP_FPAGE_W.

References disassociate().

Referenced by unmap().

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

## disassociate()

long L4Re::Dma_space::disassociate | ( |  | ) |

Disassociate the (kernel) DMA space from this Dma_space.

Return values

  L4_EOK | Operation successful.
  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_ENOENT |

Precondition
  The invoked Dma_space capability must have the permission L4_CAP_FPAGE_W.

Referenced by associate().

Here is the caller graph for this function:

## map()

long L4Re::Dma_space::map | ( | L4::Ipc::Cap< L4Re::Dataspace > | src,
|  | L4Re::Dataspace::Offset | offset,
|  | L4::Ipc::In_out< l4_size_t * > | size,
|  | Attributes | attrs,
|  | Direction | dir,
|  | Dma_addr * | dma_addr )

Map the given part of this data space into the DMA address space.

Parameters

  [in] | src | Source data space (that describes the memory). Caller needs write right to the data space.
  [in] | offset | The offset (bytes) within src.
  [in,out] | size | The size (bytes) of the region to be mapped for DMA, after successful mapping the size returned is the size mapped for DMA as a single block. This size might be smaller than the original input size, in this case the caller might call map() again with a new offset and the remaining size.
  [in] | attrs | The attributes used for this DMA mapping (a combination of Dma_space::Attribute values).
  [in] | dir | The direction of the DMA transfer issued with this mapping. The same value must later be passed to unmap().
  [out] | dma_addr | The DMA address to use for DMA with the associated device.

Return values

  L4_EOK | Operation successful.
  -L4_EPERM | Insufficient permissions; see precondition.
  -L4_EINVAL | The capability src is invalid or does not refer to a valid dataspace.
  -L4_EEXIST | The specified region overlaps an existing mapping.
  -L4_ENOMEM | Not enough memory to allocate internal datastructures.
  -L4_ERANGE | offset is larger than the size of the dataspace.

Precondition
  The capability src must have the permission L4_CAP_FPAGE_W.

Note
  associate() must be called prior to mapping memory. Usually this is done implicitely when binding the managed Dma_space to a DMA domain (see L4vbus::Vbus::assign_dma_domain()).

References unmap().

Here is the call graph for this function:

## unmap()

long L4Re::Dma_space::unmap | ( | Dma_addr | dma_addr,
|  | l4_size_t | size,
|  | Attributes | attrs,
|  | Direction | dir )

Unmap the given part of this data space from the DMA address space.

Parameters

  dma_addr | The DMA address (returned by Dma_space::map()).
  size | The size (bytes) of the memory region to unmap.
  attrs | The attributes for the unmap (currently none).
  dir | The direction of the finished DMA operation.

Returns
  0 in the case of success, a negative error code otherwise.

References associate().

Referenced by map().

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 file:

- l4/re/dma_space