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/man9f/ddi_dmae.9f
+++ new/usr/src/man/man9f/ddi_dmae.9f
1 1 '\" te
2 +.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 3 .\" Copyright (c) 2006 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 9F "Feb 02, 2012"
7 +.TH DDI_DMAE 9F "May 24, 2014"
8 8 .SH NAME
9 9 ddi_dmae, ddi_dmae_alloc, ddi_dmae_release, ddi_dmae_prog, ddi_dmae_disable,
10 10 ddi_dmae_enable, ddi_dmae_stop, ddi_dmae_getcnt, ddi_dmae_1stparty,
11 -ddi_dmae_getlim, ddi_dmae_getattr \- system DMA engine functions
11 +ddi_dmae_getattr \- system DMA engine functions
12 12 .SH SYNOPSIS
13 13 .LP
14 14 .nf
15 15 \fBint\fR \fBddi_dmae_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint (*\fR\fIcallback\fR) (caddr_t),
16 16 \fBcaddr_t\fR \fIarg\fR);
17 17 .fi
18 18
19 19 .LP
20 20 .nf
21 21 \fBint\fR \fBddi_dmae_release\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
22 22 .fi
23 23
24 24 .LP
25 25 .nf
26 26 \fBint\fR \fBddi_dmae_prog\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct ddi_dmae_req *\fR\fIdmaereqp\fR,
27 27 \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBint\fR \fIchnl\fR);
28 28 .fi
29 29
30 30 .LP
31 31 .nf
32 32 \fBint\fR \fBddi_dmae_disable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
33 33 .fi
34 34
35 35 .LP
36 36 .nf
37 37 \fBint\fR \fBddi_dmae_enable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
38 38 .fi
39 39
40 40 .LP
41 41 .nf
42 42 \fBint\fR \fBddi_dmae_stop\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
43 43 .fi
44 44
45 45 .LP
46 46 .nf
|
↓ open down ↓ |
25 lines elided |
↑ open up ↑ |
47 47 \fBint\fR \fBddi_dmae_getcnt\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint *\fR\fIcountp\fR);
48 48 .fi
49 49
50 50 .LP
51 51 .nf
52 52 \fBint\fR \fBddi_dmae_1stparty\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
53 53 .fi
54 54
55 55 .LP
56 56 .nf
57 -\fBint\fR \fBddi_dmae_getlim\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimitsp\fR);
58 -.fi
59 -
60 -.LP
61 -.nf
62 57 \fBint\fR \fBddi_dmae_getattr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattrp\fR);
63 58 .fi
64 59
65 60 .SH INTERFACE LEVEL
66 61 .sp
67 62 .LP
68 -Solaris DDI specific (Solaris DDI). The \fBddi_dmae_getlim()\fR interface,
69 -described below, is obsolete. Use \fBddi_dmae_getattr()\fR, also described
70 -below, to replace it.
63 +Solaris DDI specific (Solaris DDI).
71 64 .SH PARAMETERS
72 65 .sp
73 66 .ne 2
74 67 .na
75 68 \fB\fIdip\fR\fR
76 69 .ad
77 70 .RS 12n
78 71 A \fBdev_info\fR pointer that identifies the device.
79 72 .RE
80 73
81 74 .sp
82 75 .ne 2
83 76 .na
84 77 \fB\fIchnl\fR\fR
85 78 .ad
86 79 .RS 12n
87 80 A \fBDMA\fR channel number. On \fBISA\fR buses this number must be \fB0\fR,
88 81 \fB1\fR, \fB2\fR, \fB3\fR, \fB5\fR, \fB6\fR, or \fB7\fR.
89 82 .RE
90 83
91 84 .sp
92 85 .ne 2
93 86 .na
94 87 \fB\fIcallback\fR\fR
95 88 .ad
96 89 .RS 12n
97 90 The address of a function to call back later if resources are not currently
98 91 available. The following special function addresses may also be used:
99 92 .sp
100 93 .ne 2
101 94 .na
102 95 \fB\fBDDI_DMA_SLEEP\fR\fR
103 96 .ad
104 97 .RS 20n
105 98 Wait until resources are available.
106 99 .RE
107 100
108 101 .sp
109 102 .ne 2
110 103 .na
111 104 \fB\fBDDI_DMA_DONTWAIT\fR\fR
112 105 .ad
113 106 .RS 20n
114 107 Do not wait until resources are available and do not schedule a callback.
115 108 .RE
116 109
117 110 .RE
118 111
119 112 .sp
120 113 .ne 2
121 114 .na
122 115 \fB\fIarg\fR\fR
123 116 .ad
124 117 .RS 12n
125 118 Argument to be passed to the callback function, if specified.
126 119 .RE
127 120
128 121 .sp
129 122 .ne 2
130 123 .na
131 124 \fB\fIdmaereqp\fR\fR
132 125 .ad
133 126 .RS 12n
134 127 A pointer to a \fBDMA\fR engine request structure. See \fBddi_dmae_req\fR(9S).
135 128 .RE
136 129
137 130 .sp
138 131 .ne 2
139 132 .na
140 133 \fB\fIcookiep\fR\fR
141 134 .ad
142 135 .RS 12n
143 136 A pointer to a \fBddi_dma_cookie\fR(9S) object,
144 137 which contains the address and count.
145 138 .RE
146 139
147 140 .sp
148 141 .ne 2
149 142 .na
|
↓ open down ↓ |
69 lines elided |
↑ open up ↑ |
150 143 \fB\fIcountp\fR\fR
151 144 .ad
152 145 .RS 12n
153 146 A pointer to an integer that will receive the count of the number of bytes not
154 147 yet transferred upon completion of a \fBDMA\fR operation.
155 148 .RE
156 149
157 150 .sp
158 151 .ne 2
159 152 .na
160 -\fB\fIlimitsp\fR\fR
161 -.ad
162 -.RS 12n
163 -A pointer to a \fBDMA\fR limit structure. See \fBddi_dma_lim_x86\fR(9S).
164 -.RE
165 -
166 -.sp
167 -.ne 2
168 -.na
169 153 \fB\fIattrp\fR\fR
170 154 .ad
171 155 .RS 12n
172 156 A pointer to a \fBDMA \fR attribute structure. See \fBddi_dma_attr\fR(9S).
173 157 .RE
174 158
175 159 .SH DESCRIPTION
176 160 .sp
177 161 .LP
178 162 There are three possible ways that a device can perform \fBDMA\fR engine
179 163 functions:
180 164 .sp
181 165 .ne 2
182 166 .na
183 167 \fBBus master DMA\fR
184 168 .ad
185 169 .RS 19n
186 170 If the device is capable of acting as a true bus master, then the driver should
187 171 program the device's \fBDMA\fR registers directly and not make use of the
188 172 \fBDMA\fR engine functions described here. The driver should obtain the
189 173 \fBDMA\fR address and count from \fBddi_dma_cookie\fR(9S).
190 174 .RE
191 175
192 176 .sp
193 177 .ne 2
194 178 .na
195 179 \fBThird-party \fBDMA\fR\fR
196 180 .ad
197 181 .RS 19n
198 182 This method uses the system \fBDMA\fR engine that is resident on the main
199 183 system board. In this model, the device cooperates with the system's \fBDMA\fR
200 184 engine to effect the data transfers between the device and memory. The driver
201 185 uses the functions documented here, except \fBddi_dmae_1stparty()\fR, to
202 186 initialize and program the \fBDMA\fR engine. For each \fBDMA\fR data transfer,
203 187 the driver programs the \fBDMA\fR engine and then gives the device a command
204 188 to initiate the transfer in cooperation with that engine.
205 189 .RE
206 190
207 191 .sp
208 192 .ne 2
209 193 .na
210 194 \fBFirst-party DMA\fR
211 195 .ad
212 196 .RS 19n
213 197 Using this method, the device uses its own \fBDMA\fR bus cycles, but requires a
214 198 channel from the system's \fBDMA\fR engine. After allocating the \fBDMA\fR
215 199 channel, the \fBddi_dmae_1stparty()\fR function may be used to perform whatever
216 200 configuration is necessary to enable this mode.
217 201 .RE
218 202
219 203 .SS "\fBddi_dmae_alloc()\fR"
220 204 .sp
221 205 .LP
222 206 The \fBddi_dmae_alloc()\fR function is used to acquire a \fBDMA\fR channel of
223 207 the system \fBDMA\fR engine. \fBddi_dmae_alloc()\fR allows only one device at a
224 208 time to have a particular \fBDMA\fR channel allocated. It must be called prior
225 209 to any other system \fBDMA\fR engine function on a channel. If the device
226 210 allows the channel to be shared with other devices, it must be freed using
227 211 \fBddi_dmae_release()\fR after completion of the \fBDMA\fR operation. In any
228 212 case, the channel must be released before the driver successfully detaches. See
229 213 \fBdetach\fR(9E). No other driver may acquire the \fBDMA\fR channel until it is
230 214 released.
231 215 .sp
232 216 .LP
233 217 If the requested channel is not immediately available, the value of
234 218 \fIcallback\fR determines what action will be taken. If the value of
235 219 \fIcallback\fR is \fBDDI_DMA_DONTWAIT\fR, \fBddi_dmae_alloc()\fR will return
236 220 immediately. The value \fBDDI_DMA_SLEEP\fR will cause the thread to sleep and
237 221 not return until the channel has been acquired. Any other value is assumed to
238 222 be a callback function address. In that case, \fBddi_dmae_alloc()\fR returns
239 223 immediately, and when resources might have become available, the callback
240 224 function is called (with the argument \fIarg\fR) from interrupt context. When
241 225 the callback function is called, it should attempt to allocate the \fBDMA\fR
242 226 channel again. If it succeeds or no longer needs the channel, it must return
243 227 the value \fBDDI_DMA_CALLBACK_DONE\fR. If it tries to allocate the channel but
244 228 fails to do so, it must return the value \fBDDI_DMA_CALLBACK_RUNOUT\fR. In this
245 229 case, the callback function is put back on a list to be called again later.
246 230 .SS "\fBddi_dmae_prog()\fR"
247 231 .sp
248 232 .LP
249 233 The \fBddi_dmae_prog()\fR function programs the \fBDMA\fR channel for a
250 234 \fBDMA\fR transfer. The \fBddi_dmae_req\fR structure contains all the
251 235 information necessary to set up the channel, except for the memory address and
252 236 count. Once the channel has been programmed, subsequent calls to
253 237 \fBddi_dmae_prog()\fR may specify a value of \fINULL\fR for \fIdmaereqp\fR if
254 238 no changes to the programming are required other than the address and count
255 239 values. It disables the channel prior to setup, and enables the channel before
256 240 returning. The \fBDMA\fR address and count are specified by passing
257 241 \fBddi_dmae_prog()\fR a \fBDMA\fR cookie.
258 242 Other \fBDMA\fR engine parameters are specified by the \fBDMA\fR engine request
259 243 structure passed in through \fIdmaereqp\fR. The fields of that structure are
260 244 documented in \fBddi_dmae_req\fR(9S).
261 245 .sp
262 246 .LP
263 247 Before using \fBddi_dmae_prog()\fR, you must allocate system \fBDMA\fR
264 248 resources using \fBDMA\fR setup functions such as \fBddi_dma_mem_alloc\fR(9F).
265 249 \fBddi_dma_addr_bind_handle\fR(9F) can then be used to retrieve a cookie which
266 250 contains the address and count. Then this cookie is passed to
267 251 \fBddi_dmae_prog()\fR.
268 252 .SS "\fBddi_dmae_disable()\fR"
269 253 .sp
270 254 .LP
271 255 The \fBddi_dmae_disable()\fR function disables the \fBDMA\fR channel so that it
272 256 no longer responds to a device's \fBDMA\fR service requests.
273 257 .SS "\fBddi_dmae_enable()\fR"
274 258 .sp
275 259 .LP
276 260 The \fBddi_dmae_enable()\fR function enables the \fBDMA\fR channel for
277 261 operation. This may be used to re-enable the channel after a call to
278 262 \fBddi_dmae_disable()\fR. The channel is automatically enabled after successful
279 263 programming by \fBddi_dmae_prog()\fR.
280 264 .SS "\fBddi_dmae_stop()\fR"
281 265 .sp
282 266 .LP
283 267 The \fBddi_dmae_stop()\fR function disables the channel and terminates any
284 268 active operation.
285 269 .SS "\fBddi_dmae_getcnt()\fR"
286 270 .sp
287 271 .LP
288 272 The \fBddi_dmae_getcnt()\fR function examines the count register of the
289 273 \fBDMA\fR channel and sets \fI*countp\fR to the number of bytes remaining to be
290 274 transferred. The channel is assumed to be stopped.
291 275 .SS "\fBddi_dmae_1stparty()\fR"
292 276 .sp
|
↓ open down ↓ |
114 lines elided |
↑ open up ↑ |
293 277 .LP
294 278 In the case of \fBISA\fR buses, \fBddi_dmae_1stparty()\fR configures a channel
295 279 in the system's \fBDMA\fR engine to operate in a ``slave'' (``cascade'') mode.
296 280 .sp
297 281 .LP
298 282 When operating in \fBddi_dmae_1stparty()\fR mode, the \fBDMA\fR channel must
299 283 first be allocated using \fBddi_dmae_alloc()\fR and then configured using
300 284 \fBddi_dmae_1stparty()\fR. The driver then programs the device to perform the
301 285 I/O, including the necessary \fBDMA\fR address and count values obtained from
302 286 the \fBddi_dma_cookie\fR(9S).
303 -.SS "\fBddi_dmae_getlim()\fR"
304 -.sp
305 -.LP
306 -This function is obsolete. Use \fBddi_dmae_getattr()\fR, described below,
307 -instead.
308 -.sp
309 -.LP
310 -The \fBddi_dmae_getlim()\fR function fills in the \fBDMA\fR limit structure,
311 -pointed to by \fIlimitsp\fR, with the \fBDMA\fR limits of the system \fBDMA\fR
312 -engine. Drivers for devices that perform their own bus mastering or use
313 -first-party \fBDMA\fR must create and initialize their own \fBDMA\fR limit
314 -structures; they should not use \fBddi_dmae_getlim()\fR. The \fBDMA\fR limit
315 -structure must be passed to the \fBDMA\fR setup routines so that they will know
316 -how to break the \fBDMA\fR request into windows. If the device has any
317 -particular restrictions on transfer size or granularity (such as the size of
318 -disk sector), the driver should further restrict the values in the structure
319 -members before passing them to the \fBDMA\fR setup routines. The driver must
320 -not relax any of the restrictions embodied in the structure after it is filled
321 -in by \fBddi_dmae_getlim()\fR. After calling \fBddi_dmae_getlim()\fR, a driver
322 -must examine, and possibly set, the size of the \fBDMA\fR engine's
323 -scatter/gather list to determine whether \fBDMA\fR chaining will be used. See
324 -\fBddi_dma_lim_x86\fR(9S) and \fBddi_dmae_req\fR(9S) for additional information
325 -on scatter/gather DMA.
326 287 .SS "\fBddi_dmae_getattr()\fR"
327 288 .sp
328 289 .LP
329 290 The \fBddi_dmae_getattr()\fR function fills in the \fBDMA\fR attribute
330 291 structure, pointed to by \fIattrp\fR, with the \fBDMA\fR attributes of the
331 292 system \fBDMA\fR engine. Drivers for devices that perform their own bus
332 293 mastering or use first-party \fBDMA\fR must create and initialize their own
333 294 \fBDMA\fR attribute structures; they should not use \fBddi_dmae_getattr()\fR.
334 295 The \fBDMA\fR attribute structure must be passed to the \fBDMA\fR resource
335 296 allocation functions to provide the information necessary to break the
336 297 \fBDMA\fR request into \fBDMA\fR windows and \fBDMA\fR cookies. See
337 298 \fBddi_dma_nextcookie\fR(9F) and \fBddi_dma_getwin\fR(9F).
338 299 .SH RETURN VALUES
339 300 .sp
340 301 .ne 2
341 302 .na
342 303 \fB\fBDDI_SUCCESS\fR\fR
343 304 .ad
344 305 .RS 23n
345 306 Upon success, for all of these routines.
346 307 .RE
347 308
348 309 .sp
349 310 .ne 2
350 311 .na
351 312 \fB\fBDDI_FAILURE\fR\fR
352 313 .ad
353 314 .RS 23n
354 315 May be returned due to invalid arguments.
355 316 .RE
356 317
357 318 .sp
358 319 .ne 2
359 320 .na
360 321 \fB\fBDDI_DMA_NORESOURCES\fR\fR
361 322 .ad
362 323 .RS 23n
363 324 May be returned by \fBddi_dmae_alloc()\fR if the requested resources are not
364 325 available and the value of \fIdmae_waitfp\fR is not \fBDDI_DMA_SLEEP\fR.
365 326 .RE
366 327
367 328 .SH CONTEXT
368 329 .sp
369 330 .LP
370 331 If \fBddi_dmae_alloc()\fR is called from interrupt context, then its
371 332 \fIdmae_waitfp\fR argument and the callback function must not have the value
372 333 \fBDDI_DMA_SLEEP\fR. Otherwise, all these routines can be called from user,
373 334 interrupt, or kernel context.
374 335 .SH ATTRIBUTES
375 336 .sp
376 337 .LP
377 338 See \fBattributes\fR(5) for descriptions of the following attributes:
378 339 .sp
379 340
380 341 .sp
381 342 .TS
382 343 box;
383 344 c | c
384 345 l | l .
385 346 ATTRIBUTE TYPE ATTRIBUTE VALUE
|
↓ open down ↓ |
50 lines elided |
↑ open up ↑ |
386 347 _
387 348 Architecture x86
388 349 .TE
389 350
390 351 .SH SEE ALSO
391 352 .sp
392 353 .LP
393 354 \fBisa\fR(4), \fBattributes\fR(5), \fBddi_dma_buf_setup\fR(9F),
394 355 \fBddi_dma_getwin\fR(9F), \fBddi_dma_nextcookie\fR(9F),
395 356 \fBddi_dma_mem_alloc\fR(9F), \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_attr\fR(9S),
396 -\fBddi_dma_cookie\fR(9S), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S),
357 +\fBddi_dma_cookie\fR(9S),
397 358 \fBddi_dmae_req\fR(9S)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX