Add the bus_dma(9) manual page to our section 9 collection. It

provides comprehensive documentation on FreeBSD's Bus DMA interface.

Approved by: gibbs, re@ (scottl)
Reviewed by: gibbs, scottl, des, sam, jake, tmm

2 files changed, 732 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index f5c7cb6..522414c 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -22,6 +22,7 @@ MAN=	BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
 	accept_filter.9 accf_data.9 accf_http.9 acl.9 atomic.9 \
 	bios.9 boot.9 buf.9 bus_activate_resource.9 \
 	bus_alloc_resource.9 bus_child_present.9 bus_generic_attach.9 \
+	bus_dma.9 \
 	bus_generic_detach.9 \
 	bus_generic_print_child.9 bus_generic_read_ivar.9 \
 	bus_generic_shutdown.9 bus_release_resource.9 \
@@ -112,6 +113,17 @@ MLINKS+=atomic.9 atomic_set.9
 MLINKS+=atomic.9 atomic_subtract.9
 MLINKS+=atomic.9 atomic_store.9
 MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9
+MLINKS+=bus_dma.9 bus_dma_tag_create.9
+MLINKS+=bus_dma.9 bus_dma_tag_destroy.9
+MLINKS+=bus_dma.9 bus_dmamap_create.9
+MLINKS+=bus_dma.9 bus_dmamap_destroy.9
+MLINKS+=bus_dma.9 bus_dmamap_load.9
+MLINKS+=bus_dma.9 bus_dmamap_load_mbuf.9
+MLINKS+=bus_dma.9 bus_dmamap_load_uio.9
+MLINKS+=bus_dma.9 bus_dmamap_sync.9
+MLINKS+=bus_dma.9 bus_dmamap_unload.9
+MLINKS+=bus_dma.9 bus_dmamem_alloc.9
+MLINKS+=bus_dma.9 bus_dmamem_free.9
 MLINKS+=byteorder.9 bswap16.9
 MLINKS+=byteorder.9 bswap32.9
 MLINKS+=byteorder.9 bswap64.9
diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9
new file mode 100644
index 0000000..b7b1fa2
--- /dev/null
+++ b/share/man/man9/bus_dma.9
@@ -0,0 +1,720 @@
+.\" Copyright (c) 2002, 2003 Hiten M. Pandya.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions, and the following disclaimer,
+.\"    without modification, immediately at the beginning of the file.
+.\" 2. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, CONTRIBUTORS OR THE
+.\" VOICES IN HITEN PANDYA'S HEAD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
+.\" NASA Ames Research Center.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgment:
+.\" 	This product includes software developed by the NetBSD
+.\" 	Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $
+.\"
+.Dd May 28, 2003
+.Dt BUS_DMA 9
+.Os
+.Sh NAME
+.Nm bus_dma ,
+.Nm bus_dma_tag_create ,
+.Nm bus_dma_tag_destroy ,
+.Nm bus_dmamap_create ,
+.Nm bus_dmamap_destroy ,
+.Nm bus_dmamap_load ,
+.Nm bus_dmamap_load_mbuf ,
+.Nm bus_dmamap_load_uio ,
+.Nm bus_dmamap_unload ,
+.Nm bus_dmamap_sync ,
+.Nm bus_dmamem_alloc ,
+.Nm bus_dmamem_free ,
+.Nd Bus and Machine Independent DMA Mapping Interface
+.Sh SYNOPSIS
+.In machine/bus.h
+.Ft int
+.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \
+"bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \
+"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \
+"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat"
+.Ft int
+.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
+.Ft int
+.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
+.Ft int
+.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map"
+.Ft int
+.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \
+"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \
+"int flags"
+.Ft int
+.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \
+"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
+"int flags"
+.Ft int
+.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \
+"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
+"int flags"
+.Ft int
+.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \
+"int flags" "bus_dmamap_t *mapp"
+.Ft void
+.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map"
+.Ft void
+.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \
+"op"
+.Ft void
+.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \
+"bus_dmamap_t map"
+.Sh DESCRIPTION
+Direct Memory Access (DMA) is a method of transferring data
+without involving the CPU, thus providing higher performance.
+A DMA transaction can be achieved between device to memory,
+device to device, or memory to memory.
+.Pp
+The
+.Nm
+API is a bus, device, and machine-independent (MI) interface to
+DMA mechanisms.
+It provides the client with flexibility and simplicity by
+abstracting machine dependent issues like setting up
+DMA mappings, handling cache issues, bus specific features
+and limitations.
+.Sh STRUCTURES AND TYPES
+.Bl -tag -width compact
+.It Vt bus_dma_tag_t
+A machine-dependent (MD) opaque type that describes the
+characteristics of DMA transactions.
+DMA tags are organized into a hierarchy, with each child
+tag inheriting the restrictions of its parent.
+This allows all devices along the path of DMA transactions
+to contribute to the constraints of those transactions.
+.It Vt bus_dma_filter_t
+Client specified address filter having the format:
+.Bl -tag -width compact
+.It Ft int
+.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr"
+.El
+.sp
+Address filters can be specified during tag creation to allow
+for devices who's DMA address restrictions cannot be specified
+by a single window.
+The
+.Fa filtarg
+is client specified during tag creation to be passed to all
+invocations of the callback.
+The
+.Fa testaddr
+argument contains a potential starting address of a DMA mapping.
+The filter function operates on the set of addresses from
+.Fa testaddr
+to
+.Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
+inclusive.
+The filter function should return zero for any mapping in this range
+that can be accommodated by the device and non-zero otherwise.
+.It Vt bus_dma_segment_t
+A machine-dependent type that describes individual
+DMA segments.
+.Bd -literal
+	bus_addr_t	ds_addr;
+	bus_size_t	ds_len;
+.Ed
+.sp
+The
+.Fa ds_addr
+field contains the device visible address of the DMA segment, and
+.Fa ds_len
+contains the length of the DMA segment.
+Although the DMA segments returned by a mapping call will adhere to
+all restrictions necessary for a successful DMA operation, some conversion
+(e.g. a conversion from host byte order to the device's byte order) is
+almost always required when presenting segment information to the device.
+.It Vt bus_dmamap_t
+A machine-dependent opaque type describing an individual mapping.
+Multiple DMA maps can be associated with one DMA tag.
+.It Vt bus_dmamap_callback_t
+Client specified callback for receiving mapping information resulting from
+the load of a
+.Vt bus_dmamap_t
+via
+.Fn bus_dmamap_load .
+Callbacks are of the format:
+.Bl -tag -width compact
+.It Ft void
+.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \
+"int nseg" "int error"
+.El
+.sp
+The
+.Fa callback_arg
+is the callback argument passed to dmamap load functions.
+The 
+.Fa segs
+and
+.Fa nseg
+parameters describe an array of
+.Vt bus_dma_segment_t
+structures that represent the mapping.
+This array is only valid within the scope of the callback function.
+The success or failure of the mapping is indicated by the
+.Fa error
+parameter.
+More information on the use of callbacks can be found in the
+description of the individual dmamap load functions.
+.It Vt bus_dmamap_callback2_t
+Client specified callback for receiving mapping information resulting from
+the load of a
+.Vt bus_dmamap_t
+via
+.Fn bus_dmamap_load_uio
+or 
+.Fn bus_dmamap_load_mbuf .
+.sp
+Callback2s are of the format:
+.Bl -tag -width compact
+.It Ft void
+.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \
+"int nseg" "bus_size_t mapsize" "int error"
+.El
+.sp
+Callback2's behavior is the same as
+.Vt bus_dmamap_callback_t
+with the addition that the length of the data mapped is provided via
+.Fa mapsize .
+.It Vt bus_dmasync_op_t
+Memory synchronization operation specifier.
+Bus DMA requires explicit synchronization of memory with it's device
+visible mapping in order to guarantee memory coherency.
+The
+.Vt bus_dmasync_op_t
+allows the type of DMA operation that will be or has been performed
+to be communicated to the system so that the correct coherency measures
+are taken.
+All operations specified below are performed from the DMA engine's
+point of view:
+.Bl -tag -width BUS_DMASYNC_POSTWRITE
+.It Dv BUS_DMASYNC_PREREAD
+Perform any synchronization required after an update of memory by the CPU
+but prior to DMA read operations.
+.It Dv BUS_DMASYNC_PREWRITE
+Perform any synchronization required after an update of memory by the CPU
+but prior to DMA write operations.
+.It Dv BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE
+Perform any synchronization required prior to a combination of DMA read
+and write operations.
+.It Dv BUS_DMASYNC_POSTREAD
+Perform any synchronization required after DMA read operations, but prior
+to CPU access of the memory.
+.It Dv BUS_DMASYNC_POSTWRITE
+Perform any synchronization required after DMA write operations, but prior
+to CPU access of the memory.
+.It Dv BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE
+Perform any synchronization required after a combination of DMA read
+and write operations.
+.El
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \
+"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \
+"flags" "*dmat"
+Allocates a device specific DMA tag, and initializes it according to
+the arguments provided:
+.Bl -tag -width *filtfuncarg -compact
+.It Fa parent
+Indicates restrictions between the parent bridge, CPU memory, and the
+device.
+May be NULL, if no DMA restrictions are to be inherited.
+.It Fa alignment
+Alignment constraint, in bytes, of any mappings created using this tag.
+The alignment must be a power of 2.
+Hardware that can DMA starting at any address would specify
+.Em 1
+for byte alignment.
+Hardware requiring DMA transfers to start on a multiple of 4K
+would specify
+.Em 4096.
+.It Fa boundary
+Boundary constraint, in bytes, of the target DMA memory region.
+The boundary indicates the set of addresses, all multiples of the
+boundary argument, that cannot be crossed by a single
+.Vt bus_dma_segment_t .
+The boundary must be either a power of 2 or 0.
+.Ql 0
+indicates that there are no boundary restrictions.
+.It Fa lowaddr
+.It Fa highaddr
+Bounds of the window of bus address space that
+.Em cannot
+be directly accessed by the device.
+The window contains all address greater than lowaddr and
+less than or equal to highaddr.
+For example, a device incapable of DMA above 4GB, would specify
+a highaddr of
+.Dv BUS_SPACE_MAXADDR
+and a lowaddr of
+.Dv BUS_SPACE_MAXADDR_32BIT .
+Similarly a device that can only dma to addresses bellow 16MB would
+specify a highaddr of
+.Dv BUS_SPACE_MAXADDR
+and a lowaddr of
+.Dv BUS_SPACE_MAXADDR_24BIT .
+Some implementations requires that some region of device visible
+address space, overlapping available host memory, be outside the
+window.
+This area of
+.Ql safe memory
+is used to bounce requests that would otherwise conflict with
+the exclusion window.
+.It Fa filtfunc
+Optional filter function (may be NULL) to be called for any attempt to
+map memory into the window described by
+.Fa lowaddr
+and
+.Fa highaddr.
+A filter function is only required when the single window described
+by
+.Fa lowaddr
+and
+.Fa highaddr
+cannot adequately describe the constraints of the device.
+The filter function will be called for every machine page
+that overlaps the exclusion window.
+.It Fa filtfuncarg
+Argument passed to all calls to the filter function for this tag.
+May be NULL.
+.It Fa maxsegsz
+Maximum size, in bytes, of a segment in any DMA mapped region associated
+with
+.Fa dmat .
+.It Fa maxsize
+Maximum size, in bytes, of the sum of all segment lengths in a given
+DMA mapping associated with this tag.
+.It Fa nsegments
+Number of discontinuities (scatter/gather segments) allowed
+in a DMA mapped region.
+If there is no restriction, 
+.Dv BUS_SPACE_UNRESTRICTED
+may be specified.
+.It Fa flags
+Are as follows:
+.Bl -tag -width "BUS_DMA_ALLOCNOW" -compact
+.It Dv BUS_DMA_ALLOCNOW
+Allocate the resources necessary to guarantee that all map load
+operations associated with this tag will not block.
+If sufficient resources are not available,
+.Er ENOMEM
+is returned.
+.El
+.It Fa dmat
+Pointer to a bus_dma_tag_t where the resulting DMA tag will 
+be stored.
+.El
+.Pp
+Returns
+.Er ENOMEM
+if sufficient memory is not available for tag creation
+or allocating mapping resources.
+.It Fn bus_dma_tag_destroy "dmat"
+Deallocate the DMA tag
+.Fa dmat
+that was created by
+.Fn bus_dma_tag_create .
+.Pp
+Returns
+.Er EBUSY
+if any DMA maps remain associated with
+.Fa dmat
+or
+.Ql 0
+on success.
+.It Fn bus_dmamap_create "dmat" "flags" "*mapp"
+Allocates and initializes a DMA map.
+Arguments are as follows:
+.Bl -tag -width nsegments -compact
+.It Fa dmat
+DMA tag.
+.It Fa flags
+The value of this argument is currently undefined and should be
+specified as
+.Ql 0 .
+.It Fa mapp
+Pointer to a
+.Vt bus_dmamap_t
+where the resulting DMA map will be stored.
+.El
+.Pp
+Returns
+.Er ENOMEM
+if sufficient memory is not available for creating the
+map or allocating mapping resources.
+.It Fn bus_dmamap_destroy "dmat" "map"
+Frees all resources associated with a given DMA map.
+Arguments are as follows:
+.Bl -tag -width dmat -compact
+.It Fa dmat
+DMA tag used to allocate
+.Fa map .
+.It Fa map
+The DMA map to destroy.
+.El
+.Pp
+Returns
+.Er EBUSY
+if a mapping is still active for
+.Fa map .
+.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..."
+Creates a mapping in device visible address space of
+.Fa buflen
+bytes of
+.Fa buf ,
+associated with the DMA map
+.Fa map.
+Arguments are as follows:
+.Bl -tag -width buflen -compact
+.It Fa dmat
+DMA tag used to allocate
+.Fa map.
+.It Fa map
+A DMA map without a currently active mapping.
+.It Fa buf
+A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
+mapped into device visible address space.
+.It Fa buflen
+The size of the buffer.
+.It Fa callback Fa callback_arg
+The callback function, and its argument.
+.It Fa flags
+The value of this argument is currently undefined, and should be
+specified as
+.Ql 0 .
+.El
+.Pp
+Return values to the caller are as follows:
+.Bl -tag -width EINPROGRESS -compact
+.It 0
+The callback has been called and completed.
+The status of the mapping has been delivered to the callback.
+.It Er EINPROGRESS
+The mapping has been deferred for lack of resources.
+The callback will be called as soon as resources are available.
+Callbacks are serviced in FIFO order.
+DMA maps created from DMA tags that are allocated with
+the
+.Dv BUS_DMA_ALLOCNOW
+flag will never return this status for a load operation.
+.It Er EINVAL
+The load request was invalid.
+The callback has not, and will not be called.
+This error value may indicate that
+.Fa dmat ,
+.Fa map ,
+.Fa buf ,
+or
+.Fa callback
+were invalid, or
+.Fa buslen
+was larger than the
+.Fa maxsize
+argument used to create the dma tag
+.Fa dmat .
+.El
+.Pp
+When the callback is called, it is presented with an error value
+indicating the disposition of the mapping.
+Error may be one of the following:
+.Bl -tag -width EINPROGRESS -compact
+.It 0
+The mapping was successful and the
+.Fa dm_segs
+callback argument contains an array of
+.Vt bus_dma_segment_t
+elements describing the mapping.
+This array is only valid during the scope of the callback function.
+.It Er EFBIG
+A mapping could not be achieved within the segment constraints provided
+in the tag even though the requested allocation size was less than maxsize.
+.El
+.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \
+"flags"
+This is a variation of
+.Fn bus_dmamap_load
+which maps mbuf chains
+for DMA transfers.
+A
+.Vt bus_size_t
+argument is also passed to the callback routine, which
+contains the mbuf chain's packet header length.
+.Pp
+Mbuf chains are assumed to be in kernel virtual address space.
+.Pp
+Returns
+.Er EINVAL
+if the size of the mbuf chain exceeds the maximum limit of the
+DMA tag.
+.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags"
+This is a variation of
+.Fn bus_dmamap_load
+which maps buffers pointed to by
+.Fa uio
+for DMA transfers.
+A
+.Vt bus_size_t
+argument is also passed to the callback routine, which contains the size of
+.Fa uio ,
+i.e.
+.Fa uio->uio_resid .
+.Pp
+If
+.Fa uio->uio_segflg
+is
+.Dv UIO_USERSPACE ,
+then it is assumed that the buffer,
+.Fa uio
+is in
+.Fa "uio->uio_td->td_proc" Ns 's
+address space.
+User space memory must be in-core and wired prior to attempting a map
+load operation.
+.It Fn bus_dmamap_unload "dmat" "map"
+Unloads a DMA map.
+Arguments are as follows:
+.Bl -tag -width dmam -compact
+.It Fa dmat
+DMA tag used to allocate
+.Fa map .
+.It Fa map
+The DMA map that is to be unloaded.
+.El
+.Pp
+.Fn bus_dmamap_unload
+will not perform any implicit synchronization of DMA buffers.
+This must be done explicitly by a call to
+.Fn bus_dmamap_sync
+prior to unloading the map.
+.It Fn bus_dmamap_sync "dmat" "map" "op"
+Performs synchronization of a device visible mapping with the CPU visible
+memory referenced by that mapping.
+Arguments are as follows:
+.Bl -tag -width dmat -compact
+.It Fa dmat
+DMA tag used to allocate
+.Fa map .
+.It Fa map
+The DMA mapping to be synchronized.
+.It Fa op
+Type of synchronization operation to perform.
+See the definition of
+.Vt bus_dmasync_op_t
+for a description of the acceptable values for
+.Fa op .
+.El
+.Pp
+.Fn bus_dmamap_sync
+is the method used to ensure that CPU and device DMA access to shared
+memory is coherent.
+For example, the CPU might be used to setup the contents of a buffer
+that is to be DMA'ed into a device.
+To ensure that the data are visible via the device's mapping of that
+memory, the buffer must be loaded and a dma sync operation of
+.Dv BUS_DMASYNC_PREREAD
+must be performed.
+Additional sync operations must be performed after every CPU write
+to this memory if additional DMA reads are to be performed.
+Conversely, for the DMA write case, the buffer must be loaded,
+and a dma sync operation of
+.Dv BUS_DMASYNC_PREWRITE
+must be performed.
+The CPU will only be able to see the results of this DMA write
+once the DMA has completed and a
+.Dv BUS_DMASYNC_POSTWRITE
+operation has been performed.
+.Pp
+If DMA read and write operations are not preceded and followed by the
+appropriate synchronization operations, behavior is undefined.
+.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp"
+Allocates memory that is mapped into KVA at the address returned
+in
+.Fa vaddr
+that is permanently loaded into the newly created
+.Vt bus_dmamap_t
+returned via
+.Fa mapp .
+Arguments are as follows:
+.Bl -tag -width alignment -compact
+.It Fa dmat 
+DMA tag describing the constraints of the DMA mapping.
+.It Fa vaddr
+Pointer to a pointer that will hold the returned KVA mapping of
+the allocated region.
+.It Fa flags
+Flags are defined as follows:
+.Bl -tag -width BUS_DMA_NOWAIT -compact
+.It Dv BUS_DMA_WAITOK
+The routine can safely wait (sleep) for resources.
+.It Dv BUS_DMA_NOWAIT
+The routine is not allowed to wait for resources.
+If resources are not available, 
+.Dv ENOMEM
+is returned.
+.It Dv BUS_DMA_COHERENT
+Attempt to map this memory such that cache sync operations are
+as cheap as possible.
+This flag is typically set on memory that will be accessed by both
+a CPU and a DMA engine, frequently.
+Use of this flag does not remove the requirement of using
+bus_dmamap_sync, but it may reduce the cost of performing
+these operations.
+.El
+.It Fa mapp
+Pointer to storage for the returned DMA map.
+.El
+.Pp
+The size of memory to be allocated is
+.Fa maxsize
+as specified in
+.Fa dmat .
+.Pp
+The current implementation of
+.Fn bus_dmamem_alloc
+will allocate all requests as a single segment.
+.Pp
+Although no explicit loading is required to access the memory
+referenced by the returned map, the synchronization requirements
+as described in the
+.Fn bus_dmamap_sync
+section still apply.
+.Pp
+Returns
+.Er ENOMEM
+if sufficient memory is not available for completing
+the operation.
+.It Fn bus_dmamem_free "dmat" "*vaddr" "map"
+Frees memory previously allocated by
+.Fn bus_dmamem_alloc .
+Any mappings
+will be invalidated.
+Arguments are as follows:
+.Bl -tag -width vaddr -compact
+.It Fa dmat
+DMA tag.
+.It Fa vaddr
+Kernel virtual address of the memory.
+.It Fa map
+DMA map to be invalidated.
+.El
+.El
+.Sh RETURN VALUES
+Behavior is undefined if invalid arguments are passed to
+any of the above functions.
+If sufficient resources cannot be allocated for a given
+transaction,
+.Er ENOMEM
+is returned.
+All
+routines that are not of type,
+.Vt void ,
+will return 0 on success or an error
+code, as discussed above.
+.Pp
+All
+.Vt void
+routines will succeed if provided with valid arguments.
+.Sh SEE ALSO
+.Xr devclass 9 ,
+.Xr device 9 ,
+.Xr driver 9 ,
+.Xr rman 9
+.Pp
+.Rs
+.%A "Jason R. Thorpe"
+.%T "A Machine-Independent DMA Framework for NetBSD"
+.%J "Proceedings of the Summer 1998 USENIX Technical Conference"
+.%Q "USENIX Association"
+.%D "June 1998"
+.Re
+.Sh HISTORY
+The
+.Nm
+interface first appeared in
+.Nx 1.3 .
+.Pp
+The
+.Nm
+API was adopted from
+.Nx
+for use in the CAM SCSI subsystem.
+The alterations to the original API were aimed to remove the need for
+a
+.Vt bus_dma_segment_t
+array stored in each
+.Vt bus_dmamap_t
+while allowing callers to queue up on scarce resources.
+.Sh AUTHORS
+The
+.Nm
+interface was designed and implemented by Jason R. Thorpe of the
+Numerical Aerospace Simulation Facility, NASA Ames Research Center.
+Additional input on the
+.Nm
+design was provided by Chris Demetriou, Charles Hannum, Ross Harvey,
+Matthew Jacob, Jonathan Stone, and Matt Thomas.
+.Pp
+The
+.Nm
+interface in
+.Fx
+benefits from the contributions of Justin T. Gibbs,
+Peter Wemm, Doug Rabson, Matthew N. Dodd, Sam Leffler,
+Maxime Henrion, Jake Burkholder, Takahashi Yoshihiro,
+Scott Long and many others.
+.Pp
+This manual page was written by Hiten M. Pandya and Justin T. Gibbs.