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 32 \fBint\fR \fBddi_dmae_disable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); 33 .fi 34 35 .LP 36 .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 91 .sp 92 .ne 2 93 .na 94 \fB\fIcallback\fR\fR 95 .ad 96 .RS 12n 97 The address of a function to call back later if resources are not currently 98 available. The following special function addresses may also be used: 99 .sp 100 .ne 2 101 .na 102 \fB\fBDDI_DMA_SLEEP\fR\fR 103 .ad 104 .RS 20n 105 Wait until resources are available. 106 .RE 107 108 .sp 109 .ne 2 110 .na 111 \fB\fBDDI_DMA_DONTWAIT\fR\fR 112 .ad 113 .RS 20n 114 Do not wait until resources are available and do not schedule a callback. 115 .RE 116 117 .RE 118 119 .sp 120 .ne 2 121 .na 122 \fB\fIarg\fR\fR 123 .ad 124 .RS 12n 125 Argument to be passed to the callback function, if specified. 126 .RE 127 128 .sp 129 .ne 2 130 .na 131 \fB\fIdmaereqp\fR\fR 132 .ad 133 .RS 12n 134 A pointer to a \fBDMA\fR engine request structure. See \fBddi_dmae_req\fR(9S). 135 .RE 136 137 .sp 138 .ne 2 139 .na 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 189 \fBDMA\fR address and count from \fBddi_dma_cookie\fR(9S). 190 .RE 191 192 .sp 193 .ne 2 194 .na 195 \fBThird-party \fBDMA\fR\fR 196 .ad 197 .RS 19n 198 This method uses the system \fBDMA\fR engine that is resident on the main 199 system board. In this model, the device cooperates with the system's \fBDMA\fR 200 engine to effect the data transfers between the device and memory. The driver 201 uses the functions documented here, except \fBddi_dmae_1stparty()\fR, to 202 initialize and program the \fBDMA\fR engine. For each \fBDMA\fR data transfer, 203 the driver programs the \fBDMA\fR engine and then gives the device a command 204 to initiate the transfer in cooperation with that engine. 205 .RE 206 207 .sp 208 .ne 2 209 .na 210 \fBFirst-party DMA\fR 211 .ad 212 .RS 19n 213 Using this method, the device uses its own \fBDMA\fR bus cycles, but requires a 214 channel from the system's \fBDMA\fR engine. After allocating the \fBDMA\fR 215 channel, the \fBddi_dmae_1stparty()\fR function may be used to perform whatever 216 configuration is necessary to enable this mode. 217 .RE 218 219 .SS "\fBddi_dmae_alloc()\fR" 220 .sp 221 .LP 222 The \fBddi_dmae_alloc()\fR function is used to acquire a \fBDMA\fR channel of 223 the system \fBDMA\fR engine. \fBddi_dmae_alloc()\fR allows only one device at a 224 time to have a particular \fBDMA\fR channel allocated. It must be called prior 225 to any other system \fBDMA\fR engine function on a channel. If the device 226 allows the channel to be shared with other devices, it must be freed using 227 \fBddi_dmae_release()\fR after completion of the \fBDMA\fR operation. In any 228 case, the channel must be released before the driver successfully detaches. See 229 \fBdetach\fR(9E). No other driver may acquire the \fBDMA\fR channel until it is 230 released. 231 .sp 232 .LP 233 If the requested channel is not immediately available, the value of 234 \fIcallback\fR determines what action will be taken. If the value of 235 \fIcallback\fR is \fBDDI_DMA_DONTWAIT\fR, \fBddi_dmae_alloc()\fR will return 236 immediately. The value \fBDDI_DMA_SLEEP\fR will cause the thread to sleep and 237 not return until the channel has been acquired. Any other value is assumed to 238 be a callback function address. In that case, \fBddi_dmae_alloc()\fR returns 239 immediately, and when resources might have become available, the callback 240 function is called (with the argument \fIarg\fR) from interrupt context. When 241 the callback function is called, it should attempt to allocate the \fBDMA\fR 242 channel again. If it succeeds or no longer needs the channel, it must return 243 the value \fBDDI_DMA_CALLBACK_DONE\fR. If it tries to allocate the channel but 244 fails to do so, it must return the value \fBDDI_DMA_CALLBACK_RUNOUT\fR. In this 245 case, the callback function is put back on a list to be called again later. 246 .SS "\fBddi_dmae_prog()\fR" 247 .sp 248 .LP 249 The \fBddi_dmae_prog()\fR function programs the \fBDMA\fR channel for a 250 \fBDMA\fR transfer. The \fBddi_dmae_req\fR structure contains all the 251 information necessary to set up the channel, except for the memory address and 252 count. Once the channel has been programmed, subsequent calls to 253 \fBddi_dmae_prog()\fR may specify a value of \fINULL\fR for \fIdmaereqp\fR if 254 no changes to the programming are required other than the address and count 255 values. It disables the channel prior to setup, and enables the channel before 256 returning. The \fBDMA\fR address and count are specified by passing 257 \fBddi_dmae_prog()\fR a \fBDMA\fR cookie. 258 Other \fBDMA\fR engine parameters are specified by the \fBDMA\fR engine request 259 structure passed in through \fIdmaereqp\fR. The fields of that structure are 260 documented in \fBddi_dmae_req\fR(9S). 261 .sp 262 .LP 263 Before using \fBddi_dmae_prog()\fR, you must allocate system \fBDMA\fR 264 resources using \fBDMA\fR setup functions such as \fBddi_dma_mem_alloc\fR(9F). 265 \fBddi_dma_addr_bind_handle\fR(9F) can then be used to retrieve a cookie which 266 contains the address and count. Then this cookie is passed to 267 \fBddi_dmae_prog()\fR. 268 .SS "\fBddi_dmae_disable()\fR" 269 .sp 270 .LP 271 The \fBddi_dmae_disable()\fR function disables the \fBDMA\fR channel so that it 272 no longer responds to a device's \fBDMA\fR service requests. 273 .SS "\fBddi_dmae_enable()\fR" 274 .sp 275 .LP 276 The \fBddi_dmae_enable()\fR function enables the \fBDMA\fR channel for 277 operation. This may be used to re-enable the channel after a call to 278 \fBddi_dmae_disable()\fR. The channel is automatically enabled after successful 279 programming by \fBddi_dmae_prog()\fR. 280 .SS "\fBddi_dmae_stop()\fR" 281 .sp 282 .LP 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. 346 .RE 347 348 .sp 349 .ne 2 350 .na 351 \fB\fBDDI_FAILURE\fR\fR 352 .ad 353 .RS 23n 354 May be returned due to invalid arguments. 355 .RE 356 357 .sp 358 .ne 2 359 .na 360 \fB\fBDDI_DMA_NORESOURCES\fR\fR 361 .ad 362 .RS 23n 363 May be returned by \fBddi_dmae_alloc()\fR if the requested resources are not 364 available and the value of \fIdmae_waitfp\fR is not \fBDDI_DMA_SLEEP\fR. 365 .RE 366 367 .SH CONTEXT 368 .sp 369 .LP 370 If \fBddi_dmae_alloc()\fR is called from interrupt context, then its 371 \fIdmae_waitfp\fR argument and the callback function must not have the value 372 \fBDDI_DMA_SLEEP\fR. Otherwise, all these routines can be called from user, 373 interrupt, or kernel context. 374 .SH ATTRIBUTES 375 .sp 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)