usr/src/man/man9f/ddi_dmae.9f

   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)