Tribblix: manual page: ddi_dma

DDI_DMA_SYNC(9F) Kernel Functions for Drivers DDI_DMA_SYNC(9F)

NAME

ddi_dma_sync - synchronize CPU and I/O views of memory

SYNOPSIS

#include <sys/ddi.h>
#include <sys/sunddi.h>

int ddi_dma_sync(ddi_dma_handle_t handle, off_t offset,
size_t length, uint_t type);

INTERFACE LEVEL

illumos DDI specific (illumos DDI).

PARAMETERS

handle
The handle filled in by a call to ddi_dma_alloc_handle(9F).

offset
The offset into the object described by the handle.

length
The length, in bytes, of the area to synchronize. When
length is zero, the entire range starting from offset to
the end of the object has the requested operation applied
to it.

type
Indicates the caller's desire about what view of the memory
object to synchronize. The possible values are
DDI_DMA_SYNC_FORDEV, DDI_DMA_SYNC_FORCPU and
DDI_DMA_SYNC_FORKERNEL.

DESCRIPTION

The ddi_dma_sync() function is used to selectively synchronize either
a DMA device's or a CPU's view of a memory object that has DMA
resources allocated for I/O . This may involve operations such as
flushes of CPU or I/O caches, as well as other more complex
operations such as stalling until hardware write buffers have
drained.

This function need only be called under certain circumstances. When
resources are allocated for DMA using ddi_dma_addr_bind_handle() or
ddi_dma_buf_bind_handle(), an implicit ddi_dma_sync() is done. When
DMA resources are deallocated using ddi_dma_unbind_handle(9F), an
implicit ddi_dma_sync() is done. However, at any time between DMA
resource allocation and deallocation, if the memory object has been
modified by either the DMA device or a CPU and you wish to ensure
that the change is noticed by the party that did not do the
modifying, a call to ddi_dma_sync() is required. This is true
independent of any attributes of the memory object including, but not
limited to, whether or not the memory was allocated for consistent
mode I/O (see ddi_dma_mem_alloc(9F)) or whether or not DMA resources
have been allocated for consistent mode I/O (see
ddi_dma_addr_bind_handle(9F) or ddi_dma_buf_bind_handle(9F)).

If a consistent view of the memory object must be ensured between the
time DMA resources are allocated for the object and the time they are
deallocated, you must call ddi_dma_sync() to ensure that either a CPU
or a DMA device has such a consistent view.

What to set type to depends on the view you are trying to ensure
consistency for. If the memory object is modified by a CPU, and the
object is going to be read by the DMA engine of the device, use
DDI_DMA_SYNC_FORDEV. This ensures that the device's DMA engine sees
any changes that a CPU has made to the memory object. If the DMA
engine for the device has written to the memory object, and you are
going to read (with a CPU) the object (using an extant virtual
address mapping that you have to the memory object), use
DDI_DMA_SYNC_FORCPU. This ensures that a CPU's view of the memory
object includes any changes made to the object by the device's DMA
engine. If you are only interested in the kernel's view (kernel-space
part of the CPU's view) you may use DDI_DMA_SYNC_FORKERNEL. This
gives a hint to the system--that is, if it is more economical to
synchronize the kernel's view only, then do so; otherwise,
synchronize for CPU.

RETURN VALUES

The ddi_dma_sync() function returns:

DDI_SUCCESS
Caches are successfully flushed.

DDI_FAILURE
The address range to be flushed is out of the address
range established by ddi_dma_addr_bind_handle(9F) or
ddi_dma_buf_bind_handle(9F).

CONTEXT

The ddi_dma_sync() function can be called from user, interrupt, or
kernel context.