udi_dma_sync(3udi)

---

Sync host & device views of DMA-able memory

SYNOPSIS

#include <udi.h>

void udi_dma_sync (

	udi_dma_sync_call_t *callback,

	udi_cb_t *gcb,

	udi_dma_handle_t dma_handle, 

	udi_size_t offset,

	udi_size_t length,

	udi_ubit8_t flags );
 
typedef void udi_dma_sync_call_t (

	udi_cb_t *gcb );
 
/* Values for flags */
 

#define  UDI_DMA_OUT				(1U<<2)
 
#define  UDI_DMA_IN				(1U<<3)
 

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 a DMA handle previously mapped via udi_dma_buf_map or udi_dma_mem_alloc.

offset is a logical offset into the mapped buffer data. That is, it is relative to the offset value provided to udi_dma_buf_map.

length is the length, in bytes, of the area to synchronize. When length is zero, it applies to the entire data object referenced by dma_handle, and offset must be zero.

flags indicates which view of the buffer to synchronize. The flags argument may be set to one or more of the following values:

UDI_DMA_OUT - sync before starting an outbound DMA to the device

UDI_DMA_IN - sync after completing an inbound DMA from the device

DESCRIPTION udi_dma_sync is used to synchronize the host and device views of a data object that has been loaded for DMA. This may involve flushes of CPU or I/O caches, or assuring that hardware write buffers have drained.

The required direction flags depend on the direction(s) of I/O transactions since the last synchronization points. If the buffer has been modified by the CPU, and is going to be read by the device's DMA engine, then udi_dma_sync must be called with UDI_DMA_OUT set. This ensures that the device's DMA engine sees the changes previously made to the buffer memory by the driver. If the device's DMA engine has written to the buffer, and it is going to be read by the driver, udi_dma_sync must be called with UDI_DMA_IN set. This makes sure the CPU's view of the memory includes any changes previously made by the device's DMA engine.

Note that the UDI_DMA_OUT and/or UDI_DMA_IN flags must have been set in the call to udi_dma_prepare or udi_dma_mem_alloc if the same flag is to be set in udi_dma_sync.

REFERENCES udi_dma_buf_map, udi_dma_buf_unmap, udi_dma_mem_alloc, udi_dma_mem_barrier, udi_dma_scgth_sync