2 .\" Copyright (c) 2002, 2003, 2004 The DragonFly Project. All rights reserved.
4 .\" This code is derived from software contributed to The DragonFly Project
5 .\" by Hiten Pandya <hmp@backplane.com>.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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
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.
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
34 .\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
35 .\" All rights reserved.
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.
41 .\" Redistribution and use in source and binary forms, with or without
42 .\" modification, are permitted provided that the following conditions
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.
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.
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 .\" $DragonFly: src/share/man/man9/bus_dma.9,v 1.3 2004/07/16 05:04:36 hmp Exp $
78 .Nm bus_dma_tag_create ,
79 .Nm bus_dma_tag_destroy ,
80 .Nm bus_dmamap_create ,
81 .Nm bus_dmamap_destroy ,
83 .Nm bus_dmamap_load_mbuf ,
84 .Nm bus_dmamap_load_uio ,
85 .Nm bus_dmamap_unload ,
87 .Nm bus_dmamem_alloc ,
89 .Nd Bus and Machine Independent DMA Mapping Interface
93 .Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \
94 "bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \
95 "bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \
96 "int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat"
98 .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
100 .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
102 .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map"
104 .Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \
105 "bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \
108 .Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \
109 "struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
112 .Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \
113 "struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
116 .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \
117 "int flags" "bus_dmamap_t *mapp"
119 .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map"
121 .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \
124 .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \
127 Direct Memory Access (DMA) is a method of transferring data
128 without involving the CPU, thus providing higher performance.
129 A DMA transaction can be achieved between device to memory,
130 device to device, or memory to memory.
134 API is a bus, device, and machine-independent (MI) interface to
136 It provides the client with flexibility and simplicity by
137 abstracting machine dependent issues like setting up
138 DMA mappings, handling cache issues, bus specific features
140 .Sh STRUCTURES AND TYPES
141 .Bl -tag -width compact
143 A machine-dependent (MD) opaque type that describes the
144 characteristics of DMA transactions.
145 DMA tags are organized into a hierarchy, with each child
146 tag inheriting the restrictions of its parent.
147 This allows all devices along the path of DMA transactions
148 to contribute to the constraints of those transactions.
149 .It Vt bus_dma_filter_t
150 Client specified address filter having the format:
151 .Bl -tag -width compact
153 .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr"
156 Address filters can be specified during tag creation to allow
157 for devices who's DMA address restrictions cannot be specified
161 is client specified during tag creation to be passed to all
162 invocations of the callback.
165 argument contains a potential starting address of a DMA mapping.
166 The filter function operates on the set of addresses from
169 .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
171 The filter function should return zero for any mapping in this range
172 that can be accommodated by the device and non-zero otherwise.
173 .It Vt bus_dma_segment_t
174 A machine-dependent type that describes individual
183 field contains the device visible address of the DMA segment, and
185 contains the length of the DMA segment.
186 Although the DMA segments returned by a mapping call will adhere to
187 all restrictions necessary for a successful DMA operation, some conversion
188 (e.g. a conversion from host byte order to the device's byte order) is
189 almost always required when presenting segment information to the device.
191 A machine-dependent opaque type describing an individual mapping.
192 Multiple DMA maps can be associated with one DMA tag.
193 .It Vt bus_dmamap_callback_t
194 Client specified callback for receiving mapping information resulting from
198 .Fn bus_dmamap_load .
199 Callbacks are of the format:
200 .Bl -tag -width compact
202 .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \
203 "int nseg" "int error"
208 is the callback argument passed to dmamap load functions.
213 parameters describe an array of
214 .Vt bus_dma_segment_t
215 structures that represent the mapping.
216 This array is only valid within the scope of the callback function.
217 The success or failure of the mapping is indicated by the
220 More information on the use of callbacks can be found in the
221 description of the individual dmamap load functions.
222 .It Vt bus_dmamap_callback2_t
223 Client specified callback for receiving mapping information resulting from
227 .Fn bus_dmamap_load_uio
229 .Fn bus_dmamap_load_mbuf .
231 Callback2s are of the format:
232 .Bl -tag -width compact
234 .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \
235 "int nseg" "bus_size_t mapsize" "int error"
238 Callback2's behavior is the same as
239 .Vt bus_dmamap_callback_t
240 with the addition that the length of the data mapped is provided via
242 .It Vt bus_dmasync_op_t
243 Memory synchronization operation specifier.
244 Bus DMA requires explicit synchronization of memory with it's device
245 visible mapping in order to guarantee memory coherency.
248 allows the type of DMA operation that will be or has been performed
249 to be communicated to the system so that the correct coherency measures
251 All operations specified below are performed from the DMA engine's
253 .Bl -tag -width BUS_DMASYNC_POSTWRITE
254 .It Dv BUS_DMASYNC_PREREAD
255 Perform any synchronization required after an update of memory by the CPU
256 but prior to DMA read operations.
257 .It Dv BUS_DMASYNC_PREWRITE
258 Perform any synchronization required after an update of memory by the CPU
259 but prior to DMA write operations.
260 .It Dv BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE
261 Perform any synchronization required prior to a combination of DMA read
262 and write operations.
263 .It Dv BUS_DMASYNC_POSTREAD
264 Perform any synchronization required after DMA read operations, but prior
265 to CPU access of the memory.
266 .It Dv BUS_DMASYNC_POSTWRITE
267 Perform any synchronization required after DMA write operations, but prior
268 to CPU access of the memory.
269 .It Dv BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE
270 Perform any synchronization required after a combination of DMA read
271 and write operations.
276 .Bl -tag -width compact
277 .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \
278 "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \
280 Allocates a device specific DMA tag, and initializes it according to
281 the arguments provided:
282 .Bl -tag -width *filtfuncarg -compact
284 Indicates restrictions between the parent bridge, CPU memory, and the
286 May be NULL, if no DMA restrictions are to be inherited.
288 Alignment constraint, in bytes, of any mappings created using this tag.
289 The alignment must be a power of 2.
290 Hardware that can DMA starting at any address would specify
293 Hardware requiring DMA transfers to start on a multiple of 4K
297 Boundary constraint, in bytes, of the target DMA memory region.
298 The boundary indicates the set of addresses, all multiples of the
299 boundary argument, that cannot be crossed by a single
300 .Vt bus_dma_segment_t .
301 The boundary must be either a power of 2 or 0.
303 indicates that there are no boundary restrictions.
306 Bounds of the window of bus address space that
308 be directly accessed by the device.
309 The window contains all address greater than lowaddr and
310 less than or equal to highaddr.
311 For example, a device incapable of DMA above 4GB, would specify
313 .Dv BUS_SPACE_MAXADDR
315 .Dv BUS_SPACE_MAXADDR_32BIT .
316 Similarly a device that can only dma to addresses bellow 16MB would
317 specify a highaddr of
318 .Dv BUS_SPACE_MAXADDR
320 .Dv BUS_SPACE_MAXADDR_24BIT .
321 Some implementations requires that some region of device visible
322 address space, overlapping available host memory, be outside the
326 is used to bounce requests that would otherwise conflict with
327 the exclusion window.
329 Optional filter function (may be NULL) to be called for any attempt to
330 map memory into the window described by
334 A filter function is only required when the single window described
339 cannot adequately describe the constraints of the device.
340 The filter function will be called for every machine page
341 that overlaps the exclusion window.
343 Argument passed to all calls to the filter function for this tag.
346 Maximum size, in bytes, of the sum of all segment lengths in a given
347 DMA mapping associated with this tag.
349 Number of discontinuities (scatter/gather segments) allowed
350 in a DMA mapped region.
351 If there is no restriction,
352 .Dv BUS_SPACE_UNRESTRICTED
355 Maximum size, in bytes, of a segment in any DMA mapped region associated
360 .Bl -tag -width "BUS_DMA_ALLOCNOW" -compact
361 .It Dv BUS_DMA_ALLOCNOW
362 Allocate the resources necessary to guarantee that all map load
363 operations associated with this tag will not block.
364 If sufficient resources are not available,
369 Pointer to a bus_dma_tag_t where the resulting DMA tag will
375 if sufficient memory is not available for tag creation
376 or allocating mapping resources.
377 .It Fn bus_dma_tag_destroy "dmat"
378 Deallocate the DMA tag
381 .Fn bus_dma_tag_create .
385 if any DMA maps remain associated with
390 .It Fn bus_dmamap_create "dmat" "flags" "*mapp"
391 Allocates and initializes a DMA map.
392 Arguments are as follows:
393 .Bl -tag -width nsegments -compact
397 The value of this argument is currently undefined and should be
403 where the resulting DMA map will be stored.
408 if sufficient memory is not available for creating the
409 map or allocating mapping resources.
410 .It Fn bus_dmamap_destroy "dmat" "map"
411 Frees all resources associated with a given DMA map.
412 Arguments are as follows:
413 .Bl -tag -width dmat -compact
415 DMA tag used to allocate
418 The DMA map to destroy.
423 if a mapping is still active for
425 .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..."
426 Creates a mapping in device visible address space of
430 associated with the DMA map
432 Arguments are as follows:
433 .Bl -tag -width buflen -compact
435 DMA tag used to allocate
438 A DMA map without a currently active mapping.
440 A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
441 mapped into device visible address space.
443 The size of the buffer.
444 .It Fa callback Fa callback_arg
445 The callback function, and its argument.
447 The value of this argument is currently undefined, and should be
452 Return values to the caller are as follows:
453 .Bl -tag -width EINPROGRESS -compact
455 The callback has been called and completed.
456 The status of the mapping has been delivered to the callback.
458 The mapping has been deferred for lack of resources.
459 The callback will be called as soon as resources are available.
460 Callbacks are serviced in FIFO order.
461 DMA maps created from DMA tags that are allocated with
464 flag will never return this status for a load operation.
466 The load request was invalid.
467 The callback has not, and will not be called.
468 This error value may indicate that
478 argument used to create the dma tag
482 When the callback is called, it is presented with an error value
483 indicating the disposition of the mapping.
484 Error may be one of the following:
485 .Bl -tag -width EINPROGRESS -compact
487 The mapping was successful and the
489 callback argument contains an array of
490 .Vt bus_dma_segment_t
491 elements describing the mapping.
492 This array is only valid during the scope of the callback function.
494 A mapping could not be achieved within the segment constraints provided
495 in the tag even though the requested allocation size was less than maxsize.
497 .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \
499 This is a variation of
501 which maps mbuf chains
505 argument is also passed to the callback routine, which
506 contains the mbuf chain's packet header length.
508 Mbuf chains are assumed to be in kernel virtual address space.
512 if the size of the mbuf chain exceeds the maximum limit of the
514 .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags"
515 This is a variation of
517 which maps buffers pointed to by
522 argument is also passed to the callback routine, which contains the size of
531 then it is assumed that the buffer,
534 .Fa "uio->uio_td->td_proc" Ns 's
536 User space memory must be in-core and wired prior to attempting a map
538 .It Fn bus_dmamap_unload "dmat" "map"
540 Arguments are as follows:
541 .Bl -tag -width dmam -compact
543 DMA tag used to allocate
546 The DMA map that is to be unloaded.
549 .Fn bus_dmamap_unload
550 will not perform any implicit synchronization of DMA buffers.
551 This must be done explicitly by a call to
553 prior to unloading the map.
554 .It Fn bus_dmamap_sync "dmat" "map" "op"
555 Performs synchronization of a device visible mapping with the CPU visible
556 memory referenced by that mapping.
557 Arguments are as follows:
558 .Bl -tag -width dmat -compact
560 DMA tag used to allocate
563 The DMA mapping to be synchronized.
565 Type of synchronization operation to perform.
566 See the definition of
568 for a description of the acceptable values for
573 is the method used to ensure that CPU and device DMA access to shared
575 For example, the CPU might be used to setup the contents of a buffer
576 that is to be DMA'ed into a device.
577 To ensure that the data are visible via the device's mapping of that
578 memory, the buffer must be loaded and a dma sync operation of
579 .Dv BUS_DMASYNC_PREREAD
581 Additional sync operations must be performed after every CPU write
582 to this memory if additional DMA reads are to be performed.
583 Conversely, for the DMA write case, the buffer must be loaded,
584 and a dma sync operation of
585 .Dv BUS_DMASYNC_PREWRITE
587 The CPU will only be able to see the results of this DMA write
588 once the DMA has completed and a
589 .Dv BUS_DMASYNC_POSTWRITE
590 operation has been performed.
592 If DMA read and write operations are not preceded and followed by the
593 appropriate synchronization operations, behavior is undefined.
594 .It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp"
595 Allocates memory that is mapped into KVA at the address returned
598 that is permanently loaded into the newly created
602 Arguments are as follows:
603 .Bl -tag -width alignment -compact
605 DMA tag describing the constraints of the DMA mapping.
607 Pointer to a pointer that will hold the returned KVA mapping of
608 the allocated region.
610 Flags are defined as follows:
611 .Bl -tag -width BUS_DMA_NOWAIT -compact
612 .It Dv BUS_DMA_WAITOK
613 The routine can safely wait (sleep) for resources.
614 .It Dv BUS_DMA_NOWAIT
615 The routine is not allowed to wait for resources.
616 If resources are not available,
619 .It Dv BUS_DMA_COHERENT
620 Attempt to map this memory such that cache sync operations are
621 as cheap as possible.
622 This flag is typically set on memory that will be accessed by both
623 a CPU and a DMA engine, frequently.
624 Use of this flag does not remove the requirement of using
625 bus_dmamap_sync, but it may reduce the cost of performing
628 Causes the allocated memory to be set to all zeros.
631 Pointer to storage for the returned DMA map.
634 The size of memory to be allocated is
639 The current implementation of
641 will allocate all requests as a single segment.
643 Although no explicit loading is required to access the memory
644 referenced by the returned map, the synchronization requirements
651 if sufficient memory is not available for completing
653 .It Fn bus_dmamem_free "dmat" "*vaddr" "map"
654 Frees memory previously allocated by
655 .Fn bus_dmamem_alloc .
658 Arguments are as follows:
659 .Bl -tag -width vaddr -compact
663 Kernel virtual address of the memory.
665 DMA map to be invalidated.
669 Behavior is undefined if invalid arguments are passed to
670 any of the above functions.
671 If sufficient resources cannot be allocated for a given
676 routines that are not of type,
678 will return 0 on success or an error
679 code, as discussed above.
683 routines will succeed if provided with valid arguments.
691 .%A "Jason R. Thorpe"
692 .%T "A Machine-Independent DMA Framework for NetBSD"
693 .%J "Proceedings of the Summer 1998 USENIX Technical Conference"
694 .%Q "USENIX Association"
700 interface first appeared in
707 for use in the CAM SCSI subsystem.
708 The alterations to the original API were aimed to remove the need for
710 .Vt bus_dma_segment_t
713 while allowing callers to queue up on scarce resources.
717 interface was designed and implemented by
719 of the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
720 Additional input on the
722 design was provided by
724 .An Chris Demetriou ,
732 This manual page was written by
735 .An Justin T. Gibbs .