Manual Pages for UNIX Operating System command usage for man ddi_dma_sync

Kernel Functions for Drivers                     ddi_dma_sync(9F)



NAME
     ddi_dma_sync - synchronize CPU and I/O views of memory

SYNOPSIS
     #include 
     #include 

     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  han-
               dle.


     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 synchron-
     ize 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  cir-
     cumstances.  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



SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                     ddi_dma_sync(9F)



     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,  inter-
     rupt, or kernel context.




SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                     ddi_dma_sync(9F)



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.11          Last change: 16 Jan 2006                    3