| blob | c4c100bf94af9ad9f7eeee3191bec8cc596a06da |
1 '\" te
2 .\" Copyright (c) 2009, 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_ATTR 9S "Feb 12, 2009"
7 .SH NAME
8 ddi_dma_attr \- DMA attributes structure
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/ddidmareq.h>
13 .fi
15 .SH INTERFACE LEVEL
16 .sp
17 .LP
18 Solaris DDI specific (Solaris DDI)
19 .SH DESCRIPTION
20 .sp
21 .LP
22 A \fBddi_dma_attr_t\fR structure describes device- and \fBDMA\fR
23 engine-specific attributes necessary to allocate \fBDMA\fR resources for a
24 device. The driver might have to extend the attributes with bus-specific
25 information, depending on the bus to which the device is connected.
26 .SH STRUCTURE MEMBERS
27 .sp
28 .in +2
29 .nf
30 uint_t dma_attr_version; /* version number */
31 uint64_t dma_attr_addr_lo; /* low DMA address range */
32 uint64_t dma_attr_addr_hi; /* high DMA address range */
33 uint64_t dma_attr_count_max; /* DMA counter register */
34 uint64_t dma_attr_align; /* DMA address alignment */
35 uint_t dma_attr_burstsizes; /* DMA burstsizes */
36 uint32_t dma_attr_minxfer; /* min effective DMA size */
37 uint64_t dma_attr_maxxfer; /* max DMA xfer size */
38 uint64_t dma_attr_seg; /* segment boundary */
39 int dma_attr_sgllen; /* s/g list length */
40 uint32_t dma_attr_granular; /* granularity of device */
41 uint_t dma_attr_flags; /* DMA transfer flags */
42 \fI\fR
43 .fi
44 .in -2
46 .sp
47 .LP
48 The \fBdma_attr_version\fR stores the version number of this \fBDMA\fR
49 attribute structure. It should be set to \fBDMA_ATTR_V0\fR.
50 .sp
51 .LP
52 The \fBdma_attr_addr_lo\fR and \fBdma_attr_addr_hi\fR fields specify the
53 address range the device's \fBDMA\fR engine can access. The
54 \fBdma_attr_addr_lo\fR field describes the inclusive lower 64-bit boundary. The
55 \fBdma_attr_addr_hi\fR describes the inclusive upper 64-bit boundary. The
56 system ensures that allocated \fBDMA\fR resources are within the range
57 specified. See \fBddi_dma_cookie\fR(9S).
58 .sp
59 .LP
60 The \fBdma_attr_count_max\fR describes an inclusive upper bound for the
61 device's \fBDMA\fR counter register. For example, \fB0xFFFFFF\fR would describe
62 a \fBDMA\fR engine with a 24-bit counter register. \fBDMA\fR resource
63 allocation functions have to break up a \fBDMA\fR object into multiple
64 \fBDMA\fR cookies if the size of the object exceeds the size of the \fBDMA\fR
65 counter register.
66 .sp
67 .LP
68 The \fBdma_attr_align\fR specifies alignment requirements for allocated
69 \fBDMA\fR resources. This field can be used to force more restrictive alignment
70 than imposed by \fBdma_attr_burstsizes\fR or \fBdma_attr_minxfer\fR, such as
71 alignment at a page boundary. Most drivers set this field to 1, indicating byte
72 alignment.
73 .sp
74 .LP
75 The \fBdma_attr_align\fR only specifies alignment requirements for allocated
76 \fBDMA\fR resources. The buffer passed to \fBddi_dma_addr_bind_handle\fR(9F) or
77 \fBddi_dma_buf_bind_handle\fR(9F) must have an equally restrictive alignment
78 (see \fBddi_dma_mem_alloc\fR(9F)).
79 .sp
80 .LP
81 The \fBdma_attr_burstsizes\fR field describes the possible burst sizes the
82 \fBDMA\fR engine of a device can accept. The format of the data sizes is
83 binary, encoded in terms of powers of two. When \fBDMA\fR resources are
84 allocated, the system can modify the \fBburstsizes\fR value to reflect the
85 system limits. The driver must use the allowable \fBburstsizes\fR to program
86 the \fBDMA\fR engine. See \fBddi_dma_burstsizes\fR(9F).
87 .sp
88 .LP
89 The \fBdma_attr_minxfer\fR field describes the minimum effective \fBDMA\fR
90 access size in units of bytes. \fBDMA\fR resources can be modified, depending
91 on the presence and use of \fBI/O\fR caches and write buffers between the
92 \fBDMA\fR engine and the memory object. This field is used to determine
93 alignment and padding requirements for \fBddi_dma_mem_alloc\fR(9F).
94 .sp
95 .LP
96 The \fBdma_attr_maxxfer\fR field describes the maximum effective \fBDMA\fR
97 access size in units of bytes.
98 .sp
99 .LP
100 The \fBdma_attr_seg\fR field specifies segment boundary restrictions for
101 allocated \fBDMA\fR resources. The system allocates \fBDMA\fR resources for the
102 device so that the object does not span the segment boundary specified by
103 \fBdma_attr_seg\fR. For example, a value of \fB0xFFFF\fR means \fBDMA\fR
104 resources must not cross a 64-Kbyte boundary. \fBDMA\fR resource allocation
105 functions might have to break up a \fBDMA\fR object into multiple \fBDMA\fR
106 cookies to enforce segment boundary restrictions. In this case, the transfer
107 must be performed using scatter-gather \fBI/O\fR or multiple \fBDMA\fR windows.
108 .sp
109 .LP
110 The \fBdma_attr_sgllen\fR field describes the length of the \fBDMA\fR
111 scatter/gather list of a device. Possible values are as follows:
112 .sp
113 .ne 2
114 .na
115 \fB\fB< 0\fR\fR
116 .ad
117 .RS 7n
118 Device \fBDMA\fR engine is not constrained by the size, for example,
119 with\fBDMA\fR chaining.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB= 0\fR\fR
126 .ad
127 .RS 7n
128 Reserved.
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB\fB= 1\fR\fR
135 .ad
136 .RS 7n
137 Device \fBDMA\fR engine does not support scatter/gather such as third party
138 \fBDMA\fR.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fB> 1\fR\fR
145 .ad
146 .RS 7n
147 Device \fBDMA\fR engine uses scatter/gather. The \fBdma_attr_sgllen\fR value is
148 the maximum number of entries in the list.
149 .RE
151 .sp
152 .LP
153 The \fBdma_attr_granular\fR field describes the granularity of the device
154 transfer size in units of bytes. When the system allocates \fBDMA\fR resources,
155 the size of a single segment is a multiple of the device granularity. If
156 \fBdma_attr_sgllen\fR is larger than \fB1\fR within a window, the sum of the
157 sizes for a subgroup of segments is a multiple of the device granularity.
158 .sp
159 .LP
160 All driver requests for \fBDMA\fR resources must be a multiple of the
161 granularity of the device transfer size.
162 .sp
163 .LP
164 The \fBdma_attr_flags\fR field can be set to a combination of:
165 .sp
166 .ne 2
167 .na
168 \fB\fBDDI_DMA_FORCE_PHYSICAL\fR\fR
169 .ad
170 .sp .6
171 .RS 4n
172 Some platforms, such as SPARC systems, support what is called Direct Virtual
173 Memory Access (\fBDVMA\fR). On these platforms, the device is provided with a
174 virtual address by the system in order to perform the transfer. In this case,
175 the underlying platform provides an \fIIOMMU\fR, which translates accesses to
176 these virtual addresses into the proper physical addresses. Some of these
177 platforms also support \fBDMA.\fR \fBDDI_DMA_FORCE_PHYSICAL\fR indicates that
178 the system should return physical rather than virtual \fBI/O\fR addresses if
179 the system supports both. If the system does not support physical \fBDMA\fR,
180 the return value from \fBddi_dma_alloc_handle\fR(9F) is \fBDDI_DMA_BADATTR.\fR
181 In this case, the driver has to clear \fBDDI_DMA_FORCE_PHYSICAL\fR and retry
182 the operation.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBDDI_DMA_FLAGERR\fR\fR
189 .ad
190 .sp .6
191 .RS 4n
192 Using this value indicates that the driver is hardened: able to cope with the
193 incorrect results of \fBDMA\fR operations that might result from an \fBI/O\fR
194 fault. The value also indicates that the driver will use
195 \fBddi_fm_dma_err_get\fR(9F) to check \fBDMA\fR handles for faults on a regular
196 basis.
197 .sp
198 If a \fBDMA\fR error is detected during a \fBDMA\fR access to an area mapped by
199 such a handle, the system should not panic if possible, but should instead mark
200 the \fBDMA\fR handle as having faulted.
201 .sp
202 This value is advisory: it tells the system that the driver can continue in the
203 face of \fBI/O\fR faults. It does not guarantee that the system will not panic,
204 as that depends on the nature of the fault and the capabilities of the system.
205 It is quite legitimate for an implementation to ignore this flag and panic
206 anyway.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fBDDI_DMA_RELAXED_ORDERING\fR\fR
213 .ad
214 .sp .6
215 .RS 4n
216 This optional flag can be set if the \fBDMA\fR transactions associated with
217 this handle are not required to observe strong \fBDMA\fR write ordering among
218 themselves, nor with \fBDMA\fR write transactions of other handles.
219 .sp
220 The flag allows the host bridge to transfer data to and from memory more
221 efficiently and might result in better \fBDMA\fR performance on some platforms.
222 .sp
223 Drivers for devices with hardware support, such as marking the bus transactions
224 relaxed ordered, should not use this flag. Such drivers should use the hardware
225 capability instead.
226 .RE
228 .SH EXAMPLES
229 .LP
230 \fBExample 1 \fRInitializing the \fBddi_dma_attr_t\fR Structure
231 .sp
232 .LP
233 Assume a device has the following \fBDMA\fR characteristics:
234 .RS +4
235 .TP
236 .ie t \(bu
237 .el o
238 Full 32-bit range addressable
239 .RE
240 .RS +4
241 .TP
242 .ie t \(bu
243 .el o
244 24-bit DMA counter register
245 .RE
246 .RS +4
247 .TP
248 .ie t \(bu
249 .el o
250 Byte alignment
251 .RE
252 .RS +4
253 .TP
254 .ie t \(bu
255 .el o
256 4- and 8-byte burst sizes support
257 .RE
258 .RS +4
259 .TP
260 .ie t \(bu
261 .el o
262 Minimum effective transfer size of 1 bytes
263 .RE
264 .RS +4
265 .TP
266 .ie t \(bu
267 .el o
268 64 Mbyte minus 1 (26-bit) maximum transfer size limit
269 .RE
270 .RS +4
271 .TP
272 .ie t \(bu
273 .el o
274 Maximum segment size of 32 Kbyte
275 .RE
276 .RS +4
277 .TP
278 .ie t \(bu
279 .el o
280 17 scatter/gather list elements
281 .RE
282 .RS +4
283 .TP
284 .ie t \(bu
285 .el o
286 512-byte device transfer size granularity
287 .RE
288 .sp
289 .LP
290 The corresponding \fBddi_dma_attr_t\fR structure is initialized as follows:
292 .sp
293 .in +2
294 .nf
295 static ddi_dma_attr_t dma_attrs = {
296 DMA_ATTR_V0 /* version number */
297 (uint64_t)0x0, /* low address */
298 (uint64_t)0xffffffff, /* high address */
299 (uint64_t)0xffffff, /* DMA counter max */
300 (uint64_t)0x1 /* alignment */
301 0x0c, /* burst sizes */
302 0x1, /* minimum transfer size */
303 (uint64_t)0x3ffffff, /* maximum transfer size */
304 (uint64_t)0x7fff, /* maximum segment size */
305 17, /* scatter/gather list lgth */
306 512 /* granularity */
307 0 /* DMA flags */
308 };
309 .fi
310 .in -2
312 .SH ATTRIBUTES
313 .sp
314 .LP
315 See \fBattributes\fR(5) for descriptions of the following attributes:
316 .sp
318 .sp
319 .TS
320 box;
321 c | c
322 l | l .
323 ATTRIBUTE TYPE ATTRIBUTE VALUE
324 _
325 Interface Stability Committed
326 .TE
328 .SH SEE ALSO
329 .sp
330 .LP
331 \fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F),
332 \fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F),
333 \fBddi_dma_burstsizes\fR(9F), \fBddi_dma_mem_alloc\fR(9F),
334 \fBddi_dma_nextcookie\fR(9F), \fBddi_fm_dma_err_get\fR(9F),
335 \fBddi_dma_cookie\fR(9S)
336 .sp
337 .LP
338 \fIWriting Device Drivers\fR