1ddi_dma_mem_alloc(9F) Kernel Functions for Drivers ddi_dma_mem_alloc(9F)
2
6 ddi_dma_mem_alloc - allocate memory for DMA transfer
7
9 #include <sys/ddi.h>
10 #include <sys/sunddi.h>
11 int ddi_dma_mem_alloc(ddi_dma_handle_t handle, size_t length,
15 ddi_device_acc_attr_t *accattrp, uint_t flags,
16 int (*waitfp) (caddr_t), caddr_t arg, caddr_t *kaddrp,
17 size_t *real_length, ddi_acc_handle_t *handlep);
18
21 Solaris DDI specific (Solaris DDI).
22
24 handle The DMA handle previously allocated by a call to
25 ddi_dma_alloc_handle(9F).
26 length The length in bytes of the desired allocation.
29 accattrp Pointer to a ddi_device_acc_attr() structure of the
32 device. See ddi_device_acc_attr(9S). The value in
33 devacc_attr_dataorder is ignored in the current release.
34 The value in devacc_attr_endian_flags is meaningful on
35 the SPARC architecture only.
36 flags Used to determine the data transfer mode and/or the
39 cache attribute.
40 Possible values of the data transfer are:
42 DDI_DMA_STREAMING Sequential, unidirectional, block-
44 sized, and block-aligned trans‐
45 fers.
46 DDI_DMA_CONSISTENT Nonsequential transfers of small
49 objects.
50 Possible values of the cache attribute are:
52 IOMEM_DATA_CACHED The CPU can cache the data
54 it fetches and push it to
55 memory at a later time. This
56 is the default attribute
57 that is used if no cache
58 attributes are specified.
59 IOMEM_DATA_UC_WR_COMBINE The CPU never caches the
62 data, but writes can occur
63 out of order or can be com‐
64 bined. Reordering is
65 implied.
66 If IOMEM_DATA_UC_WR_COMBINE
68 is specified but not sup‐
69 ported, IOMEM_DATA_UNCACHED
70 is used instead.
71 IOMEM_DATA_UNCACHED The CPU never caches data,
74 but has uncacheable access
75 to memory. Strict ordering
76 is implied.
77 The cache attributes are mutually exclusive. Any combi‐
79 nation of the values leads to a failure. On the SPARC
80 architecture, only IOMEM_DATA_CACHED is meaningful. Oth‐
81 ers lead to a failure.
82 waitfp The address of a function to call back later if
85 resources are not available now. The callback function
86 indicates how a caller wants to handle the possibility
87 of resources not being available. If callback is set to
88 DDI_DMA_DONTWAIT, the caller does not care if the allo‐
89 cation fails, and can handle an allocation failure
90 appropriately. If callback is set to DDI_DMA_SLEEP, the
91 caller wishes to have the allocation routines wait for
92 resources to become available. If any other value is set
93 and a DMA resource allocation fails, this value is
94 assumed to be the address of a function to be called
95 when resources become available. When the specified
96 function is called, arg is passed to it as an argument.
97 The specified callback function must return either
98 DDI_DMA_CALLBACK_RUNOUT or DDI_DMA_CALLBACK_DONE.
99 DDI_DMA_CALLBACK_RUNOUT indicates that the callback
100 function attempted to allocate DMA resources but failed.
101 In this case, the callback function is put back on a
102 list to be called again later. DDI_DMA_CALLBACK_DONE
103 indicates that either the allocation of DMA resources
104 was successful or the driver no longer wishes to retry.
105 The callback function is called in interrupt context.
106 Therefore, only system functions accessible from inter‐
107 rupt context are available.
108 The callback function must take whatever steps are nec‐
110 essary to protect its critical resources, data struc‐
111 tures, queues, and so on.
112 arg Argument to be passed to the callback function, if such
115 a function is specified.
116 kaddrp On successful return, kaddrp points to the allocated
119 memory.
120 real_length The amount of memory, in bytes, allocated. Alignment and
123 padding requirements may require ddi_dma_mem_alloc() to
124 allocate more memory than requested in length.
125 handlep Pointer to a data access handle.
128
131 The ddi_dma_mem_alloc() function allocates memory for DMA transfers to
132 or from a device. The allocation will obey the alignment, padding con‐
133 straints and device granularity as specified by the DMA attributes (see
134 ddi_dma_attr(9S)) passed to ddi_dma_alloc_handle(9F) and the more
135 restrictive attributes imposed by the system.
136 The flags parameter should be set to DDI_DMA_STREAMING if the device is
139 doing sequential, unidirectional, block-sized, and block-aligned trans‐
140 fers to or from memory. The alignment and padding constraints specified
141 by the minxfer and burstsizes fields in the DMA attribute structure,
142 ddi_dma_attr(9S) (see ddi_dma_alloc_handle(9F)) will be used to allo‐
143 cate the most effective hardware support for large transfers. For exam‐
144 ple, if an I/O transfer can be sped up by using an I/O cache, which has
145 a minimum transfer of one cache line, ddi_dma_mem_alloc() will align
146 the memory at a cache line boundary and it will round up real_length to
147 a multiple of the cache line size.
148 The flags parameter should be set to DDI_DMA_CONSISTENT if the device
151 accesses memory randomly, or if synchronization steps using
152 ddi_dma_sync(9F) need to be as efficient as possible. I/O parameter
153 blocks used for communication between a device and a driver should be
154 allocated using DDI_DMA_CONSISTENT.
155 The device access attributes are specified in the location pointed by
158 the accattrp argument (see ddi_device_acc_attr(9S)).
159 The data access handle is returned in handlep. handlep is opaque -
162 drivers may not attempt to interpret its value. To access the data con‐
163 tent, the driver must invoke ddi_get8(9F) or ddi_put8(9F) (depending on
164 the data transfer direction) with the data access handle.
165 DMA resources must be established before performing a DMA transfer by
168 passing kaddrp and real_length as returned from ddi_dma_mem_alloc() and
169 the flag DDI_DMA_STREAMING or DDI_DMA_CONSISTENT to
170 ddi_dma_addr_bind_handle(9F). In addition, to ensure the consistency of
171 a memory object shared between the CPU and the device after a DMA
172 transfer, explicit synchronization steps using ddi_dma_sync(9F) or
173 ddi_dma_unbind_handle(9F) are required.
174
176 The ddi_dma_mem_alloc() function returns:
177 DDI_SUCCESS Memory successfully allocated.
179 DDI_FAILURE Memory allocation failed.
182
185 The ddi_dma_mem_alloc() function can be called from user, interrupt, or
186 kernel context except when waitfp is set to DDI_DMA_SLEEP, in which
187 case it cannot be called from interrupt context.
188
190 ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
191 ddi_dma_mem_free(9F), ddi_dma_sync(9F), ddi_dma_unbind_handle(9F),
192 ddi_get8(9F), ddi_put8(9F), ddi_device_acc_attr(9S), ddi_dma_attr(9S)
193 Writing Device Drivers
196
198 If DDI_NEVERSWAP_ACC is specified, memory can be used for any purpose;
199 but if either endian mode is specified, you must use ddi_get/put* and
200 never anything else.
201SunOS 5.11 05 Jun 2006 ddi_dma_mem_alloc(9F)