L4Re - L4 Runtime Environment
L4Re::Dma_space Class Reference

DMA Address Space. More...

Inherits L4::Kobject_0t< Derived, PROTO, S_DEMAND >.

+ 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< AttributeAttributes
 Attributes for DMA mappings. More...
 
typedef L4::Types::Flags< Space_attribSpace_attribs
 Attributes used when configuring the DMA space.
 

Public Member Functions

long map (L4::Ipc::Cap< L4Re::Dataspace > src, l4_addr_t 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. More...
 
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. More...
 
long associate (L4::Ipc::Opt< L4::Ipc::Cap< L4::Task > > dma_task, Space_attribs attr)
 Associate a DMA task for a device to this Dma_space. More...
 
long disassociate ()
 Disassociate the DMA task from this Dma_space. More...
 

Detailed Description

DMA Address Space.

A Dma_space represents the DMA address space of a device. Whenever a device needs direct access to parts of an L4Re::Dataspace, that part of the data space must be mapped to the DMA address space that is assigned to that device. After the DMA accesses to the memory are finished the memory must be unmapped from the device's DMA address space.

Mapping to a 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 61 of file dma_space.

Member Typedef Documentation

◆ Attributes

Attributes for DMA mappings.

See also
Attribute

Definition at line 106 of file dma_space.

Member Enumeration Documentation

◆ 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 85 of file 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 73 of file 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 113 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 DMA task for a device to this Dma_space.

Precondition
requires capability rights: {RW}
Parameters
[in]dma_taskThe DMA task used for the device that shall be associated with this DMA space. The dma_task might be an invalid capability when Phys_space is set in attr, in this case the CPUs physical memory is used as DMA address space.
[in]attrAttributes for this DMA space. See Space_attrib.

◆ disassociate()

long L4Re::Dma_space::disassociate ( )

Disassociate the DMA task from this Dma_space.

Precondition
requires capability rights: {RW}

◆ map()

long L4Re::Dma_space::map ( L4::Ipc::Cap< L4Re::Dataspace src,
l4_addr_t  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.

Precondition
requires capability rights: {R}
Parameters
[in]srcSource data space (that describes the memory). Caller needs write rights to the data space.
[in]offsetThe offset (bytes) within src.
[in,out]sizeThe size (bytes) of the of the region to be mapped to for DMA, after successful mapping the size returned is the size mapped for DMA as 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]attrsThe attributes used for this DMA mapping (a combination of Dma_space::Attribute values).
[in]dirThe direction of the DMA transfer issued with this mapping. The same value must later be passed to unmap().
[out]dma_addrThe DMA address to use for DMA with the associated device.
Returns
0 in the case of success, a negative error code otherwise.

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

Precondition
requires capability rights: {R}
Parameters
dma_addrThe DMA address (returned by Dma_space::map()).
sizeThe size (bytes) of the memory region to unmap.
attrsThe attributes for the unmap (currently none).
dirThe direction of the finished DMA operation.

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