1 '\" te
2 .\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2012 Garrett D'Amore <garrett@damore.org>. All rights reserved.
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 .\" 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 .\" 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"
8 .SH NAME
9 ddi_dmae, ddi_dmae_alloc, ddi_dmae_release, ddi_dmae_prog, ddi_dmae_disable,
10 ddi_dmae_enable, ddi_dmae_stop, ddi_dmae_getcnt, ddi_dmae_1stparty,
11 ddi_dmae_getlim, ddi_dmae_getattr \- system DMA engine functions
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBint\fR \fBddi_dmae_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint (*\fR\fIcallback\fR) (caddr_t),
16 \fBcaddr_t\fR \fIarg\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBddi_dmae_release\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBint\fR \fBddi_dmae_prog\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct ddi_dmae_req *\fR\fIdmaereqp\fR,
27 \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBint\fR \fIchnl\fR);
28 .fi
29
30 .LP
31 .nf
37 \fBint\fR \fBddi_dmae_enable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
38 .fi
39
40 .LP
41 .nf
42 \fBint\fR \fBddi_dmae_stop\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
43 .fi
44
45 .LP
46 .nf
47 \fBint\fR \fBddi_dmae_getcnt\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint *\fR\fIcountp\fR);
48 .fi
49
50 .LP
51 .nf
52 \fBint\fR \fBddi_dmae_1stparty\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
53 .fi
54
55 .LP
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 \fBint\fR \fBddi_dmae_getattr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattrp\fR);
63 .fi
64
65 .SH INTERFACE LEVEL
66 .sp
67 .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.
71 .SH PARAMETERS
72 .sp
73 .ne 2
74 .na
75 \fB\fIdip\fR\fR
76 .ad
77 .RS 12n
78 A \fBdev_info\fR pointer that identifies the device.
79 .RE
80
81 .sp
82 .ne 2
83 .na
84 \fB\fIchnl\fR\fR
85 .ad
86 .RS 12n
87 A \fBDMA\fR channel number. On \fBISA\fR buses this number must be \fB0\fR,
88 \fB1\fR, \fB2\fR, \fB3\fR, \fB5\fR, \fB6\fR, or \fB7\fR.
89 .RE
90
140 \fB\fIcookiep\fR\fR
141 .ad
142 .RS 12n
143 A pointer to a \fBddi_dma_cookie\fR(9S) object,
144 which contains the address and count.
145 .RE
146
147 .sp
148 .ne 2
149 .na
150 \fB\fIcountp\fR\fR
151 .ad
152 .RS 12n
153 A pointer to an integer that will receive the count of the number of bytes not
154 yet transferred upon completion of a \fBDMA\fR operation.
155 .RE
156
157 .sp
158 .ne 2
159 .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 \fB\fIattrp\fR\fR
170 .ad
171 .RS 12n
172 A pointer to a \fBDMA \fR attribute structure. See \fBddi_dma_attr\fR(9S).
173 .RE
174
175 .SH DESCRIPTION
176 .sp
177 .LP
178 There are three possible ways that a device can perform \fBDMA\fR engine
179 functions:
180 .sp
181 .ne 2
182 .na
183 \fBBus master DMA\fR
184 .ad
185 .RS 19n
186 If the device is capable of acting as a true bus master, then the driver should
187 program the device's \fBDMA\fR registers directly and not make use of the
188 \fBDMA\fR engine functions described here. The driver should obtain the
283 The \fBddi_dmae_stop()\fR function disables the channel and terminates any
284 active operation.
285 .SS "\fBddi_dmae_getcnt()\fR"
286 .sp
287 .LP
288 The \fBddi_dmae_getcnt()\fR function examines the count register of the
289 \fBDMA\fR channel and sets \fI*countp\fR to the number of bytes remaining to be
290 transferred. The channel is assumed to be stopped.
291 .SS "\fBddi_dmae_1stparty()\fR"
292 .sp
293 .LP
294 In the case of \fBISA\fR buses, \fBddi_dmae_1stparty()\fR configures a channel
295 in the system's \fBDMA\fR engine to operate in a ``slave'' (``cascade'') mode.
296 .sp
297 .LP
298 When operating in \fBddi_dmae_1stparty()\fR mode, the \fBDMA\fR channel must
299 first be allocated using \fBddi_dmae_alloc()\fR and then configured using
300 \fBddi_dmae_1stparty()\fR. The driver then programs the device to perform the
301 I/O, including the necessary \fBDMA\fR address and count values obtained from
302 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 .SS "\fBddi_dmae_getattr()\fR"
327 .sp
328 .LP
329 The \fBddi_dmae_getattr()\fR function fills in the \fBDMA\fR attribute
330 structure, pointed to by \fIattrp\fR, with the \fBDMA\fR attributes of the
331 system \fBDMA\fR engine. Drivers for devices that perform their own bus
332 mastering or use first-party \fBDMA\fR must create and initialize their own
333 \fBDMA\fR attribute structures; they should not use \fBddi_dmae_getattr()\fR.
334 The \fBDMA\fR attribute structure must be passed to the \fBDMA\fR resource
335 allocation functions to provide the information necessary to break the
336 \fBDMA\fR request into \fBDMA\fR windows and \fBDMA\fR cookies. See
337 \fBddi_dma_nextcookie\fR(9F) and \fBddi_dma_getwin\fR(9F).
338 .SH RETURN VALUES
339 .sp
340 .ne 2
341 .na
342 \fB\fBDDI_SUCCESS\fR\fR
343 .ad
344 .RS 23n
345 Upon success, for all of these routines.
376 .LP
377 See \fBattributes\fR(5) for descriptions of the following attributes:
378 .sp
379
380 .sp
381 .TS
382 box;
383 c | c
384 l | l .
385 ATTRIBUTE TYPE ATTRIBUTE VALUE
386 _
387 Architecture x86
388 .TE
389
390 .SH SEE ALSO
391 .sp
392 .LP
393 \fBisa\fR(4), \fBattributes\fR(5), \fBddi_dma_buf_setup\fR(9F),
394 \fBddi_dma_getwin\fR(9F), \fBddi_dma_nextcookie\fR(9F),
395 \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),
397 \fBddi_dmae_req\fR(9S)
|
1 '\" te
2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
3 .\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
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 .\" 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 .\" 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 "May 24, 2014"
8 .SH NAME
9 ddi_dmae, ddi_dmae_alloc, ddi_dmae_release, ddi_dmae_prog, ddi_dmae_disable,
10 ddi_dmae_enable, ddi_dmae_stop, ddi_dmae_getcnt, ddi_dmae_1stparty,
11 ddi_dmae_getattr \- system DMA engine functions
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBint\fR \fBddi_dmae_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint (*\fR\fIcallback\fR) (caddr_t),
16 \fBcaddr_t\fR \fIarg\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBddi_dmae_release\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBint\fR \fBddi_dmae_prog\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct ddi_dmae_req *\fR\fIdmaereqp\fR,
27 \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBint\fR \fIchnl\fR);
28 .fi
29
30 .LP
31 .nf
37 \fBint\fR \fBddi_dmae_enable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
38 .fi
39
40 .LP
41 .nf
42 \fBint\fR \fBddi_dmae_stop\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
43 .fi
44
45 .LP
46 .nf
47 \fBint\fR \fBddi_dmae_getcnt\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint *\fR\fIcountp\fR);
48 .fi
49
50 .LP
51 .nf
52 \fBint\fR \fBddi_dmae_1stparty\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR);
53 .fi
54
55 .LP
56 .nf
57 \fBint\fR \fBddi_dmae_getattr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattrp\fR);
58 .fi
59
60 .SH INTERFACE LEVEL
61 .sp
62 .LP
63 Solaris DDI specific (Solaris DDI).
64 .SH PARAMETERS
65 .sp
66 .ne 2
67 .na
68 \fB\fIdip\fR\fR
69 .ad
70 .RS 12n
71 A \fBdev_info\fR pointer that identifies the device.
72 .RE
73
74 .sp
75 .ne 2
76 .na
77 \fB\fIchnl\fR\fR
78 .ad
79 .RS 12n
80 A \fBDMA\fR channel number. On \fBISA\fR buses this number must be \fB0\fR,
81 \fB1\fR, \fB2\fR, \fB3\fR, \fB5\fR, \fB6\fR, or \fB7\fR.
82 .RE
83
133 \fB\fIcookiep\fR\fR
134 .ad
135 .RS 12n
136 A pointer to a \fBddi_dma_cookie\fR(9S) object,
137 which contains the address and count.
138 .RE
139
140 .sp
141 .ne 2
142 .na
143 \fB\fIcountp\fR\fR
144 .ad
145 .RS 12n
146 A pointer to an integer that will receive the count of the number of bytes not
147 yet transferred upon completion of a \fBDMA\fR operation.
148 .RE
149
150 .sp
151 .ne 2
152 .na
153 \fB\fIattrp\fR\fR
154 .ad
155 .RS 12n
156 A pointer to a \fBDMA \fR attribute structure. See \fBddi_dma_attr\fR(9S).
157 .RE
158
159 .SH DESCRIPTION
160 .sp
161 .LP
162 There are three possible ways that a device can perform \fBDMA\fR engine
163 functions:
164 .sp
165 .ne 2
166 .na
167 \fBBus master DMA\fR
168 .ad
169 .RS 19n
170 If the device is capable of acting as a true bus master, then the driver should
171 program the device's \fBDMA\fR registers directly and not make use of the
172 \fBDMA\fR engine functions described here. The driver should obtain the
267 The \fBddi_dmae_stop()\fR function disables the channel and terminates any
268 active operation.
269 .SS "\fBddi_dmae_getcnt()\fR"
270 .sp
271 .LP
272 The \fBddi_dmae_getcnt()\fR function examines the count register of the
273 \fBDMA\fR channel and sets \fI*countp\fR to the number of bytes remaining to be
274 transferred. The channel is assumed to be stopped.
275 .SS "\fBddi_dmae_1stparty()\fR"
276 .sp
277 .LP
278 In the case of \fBISA\fR buses, \fBddi_dmae_1stparty()\fR configures a channel
279 in the system's \fBDMA\fR engine to operate in a ``slave'' (``cascade'') mode.
280 .sp
281 .LP
282 When operating in \fBddi_dmae_1stparty()\fR mode, the \fBDMA\fR channel must
283 first be allocated using \fBddi_dmae_alloc()\fR and then configured using
284 \fBddi_dmae_1stparty()\fR. The driver then programs the device to perform the
285 I/O, including the necessary \fBDMA\fR address and count values obtained from
286 the \fBddi_dma_cookie\fR(9S).
287 .SS "\fBddi_dmae_getattr()\fR"
288 .sp
289 .LP
290 The \fBddi_dmae_getattr()\fR function fills in the \fBDMA\fR attribute
291 structure, pointed to by \fIattrp\fR, with the \fBDMA\fR attributes of the
292 system \fBDMA\fR engine. Drivers for devices that perform their own bus
293 mastering or use first-party \fBDMA\fR must create and initialize their own
294 \fBDMA\fR attribute structures; they should not use \fBddi_dmae_getattr()\fR.
295 The \fBDMA\fR attribute structure must be passed to the \fBDMA\fR resource
296 allocation functions to provide the information necessary to break the
297 \fBDMA\fR request into \fBDMA\fR windows and \fBDMA\fR cookies. See
298 \fBddi_dma_nextcookie\fR(9F) and \fBddi_dma_getwin\fR(9F).
299 .SH RETURN VALUES
300 .sp
301 .ne 2
302 .na
303 \fB\fBDDI_SUCCESS\fR\fR
304 .ad
305 .RS 23n
306 Upon success, for all of these routines.
337 .LP
338 See \fBattributes\fR(5) for descriptions of the following attributes:
339 .sp
340
341 .sp
342 .TS
343 box;
344 c | c
345 l | l .
346 ATTRIBUTE TYPE ATTRIBUTE VALUE
347 _
348 Architecture x86
349 .TE
350
351 .SH SEE ALSO
352 .sp
353 .LP
354 \fBisa\fR(4), \fBattributes\fR(5), \fBddi_dma_buf_setup\fR(9F),
355 \fBddi_dma_getwin\fR(9F), \fBddi_dma_nextcookie\fR(9F),
356 \fBddi_dma_mem_alloc\fR(9F), \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_attr\fR(9S),
357 \fBddi_dma_cookie\fR(9S),
358 \fBddi_dmae_req\fR(9S)
|