ddi_dma_sync man page on SmartOS

Printed from http://www.polarhome.com/service/man/?qf=ddi_dma_sync&af=0&tf=2&of=SmartOS

DDI_DMA_SYNC(9F)					      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
       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 allo‐
       cated 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  con‐
       sistency 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 ker‐
       nel 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_han‐
       dle(9F)

       Writing Device Drivers

				 Jan 16, 2006		      DDI_DMA_SYNC(9F)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net