opensolaris man page for ddi_dma_nextcookie

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

NAME
       ddi_dma_nextcookie - retrieve subsequent DMA cookie

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

       void ddi_dma_nextcookie(ddi_dma_handle_t handle,
	    ddi_dma_cookie_t *cookiep);

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

       cookiep	  A pointer to a  ddi_dma_cookie(9S) structure.

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI).

DESCRIPTION
       ddi_dma_nextcookie() retrieves subsequent  DMA cookies for a  DMA object.   ddi_dma_nextcookie() fills in the  ddi_dma_cookie(9S) structure
       pointed to by  cookiep. The ddi_dma_cookie(9S) structure must be allocated prior to calling  ddi_dma_nextcookie().

       The DMA cookie count returned by ddi_dma_buf_bind_handle(9F), ddi_dma_addr_bind_handle(9F), or ddi_dma_getwin(9F) indicates the	number	of
       DMA  cookies  a DMA object consists of. If the resulting cookie count,  N, is larger than 1,  ddi_dma_nextcookie() must be called N-1 times
       to retrieve all	DMA cookies.

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

EXAMPLES
       Example 1 Process a scatter-gather list of I/O requests.

       This example demonstrates the use of  ddi_dma_nextcookie() to process a scatter-gather list of I/O requests.

	 /* setup scatter-gather list with multiple DMA cookies */
	 ddi_dma_cookie_t  dmacookie;
	 uint_t 	   ccount;
	 ...

	 status = ddi_dma_buf_bind_handle(handle, bp, DDI_DMA_READ,
	      NULL, NULL, &dmacookie, &ccount);

	 if (status == DDI_DMA_MAPPED) {

	      /* program DMA engine with first cookie */

	      while (--ccount > 0) {
		   ddi_dma_nextcookie(handle, &dmacookie);
		   /* program DMA engine with next cookie */
	      }
	 }
	 ...

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

       Writing Device Drivers

SunOS 5.11							    26 Sep 1994 					    ddi_dma_nextcookie(9F)