Current File : //usr/share/man/man9f/ddi_dma_nextseg.9f

'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.TH ddi_dma_nextseg 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_dma_nextseg \- get next DMA segment
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h> 
#include <sys/sunddi.h>

\fBint\fR \fBddi_dma_nextseg\fR(\fBddi_dma_win_t\fR \fIwin\fR, \fBddi_dma_seg_t\fR \fIseg\fR, 
     \fBddi_dma_seg_t *\fR\fInseg\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
This interface is obsolete. \fBddi_dma_nextcookie\fR(9F) should be used instead.
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIwin\fR\fR
.ad
.RS 8n
.rt  
A \fBDMA\fR window.
.RE

.sp
.ne 2
.mk
.na
\fB\fIseg\fR\fR
.ad
.RS 8n
.rt  
The current \fBDMA\fR segment or \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fInseg\fR\fR
.ad
.RS 8n
.rt  
A pointer to the next \fBDMA\fR segment to be filled in. If \fIseg\fR is \fINULL\fR, a pointer to the first segment within the specified window is returned. 
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_dma_nextseg()\fR function gets the next \fBDMA\fR segment within the specified window \fIwin\fR. If the current segment is \fINULL\fR, the first \fBDMA\fR segment within the window is returned.
.sp
.LP
A \fBDMA\fR segment is always required for a \fBDMA\fR window.  A \fBDMA\fR segment is a contiguous portion of a \fBDMA\fR window (see  \fBddi_dma_nextwin\fR(9F)) which is entirely addressable by the device for a data transfer operation.
.sp
.LP
An example where multiple \fBDMA\fR segments are allocated is where the system does not contain \fBDVMA\fR capabilities and the object may be non-contiguous. In this example the object will be broken into smaller contiguous \fBDMA\fR segments. Another example is where the device has  an upper limit on its transfer size (for example an 8-bit address register) and has expressed this in the \fBDMA\fR limit structure (see \fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). In this example the object will be broken into smaller addressable \fBDMA\fR segments.
.SH RETURN VALUES
.sp
.LP
The \fBddi_dma_nextseg()\fR function returns:
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 17n
.rt  
Successfully filled in the next segment pointer.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_DMA_DONE\fR\fR
.ad
.RS 17n
.rt  
There is no next segment. The current segment is the final segment within the specified window.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_DMA_STALE\fR\fR
.ad
.RS 17n
.rt  
\fIwin\fR does not refer to the currently active window.
.RE

.SH CONTEXT
.sp
.LP
The \fBddi_dma_nextseg()\fR function can be called from user, interrupt, or kernel context.
.SH EXAMPLES
.sp
.LP
For an example, see \fBddi_dma_segtocookie\fR(9F).
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityObsolete
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), \fBddi_dma_nextcookie\fR(9F), \fBddi_dma_nextwin\fR(9F), \fBddi_dma_segtocookie\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_lim_sparc\fR(9S), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S)
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR