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