'\" te
.\" Copyright (c) 1994, Sun Microsystems, Inc.
.TH ddi_dma_nextcookie 9F "26 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_dma_nextcookie \- retrieve subsequent DMA cookie
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h> 
#include <sys/sunddi.h>

\fBvoid\fR \fBddi_dma_nextcookie\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, 
     \fBddi_dma_cookie_t *\fR\fIcookiep\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIhandle\fR\fR
.ad
.RS 11n
.rt  
The handle previously allocated by a call to  \fBddi_dma_alloc_handle\fR(9F). 
.RE

.sp
.ne 2
.mk
.na
\fB\fIcookiep\fR\fR
.ad
.RS 11n
.rt  
A pointer to a  \fBddi_dma_cookie\fR(9S) structure.
.RE

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH DESCRIPTION
.sp
.LP
\fBddi_dma_nextcookie()\fR retrieves subsequent  \fBDMA\fR cookies for a  \fBDMA\fR object.   \fBddi_dma_nextcookie()\fR fills in the  \fBddi_dma_cookie\fR(9S) structure pointed to by  \fIcookiep\fR. The \fBddi_dma_cookie\fR(9S) structure must be allocated prior to calling  \fBddi_dma_nextcookie()\fR. 
.sp
.LP
The \fBDMA\fR cookie count returned by \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_addr_bind_handle\fR(9F), or \fBddi_dma_getwin\fR(9F) indicates the number of \fBDMA\fR cookies a \fBDMA\fR object consists of. If the resulting cookie count,  \fIN\fR, is larger than 1,  \fBddi_dma_nextcookie()\fR must be called \fIN\fR-1 times to retrieve all  \fBDMA\fR cookies.
.SH CONTEXT
.sp
.LP
\fBddi_dma_nextcookie()\fR can be called from user, kernel, or interrupt context.
.SH EXAMPLES
.LP
\fBExample 1 \fRProcess a scatter-gather list of I/O requests.
.sp
.LP
This example demonstrates the use of  \fBddi_dma_nextcookie()\fR to process a scatter-gather list of I/O requests.

.sp
.in +2
.nf
/* 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 */
	}
}
\&...  
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_unbind_handle\fR(9F), \fBddi_dma_cookie\fR(9S) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR