opensolaris 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.11							    15 Nov 1996 						ddi_dma_getwin(9F)