Print this page
4888 Undocument dma_req(9s)
4884 EOF scsi_hba_attach
4886 EOF ddi_dmae_getlim
4887 EOF ddi_iomin
4634 undocument scsi_hba_attach() and ddi_dma_lim(9s)
4630 clean stale references to ddi_iopb_alloc and ddi_iopb_free
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9s/ddi_dmae_req.9s
+++ new/usr/src/man/man9s/ddi_dmae_req.9s
1 1 '\" te
2 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 3 .\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
3 -.\" Copyright 2012 Garrett D'Amore <garrett@damore.org>. All rights reserved.
4 4 .\" 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.
5 5 .\" 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.
6 6 .\" 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]
7 -.TH DDI_DMAE_REQ 9S "Feb 06, 2012"
7 +.TH DDI_DMAE_REQ 9S "May 24, 2014"
8 8 .SH NAME
9 9 ddi_dmae_req \- DMA engine request structure
10 10 .SH SYNOPSIS
11 11 .LP
12 12 .nf
13 13 #include <sys/dma_engine.h>
14 14 .fi
15 15
16 16 .SH INTERFACE LEVEL
17 17 .sp
18 18 .LP
19 19 Solaris x86 DDI specific (Solaris x86 DDI).
20 20 .SH DESCRIPTION
21 21 .sp
22 22 .LP
23 23 A device driver uses the \fBddi_dmae_req\fR structure to describe the
24 24 parameters for a \fBDMA\fR channel. This structure contains all the information
25 25 necessary to set up the channel, except for the \fBDMA\fR memory address and
26 26 transfer count. The defaults, as specified below, support most standard
27 27 devices. Other modes might be desirable for some devices, or to increase
28 28 performance. The \fBDMA\fR engine request structure is passed to
29 29 \fBddi_dmae_prog\fR(9F).
30 30 .SH STRUCTURE MEMBERS
31 31 .sp
32 32 .LP
33 33 The \fBddi_dmae_req\fR structure contains several members, each of which
34 34 controls some aspect of DMA engine operation. The structure members associated
35 35 with supported DMA engine options are described here.
36 36 .sp
37 37 .in +2
38 38 .nf
39 39 uchar_tder_command; /* Read / Write *
40 40 /uchar_tder_bufprocess; /* Standard / Chain */
41 41 uchar_tder_path; /* 8 / 16 / 32 */
42 42 uchar_tder_cycles; /* Compat / Type A / Type B / Burst */
43 43 uchar_tder_trans; /* Single / Demand / Block */
44 44 ddi_dma_cookie_t*(*proc)(); /* address of nextcookie routine */
45 45 void*procparms; /* parameter for nextcookie call */
46 46 .fi
47 47 .in -2
48 48
49 49 .sp
50 50 .ne 2
51 51 .na
52 52 \fB\fBder_command\fR\fR
53 53 .ad
54 54 .RS 18n
55 55 Specifies what \fBDMA\fR operation is to be performed. The value
56 56 \fBDMAE_CMD_WRITE\fR signifies that data is to be transferred from memory to
57 57 the \fBI/O \fRdevice. The value \fBDMAE_CMD_READ\fR signifies that data is to
58 58 be transferred from the \fBI/O\fR device to memory. This field must be set by
59 59 the driver before calling \fBddi_dmae_prog()\fR.
60 60 .RE
61 61
62 62 .sp
63 63 .ne 2
64 64 .na
65 65 \fB\fBder_bufprocess\fR\fR
66 66 .ad
67 67 .RS 18n
68 68 On some bus types, a driver can set \fBder_bufprocess\fR to the value
69 69 \fBDMAE_BUF_CHAIN\fR to specify that multiple \fBDMA\fR cookies will be given
70 70 to the \fBDMA\fR engine for a single \fBI/O\fR transfer. This action causes a
71 71 scatter/gather operation. In this mode of operation, the driver calls
72 72 \fBddi_dmae_prog()\fR to give the \fBDMA\fR engine the \fBDMA\fR engine request
73 73 structure and a pointer to the first cookie. The \fBproc\fR structure member
74 74 must be set to the address of a driver \fBnextcookie\fR routine. This routine
75 75 takes one argument, specified by the \fBprocparms\fR structure member, and
76 76 returns a pointer to a structure of type \fBddi_dma_cookie_t\fR that specifies
77 77 the next cookie for the \fBI/O \fR transfer. When the \fBDMA\fR engine is ready
78 78 to receive an additional cookie, the bus nexus driver controlling that
79 79 \fBDMA\fR engine calls the routine specified by the \fBproc\fR structure member
80 80 to obtain the next cookie from the driver. The driver's \fBnextcookie\fR
|
↓ open down ↓ |
63 lines elided |
↑ open up ↑ |
81 81 routine must then return the address of the next cookie (in static storage) to
82 82 the bus nexus routine that called it. If there are no more segments in the
83 83 current \fBDMA\fR window, then \fB(*proc)()\fR must return the \fBNULL\fR
84 84 pointer.
85 85 .sp
86 86 A driver can specify the \fBDMAE_BUF_CHAIN\fR flag only if the particular bus
87 87 architecture supports the use of multiple \fBDMA\fR cookies in a single
88 88 \fBI/O\fR transfer. A bus \fBDMA\fR engine can support this feature either with
89 89 a fixed-length scatter/gather list, or by an interrupt chaining feature. A
90 90 driver must determine whether its parent bus nexus supports this feature by
91 -examining the scatter/gather list size returned in the \fBdlim_sgllen\fR member
92 -of the \fBDMA\fR limit structure returned by the driver's call to
93 -\fBddi_dmae_getlim()\fR. (See \fBddi_dma_lim_x86\fR(9S).) If the size of the
91 +examining the scatter/gather list size returned in the \fBdma_attr_sgllen\fR
92 +member of the \fBDMA\fR attributes structure returned by the driver's call to
93 +\fBddi_dmae_getattr()\fR. (See \fBddi_dma_attr\fR(9S).) If the size of the
94 94 scatter/gather list is 1, then no chaining is available. The driver must not
95 95 specify the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR structure it
96 96 passes to \fBddi_dmae_prog()\fR, and the driver need not provide a
97 97 \fBnextcookie\fR routine.
98 98 .sp
99 99 If the size of the scatter/gather list is greater than 1, then \fBDMA\fR
100 100 chaining is available, and the driver has two options. Under the first option,
101 101 the driver chooses not to use the chaining feature. In this case (a) the driver
102 102 must \fBset\fR the size of the scatter/gather list to 1 before passing it to
103 103 the \fBDMA\fR setup routine, and (b) the driver must not set the
104 104 \fBDMAE_BUF_CHAIN\fR flag.
105 105 .sp
106 106 Under the second option, the driver chooses to use the chaining feature, in
107 107 which case, (a) it should leave the size of the scatter/gather list alone, and
108 108 (b) it must set the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR
109 109 structure. Before calling \fBddi_dmae_prog()\fR, the driver must \fIprefetch\fR
110 110 cookies until either (1) the end of the DMA window is
111 111 reached, or (2) the size of the
112 112 scatter/gather list is reached, whichever occurs first. These cookies must be
113 113 saved by the driver until they are requested by the nexus driver calling the
114 114 driver's \fBnextcookie\fR routine. The driver's \fBnextcookie\fR routine must
115 115 return the prefetched cookies in order, one cookie for each call to the
116 116 \fBnextcookie\fR routine, until the list of prefetched cookies is exhausted.
117 117 After the end of the list of cookies is reached, the \fBnextcookie\fR routine
118 118 must return the \fBNULL\fR pointer.
119 119 .sp
120 120 The size of the scatter/gather list determines how many discontiguous segments
121 121 of physical memory can participate in a single \fBDMA\fR transfer. \fBISA\fR
122 122 bus \fBDMA\fR engines have no scatter/gather capability, so their
123 123 scatter/gather list sizes are 1. Other finite scatter/gather list sizes would
124 124 also be possible. For performance reasons, drivers should use the chaining
125 125 capability if it is available on their parent bus.
126 126 .sp
127 127 As described above, a driver making use of \fBDMA\fR chaining must prefetch
128 128 \fBDMA\fR cookies before calling \fBddi_dmae_prog()\fR. The reasons for this
129 129 are:
130 130 .RS +4
131 131 .TP
132 132 .ie t \(bu
133 133 .el o
134 134 First, the driver must have some way to know the total \fBI/O\fR count with
135 135 which to program the \fBI/O\fR device. This \fBI/O\fR count must match the
136 136 total size of all the \fBDMA\fR segments that will be chained together into one
137 137 \fBDMA\fR operation. Depending on the size of the scatter/gather list and the
138 138 memory position and alignment of the \fBDMA\fR object, all or just part of the
139 139 current \fBDMA\fR window might be able to participate in a single \fBI/O\fR
140 140 operation. The driver must compute the \fBI/O\fR count by adding up the sizes
141 141 of the prefetched \fBDMA\fR cookies. The number of cookies whose sizes are to
142 142 be summed is the lesser of (a) the size of the scatter/gather list, or (b) the
143 143 number of segments remaining in the window.
144 144 .RE
145 145 .RS +4
146 146 .TP
147 147 .ie t \(bu
|
↓ open down ↓ |
44 lines elided |
↑ open up ↑ |
148 148 .el o
149 149 Second, on some bus architectures, the driver's \fBnextcookie\fR routine can be
150 150 called from a high-level interrupt routine. If the cookies were not prefetched,
151 151 the \fBnextcookie\fR routine would have to call \fBDMA\fR functions
152 152 from a high-level interrupt routine, which is not
153 153 recommended.
154 154 .RE
155 155 When breaking a \fBDMA\fR window into segments, the system arranges for the end
156 156 of every segment whose number is an integral multiple of the scatter/gather
157 157 list size to fall on a device-granularity boundary, as specified in the
158 -\fBdlim_granular\fR field in the \fBddi_dma_lim_x86\fR(9S) structure.
158 +\fBdma_attr_granular\fR field in the \fBddi_dma_attr\fR(9S) structure.
159 159 .sp
160 160 If the scatter/gather list size is 1 (either because no chaining is available
161 161 or because the driver does not want to use the chaining feature), then the
162 162 total \fBI/O\fR count for a single \fBDMA\fR operation is the size of \fBDMA\fR
163 163 segment denoted by the single \fBDMA\fR cookie that is passed in the call to
164 164 \fBddi_dmae_prog()\fR. In this case, the system arranges for each \fBDMA\fR
165 165 segment to be a multiple of the device-granularity size.
166 166 .RE
167 167
168 168 .sp
169 169 .ne 2
170 170 .na
171 171 \fB\fBder_path\fR\fR
172 172 .ad
173 173 .RS 18n
174 174 Specifies the \fBDMA\fR transfer size. The default of zero
175 175 (\fBDMAE_PATH_DEF\fR) specifies \fBISA\fR compatibility mode. In that mode,
176 176 channels 0, 1, 2, and 3 are programmed in 8-bit mode (\fBDMAE_PATH_8\fR), and
177 177 channels 5, 6, and 7 are programmed in 16-bit, count-by-word mode
178 178 (\fBDMAE_PATH_16\fR).
179 179 .RE
180 180
181 181 .sp
182 182 .ne 2
183 183 .na
184 184 \fB\fBder_cycles\fR\fR
185 185 .ad
186 186 .RS 18n
187 187 Specifies the timing mode to be used during \fBDMA\fR data transfers. The
188 188 default of zero (\fBDMAE_CYCLES_1\fR) specifies \fBISA\fR compatible timing.
189 189 Drivers using this mode must also specify \fBDMAE_TRANS_SNGL\fR in the
190 190 \fBder_trans\fR structure member.
191 191 .RE
192 192
193 193 .sp
194 194 .ne 2
195 195 .na
196 196 \fB\fBder_trans\fR\fR
197 197 .ad
198 198 .RS 18n
199 199 Specifies the bus transfer mode that the \fBDMA\fR engine should expect from
200 200 the device. The default value of zero (\fBDMAE_TRANS_SNGL\fR) specifies that
201 201 the device performs one transfer for each bus arbitration cycle. Devices that
202 202 use \fBISA\fR compatible timing (specified by a value of zero, which is the
203 203 default, in the \fBder_cycles\fR structure member) should use the
204 204 \fBDMAE_TRANS_SNGL\fR mode.
205 205 .RE
206 206
207 207 .SH ATTRIBUTES
208 208 .sp
209 209 .LP
210 210 See \fBattributes\fR(5) for descriptions of the following attributes:
211 211 .sp
212 212
213 213 .sp
214 214 .TS
215 215 box;
216 216 c | c
|
↓ open down ↓ |
48 lines elided |
↑ open up ↑ |
217 217 l | l .
218 218 ATTRIBUTE TYPE ATTRIBUTE VALUE
219 219 _
220 220 Architecture x86
221 221 .TE
222 222
223 223 .SH SEE ALSO
224 224 .sp
225 225 .LP
226 226 \fBisa\fR(4), \fBattributes\fR(5),
227 -\fBddi_dmae\fR(9F), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S)
227 +\fBddi_dmae\fR(9F), \fBddi_dma_attr\fR(9S)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX