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.

Functions
long	l4re_dma_space_map (l4re_dma_space_t dma, l4re_ds_t src, l4re_ds_offset_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.
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.
long	l4re_dma_space_associate (l4re_dma_space_t dma, l4_cap_idx_t dma_task, unsigned long attr) L4_NOTHROW
	Associate a (kernel) DMA space for a device to this Dma_space.
long	l4re_dma_space_disassociate (l4re_dma_space_t dma)
	Disassociate the (kernel) DMA space from this Dma_space.

Detailed Description

DMA Space C interface.

Typedef Documentation

l4re_dma_space_t

typedef l4_cap_idx_t l4re_dma_space_t

DMA space capability type.

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 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 (kernel) DMA space for a device to this Dma_space.

Parameters

	dma	DMA space capability
[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	No L4_CAP_FPAGE_W right on the Dma_space capability.
-L4_EINVAL
-L4_ENOENT

Precondition

requires capability rights: {RW}

l4re_dma_space_disassociate()

long l4re_dma_space_disassociate

(

l4re_dma_space_t

dma

)

Disassociate the (kernel) DMA space from this Dma_space.

Parameters

dma	DMA space capability

Return values

L4_EOK	Operation successful.
-L4_EPERM	No L4_CAP_FPAGE_W right on the Dma_space capability.
-L4_ENOENT

Precondition

requires capability rights: {RW}

l4re_dma_space_map()

long l4re_dma_space_map	(	l4re_dma_space_t	dma,
		l4re_ds_t	src,
		l4re_ds_offset_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

	dma	DMA space capability
[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	No L4_CAP_FPAGE_W right on src capability.
-L4_EINVAL	The src capability 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

requires capability rights: {R}

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()).

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

dma	DMA space capability
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.

Precondition

requires capability rights: {R}