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 $
77 .Nm bus_dma_tag_create ,
78 .Nm bus_dma_tag_destroy ,
79 .Nm bus_dmamap_create ,
80 .Nm bus_dmamap_destroy ,
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 ,
89 .Nm bus_dmamem_alloc ,
90 .Nm bus_dmamem_coherent ,
91 .Nm bus_dmamem_coherent_any ,
93 .Nd Bus and Machine Independent DMA Mapping Interface
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"
102 .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
104 .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
106 .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map"
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" \
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" \
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" \
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" \
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" \
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" \
132 .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \
133 "int flags" "bus_dmamap_t *mapp"
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"
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"
143 .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map"
145 .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \
146 "bus_dmasync_op_t op"
148 .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \
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.
158 API is a bus, device, and machine-independent (MI) interface to
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
164 .Sh STRUCTURES AND TYPES
165 .Bl -tag -width compact
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
177 .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr"
180 Address filters can be specified during tag creation to allow
181 for devices who's DMA address restrictions cannot be specified
185 is client specified during tag creation to be passed to all
186 invocations of the callback.
189 argument contains a potential starting address of a DMA mapping.
190 The filter function operates on the set of addresses from
193 .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
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
207 field contains the device visible address of the DMA segment, and
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.
215 A machine-dependent opaque type describing an individual mapping.
216 Multiple DMA maps can be associated with one DMA tag.
218 A machine-dependent type that describes DMA memory created by
219 .Fn bus_dmamem_coherent .
221 bus_dma_tag_t dmem_tag;
222 bus_dmamap_t dmem_map;
224 bus_addr_t dmem_busaddr;
229 field contains the DMA tag of the DMA memory and
231 field contains the DMA map of the DMA memory.
234 field points to the allocated DMA memory in kernel virtual address space.
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
245 .Fn bus_dmamap_load_ccb .
246 Callbacks are of the format:
247 .Bl -tag -width compact
249 .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \
250 "int nseg" "int error"
255 is the callback argument passed to dmamap load functions.
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
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
274 .Fn bus_dmamap_load_uio
276 .Fn bus_dmamap_load_mbuf .
278 Callback2s are of the format:
279 .Bl -tag -width compact
281 .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \
282 "int nseg" "bus_size_t mapsize" "int error"
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
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.
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
298 All operations specified below are performed from the DMA engine's
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.
317 .Bl -tag -width compact
318 .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \
319 "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \
321 Allocates a device specific DMA tag, and initializes it according to
322 the arguments provided:
323 .Bl -tag -width *filtfuncarg -compact
325 Indicates restrictions between the parent bridge, CPU memory, and the
327 May be NULL, if no DMA restrictions are to be inherited.
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
334 Hardware requiring DMA transfers to start on a multiple of 4K
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.
344 indicates that there are no boundary restrictions.
347 Bounds of the window of bus address space that
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
354 .Dv BUS_SPACE_MAXADDR
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
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
367 is used to bounce requests that would otherwise conflict with
368 the exclusion window.
370 Optional filter function (may be NULL) to be called for any attempt to
371 map memory into the window described by
375 A filter function is only required when the single window described
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.
384 Argument passed to all calls to the filter function for this tag.
387 Maximum size, in bytes, of the sum of all segment lengths in a given
388 DMA mapping associated with this tag.
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.
401 Maximum size, in bytes, of a segment in any DMA mapped region associated
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,
413 .It Dv BUS_DMA_WAITOK
414 Indicates that it is OK to wait for resources.
418 it is not guaranteed that the resource allocation will succeed.
419 This flag is the default one,
423 .It Dv BUS_DMA_NOWAIT
424 If the resource allocation request cannot be immediately fulfilled,
427 .It Dv BUS_DMA_ONEBPAGE
428 Allocte one bounce page at most,
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
439 will be allocated due to the
442 If unaligned memory was loaded into the DMA maps associated with this DMA tag,
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
452 .It Dv BUS_DMA_PROTECTED
453 All of the functions called with the DMA tag are already protected by the
456 code need not protect the internal data structures.
459 Pointer to a bus_dma_tag_t where the resulting DMA tag will
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
471 .Fn bus_dma_tag_create .
475 if any DMA maps remain associated with
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
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.
494 it is not guaranteed that the resource allocation will succeed.
495 This flag is the default one,
499 .It Dv BUS_DMA_NOWAIT
500 If the resource allocation request cannot be immediately fulfilled,
503 .It Dv BUS_DMA_ONEBPAGE
504 Allocte one bounce page at most,
509 indicates that multiple bounce pages are needed.
514 where the resulting DMA map will be stored.
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
526 DMA tag used to allocate
529 The DMA map to destroy.
534 if a mapping is still active for
536 .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..."
537 Creates a mapping in device visible address space of
541 associated with the DMA map
543 Arguments are as follows:
544 .Bl -tag -width buflen -compact
546 DMA tag used to allocate
549 A DMA map without a currently active mapping.
551 A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
552 mapped into device visible address space.
554 The size of the buffer.
555 .It Fa callback Fa callback_arg
556 The callback function, and its argument.
558 The value of this argument is currently undefined, and should be
563 Return values to the caller are as follows:
564 .Bl -tag -width ".Er EINPROGRESS" -compact
566 The callback has been called and completed.
567 The status of the mapping has been delivered to the callback.
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
575 flag will never return this status for a load operation.
577 The load request was invalid.
578 The callback has not, and will not be called.
579 This error value may indicate that
589 argument used to create the dma tag
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
598 The mapping was successful and the
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.
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.
608 .It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags"
609 This is a variation of
611 which maps data pointed to by
614 .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \
616 This is a variation of
618 which maps mbuf chains
622 argument is also passed to the callback routine, which
623 contains the mbuf chain's packet header length.
625 Mbuf chains are assumed to be in kernel virtual address space.
629 if the size of the mbuf chain exceeds the maximum limit of the
631 .It Fn bus_dmamap_load_mbuf_segment "dmat" "map" "mbuf" "*segs" "maxsegs" \
634 .Fn bus_dmamap_load_mbuf
636 Segmentation information are saved in the
640 if the loading is successful.
643 which indicates the number of elements in the
645 must be set by the caller and must be at least 1 and at most equal the
655 This function will not block.
656 When system is short of DMA resources,
657 this function will return
661 .It Fn bus_dmamap_load_mbuf_defrag "dmat" "map" "*mbuf" "*segs" "maxsegs" \
663 This function is like
664 .Fn bus_dmamap_load_mbuf_segment ,
670 if low level code indicates too many fragments in the
674 will be updated under this situation.
677 would not be freed by this function,
687 .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags"
688 This is a variation of
690 which maps buffers pointed to by
695 argument is also passed to the callback routine, which contains the size of
704 then it is assumed that the buffer,
707 .Fa "uio->uio_td->td_proc" Ns 's
709 User space memory must be in-core and wired prior to attempting a map
711 .It Fn bus_dmamap_unload "dmat" "map"
713 Arguments are as follows:
714 .Bl -tag -width dmam -compact
716 DMA tag used to allocate
719 The DMA map that is to be unloaded.
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
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
733 DMA tag used to allocate
736 The DMA mapping to be synchronized.
738 Type of synchronization operation to perform.
739 See the definition of
741 for a description of the acceptable values for
746 is the method used to ensure that CPU and device DMA access to shared
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
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
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.
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
771 that is permanently loaded into the newly created
775 Arguments are as follows:
776 .Bl -tag -width alignment -compact
778 DMA tag describing the constraints of the DMA mapping.
780 Pointer to a pointer that will hold the returned KVA mapping of
781 the allocated region.
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,
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
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
809 Strong Uncacheable PAT to be set for the allocated virtual address range.
812 Pointer to storage for the returned DMA map.
815 The size of memory to be allocated is
820 The current implementation of
822 will allocate all requests as a single segment.
824 Although no explicit loading is required to access the memory
825 referenced by the returned map, the synchronization requirements
832 if sufficient memory is not available for completing
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
841 bus_dma_tag_create(..., dtag);
842 bus_dmamem_alloc(*dtag, vaddr, ..., dmap);
843 bus_dmamap_load(*dtag, *dmap, *vaddr, ..., \\
844 callback, busaddr, ...);
847 The final results of the above function calls are:
850 DMA memory's kernel virtual address and
851 its device visible address.
852 .Fn bus_dmamem_coherent
864 .Fn bus_dma_tag_create
869 .Fn bus_dma_tag_create
877 .Fn bus_dma_tag_create
884 will be first or'ed with
887 The final results of the above three functions,
890 DMA memory's kernel virtual address and
891 its device visible address,
894 If any of the three functions failed,
895 this function will return the error code and the
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
909 .Dv BUS_SPACE_MAXADDR
913 .Dv BUS_SPACE_MAXADDR .
916 usually should not be NULL.
918 Return the DMA memory's kernel virtual address.
919 The DMA tag, DMA map and device visible address are returned in
924 If this function failed,
925 NULL will be returned;
931 .It Fn bus_dmamem_free "dmat" "*vaddr" "map"
932 Frees memory previously allocated by
933 .Fn bus_dmamem_alloc .
936 Arguments are as follows:
937 .Bl -tag -width vaddr -compact
941 Kernel virtual address of the memory.
943 DMA map to be invalidated.
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
954 routines that are not of type,
956 will return 0 on success or an error
957 code, as discussed above.
961 routines will succeed if provided with valid arguments.
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"
977 interface first appeared in
984 for use in the CAM SCSI subsystem.
985 The alterations to the original API were aimed to remove the need for
987 .Vt bus_dma_segment_t
990 while allowing callers to queue up on scarce resources.
994 interface was designed and implemented by
996 of the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
997 Additional input on the
999 design was provided by
1001 .An Chris Demetriou ,
1002 .An Charles Hannum ,
1005 .An Jonathan Stone ,
1009 This manual page was written by
1012 .An Justin T. Gibbs .