1ddi_dma_attr(9S) Data Structures for Drivers ddi_dma_attr(9S)
2
6 ddi_dma_attr - DMA attributes structure
7
9 #include <sys/ddidmareq.h>
10
13 Solaris DDI specific (Solaris DDI)
14
16 A ddi_dma_attr_t structure describes device- and DMA engine-specific
17 attributes necessary to allocate DMA resources for a device. The driver
18 might have to extend the attributes with bus-specific information,
19 depending on the bus to which the device is connected.
20
22 uint_t dma_attr_version; /* version number */
23 uint64_t dma_attr_addr_lo; /* low DMA address range */
24 uint64_t dma_attr_addr_hi; /* high DMA address range */
25 uint64_t dma_attr_count_max; /* DMA counter register */
26 uint64_t dma_attr_align; /* DMA address alignment */
27 uint_t dma_attr_burstsizes; /* DMA burstsizes */
28 uint32_t dma_attr_minxfer; /* min effective DMA size */
29 uint64_t dma_attr_maxxfer; /* max DMA xfer size */
30 uint64_t dma_attr_seg; /* segment boundary */
31 int dma_attr_sgllen; /* s/g list length */
32 uint32_t dma_attr_granular; /* granularity of device */
33 uint_t dma_attr_flags; /* DMA transfer flags */
34 The dma_attr_version stores the version number of this DMA attribute
38 structure. It should be set to DMA_ATTR_V0.
39 The dma_attr_addr_lo and dma_attr_addr_hi fields specify the address
42 range the device's DMA engine can access. The dma_attr_addr_lo field
43 describes the inclusive lower 64-bit boundary. The dma_attr_addr_hi
44 describes the inclusive upper 64-bit boundary. The system ensures that
45 allocated DMA resources are within the range specified. See
46 ddi_dma_cookie(9S).
47 The dma_attr_count_max describes an inclusive upper bound for the
50 device's DMA counter register. For example, 0xFFFFFF would describe a
51 DMA engine with a 24-bit counter register. DMA resource allocation
52 functions have to break up a DMA object into multiple DMA cookies if
53 the size of the object exceeds the size of the DMA counter register.
54 The dma_attr_align specifies alignment requirements for allocated DMA
57 resources. This field can be used to force more restrictive alignment
58 than imposed by dma_attr_burstsizes or dma_attr_minxfer, such as align‐
59 ment at a page boundary. Most drivers set this field to 1, indicating
60 byte alignment.
61 The dma_attr_align only specifies alignment requirements for allocated
64 DMA resources. The buffer passed to ddi_dma_addr_bind_handle(9F) or
65 ddi_dma_buf_bind_handle(9F) must have an equally restrictive alignment
66 (see ddi_dma_mem_alloc(9F)).
67 The dma_attr_burstsizes field describes the possible burst sizes the
70 DMA engine of a device can accept. The format of the data sizes is
71 binary, encoded in terms of powers of two. When DMA resources are allo‐
72 cated, the system can modify the burstsizes value to reflect the system
73 limits. The driver must use the allowable burstsizes to program the DMA
74 engine. See ddi_dma_burstsizes(9F).
75 The dma_attr_minxfer field describes the minimum effective DMA access
78 size in units of bytes. DMA resources can be modified, depending on the
79 presence and use of I/O caches and write buffers between the DMA engine
80 and the memory object. This field is used to determine alignment and
81 padding requirements for ddi_dma_mem_alloc(9F).
82 The dma_attr_maxxfer field describes the maximum effective DMA access
85 size in units of bytes.
86 The dma_attr_seg field specifies segment boundary restrictions for
89 allocated DMA resources. The system allocates DMA resources for the
90 device so that the object does not span the segment boundary specified
91 by dma_attr_seg. For example, a value of 0xFFFF means DMA resources
92 must not cross a 64-Kbyte boundary. DMA resource allocation functions
93 might have to break up a DMA object into multiple DMA cookies to
94 enforce segment boundary restrictions. In this case, the transfer must
95 be performed using scatter-gather I/O or multiple DMA windows.
96 The dma_attr_sgllen field describes the length of the DMA scat‐
99 ter/gather list of a device. Possible values are as follows:
100 < 0 Device DMA engine is not constrained by the size, for example,
102 withDMA chaining.
103 = 0 Reserved.
106 = 1 Device DMA engine does not support scatter/gather such as third
109 party DMA.
110 > 1 Device DMA engine uses scatter/gather. The dma_attr_sgllen value
113 is the maximum number of entries in the list.
114 The dma_attr_granular field describes the granularity of the device
118 transfer size in units of bytes. When the system allocates DMA
119 resources, the size of a single segment is a multiple of the device
120 granularity. If dma_attr_sgllen is larger than 1 within a window, the
121 sum of the sizes for a subgroup of segments is a multiple of the device
122 granularity.
123 All driver requests for DMA resources must be a multiple of the granu‐
126 larity of the device transfer size.
127 The dma_attr_flags field can be set to a combination of:
130 DDI_DMA_FORCE_PHYSICAL
132 Some platforms, such as SPARC systems, support what is called
134 Direct Virtual Memory Access (DVMA). On these platforms, the device
135 is provided with a virtual address by the system in order to per‐
136 form the transfer. In this case, the underlying platform provides
137 an IOMMU, which translates accesses to these virtual addresses into
138 the proper physical addresses. Some of these platforms also support
139 DMA. DDI_DMA_FORCE_PHYSICAL indicates that the system should return
140 physical rather than virtual I/O addresses if the system supports
141 both. If the system does not support physical DMA, the return value
142 from ddi_dma_alloc_handle(9F) is DDI_DMA_BADATTR. In this case, the
143 driver has to clear DDI_DMA_FORCE_PHYSICAL and retry the operation.
144 DDI_DMA_FLAGERR
147 Using this value indicates that the driver is hardened: able to
149 cope with the incorrect results of DMA operations that might result
150 from an I/O fault. The value also indicates that the driver will
151 use ddi_fm_dma_err_get(9F) to check DMA handles for faults on a
152 regular basis.
153 If a DMA error is detected during a DMA access to an area mapped by
155 such a handle, the system should not panic if possible, but should
156 instead mark the DMA handle as having faulted.
157 This value is advisory: it tells the system that the driver can
159 continue in the face of I/O faults. It does not guarantee that the
160 system will not panic, as that depends on the nature of the fault
161 and the capabilities of the system. It is quite legitimate for an
162 implementation to ignore this flag and panic anyway.
163 DDI_DMA_RELAXED_ORDERING
166 This optional flag can be set if the DMA transactions associated
168 with this handle are not required to observe strong DMA write
169 ordering among themselves, nor with DMA write transactions of other
170 handles.
171 The flag allows the host bridge to transfer data to and from memory
173 more efficiently and might result in better DMA performance on some
174 platforms.
175 Drivers for devices with hardware support, such as marking the bus
177 transactions relaxed ordered, should not use this flag. Such driv‐
178 ers should use the hardware capability instead.
179
182 Example 1 Initializing the ddi_dma_attr_t Structure
183 Assume a device has the following DMA characteristics:
186 o Full 32-bit range addressable
188 o 24-bit DMA counter register
190 o Byte alignment
192 o 4- and 8-byte burst sizes support
194 o Minimum effective transfer size of 1 bytes
196 o 64 Mbyte minus 1 (26-bit) maximum transfer size limit
198 o Maximum segment size of 32 Kbyte
200 o 17 scatter/gather list elements
202 o 512-byte device transfer size granularity
204 The corresponding ddi_dma_attr_t structure is initialized as follows:
207 static ddi_dma_attr_t dma_attrs = {
210 DMA_ATTR_V0 /* version number */
211 (uint64_t)0x0, /* low address */
212 (uint64_t)0xffffffff, /* high address */
213 (uint64_t)0xffffff, /* DMA counter max */
214 (uint64_t)0x1 /* alignment */
215 0x0c, /* burst sizes */
216 0x1, /* minimum transfer size */
217 (uint64_t)0x3ffffff, /* maximum transfer size */
218 (uint64_t)0x7fff, /* maximum segment size */
219 17, /* scatter/gather list lgth */
220 512 /* granularity */
221 0 /* DMA flags */
222 };
223
226 See attributes(5) for descriptions of the following attributes:
227 ┌─────────────────────────────┬─────────────────────────────┐
232 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
233 ├─────────────────────────────┼─────────────────────────────┤
234 │Interface Stability │Committed │
235 └─────────────────────────────┴─────────────────────────────┘
236
238 attributes(5), ddi_dma_addr_bind_handle(9F), ddi_dma_alloc_handle(9F),
239 ddi_dma_buf_bind_handle(9F), ddi_dma_burstsizes(9F),
240 ddi_dma_mem_alloc(9F), ddi_dma_nextcookie(9F), ddi_fm_dma_err_get(9F),
241 ddi_dma_cookie(9S)
242 Writing Device Drivers
245SunOS 5.11 12 Feb 2009 ddi_dma_attr(9S)