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
  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_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 
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIcallback\fR\fR
  88 .ad
  89 .RS 12n
  90 The address of a function to call back later if resources are not currently
  91 available. The following special function addresses may also be used:
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBDDI_DMA_SLEEP\fR\fR
  96 .ad
  97 .RS 20n
  98 Wait until resources are available.
  99 .RE
 100 
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBDDI_DMA_DONTWAIT\fR\fR
 105 .ad
 106 .RS 20n
 107 Do not wait until resources are available and do not schedule a callback.
 108 .RE
 109 
 110 .RE
 111 
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fIarg\fR\fR
 116 .ad
 117 .RS 12n
 118 Argument to be passed to the callback function, if specified.
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fIdmaereqp\fR\fR
 125 .ad
 126 .RS 12n
 127 A pointer to a \fBDMA\fR engine request structure. See \fBddi_dmae_req\fR(9S).
 128 .RE
 129 
 130 .sp
 131 .ne 2
 132 .na
 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
 173 \fBDMA\fR address and count from \fBddi_dma_cookie\fR(9S).
 174 .RE
 175 
 176 .sp
 177 .ne 2
 178 .na
 179 \fBThird-party \fBDMA\fR\fR
 180 .ad
 181 .RS 19n
 182 This method uses the system \fBDMA\fR engine that is resident on the main
 183 system board. In this model, the device cooperates with the system's \fBDMA\fR
 184 engine to effect the data transfers between the device and memory. The driver
 185 uses the functions documented here, except \fBddi_dmae_1stparty()\fR, to
 186 initialize and program the \fBDMA\fR engine. For each \fBDMA\fR data transfer,
 187 the driver programs the \fBDMA\fR engine and then gives the device  a command
 188 to initiate the transfer in cooperation with that engine.
 189 .RE
 190 
 191 .sp
 192 .ne 2
 193 .na
 194 \fBFirst-party DMA\fR
 195 .ad
 196 .RS 19n
 197 Using this method, the device uses its own \fBDMA\fR bus cycles, but requires a
 198 channel from the system's \fBDMA\fR engine. After allocating the \fBDMA\fR
 199 channel, the \fBddi_dmae_1stparty()\fR function may be used to perform whatever
 200 configuration is necessary to enable this mode.
 201 .RE
 202 
 203 .SS "\fBddi_dmae_alloc()\fR"
 204 .sp
 205 .LP
 206 The \fBddi_dmae_alloc()\fR function is used to acquire a \fBDMA\fR channel of
 207 the system \fBDMA\fR engine. \fBddi_dmae_alloc()\fR allows only one device at a
 208 time to have a particular \fBDMA\fR channel allocated. It must be called prior
 209 to any other system  \fBDMA\fR engine function on a channel. If the device
 210 allows the channel to be shared with other devices, it must be freed using
 211 \fBddi_dmae_release()\fR after completion of the \fBDMA\fR operation. In any
 212 case, the channel must be released before the driver successfully detaches. See
 213 \fBdetach\fR(9E). No other driver may acquire the \fBDMA\fR channel until it is
 214 released.
 215 .sp
 216 .LP
 217 If the requested channel is not immediately available, the value of
 218 \fIcallback\fR determines what action will be taken. If the value of
 219 \fIcallback\fR is \fBDDI_DMA_DONTWAIT\fR, \fBddi_dmae_alloc()\fR will return
 220 immediately. The value \fBDDI_DMA_SLEEP\fR will cause the thread to sleep and
 221 not return until the channel has been acquired. Any other value is assumed to
 222 be a callback function address. In that case, \fBddi_dmae_alloc()\fR returns
 223 immediately, and when resources might have become available, the callback
 224 function is called (with the argument \fIarg\fR) from interrupt context. When
 225 the callback function is called, it should attempt to allocate the \fBDMA\fR
 226 channel again. If it succeeds or no longer needs the channel, it must return
 227 the value \fBDDI_DMA_CALLBACK_DONE\fR. If it tries to allocate the channel but
 228 fails to do so, it must return the value \fBDDI_DMA_CALLBACK_RUNOUT\fR. In this
 229 case, the callback function is put back on a list to be called again later.
 230 .SS "\fBddi_dmae_prog()\fR"
 231 .sp
 232 .LP
 233 The \fBddi_dmae_prog()\fR function programs the \fBDMA\fR channel for a
 234 \fBDMA\fR transfer. The \fBddi_dmae_req\fR structure contains all the
 235 information necessary to set up the channel, except for the memory address and
 236 count. Once the channel has been programmed, subsequent calls to
 237 \fBddi_dmae_prog()\fR may specify a value of \fINULL\fR for \fIdmaereqp\fR if
 238 no changes to the programming are required other than the address and count
 239 values. It disables the channel prior to setup, and enables the channel before
 240 returning. The \fBDMA\fR address and count are specified by passing
 241 \fBddi_dmae_prog()\fR a \fBDMA\fR cookie.
 242 Other \fBDMA\fR engine parameters are specified by the \fBDMA\fR engine request
 243 structure passed in through \fIdmaereqp\fR. The fields of that structure are
 244 documented in \fBddi_dmae_req\fR(9S).
 245 .sp
 246 .LP
 247 Before using \fBddi_dmae_prog()\fR, you must allocate system \fBDMA\fR
 248 resources using \fBDMA\fR setup functions such as \fBddi_dma_mem_alloc\fR(9F).
 249 \fBddi_dma_addr_bind_handle\fR(9F) can then be used to retrieve a cookie which
 250 contains the address and count. Then this cookie is passed to
 251 \fBddi_dmae_prog()\fR.
 252 .SS "\fBddi_dmae_disable()\fR"
 253 .sp
 254 .LP
 255 The \fBddi_dmae_disable()\fR function disables the \fBDMA\fR channel so that it
 256 no longer responds to a device's  \fBDMA\fR service requests.
 257 .SS "\fBddi_dmae_enable()\fR"
 258 .sp
 259 .LP
 260 The \fBddi_dmae_enable()\fR function enables the \fBDMA\fR channel for
 261 operation. This may be used to re-enable the channel after a call to
 262 \fBddi_dmae_disable()\fR. The channel is automatically enabled after successful
 263 programming by \fBddi_dmae_prog()\fR.
 264 .SS "\fBddi_dmae_stop()\fR"
 265 .sp
 266 .LP
 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.
 307 .RE
 308 
 309 .sp
 310 .ne 2
 311 .na
 312 \fB\fBDDI_FAILURE\fR\fR
 313 .ad
 314 .RS 23n
 315 May be returned due to invalid arguments.
 316 .RE
 317 
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fBDDI_DMA_NORESOURCES\fR\fR
 322 .ad
 323 .RS 23n
 324 May be returned by \fBddi_dmae_alloc()\fR if the requested resources are not
 325 available and the value of \fIdmae_waitfp\fR is not \fBDDI_DMA_SLEEP\fR.
 326 .RE
 327 
 328 .SH CONTEXT
 329 .sp
 330 .LP
 331 If \fBddi_dmae_alloc()\fR is called from interrupt context, then its
 332 \fIdmae_waitfp\fR argument and the callback function must not have the value
 333 \fBDDI_DMA_SLEEP\fR. Otherwise, all these routines can be called from user,
 334 interrupt, or kernel context.
 335 .SH ATTRIBUTES
 336 .sp
 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)