usr/src/man/man9f/ddi_dma_nextwin.9f

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_DMA_NEXTWIN 9F "Jan 16, 2006"
   7 .SH NAME
   8 ddi_dma_nextwin \- get next DMA window
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBddi_dma_nextwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBddi_dma_win_t\fR \fIwin\fR,
  18      \fBddi_dma_win_t *\fR\fInwin\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 This interface is obsolete. \fBddi_dma_getwin\fR(9F) should be used instead.
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIhandle\fR\fR
  30 .ad
  31 .RS 10n
  32 A \fBDMA\fR handle.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIwin\fR\fR
  39 .ad
  40 .RS 10n
  41 The current \fBDMA\fR window or \fINULL\fR.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fInwin\fR\fR
  48 .ad
  49 .RS 10n
  50 A pointer to the next \fBDMA\fR window to be filled in. If \fIwin\fR is
  51 \fINULL\fR, a pointer to the first window within the object is returned.
  52 .RE
  53
  54 .SH DESCRIPTION
  55 .sp
  56 .LP
  57 The \fBddi_dma_nextwin()\fR function shifts the current \fBDMA\fR window
  58 \fIwin\fR within the object referred to by \fIhandle\fR to the next \fBDMA\fR
  59 window \fInwin\fR. If the current window is \fINULL\fR, the first window within
  60 the object is returned. A \fBDMA\fR window is a portion of a \fBDMA\fR object
  61 or might be the entire object. A \fBDMA\fR window has system resources
  62 allocated to it and is prepared to accept data transfers. Examples of system
  63 resources are \fBDVMA\fR mapping resources and intermediate transfer buffer
  64 resources.
  65 .sp
  66 .LP
  67 All \fBDMA\fR objects require a window. If the \fBDMA\fR window represents the
  68 whole \fBDMA\fR object it has system resources allocated for the entire data
  69 transfer. However, if the system is unable to setup the entire \fBDMA\fR object
  70 due to system resource limitations, the driver writer may allow the system to
  71 allocate system resources for less than the entire \fBDMA\fR object. This can
  72 be accomplished by specifying the \fBDDI_DMA_PARTIAL\fR flag as a parameter to
  73 \fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_addr_setup\fR(9F) or as part of a
  74 \fBddi_dma_req\fR(9S) structure in a call to \fBddi_dma_setup\fR(9F).
  75 .sp
  76 .LP
  77 Only the window that has resources allocated is valid per object at any one
  78 time. The currently valid window is the one that was most recently returned
  79 from \fBddi_dma_nextwin()\fR. Furthermore, because a call to
  80 \fBddi_dma_nextwin()\fR will reallocate system resources to the new window, the
  81 previous window will become invalid. It is a \fBsevere\fR error to call
  82 \fBddi_dma_nextwin()\fR before any transfers into the current window are
  83 complete.
  84 .sp
  85 .LP
  86 The \fBddi_dma_nextwin()\fR function takes care of underlying memory
  87 synchronizations required to shift the window. However, if you want to access
  88 the data before or after moving the window, further synchronizations using
  89 \fBddi_dma_sync\fR(9F) are required.
  90 .SH RETURN VALUES
  91 .sp
  92 .LP
  93 The \fBddi_dma_nextwin()\fR function returns:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBDDI_SUCCESS\fR\fR
  98 .ad
  99 .RS 17n
 100 Successfully filled in the next window pointer.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBDDI_DMA_DONE\fR\fR
 107 .ad
 108 .RS 17n
 109 There is no next window. The current window is the final window within the
 110 specified object.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBDDI_DMA_STALE\fR\fR
 117 .ad
 118 .RS 17n
 119 \fIwin\fR does not refer to the currently active window.
 120 .RE
 121
 122 .SH CONTEXT
 123 .sp
 124 .LP
 125 The \fBddi_dma_nextwin()\fR function can be called from user, interrupt, or
 126 kernel context.
 127 .SH EXAMPLES
 128 .sp
 129 .LP
 130 For an example see \fBddi_dma_segtocookie\fR(9F).
 131 .SH ATTRIBUTES
 132 .sp
 133 .LP
 134 See \fBattributes\fR(5) for a description of the following attributes:
 135 .sp
 136
 137 .sp
 138 .TS
 139 box;
 140 c | c
 141 l | l .
 142 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 143 _
 144 Stability Level Obsolete
 145 .TE
 146
 147 .SH SEE ALSO
 148 .sp
 149 .LP
 150 \fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F),
 151 \fBddi_dma_getwin\fR(9F), \fBddi_dma_nextseg\fR(9F),
 152 \fBddi_dma_segtocookie\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_req\fR(9S)
 153 .sp
 154 .LP
 155 \fIWriting Device Drivers\fR