udi_dma_constraints_attr_t(3udi)
DMA constraints attributes
#include <udi.h>typedef udi_ubit8_t udi_dma_constraints_attr_t; /* DMA Convenience Attribute Codes */#define UDI_DMA_ADDRESSABLE_BITS 100 #define UDI_DMA_ALIGNMENT_BITS 101/* DMA Constraints on the Entire Transfer */#define UDI_DMA_DATA_ADDRESSABLE_BITS 110 #define UDI_DMA_NO_PARTIAL 111/* DMA Constraints on the Scatter/Gather List */#define UDI_DMA_SCGTH_MAX_ELEMENTS 120 #define UDI_DMA_SCGTH_FORMAT 121 #define UDI_DMA_SCGTH_ENDIANNESS 122 #define UDI_DMA_SCGTH_ADDRESSABLE_BITS 123 #define UDI_DMA_SCGTH_MAX_SEGMENTS 124/* DMA Constraints on Scatter/Gather Segments */#define UDI_DMA_SCGTH_ALIGNMENT_BITS 130 #define UDI_DMA_SCGTH_MAX_EL_PER_SEG 131 #define UDI_DMA_SCGTH_PREFIX_BYTES 132/* DMA Constraints on Scatter/Gather Elements */#define UDI_DMA_ELEMENT_ALIGNMENT_BITS 140 #define UDI_DMA_ELEMENT_LENGTH_BITS 141 #define UDI_DMA_ELEMENT_GRANULARITY_BITS 142/* DMA Constraints for Special Addressing */#define UDI_DMA_ADDR_FIXED_BITS 150 #define UDI_DMA_ADDR_FIXED_TYPE 151 #define UDI_DMA_ADDR_FIXED_VALUE_LO 152 #define UDI_DMA_ADDR_FIXED_VALUE_HI 153/* DMA Constraints on DMA Access Behavior */#define UDI_DMA_SEQUENTIAL 160 #define UDI_DMA_SLOP_IN_BITS 161 #define UDI_DMA_SLOP_OUT_BITS 162 #define UDI_DMA_SLOP_OUT_EXTRA 163 #define UDI_DMA_SLOP_BARRIER_BITS 164/* Values for UDI_DMA_SCGTH_ENDIANNESS */#define UDI_DMA_LITTLE_ENDIAN (1U<<6) #define UDI_DMA_BIG_ENDIAN (1U<<5)/* Values for UDI_DMA_ADDR_FIXED_TYPE */#define UDI_DMA_FIXED_ELEMENT 1 #define UDI_DMA_FIXED_LIST 2 #define UDI_DMA_FIXED_VALUE 3DESCRIPTION This type is used to select a particular attribute of a constraints object. Constrants objects, referenced by constraints handles (see udi_dma_constraints_t), are used to constrain data and transfer properties to most optimally meet the requirements of all drivers handling the data.
A constraints attribute is a mnemonic constant (UDI_DMA_XXX in the tables below) which is used to set an associated value in a constraints handle. Definitions of use and the meaning of each attribute follow the tables.
There are two general types of constraints: restrictions and capabilities. Restriction constraints indicate that the operation is restricted to a specific value or set of values, and if propagated, restriction constraints typically become more constrictive with each module. For these types of constraints, there is a default value along with a minimum and maximum value (specified in the tables below or elsewhere) and the effects of the combine operation are to make the constraint the more or less restrictive value of the attributes being combined. The tables also specify any special interpretation for a constraint vaue of zero or N/A if zero is not a special case.
The capability constraints are used to indicate the various capabilities of a module and are not as simply described as the restriction constraints. Capability constraints are not usually linear values and don't have a standard meaning when used with combine operations. For these types of constraints, the most and least restrictive values are specified as "N/A" indicating that they do not apply and the description of the constraint must be consulted to determine the effects of the combine operation.
Constraints objects, referenced by constraints handles (udi_dma_constraints_t), are used to constrain transfer properties as well as memory placement of udi_buf_t data, memory allocated by udi_dma_mem_alloc, and scatter/gather lists, in order to make them addressable via DMA from a particular device.
Any driver that will be using DMA, or drives a bus bridge that has an effect on DMA transfers, must apply its DMA constraints attributes to a constraints object by calling udi_dma_constraints_attr_set. The driver must then pass the constraints handle to udi_dma_prepare or udi_dma_mem_alloc to allow the environment to allocate and/or copy the memory and mapping registers used for DMA so that they meet the specified constraints. If different DMA transactions have different alignment restrictions (e.g., transmit DMA can be byte-aligned, but receive DMA must be 4-byte aligned), the driver would need to create a separate handle for each case.
A list of supported DMA constraints attribute codes is given below, along with the range of valid values for each attribute, which of these values are considered least and most restrictive, and the default value for the attribute. This is presented in the form of a table for each attribute category; each table is followed by detailed descriptions of each attribute.
In addition to the individual attributes specified for DMA operations there are a set of convenience attributes, which are used to specify a grouping of individual attributes. For most DMA situations, there are sets of related attributes which can all be set to identical values because the DMA engine does not distinguish between the conditions represented by the individual attributes. UDI provides convenience attributes that refer to a group of individual attributes and when used, causes all the individual attributes which are part of the group to be set at once without requiring explicit specification of each individual attribute.
UDI_DMA_ADDRESSABLE_BITS is used to simultaneously set UDI_DMA_DATA_ADDRESSABLE_BITS and UDI_DMA_SCGTH_ADDRESSABLE_BITS. This specifies the number of bits of bus address that the DMA engine can generate for access to either data or scatter/gather elements.
UDI_DMA_ALIGNMENT_BITS is used to simultaneously set UDI_DMA_ELEMENT_ALIGNMENT_BITS and UDI_DMA_SCGTH_ALIGNMENT_BITS. This specifies the # of LSB bits that must be zero in the starting bus addresses of data elements and scatter/gather segments; i.e. the starting bus addresses of data elements and scatter/gather segments must be multiples of 2^UDI_DMA_ALIGNMENT_BITS.
Table 3-2 DMA Constraints on the Entire Transfer Valid Range Least Restrictive Value Most Restrictive Value Default Value Special Case Behavior for 0 16..255 255 16 255 N/A 0..1 0 1 0 N/A UDI_DMA_DATA_ADDRESSABLE_BITS is the # of bits of bus address that the DMA engine can generate for access to data elements.
UDI_DMA_NO_PARTIAL is a flag indicating (if non-zero) that the device and/or driver cannot handle partial DMA mappings from udi_dma_buf_map. Either the entire request must be mapped in one call, or it must be failed.
UDI_DMA_SCGTH_MAX_ELEMENTS is the maximum # of elements that can be handled in one scatter/gather list. For DMA engines without scatter/gather support, this should be set to 1.
UDI_DMA_SCGTH_FORMAT determines the format of the scatter/gather list. It must be set to one of the legal values for the scgth_format member of udi_scgth_t, described on page 3-11. Both UDI_SCGTH_32 and UDI_SCGTH_64 may be set if the device supports both; each returned scatter/gather list's scgth_format member will indicate which mapping was used for that scatter/gather list (only one is used for the entire list and a 64-bit mapping is preferred).
The default value for this attribute is UDI_SCGTH_DMA_MAPPED + UDI_SCGTH_32.
The following attributes are relevant only to DMA-mapped scatter/gather lists and need not be set if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED:
UDI_DMA_SCGTH_ENDIANNESS
UDI_DMA_SCGTH_ADDRESSABLE_BITS
UDI_DMA_SCGTH_ALIGNMENT_BITS
UDI_DMA_SCGTH_MAX_SEGMENTS
UDI_DMA_SCGTH_MAX_EL_PER_SEG
UDI_DMA_SCGTH_PREFIX_BYTESUDI_DMA_SCGTH_ENDIANNESS determines the desired device endianness of DMA-mapped scatter/gather elements. This attribute may be set to one of the following values:
UDI_DMA_LITTLE_ENDIAN
UDI_DMA_BIG_ENDIANThe default value for this attribute is unspecified. If UDI_DMA_SCGTH_FORMAT includes UDI_SCGTH_DMA_MAPPED, this attribute must be explicitly set before the constraints object can be used with udi_dma_prepare or udi_dma_mem_alloc.
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_SCGTH_ADDRESSABLE_BITS is the # of bits of bus address that the DMA engine can generate for accesses to scatter/gather list elements.
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_SCGTH_MAX_SEGMENTS is the maximum # of scatter/gather segments that the DMA engine can handle. (One segment references another through indirect scatter/gather elements.)
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_SCGTH_ALIGNMENT_BITS is the # of LSB bits that must be zero in the starting bus address of each scatter/gather segment); i.e. the starting bus address of each segment must be a multiple of 2^UDI_DMA_SCGTH_ALIGNMENT_BITS.
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_SCGTH_MAX_EL_PER_SEG is the maximum # of scatter/gather elements that can be handled in one segment, not including chain pointers to the next segment if any.
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_SCGTH_PREFIX_BYTES is the # bytes of extra uninitialized DMA-mapped memory that will be allocated preceding the actual scatter/gather element array in each scatter/gather segment. This is typically used to provide additional shared control structures for communicating with the device, or as space for conversion to alternate (larger) scatter/gather formats.
Alignment constraints on the starting address of scatter/gather segments will be applied to the beginning of this prefix area rather than the beginning of the element array.
From the DMA device, the prefix bytes will be accessible at bus addresses immediately preceding the bus address of the start of the segment.
Driver access to the memory, if needed, is via the same mechanism used for access to the scatter/gather elements, through the scgth_elements pointers. In this case, the scatter/gather list must also be driver-mapped.
Ignored if UDI_DMA_SCGTH_FORMAT does not include UDI_SCGTH_DMA_MAPPED.
UDI_DMA_ELEMENT_ALIGNMENT_BITS is the # of LSB bits that must be zero in the starting bus address of each individual scatter/gather element; i.e. the starting bus address must be a multiple of 2^UDI_DMA_ELEMENT_ALIGNMENT_BITS.
UDI_DMA_ELEMENT_LENGTH_BITS is the # bits supported for the length (in bytes) of a single scatter/gather element (block_length in udi_scgth_t). No matter what this parameter is set to, no more than UDI_DMA_ADDRESSABLE_BITS will be used.
UDI_DMA_ELEMENT_GRANULARITY_BITS is the granularity of each individual scatter/gather element. The length in bytes of each element, except the last one in the whole transfer, must be a multiple of 2^UDI_DMA_ELEMENT_GRANULARITY_BITS.
UDI_DMA_ADDR_FIXED_BITS if non-zero, indicates that some number of MSB bits are "fixed"; that is, they must have the same value for all addresses in a range. Depending on the value of UDI_DMA_ADDR_FIXED_TYPE the specified bits may be "fixed" across an entire scatter/gather list or just within each element. In most cases, it doesn't matter what the "fixed" value is, as long as it is unchanging across the required range.
The value of UDI_DMA_ADDR_FIXED_BITS indicates the number of "variable" bits less significant than the least significant "fixed" bit. (This can also be thought of as the bit number of the first fixed bit, counting from the LSB, starting with 0.) All bits more significant than the first "fixed" bit, up to the most significant bit according to UDI_DMA_ADDRESSABLE_BITS, are also "fixed".
This somewhat counter-intuitive encoding is unfortunately necessary to prevent the value from being invalidated by changes to UDI_DMA_ADDRESSABLE_BITS.
The following attributes are relevant only when UDI_DMA_ADDR_FIXED_BITS is non-zero and need not be set otherwise:
UDI_DMA_ADDR_FIXED_TYPE
UDI_DMA_ADDR_FIXED_VALUE_LO
UDI_DMA_ADDR_FIXED_VALUE_HIUDI_DMA_ADDR_FIXED_TYPE specifies the type of "fixed" address restriction, if any. It takes one of the following values:
UDI_DMA_FIXED_ELEMENT:
Each scatter/gather element may have different "fixed" values. This would typically be for a case where the DMA engine's current address register has upper bits that don't cascade, such as ISA motherboard DMAC "page" registers.UDI_DMA_FIXED_LIST:
The whole scatter/gather list must have the same "fixed" value. Seems an unusual case, but it's here for completeness.UDI_DMA_FIXED_VALUE:
The "fixed" bits must be equal to the value given by the pair of UDI_DMA_ADDR_FIXED_VALUE_LO and UDI_DMA_ADDR_FIXED_VALUE_HI for the whole scatter/gather list. This would only be used by special bridge drivers for some case like multiple OS instances sharing the same bus, in which the bridge driver "knows better" than the OS since it knows it was configured to allow only a sub-portion of the bus address space to be used by this instance.UDI_DMA_FIXED_ELEMENT is least restrictive and the default. UDI_DMA_FIXED_VALUE is the most restrictive.
Ignored if UDI_DMA_ADDR_FIXED_BITS is zero.
UDI_DMA_ADDR_FIXED_VALUE_LO is the least significant 32 bits of the required "fixed" bits value in the UDI_DMA_FIXED_VALUE case; the LSB of UDI_DMA_ADDR_FIXED_VALUE_LO corresponds to the first "fixed" bit, not to the LSB of the address as a whole.
Ignored if UDI_DMA_ADDR_FIXED_BITS is zero or UDI_DMA_ADDR_FIXED_TYPE is not UDI_DMA_FIXED_VALUE.
UDI_DMA_ADDR_FIXED_VALUE_HI is the most significant 32 bits of the required "fixed" bits value in the UDI_DMA_FIXED_VALUE case. This should rarely ever need to be set.
Ignored if UDI_DMA_ADDR_FIXED_BITS is zero or UDI_DMA_ADDR_FIXED_TYPE is not UDI_DMA_FIXED_VALUE or UDI_DMA_ADDRESSABLE_BITS minus UDI_DMA_FIXED_BITS is not greater than 32.
UDI_DMA_SEQUENTIAL is a flag indicating (if non-zero) that the DMA engine accesses memory sequentially for a data transfer, in the order listed in the scatter/gather list and in sequential address order within each element. Some environment implementations can optimize DMA transfers if they get this guarantee from the driver.
UDI_DMA_SLOP_IN_BITS is the worst-case # bits of "input slop" alignment. This indicates that DMA cycles may cause accesses to additional physical memory locations besides those explicitly listed in scatter/gather elements. Specifically, the starting (inclusive) and ending (exclusive) byte addresses of each scatter/gather element may be rounded out to boundaries that are multiples of 2^UDI_DMA_SLOP_IN_BITS for "inbound" bus transactions (i.e. from device to memory).
UDI_DMA_SLOP_OUT_BITS is the worst-case # bits of "output slop" alignment. This indicates that DMA cycles may cause accesses to additional physical memory locations besides those explicitly listed in scatter/gather elements. Specifically, the starting (inclusive) and ending (exclusive) byte addresses of each scatter/gather element may be rounded out to boundaries that are multiples of 2^UDI_DMA_SLOP_OUT_BITS for "outbound" bus transactions (i.e. from memory to device).
UDI_DMA_SLOP_OUT_EXTRA is the worst-case # bytes of "extra slop". This represents additional bytes of prefetch beyond the end of each scatter/gather element after rounding up based on UDI_DMA_SLOP_OUT_BITS. This applies during outbound bus transactions only.
UDI_DMA_SLOP_BARRIER_BITS is the # bits of "slop barrier". This represents a boundary across which UDI_DMA_SLOP_OUT_EXTRA prefetching will not occur; i.e. prefetching will not cross address boundaries that are multiples of 2^UDI_DMA_SLOP_BARRIER_BITS. This is useful to alleviate the worst-case assumptions of UDI_DMA_SLOP_OUT_EXTRA.
Ignored if UDI_DMA_SLOP_OUT_EXTRA is zero.
REFERENCES udi_dma_constraints_attr_t, udi_dma_constraints_t, udi_buf_t, udi_dma_mem_alloc, udi_dma_prepare, udi_dma_constraints_attr_set