centos man page for ddi_dma_getwin

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

NAME
       ddi_dma_getwin - activate a new DMA window

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

       int ddi_dma_getwin(ddi_dma_handle_t handle, uint_t win, off_t *offp, size_t *lenp, ddi_dma_cookie_t *cookiep, uint_t *ccountp);

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI).

PARAMETERS
       handle	       The  DMA handle previously allocated by a call to  ddi_dma_alloc_handle(9F).

       win	       Number of the window to activate.

       offp	       Pointer to an offset.  Upon a successful return,  offp will contain the new offset indicating the
			beginning of the window within the object.

       lenp	       Upon a successful return,  lenp will contain the size, in bytes, of the current window.

       cookiep	       A pointer to the first  ddi_dma_cookie(9S) structure.

       ccountp	       Upon a successful return,  ccountp will contain the number of cookies for this  DMA window.

DESCRIPTION
       ddi_dma_getwin()  activates  a new  DMA window. If a  DMA resource allocation request returns DDI_DMA_PARTIAL_MAP indicating that resources
       for less than the entire object were allocated, the current  DMA window can be changed by a call to  ddi_dma_getwin().

       The caller must first determine the number of  DMA windows,  N, using ddi_dma_numwin(9F). ddi_dma_getwin() takes a  DMA window number  from
       the range  [0..N-1] as the parameter win and makes it the current  DMA window.

       ddi_dma_getwin() fills in the first DMA cookie pointed to by cookiep with the appropriate address, length, and bus type. *ccountp is set to
       the number of DMA cookies representing this DMA object. Subsequent DMA cookies must be retrieved using ddi_dma_nextcookie(9F).

       ddi_dma_getwin() takes care of underlying resource synchronizations required to shift the window. However accessing the data  prior  to	or
       after moving the window requires further synchronization steps using  ddi_dma_sync(9F).

       ddi_dma_getwin()  is normally called from an interrupt routine. The first invocation of the  DMA engine is done from the driver. All subse-
       quent invocations of the  DMA engine are done from the interrupt routine. The interrupt routine checks to see if the request has been  com-
       pleted. If it has, the interrupt routine returns without invoking another  DMA transfer. Otherwise, it calls  ddi_dma_getwin() to shift the
       current window and start another DMA transfer.

RETURN VALUES
       ddi_dma_getwin() returns:

       DDI_SUCCESS     Resources for the specified DMA window are allocated.

       DDI_FAILURE     win is not a valid window index.

CONTEXT
       ddi_dma_getwin() can be called from user, kernel, or interrupt context.

SEE ALSO
       ddi_dma_addr_bind_handle(9F),   ddi_dma_alloc_handle(9F),    ddi_dma_buf_bind_handle(9F),    ddi_dma_nextcookie(9F),    ddi_dma_numwin(9F),
       ddi_dma_sync(9F), ddi_dma_unbind_handle(9F), ddi_dma_cookie(9S)

       Writing Device Drivers

SunOS 5.10							    15 Nov 1996 						ddi_dma_getwin(9F)