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

       Solaris DDI specific (Solaris 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

       ddi_dma_sync() 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 mod-
       ified 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

       ddi_dma_sync() 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

       ddi_dma_sync() can be called from user or interrupt context.

SEE ALSO

       ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F), ddi_dma_buf_bind_handle(9F), ddi_dma_mem_alloc(9F), ddi_dma_unbind_handle(9F)

       Writing Device Drivers

SunOS 5.10							    8 Nov 2003							  ddi_dma_sync(9F)