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