| blob | c09003ececc1f75c270dae143143631c58f16893 |
1 .\"
2 .\" Copyright (c) 2002, 2003, 2004 The DragonFly Project. All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to The DragonFly Project
5 .\" by Hiten Pandya <hmp@backplane.com>.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in
15 .\" the documentation and/or other materials provided with the
16 .\" distribution.
17 .\" 3. Neither the name of The DragonFly Project nor the names of its
18 .\" contributors may be used to endorse or promote products derived
19 .\" from this software without specific, prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
35 .\" All rights reserved.
36 .\"
37 .\" This code is derived from software contributed to The NetBSD Foundation
38 .\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
39 .\" NASA Ames Research Center.
40 .\"
41 .\" Redistribution and use in source and binary forms, with or without
42 .\" modification, are permitted provided that the following conditions
43 .\" are met:
44 .\" 1. Redistributions of source code must retain the above copyright
45 .\" notice, this list of conditions and the following disclaimer.
46 .\" 2. Redistributions in binary form must reproduce the above copyright
47 .\" notice, this list of conditions and the following disclaimer in the
48 .\" documentation and/or other materials provided with the distribution.
49 .\" 3. All advertising materials mentioning features or use of this software
50 .\" must display the following acknowledgment:
51 .\" This product includes software developed by the NetBSD
52 .\" Foundation, Inc. and its contributors.
53 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
54 .\" contributors may be used to endorse or promote products derived
55 .\" from this software without specific prior written permission.
56 .\"
57 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
58 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
59 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
60 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
61 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
62 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
63 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
64 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
65 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
67 .\" POSSIBILITY OF SUCH DAMAGE.
68 .\"
69 .\" $FreeBSD: /repoman/r/ncvs/src/share/man/man9/bus_dma.9,v 1.7 2003/07/27 14:05:29 mux Exp $
70 .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $
71 .\"
72 .Dd January 11, 2010
73 .Dt BUS_DMA 9
74 .Os
75 .Sh NAME
76 .Nm bus_dma ,
77 .Nm bus_dma_tag_create ,
78 .Nm bus_dma_tag_destroy ,
79 .Nm bus_dmamap_create ,
80 .Nm bus_dmamap_destroy ,
81 .Nm bus_dmamap_load ,
82 .Nm bus_dmamap_load_mbuf ,
83 .Nm bus_dmamap_load_mbuf_segment ,
84 .Nm bus_dmamap_load_mbuf_defrag ,
85 .Nm bus_dmamap_load_uio ,
86 .Nm bus_dmamap_unload ,
87 .Nm bus_dmamap_sync ,
88 .Nm bus_dmamem_alloc ,
89 .Nm bus_dmamem_coherent ,
90 .Nm bus_dmamem_coherent_any ,
91 .Nm bus_dmamem_free
92 .Nd Bus and Machine Independent DMA Mapping Interface
93 .Sh SYNOPSIS
94 .In sys/bus.h
95 .Ft int
96 .Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \
97 "bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \
98 "bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \
99 "int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat"
100 .Ft int
101 .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
102 .Ft int
103 .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
104 .Ft int
105 .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map"
106 .Ft int
107 .Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \
108 "bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \
109 "int flags"
110 .Ft int
111 .Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \
112 "struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
113 "int flags"
114 .Ft int
115 .Fn bus_dmamap_load_mbuf_segment "bus_dma_tag_t dmat" "bus_dmamap_t map" \
116 "struct mbuf *mbuf" "bus_dma_segment_t *segs" "int maxsegs" "int *nsegs" \
117 "int flags"
118 .Ft int
119 .Fn bus_dmamap_load_mbuf_defrag "bus_dma_tag_t dmat" "bus_dmamap_t map" \
120 "struct mbuf **mbuf" "bus_dma_segment_t *segs" "int maxsegs" "int *nsegs" \
121 "int flags"
122 .Ft int
123 .Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \
124 "struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
125 "int flags"
126 .Ft int
127 .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \
128 "int flags" "bus_dmamap_t *mapp"
129 .Ft int
130 .Fn bus_dmamem_coherent "bus_dma_tag_t parent" "bus_size_t alignment" \
131 "bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \
132 "bus_size_t maxsize" "int flags" "bus_dmamem_t *dmem"
133 .Ft void *
134 .Fn bus_dmamem_coherent_any "bus_dma_tag_t parent" "bus_size_t alignment" \
135 "bus_size_t maxsize" "int flags" "bus_dma_tag_t *dtag" "bus_dmamap_t *dmap" \
136 "bus_addr_t *busaddr"
137 .Ft void
138 .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map"
139 .Ft void
140 .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \
141 "bus_dmasync_op_t op"
142 .Ft void
143 .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \
144 "bus_dmamap_t map"
145 .Sh DESCRIPTION
146 Direct Memory Access (DMA) is a method of transferring data
147 without involving the CPU, thus providing higher performance.
148 A DMA transaction can be achieved between device to memory,
149 device to device, or memory to memory.
150 .Pp
151 The
152 .Nm
153 API is a bus, device, and machine-independent (MI) interface to
154 DMA mechanisms.
155 It provides the client with flexibility and simplicity by
156 abstracting machine dependent issues like setting up
157 DMA mappings, handling cache issues, bus specific features
158 and limitations.
159 .Sh STRUCTURES AND TYPES
160 .Bl -tag -width compact
161 .It Vt bus_dma_tag_t
162 A machine-dependent (MD) opaque type that describes the
163 characteristics of DMA transactions.
164 DMA tags are organized into a hierarchy, with each child
165 tag inheriting the restrictions of its parent.
166 This allows all devices along the path of DMA transactions
167 to contribute to the constraints of those transactions.
168 .It Vt bus_dma_filter_t
169 Client specified address filter having the format:
170 .Bl -tag -width compact
171 .It Ft int
172 .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr"
173 .El
174 .sp
175 Address filters can be specified during tag creation to allow
176 for devices who's DMA address restrictions cannot be specified
177 by a single window.
178 The
179 .Fa filtarg
180 is client specified during tag creation to be passed to all
181 invocations of the callback.
182 The
183 .Fa testaddr
184 argument contains a potential starting address of a DMA mapping.
185 The filter function operates on the set of addresses from
186 .Fa testaddr
187 to
188 .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
189 inclusive.
190 The filter function should return zero for any mapping in this range
191 that can be accommodated by the device and non-zero otherwise.
192 .It Vt bus_dma_segment_t
193 A machine-dependent type that describes individual
194 DMA segments.
195 .Bd -literal
196 bus_addr_t ds_addr;
197 bus_size_t ds_len;
198 .Ed
199 .sp
200 The
201 .Fa ds_addr
202 field contains the device visible address of the DMA segment, and
203 .Fa ds_len
204 contains the length of the DMA segment.
205 Although the DMA segments returned by a mapping call will adhere to
206 all restrictions necessary for a successful DMA operation, some conversion
207 (e.g. a conversion from host byte order to the device's byte order) is
208 almost always required when presenting segment information to the device.
209 .It Vt bus_dmamap_t
210 A machine-dependent opaque type describing an individual mapping.
211 Multiple DMA maps can be associated with one DMA tag.
212 .It Vt bus_dmamem_t
213 A machine-dependent type that describes DMA memory created by
214 .Fn bus_dmamem_coherent .
215 .Bd -literal
216 bus_dma_tag_t dmem_tag;
217 bus_dmamap_t dmem_map;
218 void *dmem_addr;
219 bus_addr_t dmem_busaddr;
220 .Ed
221 .sp
222 The
223 .Fa dmem_tag
224 field contains the DMA tag of the DMA memory and
225 .Fa dmem_map
226 field contains the DMA map of the DMA memory.
227 The
228 .Fa dmem_addr
229 field points to the allocated DMA memory in kernel virtual address space.
230 The
231 .Fa dmem_busaddr
232 field contains the device visible address of the DMA memory.
233 .It Vt bus_dmamap_callback_t
234 Client specified callback for receiving mapping information resulting from
235 the load of a
236 .Vt bus_dmamap_t
237 via
238 .Fn bus_dmamap_load .
239 Callbacks are of the format:
240 .Bl -tag -width compact
241 .It Ft void
242 .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \
243 "int nseg" "int error"
244 .El
245 .sp
246 The
247 .Fa callback_arg
248 is the callback argument passed to dmamap load functions.
249 The
250 .Fa segs
251 and
252 .Fa nseg
253 parameters describe an array of
254 .Vt bus_dma_segment_t
255 structures that represent the mapping.
256 This array is only valid within the scope of the callback function.
257 The success or failure of the mapping is indicated by the
258 .Fa error
259 parameter.
260 More information on the use of callbacks can be found in the
261 description of the individual dmamap load functions.
262 .It Vt bus_dmamap_callback2_t
263 Client specified callback for receiving mapping information resulting from
264 the load of a
265 .Vt bus_dmamap_t
266 via
267 .Fn bus_dmamap_load_uio
268 or
269 .Fn bus_dmamap_load_mbuf .
270 .sp
271 Callback2s are of the format:
272 .Bl -tag -width compact
273 .It Ft void
274 .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \
275 "int nseg" "bus_size_t mapsize" "int error"
276 .El
277 .sp
278 Callback2's behavior is the same as
279 .Vt bus_dmamap_callback_t
280 with the addition that the length of the data mapped is provided via
281 .Fa mapsize .
282 .It Vt bus_dmasync_op_t
283 Memory synchronization operation specifier.
284 Bus DMA requires explicit synchronization of memory with it's device
285 visible mapping in order to guarantee memory coherency.
286 The
287 .Vt bus_dmasync_op_t
288 allows the type of DMA operation that will be or has been performed
289 to be communicated to the system so that the correct coherency measures
290 are taken.
291 All operations specified below are performed from the DMA engine's
292 point of view:
293 .Bl -tag -width BUS_DMASYNC_POSTWRITE
294 .It Dv BUS_DMASYNC_PREREAD
295 Perform any synchronization required after an update of memory by the CPU
296 but prior to DMA read operations.
297 .It Dv BUS_DMASYNC_PREWRITE
298 Perform any synchronization required after an update of memory by the CPU
299 but prior to DMA write operations.
300 .It Dv BUS_DMASYNC_POSTREAD
301 Perform any synchronization required after DMA read operations, but prior
302 to CPU access of the memory.
303 .It Dv BUS_DMASYNC_POSTWRITE
304 Perform any synchronization required after DMA write operations, but prior
305 to CPU access of the memory.
306 .El
307 .El
308 .sp
309 .Sh FUNCTIONS
310 .Bl -tag -width compact
311 .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \
312 "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \
313 "flags" "*dmat"
314 Allocates a device specific DMA tag, and initializes it according to
315 the arguments provided:
316 .Bl -tag -width *filtfuncarg -compact
317 .It Fa parent
318 Indicates restrictions between the parent bridge, CPU memory, and the
319 device.
320 May be NULL, if no DMA restrictions are to be inherited.
321 .It Fa alignment
322 Alignment constraint, in bytes, of any mappings created using this tag.
323 The alignment must be a power of 2.
324 Hardware that can DMA starting at any address would specify
325 .Em 1
326 for byte alignment.
327 Hardware requiring DMA transfers to start on a multiple of 4K
328 would specify
329 .Em 4096 .
330 .It Fa boundary
331 Boundary constraint, in bytes, of the target DMA memory region.
332 The boundary indicates the set of addresses, all multiples of the
333 boundary argument, that cannot be crossed by a single
334 .Vt bus_dma_segment_t .
335 The boundary must be either a power of 2 or 0.
336 .Ql 0
337 indicates that there are no boundary restrictions.
338 .It Fa lowaddr
339 .It Fa highaddr
340 Bounds of the window of bus address space that
341 .Em cannot
342 be directly accessed by the device.
343 The window contains all address greater than lowaddr and
344 less than or equal to highaddr.
345 For example, a device incapable of DMA above 4GB, would specify
346 a highaddr of
347 .Dv BUS_SPACE_MAXADDR
348 and a lowaddr of
349 .Dv BUS_SPACE_MAXADDR_32BIT .
350 Similarly a device that can only dma to addresses bellow 16MB would
351 specify a highaddr of
352 .Dv BUS_SPACE_MAXADDR
353 and a lowaddr of
354 .Dv BUS_SPACE_MAXADDR_24BIT .
355 Some implementations requires that some region of device visible
356 address space, overlapping available host memory, be outside the
357 window.
358 This area of
359 .Ql safe memory
360 is used to bounce requests that would otherwise conflict with
361 the exclusion window.
362 .It Fa filtfunc
363 Optional filter function (may be NULL) to be called for any attempt to
364 map memory into the window described by
365 .Fa lowaddr
366 and
367 .Fa highaddr .
368 A filter function is only required when the single window described
369 by
370 .Fa lowaddr
371 and
372 .Fa highaddr
373 cannot adequately describe the constraints of the device.
374 The filter function will be called for every machine page
375 that overlaps the exclusion window.
376 .It Fa filtfuncarg
377 Argument passed to all calls to the filter function for this tag.
378 May be NULL.
379 .It Fa maxsize
380 Maximum size, in bytes, of the sum of all segment lengths in a given
381 DMA mapping associated with this tag.
382 .It Fa nsegments
383 Number of discontinuities (scatter/gather segments) allowed
384 in a DMA mapped region.
385 If there is no restriction,
386 .Dv BUS_SPACE_UNRESTRICTED
387 may be specified for the tag intended to be used as the parent.
388 .Dv BUS_SPACE_UNRESTRICTED
389 must not be specified for the tags
390 which will be used to create maps.
391 For tags which will be used to create maps,
392 this argument must be less than 16384 on x86_64.
393 .It Fa maxsegsz
394 Maximum size, in bytes, of a segment in any DMA mapped region associated
395 with
396 .Fa dmat .
397 .It Fa flags
398 Are as follows:
399 .Bl -tag -width ".Dv BUS_DMA_PRIVBZONE" -compact
400 .It Dv BUS_DMA_ALLOCNOW
401 Allocate the minimum resources necessary to guarantee that all map load
402 operations associated with this tag may not block.
403 If sufficient resources are not available,
404 .Er ENOMEM
405 is returned.
406 .It Dv BUS_DMA_WAITOK
407 Indicates that it is OK to wait for resources.
408 However,
409 unlike
410 .Xr kmalloc 9 ,
411 it is not guaranteed that the resource allocation will succeed.
412 This flag is the default one,
413 if
414 .Dv BUS_DMA_NOWAIT
415 is not supplied.
416 .It Dv BUS_DMA_NOWAIT
417 If the resource allocation request cannot be immediately fulfilled,
418 .Er ENOMEM
419 is returned.
420 .It Dv BUS_DMA_ONEBPAGE
421 Allocte one bounce page at most,
422 even if the
423 .Fa maxsize
424 indicates that multiple bounce pages are needed.
425 .It Dv BUS_DMA_ALIGNED
426 Indicates that all memory to be loaded into the DMA maps associated
427 with this DMA tag is properly aligned according to
428 .Fa alignment
429 constraint.
430 No resources,
431 e.g. bounce pages,
432 will be allocated due to the
433 .Fa alignment
434 constraint.
435 If unaligned memory was loaded into the DMA maps associated with this DMA tag,
436 system will panic.
437 .It Dv BUS_DMA_PRIVBZONE
438 Uses a private bounce zone instead of a shared one.
439 A private bounce zone will vanish if the DMA tag is destroyed.
440 .It Dv BUS_DMA_ALLOCALL
441 Allocate all required resources (mainly the bounce buffer).
442 If any allocation fails,
443 .Fn bus_dma_tag_create
444 fails.
445 .It Dv BUS_DMA_PROTECTED
446 All of the functions called with the DMA tag are already protected by the
447 caller, so the
448 .Nm
449 code need not protect the internal data structures.
450 .El
451 .It Fa dmat
452 Pointer to a bus_dma_tag_t where the resulting DMA tag will
453 be stored.
454 .El
455 .Pp
456 Returns
457 .Er ENOMEM
458 if sufficient memory is not available for tag creation
459 or allocating mapping resources.
460 .It Fn bus_dma_tag_destroy "dmat"
461 Deallocate the DMA tag
462 .Fa dmat
463 that was created by
464 .Fn bus_dma_tag_create .
465 .Pp
466 Returns
467 .Er EBUSY
468 if any DMA maps remain associated with
469 .Fa dmat
470 or
471 .Ql 0
472 on success.
473 .It Fn bus_dmamap_create "dmat" "flags" "*mapp"
474 Allocates and initializes a DMA map.
475 Arguments are as follows:
476 .Bl -tag -width nsegments -compact
477 .It Fa dmat
478 DMA tag.
479 .It Fa flags
480 Are as follows:
481 .Bl -tag -width ".Dv BUS_DMA_ONEBPAGE" -compact
482 .It Dv BUS_DMA_WAITOK
483 Indicates that it is OK to wait for resources.
484 However,
485 unlike
486 .Xr kmalloc 9 ,
487 it is not guaranteed that the resource allocation will succeed.
488 This flag is the default one,
489 if
490 .Dv BUS_DMA_NOWAIT
491 is not supplied.
492 .It Dv BUS_DMA_NOWAIT
493 If the resource allocation request cannot be immediately fulfilled,
494 .Er ENOMEM
495 is returned.
496 .It Dv BUS_DMA_ONEBPAGE
497 Allocte one bounce page at most,
498 even if the
499 .Fa maxsize
500 used to create the
501 .Fa dmat
502 indicates that multiple bounce pages are needed.
503 .El
504 .It Fa mapp
505 Pointer to a
506 .Vt bus_dmamap_t
507 where the resulting DMA map will be stored.
508 .El
509 .Pp
510 Returns
511 .Er ENOMEM
512 if sufficient memory is not available for creating the
513 map or allocating mapping resources.
514 .It Fn bus_dmamap_destroy "dmat" "map"
515 Frees all resources associated with a given DMA map.
516 Arguments are as follows:
517 .Bl -tag -width dmat -compact
518 .It Fa dmat
519 DMA tag used to allocate
520 .Fa map .
521 .It Fa map
522 The DMA map to destroy.
523 .El
524 .Pp
525 Returns
526 .Er EBUSY
527 if a mapping is still active for
528 .Fa map .
529 .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..."
530 Creates a mapping in device visible address space of
531 .Fa buflen
532 bytes of
533 .Fa buf ,
534 associated with the DMA map
535 .Fa map .
536 Arguments are as follows:
537 .Bl -tag -width buflen -compact
538 .It Fa dmat
539 DMA tag used to allocate
540 .Fa map .
541 .It Fa map
542 A DMA map without a currently active mapping.
543 .It Fa buf
544 A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
545 mapped into device visible address space.
546 .It Fa buflen
547 The size of the buffer.
548 .It Fa callback Fa callback_arg
549 The callback function, and its argument.
550 .It Fa flags
551 The value of this argument is currently undefined, and should be
552 specified as
553 .Ql 0 .
554 .El
555 .Pp
556 Return values to the caller are as follows:
557 .Bl -tag -width ".Er EINPROGRESS" -compact
558 .It 0
559 The callback has been called and completed.
560 The status of the mapping has been delivered to the callback.
561 .It Er EINPROGRESS
562 The mapping has been deferred for lack of resources.
563 The callback will be called as soon as resources are available.
564 Callbacks are serviced in FIFO order.
565 DMA maps created from DMA tags that are allocated with
566 the
567 .Dv BUS_DMA_ALLOCNOW
568 flag will never return this status for a load operation.
569 .It Er EINVAL
570 The load request was invalid.
571 The callback has not, and will not be called.
572 This error value may indicate that
573 .Fa dmat ,
574 .Fa map ,
575 .Fa buf ,
576 or
577 .Fa callback
578 were invalid, or
579 .Fa buslen
580 was larger than the
581 .Fa maxsize
582 argument used to create the dma tag
583 .Fa dmat .
584 .El
585 .Pp
586 When the callback is called, it is presented with an error value
587 indicating the disposition of the mapping.
588 Error may be one of the following:
589 .Bl -tag -width ".Er EINPROGRESS" -compact
590 .It 0
591 The mapping was successful and the
592 .Fa dm_segs
593 callback argument contains an array of
594 .Vt bus_dma_segment_t
595 elements describing the mapping.
596 This array is only valid during the scope of the callback function.
597 .It Er EFBIG
598 A mapping could not be achieved within the segment constraints provided
599 in the tag even though the requested allocation size was less than maxsize.
600 .El
601 .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \
602 "flags"
603 This is a variation of
604 .Fn bus_dmamap_load
605 which maps mbuf chains
606 for DMA transfers.
607 A
608 .Vt bus_size_t
609 argument is also passed to the callback routine, which
610 contains the mbuf chain's packet header length.
611 .Pp
612 Mbuf chains are assumed to be in kernel virtual address space.
613 .Pp
614 Returns
615 .Er EINVAL
616 if the size of the mbuf chain exceeds the maximum limit of the
617 DMA tag.
618 .It Fn bus_dmamap_load_mbuf_segment "dmat" "map" "mbuf" "*segs" "maxsegs" \
619 "*nsegs" "flags"
620 It is like
621 .Fn bus_dmamap_load_mbuf
622 without callback.
623 Segmentation information are saved in the
624 .Fa segs
625 and
626 .Fa nsegs
627 if the loading is successful.
628 The
629 .Fa maxsegs ,
630 which indicates the number of elements in the
631 .Fa segs ,
632 must be set by the caller and must be at least 1 and at most equal the
633 .Fa nsegments
634 used to create the
635 .Fa dmat .
636 The
637 .Fa flags
638 must have
639 .Dv BUS_DMA_NOWAIT
640 turned on.
641 .Pp
642 This function will not block.
643 When system is short of DMA resources,
644 this function will return
645 .Er ENOMEM ,
646 instead of
647 .Er EINPROGRESS .
648 .It Fn bus_dmamap_load_mbuf_defrag "dmat" "map" "*mbuf" "*segs" "maxsegs" \
649 "*nsegs" "flags"
650 This function is like
651 .Fn bus_dmamap_load_mbuf_segment ,
652 but it will call
653 .Fn m_defrag
654 on the
655 .Fa *mbuf
656 and try reloading,
657 if low level code indicates too many fragments in the
658 .Fa *mbuf ;
659 the
660 .Fa mbuf
661 will be updated under this situation.
662 However,
663 .Fa *mbuf
664 would not be freed by this function,
665 even if
666 .Fn m_defrag
667 failed.
668 .Pp
669 Return
670 .Er ENOBUFS ,
671 if the calling of
672 .Fn m_defrag
673 failed.
674 .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags"
675 This is a variation of
676 .Fn bus_dmamap_load
677 which maps buffers pointed to by
678 .Fa uio
679 for DMA transfers.
680 A
681 .Vt bus_size_t
682 argument is also passed to the callback routine, which contains the size of
683 .Fa uio ,
684 i.e.
685 .Fa uio->uio_resid .
686 .Pp
687 If
688 .Fa uio->uio_segflg
689 is
690 .Dv UIO_USERSPACE ,
691 then it is assumed that the buffer,
692 .Fa uio
693 is in
694 .Fa "uio->uio_td->td_proc" Ns 's
695 address space.
696 User space memory must be in-core and wired prior to attempting a map
697 load operation.
698 .It Fn bus_dmamap_unload "dmat" "map"
699 Unloads a DMA map.
700 Arguments are as follows:
701 .Bl -tag -width dmam -compact
702 .It Fa dmat
703 DMA tag used to allocate
704 .Fa map .
705 .It Fa map
706 The DMA map that is to be unloaded.
707 .El
708 .Pp
709 .Fn bus_dmamap_unload
710 will not perform any implicit synchronization of DMA buffers.
711 This must be done explicitly by a call to
712 .Fn bus_dmamap_sync
713 prior to unloading the map.
714 .It Fn bus_dmamap_sync "dmat" "map" "op"
715 Performs synchronization of a device visible mapping with the CPU visible
716 memory referenced by that mapping.
717 Arguments are as follows:
718 .Bl -tag -width dmat -compact
719 .It Fa dmat
720 DMA tag used to allocate
721 .Fa map .
722 .It Fa map
723 The DMA mapping to be synchronized.
724 .It Fa op
725 Type of synchronization operation to perform.
726 See the definition of
727 .Vt bus_dmasync_op_t
728 for a description of the acceptable values for
729 .Fa op .
730 .El
731 .Pp
732 .Fn bus_dmamap_sync
733 is the method used to ensure that CPU and device DMA access to shared
734 memory is coherent.
735 For example, the CPU might be used to setup the contents of a buffer
736 that is to be DMA'ed into a device.
737 To ensure that the data are visible via the device's mapping of that
738 memory, the buffer must be loaded and a dma sync operation of
739 .Dv BUS_DMASYNC_PREREAD
740 must be performed.
741 Additional sync operations must be performed after every CPU write
742 to this memory if additional DMA reads are to be performed.
743 Conversely, for the DMA write case, the buffer must be loaded,
744 and a dma sync operation of
745 .Dv BUS_DMASYNC_PREWRITE
746 must be performed.
747 The CPU will only be able to see the results of this DMA write
748 once the DMA has completed and a
749 .Dv BUS_DMASYNC_POSTWRITE
750 operation has been performed.
751 .Pp
752 If DMA read and write operations are not preceded and followed by the
753 appropriate synchronization operations, behavior is undefined.
754 .It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp"
755 Allocates memory that is mapped into KVA at the address returned
756 in
757 .Fa vaddr
758 that is permanently loaded into the newly created
759 .Vt bus_dmamap_t
760 returned via
761 .Fa mapp .
762 Arguments are as follows:
763 .Bl -tag -width alignment -compact
764 .It Fa dmat
765 DMA tag describing the constraints of the DMA mapping.
766 .It Fa vaddr
767 Pointer to a pointer that will hold the returned KVA mapping of
768 the allocated region.
769 .It Fa flags
770 Flags are defined as follows:
771 .Bl -tag -width ".Dv BUS_DMA_COHERENT" -compact
772 .It Dv BUS_DMA_WAITOK
773 The routine can safely wait (sleep) for resources.
774 .It Dv BUS_DMA_NOWAIT
775 The routine is not allowed to wait for resources.
776 If resources are not available,
777 .Er ENOMEM
778 is returned.
779 .It Dv BUS_DMA_COHERENT
780 Attempt to map this memory such that cache sync operations are
781 as cheap as possible.
782 This flag is typically set on memory that will be accessed by both
783 a CPU and a DMA engine, frequently.
784 Use of this flag does not remove the requirement of using
785 bus_dmamap_sync, but it may reduce the cost of performing
786 these operations.
787 .It Dv BUS_DMA_ZERO
788 Causes the allocated memory to be set to all zeros.
789 .It Dv BUS_DMA_NOCACHE
790 The allocated memory will not be cached in the processor caches.
791 All memory accesses appear on the bus and are executed
792 without reordering.
793 On x86_64, the
794 .Dv BUS_DMA_NOCACHE
795 flag results in the
796 Strong Uncacheable PAT to be set for the allocated virtual address range.
797 .El
798 .It Fa mapp
799 Pointer to storage for the returned DMA map.
800 .El
801 .Pp
802 The size of memory to be allocated is
803 .Fa maxsize
804 as specified in
805 .Fa dmat .
806 .Pp
807 The current implementation of
808 .Fn bus_dmamem_alloc
809 will allocate all requests as a single segment.
810 .Pp
811 Although no explicit loading is required to access the memory
812 referenced by the returned map, the synchronization requirements
813 as described in the
814 .Fn bus_dmamap_sync
815 section still apply.
816 .Pp
817 Returns
818 .Er ENOMEM
819 if sufficient memory is not available for completing
820 the operation.
821 .It Fn bus_dmamem_coherent "parent" "alignment" "boundary" "lowaddr" \
822 "highaddr" "maxsize" "flags" "*dmem"
823 This is a convenient function to create one segment of DMA memory.
824 It combines following
825 .Xr bus_dma 9
826 function calls:
827 .Bd -literal
828 bus_dma_tag_create(..., dtag);
829 bus_dmamem_alloc(*dtag, vaddr, ..., dmap);
830 bus_dmamap_load(*dtag, *dmap, *vaddr, ..., \\
831 callback, busaddr, ...);
832 .Ed
833 .sp
834 The final results of the above function calls are:
835 DMA tag,
836 DMA map,
837 DMA memory's kernel virtual address and
838 its device visible address.
839 .Fn bus_dmamem_coherent
840 saves the results in
841 .Fa *dmem .
842 .Pp
843 The
844 .Fa parent ,
845 .Fa alignment ,
846 .Fa boundary ,
847 .Fa lowaddr
848 and
849 .Fa highaddr
850 will be passed to
851 .Fn bus_dma_tag_create
852 as they are.
853 The
854 .Fa maxsize
855 will be passed to
856 .Fn bus_dma_tag_create
857 as its
858 .Fa maxsize
859 and
860 .Fa maxsegsz
861 and
862 .Ql 1
863 will be passed to
864 .Fn bus_dma_tag_create
865 as its
866 .Fa nsegments .
867 When
868 .Fn bus_dmamem_alloc
869 is called,
870 .Fa flags
871 will be first or'ed with
872 .Dv BUS_DMA_COHERENT
873 then passed to it.
874 The final results of the above three functions,
875 i.e. DMA tag,
876 DMA map,
877 DMA memory's kernel virtual address and
878 its device visible address,
879 are saved in
880 .Fa *dmem .
881 If any of the three functions failed,
882 this function will return the error code and the
883 .Fa *dmem
884 should not be used.
885 .It Fn bus_dmamem_coherent_any "parent" "alignment" "maxsize" "flags" \
886 "*dtag" "*dmap" "*busaddr"
887 This function is a simplified version of
888 .Fn bus_dmamem_coherent
889 with
890 its
891 .Fa boundary
892 set to
893 .Ql 0 ,
894 .Fa lowaddr
895 set to
896 .Dv BUS_SPACE_MAXADDR
897 and
898 .Fa highaddr
899 set to
900 .Dv BUS_SPACE_MAXADDR .
901 The
902 .Fa parent
903 usually should not be NULL.
904 .Pp
905 Return the DMA memory's kernel virtual address.
906 The DMA tag, DMA map and device visible address are returned in
907 .Fa *dtag ,
908 .Fa *dmap ,
909 and
910 .Fa *busaddr .
911 If this function failed,
912 NULL will be returned;
913 .Fa *dtag ,
914 .Fa *dmap ,
915 and
916 .Fa *busaddr
917 are left unchanged.
918 .It Fn bus_dmamem_free "dmat" "*vaddr" "map"
919 Frees memory previously allocated by
920 .Fn bus_dmamem_alloc .
921 Any mappings
922 will be invalidated.
923 Arguments are as follows:
924 .Bl -tag -width vaddr -compact
925 .It Fa dmat
926 DMA tag.
927 .It Fa vaddr
928 Kernel virtual address of the memory.
929 .It Fa map
930 DMA map to be invalidated.
931 .El
932 .El
933 .Sh RETURN VALUES
934 Behavior is undefined if invalid arguments are passed to
935 any of the above functions.
936 If sufficient resources cannot be allocated for a given
937 transaction,
938 .Er ENOMEM
939 is returned.
940 All
941 routines that are not of type,
942 .Vt void ,
943 will return 0 on success or an error
944 code, as discussed above.
945 .Pp
946 All
947 .Vt void
948 routines will succeed if provided with valid arguments.
949 .Sh SEE ALSO
950 .Xr devclass 9 ,
951 .Xr device 9 ,
952 .Xr driver 9 ,
953 .Xr rman 9
954 .Rs
955 .%A "Jason R. Thorpe"
956 .%T "A Machine-Independent DMA Framework for NetBSD"
957 .%J "Proceedings of the Summer 1998 USENIX Technical Conference"
958 .%Q "USENIX Association"
959 .%D "June 1998"
960 .Re
961 .Sh HISTORY
962 The
963 .Nm
964 interface first appeared in
965 .Nx 1.3 .
966 .Pp
967 The
968 .Nm
969 API was adopted from
970 .Nx
971 for use in the CAM SCSI subsystem.
972 The alterations to the original API were aimed to remove the need for
973 a
974 .Vt bus_dma_segment_t
975 array stored in each
976 .Vt bus_dmamap_t
977 while allowing callers to queue up on scarce resources.
978 .Sh AUTHORS
979 The
980 .Nm
981 interface was designed and implemented by
982 .An Jason R. Thorpe
983 of the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
984 Additional input on the
985 .Nm
986 design was provided by
987 .An -nosplit
988 .An Chris Demetriou ,
989 .An Charles Hannum ,
990 .An Ross Harvey ,
991 .An Matthew Jacob ,
992 .An Jonathan Stone ,
993 and
994 .An Matt Thomas .
995 .Pp
996 This manual page was written by
997 .An Hiten Pandya
998 and
999 .An Justin T. Gibbs .