L4Re - L4 Runtime Environment
DMA Space Interface

DMA Space C interface. More...

+ Collaboration diagram for DMA Space Interface:

Typedefs

typedef l4_cap_idx_t l4re_dma_space_t
 DMA space capability type. More...
 

Functions

long l4re_dma_space_map (l4re_dma_space_t dma, l4re_ds_t src, l4_addr_t offset, l4_size_t *size, unsigned long attrs, enum l4re_dma_space_direction dir, l4re_dma_space_dma_addr_t *dma_addr) L4_NOTHROW
 Map the given part of this data space into the DMA address space. More...
 
long l4re_dma_space_unmap (l4re_dma_space_t dma, l4re_dma_space_dma_addr_t dma_addr, l4_size_t size, unsigned long attrs, enum l4re_dma_space_direction dir) L4_NOTHROW
 Unmap the given part of this data space from the DMA address space. More...
 
long l4re_dma_space_associate (l4re_dma_space_t dma, l4_cap_idx_t dma_task, unsigned long attr) L4_NOTHROW
 Associate a DMA task for a device to this Dma_space. More...
 
long l4re_dma_space_disassociate (l4re_dma_space_t dma)
 Disassociate the DMA task from this Dma_space. More...
 

Detailed Description

DMA Space C interface.

Typedef Documentation

◆ l4re_dma_space_t

DMA space capability type.

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 59 of file dma_space.h.

Function Documentation

◆ l4re_dma_space_associate()

long l4re_dma_space_associate ( l4re_dma_space_t  dma,
l4_cap_idx_t  dma_task,
unsigned long  attr 
)

Associate a DMA task for a device to this Dma_space.

Parameters
dmaDMA space capability
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.

◆ l4re_dma_space_disassociate()

long l4re_dma_space_disassociate ( l4re_dma_space_t  dma)

Disassociate the DMA task from this Dma_space.

Parameters
dmaDMA space capability
Precondition
requires capability rights: {RW}

◆ l4re_dma_space_map()

long l4re_dma_space_map ( l4re_dma_space_t  dma,
l4re_ds_t  src,
l4_addr_t  offset,
l4_size_t size,
unsigned long  attrs,
enum l4re_dma_space_direction  dir,
l4re_dma_space_dma_addr_t dma_addr 
)

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

Parameters
dmaDMA space capability
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.

◆ l4re_dma_space_unmap()

long l4re_dma_space_unmap ( l4re_dma_space_t  dma,
l4re_dma_space_dma_addr_t  dma_addr,
l4_size_t  size,
unsigned long  attrs,
enum l4re_dma_space_direction  dir 
)

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

Parameters
dmaDMA space capability
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.