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.
typedef l4_cap_idx_t	l4re_dma_space_mgr_t
	DMA space manager capability type.

Functions
l4_ret_t	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.
l4_ret_t	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.
l4_ret_t	l4re_dma_space_mgr_associate (l4re_dma_space_mgr_t dma_mgr, l4re_dma_space_t dma_space, l4_cap_idx_t dma_task, enum l4re_dma_space_mgr_space_attribs attr) L4_NOTHROW
	Associate a (kernel) DMA space for a device to a Dma_space.
l4_ret_t	l4re_dma_space_mgr_associate_phys (l4re_dma_space_mgr_t dma_mgr, l4re_dma_space_t dma_space, enum l4re_dma_space_mgr_space_attribs attr) L4_NOTHROW
	Register a Dma_space to use for DMA.
l4_ret_t	l4re_dma_space_mgr_disassociate (l4re_dma_space_mgr_t dma_mgr, l4re_dma_space_t dma_space) L4_NOTHROW
l4_ret_t	l4re_dma_space_mgr_block_area (l4re_dma_space_mgr_t dma_mgr, l4re_dma_space_t dma_space, l4re_dma_space_dma_addr_t *addr, l4re_dma_space_dma_size_t size, l4re_dma_space_dma_addr_t max_addr, enum l4re_dma_space_mgr_block_flags flags, unsigned char align) L4_NOTHROW
l4_ret_t	l4re_dma_space_mgr_set_limits (l4re_dma_space_mgr_t dma_mgr, l4re_dma_space_t dma_space, l4re_dma_space_dma_addr_t min_addr, l4re_dma_space_dma_addr_t max_addr) L4_NOTHROW

Detailed Description

DMA Space C interface.

Typedef Documentation

◆ l4re_dma_space_mgr_t

typedef l4_cap_idx_t l4re_dma_space_mgr_t

DMA space manager capability type.

A privileged interface to manage Dma_space associations for the clients.

This interface is provided as a singleton by Moe.

Definition at line 76 of file dma_space.h.

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

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

Definition at line 69 of file dma_space.h.

Function Documentation

◆ l4re_dma_space_map()

l4_ret_t 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 A suitable address in the DMA task will be chosen automatically.
[in]	src	Source data space (that describes the memory).
[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). The Search_addr attribute is forced by this overload!
[in]	dir	The direction of the DMA transfer issued with this mapping. The same value must later be passed to unmap(). (ignored)
[out]	dma_addr	The DMA address to use for DMA with the associated device.

Return values

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

The DMA mapping is created writable if capability src has the permission L4_CAP_FPAGE_W. Otherwise, a read-only DMA mapping is established.

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

Deprecated: Use the other overload without dir parameter.

References L4_CV, L4_NOTHROW, and l4re_ds_t.

◆ l4re_dma_space_mgr_associate()

l4_ret_t l4re_dma_space_mgr_associate	(	l4re_dma_space_mgr_t	dma_mgr,
		l4re_dma_space_t	dma_space,
		l4_cap_idx_t	dma_task,
		enum l4re_dma_space_mgr_space_attribs	attr )

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

Parameters

	dma_mgr	DMA space manager capability
[in]	dma_space	The Dma_space to associate the (kernel) DMA space with.
[in]	dma_task	The (kernel) DMA space used for the device that shall be associated with this DMA space.
[in]	attr	Attributes for this DMA space. See L4Re::Dma_space::Space_attrib.

Return values

L4_EOK	Operation successful.
-L4_EBUSY	The Dma_space is already associated.
-L4_EINVAL	Invalid arguments, e.g. no dma_task capability passed. In particular, when Space_attrib::Identity_map is requested, the Dma_space must not have any pre-existing blockings (see Dma_space_mgr::block_area()) and must not have custom address limits set (see Dma_space_mgr::set_limits()).
-L4_ENOENT	Invalid dma_space was passed.
-L4_ENOMEM	Not enough memory to allocate internal datastructures.
-L4_EPERM	Insufficient permissions; see precondition.

Precondition: The dma_space and dma_task capabilities must have the permission L4_CAP_FPAGE_W.

References L4_CV, and L4_NOTHROW.

◆ l4re_dma_space_mgr_associate_phys()

l4_ret_t l4re_dma_space_mgr_associate_phys	(	l4re_dma_space_mgr_t	dma_mgr,
		l4re_dma_space_t	dma_space,
		enum l4re_dma_space_mgr_space_attribs	attr )

Register a Dma_space to use for DMA.

Parameters

	dma_mgr	DMA space manager capability This function should be used, in case no IOMMU is present or configured. The CPU's physical memory is used as DMA address space.
[in]	dma_space	The Dma_space to register.
[in]	attr	Attributes for the provided DMA space. Currently not used; must be the default-constructed Space_attribs() value.

Return values

L4_EOK	Operation successful.
-L4_EBUSY	The Dma_space is already associated.
-L4_EINVAL	Invalid arguments, for example a non-zero attr, pre-existing blockings on dma_space (see Dma_space_mgr::block_area()), or custom address limits set on dma_space (see Dma_space_mgr::set_limits()).
-L4_ENOENT	Invalid dma_space was passed.
-L4_ENOMEM	Not enough memory to allocate internal datastructures.
-L4_EPERM	Insufficient permissions; see precondition.

Precondition: The dma_space capability must have the permission L4_CAP_FPAGE_W.

References L4_CV, and L4_NOTHROW.

◆ l4re_dma_space_mgr_block_area()

l4_ret_t l4re_dma_space_mgr_block_area	(	l4re_dma_space_mgr_t	dma_mgr,
		l4re_dma_space_t	dma_space,
		l4re_dma_space_dma_addr_t *	addr,
		l4re_dma_space_dma_size_t	size,
		l4re_dma_space_dma_addr_t	max_addr,
		enum l4re_dma_space_mgr_block_flags	flags,
		unsigned char	align )

Parameters

dma_mgr DMA space manager capability Block an area in a Dma_space.

The blocked area cannot be used for mappings in the given dma_space after the call. The call will fail if there are already mappings in the requested range. It is allowed to add block areas before associate() or associate_phys() has been called.

Blocked areas are allowed to overlap.

Parameters

[in]	dma_space	The Dma_space to add blocked areas.
[in,out]	addr	The DMA address of the blocked area. Either taken literally (in which case it must be page aligned) or as start address if Block_flag::Search_addr is passed.
[in]	size	Size of the blocked region. Must be page aligned.
[in]	max_addr	Highest allowed DMA address of the region (inclusive).
[in]	flags	The attributes used for this blocking (a combination of Dma_space_mgr::Block_flag values).
[in]	align	The log2 alignment of the blocked area. Only used if Block_flag::Search_addr is passed.

Return values

L4_EOK	Operation successful.
-L4_EADDRNOTAVAIL	The specified region overlaps an existing mapping or no space left for the blocking.
-L4_EINVAL	Invalid address, alignment or flag passed. Block_flag::Search_addr passed but dma_space is not associated yet.
-L4_EPERM	Dma_space is associated with physical DMA domain or insufficient permissions; see precondition.
-L4_ENOMEM	There is not enough memory to allocate internal data structures.

Precondition: The dma_space capability must have the permission L4_CAP_FPAGE_W.

References L4_CV, and L4_NOTHROW.

◆ l4re_dma_space_mgr_disassociate()

l4_ret_t l4re_dma_space_mgr_disassociate	(	l4re_dma_space_mgr_t	dma_mgr,
		l4re_dma_space_t	dma_space )

Parameters

	dma_mgr	DMA space manager capability Disassociate the (kernel) DMA space from this Dma_space.
[in]	dma_space	The Dma_space to de-register.

Return values

L4_EOK	Operation successful.
-L4_ENOENT	Invalid dma_space was passed or disassociate() called without prior calling associate()/associate_phys().
-L4_EPERM	Insufficient permissions; see precondition.

Attention: This will remove all mappings, reservations and blockings from dma_space.

Precondition: The dma_space capability must have the permission L4_CAP_FPAGE_W.

References L4_CV, and L4_NOTHROW.

◆ l4re_dma_space_mgr_set_limits()

l4_ret_t l4re_dma_space_mgr_set_limits	(	l4re_dma_space_mgr_t	dma_mgr,
		l4re_dma_space_t	dma_space,
		l4re_dma_space_dma_addr_t	min_addr,
		l4re_dma_space_dma_addr_t	max_addr )

Parameters

dma_mgr DMA space manager capability Set lower and upper bound of DMA addresses.

Mappings and blockings are only allowed in the given range.

If multiple Dma_spaces share the same kernel DMA space (i.e., were associated by passing the same dma_task to associate()), all DMA address allocations, reservations and blockings performed through any of these Dma_spaces use the intersection of all their individual limits. Tightening the limits on one Dma_space therefore also constrains all other Dma_spaces sharing the same DMA task; loosening the limits on one Dma_space has no effect beyond what the most-restrictive peer Dma_space allows.

Parameters

[in]	dma_space	The Dma_space whose limits shall be changed.
[in]	min_addr	The lowest usable address in the Dma_space.
[in]	max_addr	The highest usable address in the Dma_space (inclusive).

Return values

L4_EOK	Operation successful.
-L4_EADDRNOTAVAIL	There are existing mappings or blocking outside the bounds.
-L4_EPERM	Dma_space is associated with physical DMA domain or insufficient permissions; see precondition.
-L4_EINVAL	Invalid address passed.

Precondition: The dma_space capability must have the permission L4_CAP_FPAGE_W.

References L4_END_DECLS, and L4_NOTHROW.

◆ l4re_dma_space_unmap()

l4_ret_t 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 The calls to map() and unmap() must be balanced. That is, each page of a mapping that was established by map() previously must be unmapped exactly once.

Sub-ranges that do not currently hold a mapping are silently skipped. That is, unmapping the same region too often, is not treated as an error.

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, ignored).
dir	The direction of the finished DMA operation (ignored).

Return values

L4_EOK	Operation successful.
-L4_ENOMEM	Not enough memory to allocate internal datastructures.

Deprecated: Use the overload without attrs and dir because they are ignored.

References L4_CV, and L4_NOTHROW.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ l4re_dma_space_mgr_t

◆ l4re_dma_space_t

Function Documentation

◆ l4re_dma_space_map()

◆ l4re_dma_space_mgr_associate()

◆ l4re_dma_space_mgr_associate_phys()

◆ l4re_dma_space_mgr_block_area()

◆ l4re_dma_space_mgr_disassociate()

◆ l4re_dma_space_mgr_set_limits()

◆ l4re_dma_space_unmap()