|
|
udi_dma_buf_map(3udi)
Map a buffer for DMA
#include <udi.h>void udi_dma_buf_map ( udi_dma_buf_map_call_t *callback, udi_cb_t *gcb, udi_dma_handle_t dma_handle, udi_buf_t *buf, udi_size_t offset, udi_size_t len, udi_ubit8_t flags ); typedef void udi_dma_buf_map_call_t ( udi_cb_t *gcb, udi_scgth_t *scgth, udi_boolean_t complete, udi_status_t status ); /* Values for flags */#define UDI_DMA_OUT (1U<<2) #define UDI_DMA_IN (1U<<3) #define UDI_DMA_REWIND (1U<<4)ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Standard Calling Sequences" in the UDI Core Specification.
dma_handle is the UDI DMA handle.
buf is a pointer to the UDI buffer containing the data request.
offset is the offset, in bytes, from the first valid data byte in buf at which to begin the DMA mapping. This must be less than or equal to buf->buf_size.
len is the number of bytes to map for DMA. If flags includes UDI_DMA_IN and there are fewer than len bytes of valid data in the buffer, starting at offset, then the buffer will be extended but the initial values of the new data bytes are unspecified. If flags does not include UDI_DMA_IN, offset plus len must be less than or equal to the valid data length of the buffer.
flags is a bitmask of one or more flags indicating the direction(s) and range of transfers for which the mapping applies:
UDI_DMA_OUT data transfer from memory to device
UDI_DMA_IN data transfer from device to memory
UDI_DMA_REWIND rewind to the beginning of the bufferscgth is a pointer to a DMA scatter/gather structure.
complete is a boolean flag indicating whether the buffer was completely or partially mapped for DMA.
status is a UDI status code indicating the success or failure of the service call. If not UDI_OK, the scgth and complete values are unspecified and must be ignored.
DESCRIPTION udi_dma_buf_map allocates any additional DMA resources required to prepare the specified buffer for a DMA transfer and passes back a pointer to a DMA scatter/gather structure. The udi_scgth_t contains a set of bus address/length pairs, referencing the DMA target, which the driver may use as is, translate in place, or copy to the scatter/gather entries of its device's DMA engine, as is appropriate for its device. This scatter/gather list covers the len mapped bytes of the buffer, starting at offset.
The memory referenced by the scgth is guaranteed to meet the DMA constraints indicated by the constraints argument passed to udi_dma_prepare when dma_handle was allocated; these constraints take precedence over those associated with the buffer. Any data modified through the DMA mapping will be visible through the buffer handle once it is unmapped with udi_dma_buf_unmap.
While DMA-mapped, the buffer data must not be accessed via the buffer handle. The driver may change the buffer's buf_size value, however, but it will be ignored and ultimately overwritten by the value specified for the udi_dma_buf_unmap call.
The first time udi_dma_buf_map is called for a particular buffer using this DMA handle, the data is mapped starting at the beginning of the buffer. If the full size cannot be mapped in one piece, the complete flag is set to FALSE, indicating a partial transfer. Once this piece is complete, the driver can call udi_dma_buf_map again with the same arguments. The environment will "remember" where it left off (typically using information in the DMA handle) and will map the next section of the buffer.
To restart at the beginning of the buffer after a partial transfer, set the UDI_DMA_REWIND flag. The first call to udi_dma_buf_map for a particular buffer always starts at the beginning of the buffer, whether or not the UDI_DMA_REWIND flag is set.
At least one of UDI_DMA_IN or UDI_DMA_OUT must be specified in the flags argument, optionally combined with UDI_DMA_REWIND.
udi_dma_buf_map performs an implicit udi_dma_sync for the entire mapped range with the same UDI_DMA_IN and/or UDI_DMA_OUT flags as passed to udi_dma_buf_map.
STATUS VALUES UDI_OK is returned to indicate that the mapping completed successfully.
UDI_STAT_RESOURCE_UNAVAIL is returned to indicate a partial mapping. This value is only returned if UDI_DMA_NO_PARTIAL was not set in the constraints that were used to allocate the DMA handle and the environment is unable to map the entire request at one time. This status code indicates that the mapping has failed, the scgth pointer is NULL, and dma_handle is still unused, although new_buf may still be different than the original buf pointer.