share/man/man9f/ddi_dma_mem_alloc.9f

   1 '\" te
   2 .\"  Copyright (c) 2006, 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_MEM_ALLOC 9F "Jun 05, 2006"
   7 .SH NAME
   8 ddi_dma_mem_alloc \- allocate memory for DMA transfer
   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_mem_alloc\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBsize_t\fR \fIlength\fR,
  18      \fBddi_device_acc_attr_t *\fR\fIaccattrp\fR, \fBuint_t\fR \fIflags\fR,
  19      \fBint (*\fR\fIwaitfp\fR) (caddr_t), \fBcaddr_t\fR \fIarg\fR, \fBcaddr_t *\fR\fIkaddrp\fR,
  20      \fBsize_t *\fR\fIreal_length\fR, \fBddi_acc_handle_t *\fR\fIhandlep\fR);
  21 .fi
  22
  23 .SH INTERFACE LEVEL
  24 .sp
  25 .LP
  26 Solaris DDI specific (Solaris DDI).
  27 .SH PARAMETERS
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fIhandle\fR\fR
  32 .ad
  33 .RS 15n
  34 The \fBDMA\fR handle previously allocated by a call to
  35 \fBddi_dma_alloc_handle\fR(9F).
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIlength\fR\fR
  42 .ad
  43 .RS 15n
  44 The length in bytes of the desired allocation.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fIaccattrp\fR\fR
  51 .ad
  52 .RS 15n
  53 Pointer to a \fBddi_device_acc_attr()\fR structure of the device. See
  54 \fBddi_device_acc_attr\fR(9S). The value in \fBdevacc_attr_dataorder\fR is
  55 ignored in the current release. The value in \fBdevacc_attr_endian_flags\fR is
  56 meaningful on the SPARC architecture only.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIflags\fR\fR
  63 .ad
  64 .RS 15n
  65 Used to determine the data transfer mode and/or the cache attribute.
  66 .sp
  67 Possible values of the data transfer are:
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBDDI_DMA_STREAMING\fR\fR
  72 .ad
  73 .RS 22n
  74 Sequential, unidirectional, block-sized, and block-aligned transfers.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBDDI_DMA_CONSISTENT\fR\fR
  81 .ad
  82 .RS 22n
  83 Nonsequential transfers of small objects.
  84 .RE
  85
  86 Possible values of the cache attribute are:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBIOMEM_DATA_CACHED\fR\fR
  91 .ad
  92 .RS 28n
  93 The CPU can cache the data it fetches and push it to memory at a later time.
  94 This is the default attribute that is used if no cache attributes are
  95 specified.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBIOMEM_DATA_UC_WR_COMBINE\fR\fR
 102 .ad
 103 .RS 28n
 104 The CPU never caches the data, but writes can occur out of order or can be
 105 combined. Reordering is implied.
 106 .sp
 107 If \fBIOMEM_DATA_UC_WR_COMBINE\fR is specified but not supported,
 108 \fBIOMEM_DATA_UNCACHED\fR is used instead.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBIOMEM_DATA_UNCACHED\fR\fR
 115 .ad
 116 .RS 28n
 117 The CPU never caches data, but has uncacheable access to memory. Strict
 118 ordering is implied.
 119 .RE
 120
 121 The cache attributes are mutually exclusive. Any combination of the values
 122 leads to a failure. On the SPARC architecture, only \fBIOMEM_DATA_CACHED\fR is
 123 meaningful. Others lead to a failure.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fIwaitfp\fR\fR
 130 .ad
 131 .RS 15n
 132 The address of a function to call back later if resources are not available
 133 now. The callback function indicates how a caller wants to handle the
 134 possibility of resources not being available. If callback is set to
 135 \fBDDI_DMA_DONTWAIT\fR, the caller does not care if the allocation fails, and
 136 can handle an allocation failure appropriately. If callback is set to
 137 \fBDDI_DMA_SLEEP\fR, the caller wishes to have the allocation routines wait for
 138 resources to become available. If any other value is set and a DMA resource
 139 allocation fails, this value is assumed to be the address of a function to be
 140 called when resources become available. When the specified function is called,
 141 \fIarg\fR is passed to it as an argument. The specified callback function must
 142 return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or \fBDDI_DMA_CALLBACK_DONE\fR.
 143 \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the callback function attempted to
 144 allocate DMA resources but failed. In this case, the callback function is put
 145 back on a list to be called again  later. \fBDDI_DMA_CALLBACK_DONE\fR indicates
 146 that either the allocation of DMA resources was successful or the driver no
 147 longer wishes to retry. The callback function is called in interrupt context.
 148 Therefore, only system functions accessible from interrupt context are
 149 available.
 150 .sp
 151 The callback function must take whatever steps are necessary to protect its
 152 critical resources, data structures, queues, and so on.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fIarg\fR\fR
 159 .ad
 160 .RS 15n
 161 Argument to be passed to the callback function, if such a function is
 162 specified.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fIkaddrp\fR\fR
 169 .ad
 170 .RS 15n
 171 On successful return, \fIkaddrp\fR points to the allocated memory.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fIreal_length\fR\fR
 178 .ad
 179 .RS 15n
 180 The amount of memory, in bytes, allocated. Alignment and padding requirements
 181 may require \fBddi_dma_mem_alloc()\fR to allocate more memory than requested in
 182 \fIlength\fR.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fIhandlep\fR\fR
 189 .ad
 190 .RS 15n
 191 Pointer to a data access handle.
 192 .RE
 193
 194 .SH DESCRIPTION
 195 .sp
 196 .LP
 197 The \fBddi_dma_mem_alloc()\fR function allocates memory for \fBDMA\fR transfers
 198 to or from a device. The allocation will obey the alignment, padding
 199 constraints and device granularity as specified by the \fBDMA\fR attributes
 200 (see \fBddi_dma_attr\fR(9S)) passed to \fBddi_dma_alloc_handle\fR(9F) and the
 201 more restrictive attributes imposed by the system.
 202 .sp
 203 .LP
 204 The \fIflags\fR parameter should be set to \fBDDI_DMA_STREAMING\fR if the
 205 device is doing sequential, unidirectional, block-sized, and block-aligned
 206 transfers to or from memory. The alignment and padding constraints specified by
 207 the \fBminxfer\fR and \fBburstsizes\fR fields in the \fBDMA\fR attribute
 208 structure, \fBddi_dma_attr\fR(9S) (see \fBddi_dma_alloc_handle\fR(9F)) will be
 209 used to allocate the most effective hardware support for large transfers. For
 210 example, if an I/O transfer can be sped up by using an I/O cache, which has a
 211 minimum transfer of one cache line, \fBddi_dma_mem_alloc()\fR will align the
 212 memory at a cache line boundary and it will round up \fIreal_length\fR to a
 213 multiple of the cache line size.
 214 .sp
 215 .LP
 216 The \fIflags\fR parameter should be set to \fBDDI_DMA_CONSISTENT\fR if the
 217 device accesses memory randomly, or if synchronization steps using
 218 \fBddi_dma_sync\fR(9F) need to be as efficient as possible. I/O parameter
 219 blocks used for communication between a device and a driver should be allocated
 220 using \fBDDI_DMA_CONSISTENT\fR.
 221 .sp
 222 .LP
 223 The device access attributes are specified in the location pointed by the
 224 \fIaccattrp\fR argument (see \fBddi_device_acc_attr\fR(9S)).
 225 .sp
 226 .LP
 227 The data access handle is returned in \fIhandlep\fR. \fIhandlep\fR is opaque -
 228 drivers may not attempt to interpret its value. To access the data content, the
 229 driver must invoke \fBddi_get8\fR(9F) or \fBddi_put8\fR(9F) (depending on the
 230 data transfer direction) with the data access handle.
 231 .sp
 232 .LP
 233 \fBDMA\fR resources must be established before performing a \fBDMA\fR transfer
 234 by passing \fIkaddrp\fR and \fIreal_length\fR as returned from
 235 \fBddi_dma_mem_alloc()\fR and the flag \fBDDI_DMA_STREAMING\fR or
 236 \fBDDI_DMA_CONSISTENT\fR to \fBddi_dma_addr_bind_handle\fR(9F). In addition, to
 237 ensure the consistency of a memory object shared between the \fBCPU\fR and the
 238 device after a \fBDMA\fR transfer, explicit synchronization steps using
 239 \fBddi_dma_sync\fR(9F) or \fBddi_dma_unbind_handle\fR(9F) are required.
 240 .SH RETURN VALUES
 241 .sp
 242 .LP
 243 The \fBddi_dma_mem_alloc()\fR function returns:
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBDDI_SUCCESS\fR\fR
 248 .ad
 249 .RS 15n
 250 Memory successfully allocated.
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fBDDI_FAILURE\fR\fR
 257 .ad
 258 .RS 15n
 259 Memory allocation failed.
 260 .RE
 261
 262 .SH CONTEXT
 263 .sp
 264 .LP
 265 The \fBddi_dma_mem_alloc()\fR function can be called from user, interrupt, or
 266 kernel context except when \fIwaitfp\fR is set to \fBDDI_DMA_SLEEP\fR, in which
 267 case it cannot be called from interrupt context.
 268 .SH SEE ALSO
 269 .sp
 270 .LP
 271 \fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
 272 \fBddi_dma_mem_free\fR(9F), \fBddi_dma_sync\fR(9F),
 273 \fBddi_dma_unbind_handle\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F),
 274 \fBddi_device_acc_attr\fR(9S), \fBddi_dma_attr\fR(9S)
 275 .sp
 276 .LP
 277 \fIWriting Device Drivers\fR
 278 .SH WARNINGS
 279 .sp
 280 .LP
 281 If \fBDDI_NEVERSWAP_ACC\fR is specified, memory can be used for any purpose;
 282 but if either endian mode is specified, you must use \fBddi_get/put*\fR and
 283 never anything else.