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

   1 '\" te
   2 .\"  Copyright (c) 2002 Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DDI_DMA_BUF_BIND_HANDLE 9F "Jul 27, 1996"
   7 .SH NAME
   8 ddi_dma_buf_bind_handle \- binds a system buffer to a DMA handle
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBddi_dma_buf_bind_handle\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBstruct buf *\fR\fIbp\fR,
  18      \fBuint_t\fR \fIflags\fR, \fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR
  19      \fIarg\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBuint_t *\fR\fIccountp\fR);
  20 .fi
  21
  22 .SH INTERFACE LEVEL
  23 .sp
  24 .LP
  25 Solaris DDI specific (Solaris DDI).
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIhandle\fR\fR
  31 .ad
  32 .RS 12n
  33 The \fBDMA\fR handle previously allocated by a call to
  34 \fBddi_dma_alloc_handle\fR(9F).
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIbp\fR\fR
  41 .ad
  42 .RS 12n
  43 A pointer to a system buffer structure (see \fBbuf\fR(9S)).
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIflags\fR\fR
  50 .ad
  51 .RS 12n
  52 Valid flags include:
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBDDI_DMA_WRITE\fR\fR
  57 .ad
  58 .RS 22n
  59 Transfer direction is from memory to I/O
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBDDI_DMA_READ\fR\fR
  66 .ad
  67 .RS 22n
  68 Transfer direction is from I/O to memory
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBDDI_DMA_RDWR\fR\fR
  75 .ad
  76 .RS 22n
  77 Both read and write
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBDDI_DMA_REDZONE\fR\fR
  84 .ad
  85 .RS 22n
  86 Establish an \fBMMU\fR redzone at end of the object.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBDDI_DMA_PARTIAL\fR\fR
  93 .ad
  94 .RS 22n
  95 Partial resource allocation
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBDDI_DMA_CONSISTENT\fR\fR
 102 .ad
 103 .RS 22n
 104 Nonsequential, random, and small block transfers.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBDDI_DMA_STREAMING\fR\fR
 111 .ad
 112 .RS 22n
 113 Sequential, unidirectional, block-sized, and block-aligned transfers.
 114 .RE
 115
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fIcallback\fR\fR
 122 .ad
 123 .RS 12n
 124 The address of a function to call back later if resources are not available
 125 now. The following special function addresses may also be used.
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBDDI_DMA_SLEEP\fR\fR
 130 .ad
 131 .RS 20n
 132 Wait until resources are available.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBDDI_DMA_DONTWAIT\fR\fR
 139 .ad
 140 .RS 20n
 141 Do not wait until resources are available and do not schedule a callback.
 142 .RE
 143
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fIarg\fR\fR
 150 .ad
 151 .RS 12n
 152 Argument to be passed to the callback function, \fIcallback\fR, if such a
 153 function is specified.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fIcookiep\fR\fR
 160 .ad
 161 .RS 12n
 162 A pointer to the first \fBddi_dma_cookie\fR(9S) structure.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fIccountp\fR\fR
 169 .ad
 170 .RS 12n
 171 Upon a successful return, \fIccountp\fR points to a value representing the
 172 number of cookies for this \fBDMA\fR object.
 173 .RE
 174
 175 .SH DESCRIPTION
 176 .sp
 177 .LP
 178 \fBddi_dma_buf_bind_handle()\fR allocates \fBDMA\fR resources for a system
 179 buffer such that a device can perform \fBDMA\fR to or from the buffer.
 180 \fBDMA\fR resources are allocated considering the device's \fBDMA\fR attributes
 181 as expressed by \fBddi_dma_attr\fR(9S) (see \fBddi_dma_alloc_handle\fR(9F)).
 182 .sp
 183 .LP
 184 \fBddi_dma_buf_bind_handle()\fR fills in the first \fBDMA\fR cookie pointed to
 185 by \fIcookiep\fR with the appropriate address, length, and bus type.
 186 \fB*\fR\fIccountp\fR is set to the number of \fBDMA\fR cookies representing
 187 this \fBDMA\fR object. Subsequent \fBDMA\fR cookies must be retrieved by
 188 calling \fBddi_dma_nextcookie\fR(9F) \fB*\fR\fIcountp\fR-1 times.
 189 .sp
 190 .LP
 191 When a \fBDMA\fR transfer completes, the driver should free up system \fBDMA\fR
 192 resources by calling \fBddi_dma_unbind_handle\fR(9F).
 193 .sp
 194 .LP
 195 The \fIflags\fR argument contains information for mapping routines.
 196 .sp
 197 .ne 2
 198 .na
 199 \fB\fBDDI_DMA_WRITE\fR, \fBDDI_DMA_READ\fR, \fBDDI_DMA_RDWR\fR\fR
 200 .ad
 201 .sp .6
 202 .RS 4n
 203 These flags describe the intended direction of the \fBDMA\fR transfer.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBDDI_DMA_STREAMING\fR \fR
 210 .ad
 211 .sp .6
 212 .RS 4n
 213 This flag should be set if the device is doing sequential, unidirectional,
 214 block-sized, and block-aligned transfers to or from memory. The alignment and
 215 padding constraints specified by the \fBminxfer\fR and \fBburstsizes\fR fields
 216 in the \fBDMA\fR attribute structure, \fBddi_dma_attr\fR(9S) (see
 217 \fBddi_dma_alloc_handle\fR(9F)) is used to allocate the most effective hardware
 218 support for large transfers.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBDDI_DMA_CONSISTENT\fR \fR
 225 .ad
 226 .sp .6
 227 .RS 4n
 228 This flag should be set if the device accesses memory randomly, or if
 229 synchronization steps using \fBddi_dma_sync\fR(9F) need to be as efficient as
 230 possible. I/O parameter blocks used for communication between a device and a
 231 driver should be allocated using \fBDDI_DMA_CONSISTENT\fR.
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBDDI_DMA_REDZONE\fR \fR
 238 .ad
 239 .sp .6
 240 .RS 4n
 241 If this flag is set, the system attempts to establish a protected red zone
 242 after the object. The \fBDMA\fR resource allocation functions do not guarantee
 243 the success of this request as some implementations may not have the hardware
 244 ability to support a red zone.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBDDI_DMA_PARTIAL\fR \fR
 251 .ad
 252 .sp .6
 253 .RS 4n
 254 Setting this flag indicates the caller can accept resources for part of the
 255 object. That is, if the size of the object exceeds the resources available,
 256 only resources for a portion of the object are allocated. The system indicates
 257 this condition returning status \fBDDI_DMA_PARTIAL_MAP\fR. At a later point,
 258 the caller can use \fBddi_dma_getwin\fR(9F) to change the valid portion of the
 259 object for which resources are allocated. If resources were allocated for only
 260 part of the object, \fBddi_dma_addr_bind_handle()\fR returns resources for the
 261 first \fBDMA\fR window. Even when \fBDDI_DMA_PARTIAL\fR is set, the system may
 262 decide to allocate resources for the entire object (less overhead) in which
 263 case \fBDDI_DMA_MAPPED\fR is returned.
 264 .RE
 265
 266 .sp
 267 .LP
 268 The callback function, \fIcallback\fR, indicates how a caller wants to handle
 269 the possibility of resources not being available. If \fIcallback\fR is set to
 270 \fBDDI_DMA_DONTWAIT\fR, the caller does not care if the allocation fails, and
 271 can handle an allocation failure appropriately. If \fIcallback\fR is set to
 272 \fBDDI_DMA_SLEEP\fR, the caller wishes to have the allocation routines wait for
 273 resources to become available. If any other value is set, and a \fBDMA\fR
 274 resource allocation fails, this value is assumed to be the address of a
 275 function to call at a later time when resources may become available. When the
 276 specified function is called, it is passed \fIarg\fR as an argument. The
 277 specified callback function must return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or
 278 \fBDDI_DMA_CALLBACK_DONE\fR. \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the
 279 callback function attempted to allocate \fBDMA\fR resources but failed to do
 280 so. In this case the callback function is put back on a list to be called again
 281 later. \fBDDI_DMA_CALLBACK_DONE\fR indicates either a successful allocation of
 282 \fBDMA\fR resources or that the driver no longer wishes to retry.
 283 .sp
 284 .LP
 285 The callback function is called in interrupt context. Therefore, only system
 286 functions accessible from interrupt context are be available. The callback
 287 function must take whatever steps necessary to protect its critical resources,
 288 data structures, queues, etc.
 289 .SH RETURN VALUES
 290 .sp
 291 .LP
 292 \fBddi_dma_buf_bind_handle()\fR returns:
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBDDI_DMA_MAPPED\fR\fR
 297 .ad
 298 .RS 23n
 299 Successfully allocated resources for the entire object.
 300 .RE
 301
 302 .sp
 303 .ne 2
 304 .na
 305 \fB\fBDDI_DMA_PARTIAL_MAP\fR\fR
 306 .ad
 307 .RS 23n
 308 Successfully allocated resources for a part of the object. This is acceptable
 309 when partial transfers are permitted by setting the \fBDDI_DMA_PARTIAL\fR flag
 310 in \fIflags\fR.
 311 .RE
 312
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBDDI_DMA_INUSE\fR\fR
 317 .ad
 318 .RS 23n
 319 Another I/O transaction is using the \fBDMA\fR handle.
 320 .RE
 321
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBDDI_DMA_NORESOURCES\fR\fR
 326 .ad
 327 .RS 23n
 328 No resources are available at the present time.
 329 .RE
 330
 331 .sp
 332 .ne 2
 333 .na
 334 \fB\fBDDI_DMA_NOMAPPING\fR\fR
 335 .ad
 336 .RS 23n
 337 The object cannot be reached by the device requesting the resources.
 338 .RE
 339
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fBDDI_DMA_TOOBIG\fR\fR
 344 .ad
 345 .RS 23n
 346 The object is too big. A request of this size can never be satisfied on this
 347 particular system. The maximum size varies depending on machine and
 348 configuration.
 349 .RE
 350
 351 .SH CONTEXT
 352 .sp
 353 .LP
 354 \fBddi_dma_buf_bind_handle()\fR can be called from user, kernel, or interrupt
 355 context, except when \fIcallback\fR is set to \fBDDI_DMA_SLEEP\fR, in which
 356 case it can be called from user or kernel context only.
 357 .SH SEE ALSO
 358 .sp
 359 .LP
 360 \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
 361 \fBddi_dma_free_handle\fR(9F), \fBddi_dma_getwin\fR(9F),
 362 \fBddi_dma_nextcookie\fR(9F), \fBddi_dma_sync\fR(9F),
 363 \fBddi_dma_unbind_handle\fR(9F), \fBbuf\fR(9S), \fBddi_dma_attr\fR(9S),
 364 \fBddi_dma_cookie\fR(9S)
 365 .sp
 366 .LP
 367 \fIWriting Device Drivers\fR
 368 .SH NOTES
 369 .sp
 370 .LP
 371 If the driver permits partial mapping with the \fBDDI_DMA_PARTIAL\fR flag, the
 372 number of cookies in each window may exceed the size of the device's
 373 scatter/gather list as specified in the \fBdma_attr_sgllen\fR field in the
 374 \fBddi_dma_attr\fR(9S) structure. In this case, each set of cookies comprising
 375 a \fBDMA\fR window will satisfy the \fBDMA\fR attributes as described in the
 376 \fBddi_dma_attr\fR(9S) structure in all aspects. The driver should set up its
 377 \fBDMA\fR engine and perform one transfer for each set of cookies sufficient
 378 for its scatter/gather list, up to the number of cookies for this window,
 379 before advancing to the next window using \fBddi_dma_getwin\fR(9F).