First attempt at porting bus_dma.9 from NetBSD.

Changes to bus_dma.9 from NetBSD v1.14:

1) Delete two parameters (3rd & 4th) from bus_dmamap_sync (offset &
len)

2) Delete dm_mapsize as a 'required' member of bus_dmamap_t (only
present in vax/bus.h and alpha/bus.h)

3) Usual OpenBSD style-istic changes: no trailing white space, new
lines for all sentences, reparagraph to eliminate short lines

** Issues with bus_dma.9 **

vax/bus.h still defines two parameters in bus_dmamap_sync() that are
removed elsewhere (offset & len)

1 files changed, 737 insertions, 0 deletions

diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9
new file mode 100644
index 00000000000..09649337219
--- /dev/null
+++ b/share/man/man9/bus_dma.9
@@ -0,0 +1,737 @@
+.\"	$OpenBSD: bus_dma.9,v 1.3 2001/02/22 00:54:01 krw Exp $ 
+.\" $NetBSD: bus_dma.9,v 1.14 2000/06/14 06:49:19 cgd Exp $
+.\"
+.\" Copyright (c) 1996, 1997, 1998 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.
+.\"
+.Dd November 23, 2000
+.Dt BUS_DMA 9
+.Os
+.Sh NAME
+.Nm bus_dma ,
+.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_load_raw ,
+.Nm bus_dmamap_unload ,
+.Nm bus_dmamap_sync ,
+.Nm bus_dmamem_alloc ,
+.Nm bus_dmamem_free ,
+.Nm bus_dmamem_map ,
+.Nm bus_dmamem_unmap ,
+.Nm bus_dmamem_mmap
+.Nd bus and machine independent DMA mapping interface
+.Sh SYNOPSIS
+.Fd #include <machine/bus.h>
+.Ft int
+.Fn bus_dmamap_create "bus_dma_tag_t tag" "bus_size_t size" "int nsegments" \
+"bus_size_t maxsegsz" "bus_size_t boundary" "int flags" "bus_dmamap_t *dmamp"
+.Ft void
+.Fn bus_dmamap_destroy "bus_dma_tag_t tag" "bus_dmamap_t dmam"
+.Ft int
+.Fn bus_dmamap_load "bus_dma_tag_t tag" "bus_dmamap_t dmam" "void *buf" \
+"bus_size_t buflen" "struct proc *p" "int flags"
+.Ft int
+.Fn bus_dmamap_load_mbuf "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
+"struct mbuf *chain" "int flags"
+.Ft int
+.Fn bus_dmamap_load_uio "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
+"struct uio *uio" "int flags"
+.Ft int
+.Fn bus_dmamap_load_raw "bus_dma_tag_t tag" "bus_dmamap_t dmam" \
+"bus_dma_segment_t *segs" "int nsegs" "bus_size_t size" "int flags"
+.Ft void
+.Fn bus_dmamap_unload "bus_dma_tag_t tag" "bus_dmamap_t dmam"
+.Ft void
+.Fn bus_dmamap_sync "bus_dma_tag_t tag" "bus_dmamap_t dmam" "int ops"
+.Ft int
+.Fn bus_dmamem_alloc "bus_dma_tag_t tag" "bus_size_t size" \
+"bus_size_t alignment" "bus_size_t boundary" "bus_dma_segment_t *segs" \
+"int nsegs" "int *rsegs" "int flags"
+.Ft void
+.Fn bus_dmamem_free "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs"
+.Ft int
+.Fn bus_dmamem_map "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" \
+"size_t size" "caddr_t *kvap" "int flags"
+.Ft void
+.Fn bus_dmamem_unmap "bus_dma_tag_t tag" "caddr_t kva" "size_t size"
+.Ft int
+.Fn bus_dmamem_mmap "bus_dma_tag_t tag" "bus_dma_segment_t *segs" \
+"int nsegs" "int off" "int prot" "int flags"
+.Sh DESCRIPTION
+The
+.Nm
+interface provides a bus and machine independent mechanism
+for managing DMA data transfers to and from devices.
+.Pp
+The basic abstraction is the bus_dmamap_t, a pointer to a structure
+which contains an array of bus_dma_segment_t's (dm_segs) and a count
+of how many are currently valid (dm_nsegs).
+.Pp
+Each segment in the array describes a single physical area of memory
+which can be DMA'd, with a starting address (ds_addr) and a length
+(ds_len).
+These are the values that must be communicated to the DMA device.
+Taken together the segments exactly and completely describe the buffer
+being used to transfer data.
+.Pp
+bus_dma_tag_t's are an opaque type, received from higher software
+layers and are never created, changed, deleted or even examined in
+this interface.
+.Pp
+The basic cycle to transfer data to/from a dma device is:
+.Bd -literal
+bus_dmamap_create();         /* get a dmamap to load/unload          */
+
+for each dma xfer {
+        bus_dmamem_alloc();  /* allocate some DMA'able memory        */
+        bus_dmamem_map();    /* map it into the kernel address space */
+
+        /*
+         * Fill the allocated DMA'able memory with whatever data
+         * is to be sent out, using the pointer obtained with
+         * bus_dmamem_map().
+         */
+
+        bus_dmamap_load();   /* initialize the segments of dmamap    */
+        bus_dmamap_sync();   /* synchronize/flush any dma cache      */
+
+        for (i=0; i<dm_nsegs; i++) {
+                /*
+                 * Tell the DMA device the physical address
+                 * (dmamap->dm_segs[i].ds_addr) and the length
+                 * (dmamap->dm_segs[i].ds_len) of the memory to xfer.
+                 *
+                 * Start the DMA, wait until it's done
+                 */
+        }
+
+        bus_dmamap_sync();   /* synchronize/flush any dma cache      */
+        bus_dmamap_unload(); /* prepare dmamap for reuse             */
+
+        /*
+         * copy any data desired from the DMA'able memory using the
+         * pointer created by bus_dmamem_map().
+         */
+
+        bus_dmamem_unmap();  /* free kernel virtual address space    */
+        bus_dmamem_free();   /* free DMA'able memory                 */
+}
+
+bus_dmamap_destroy();        /* release any resources used by dmamap */
+.Ed
+.Sh NOTES
+All data structures, function prototypes, and macros are defined in
+the architecture-specific header
+.Pa Aq machine/bus.h .
+Note that this document assumes the existence of types already defined
+by the current "bus.h" interface.
+.Pp
+Unless otherwise noted, all function calls in this interface may be
+defined as
+.Xr cpp 1
+macros.
+.Sh DATA TYPES
+Individual implementations may name these structures whatever they wish,
+providing that the external representations are:
+.Bl -tag -width compact
+.It Fa bus_dma_tag_t
+A machine-dependent opaque type describing the implementation of DMA for
+a given bus.
+.It Fa bus_dma_segment_t
+A structure with at least the following members:
+.Bd -literal
+	bus_addr_t	ds_addr;
+	bus_size_t	ds_len;
+.Ed
+.sp
+The structure may have machine-dependent members and arbitrary layout.
+The values in
+.Fa ds_addr
+and
+.Fa ds_len
+are suitable for programming into DMA controller address and length
+registers.
+.It Fa bus_dmamap_t
+A pointer to a structure with at least the following members:
+.Bd -literal
+	int		   dm_nsegs;
+	bus_dma_segment_t *dm_segs;
+.Ed
+.sp
+The structure may have machine-dependent members and arbitrary layout.
+The
+.Fa dm_segs
+member may be an array of segments or a pointer to an array of segments.
+The
+.Fa dm_nsegs
+member indicates the number of segments in
+.Fa dm_segs .
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn bus_dmamap_create "tag" "size" "nsegments" "maxsegsz" "boundary" "flags" "dmamp"
+Allocates a DMA handle and initializes it according to the parameters
+provided.
+Arguments are as follows:
+.Bl -tag -width nsegments -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa size
+This is the maximum DMA transfer that can be mapped by the handle.
+.It Fa nsegments
+Number of segments the device can support in a single DMA transaction.
+This may be the number of scatter-gather descriptors supported by the
+device.
+.It Fa maxsegsz
+The maximum number of bytes that may be transferred by any given DMA
+segment.
+.It Fa boundary
+Some DMA controllers are not able to transfer data that crosses a
+particular boundary.
+This argument allows this boundary to be specified.
+The boundary lines begin at 0, and occur every
+.Fa boundary
+bytes.
+Mappings may begin on a boundary line but may not end on or cross a
+boundary line.
+If no boundary condition needs to be observed, a
+.Fa boundary
+argument of 0 should be used.
+.It Fa flags
+Flags are defined as follows:
+.Bl -tag -width BUS_DMA_ALLOCNOW -compact
+.It Dv BUS_DMA_WAITOK
+It is safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_NOWAIT
+It is not safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_ALLOCNOW
+Perform any resource allocation this handle may need now.
+If this is not specified, the allocation may be deferred to
+.Fn bus_dmamap_load .
+If this flag is specified,
+.Fn bus_dmamap_load
+will not block on resource allocation.
+.It Dv BUS_DMA_BUS[1-4]
+These flags are placeholders, and may be used by busses to provide
+bus-dependent functionality.
+.El
+.It Fa dmamp
+This is a pointer to a bus_dmamap_t.
+A DMA map will be allocated and pointed to by
+.Fa dmamp
+upon successful completion of this routine.
+.El
+.Pp
+Behavior is not defined if invalid arguments are passed to
+.Fn bus_dmamap_create .
+.Pp
+Returns 0 on success, or an error code to indicate mode of failure.
+.It Fn bus_dmamap_destroy "tag" "dmam"
+Frees all resources associated with a given DMA handle.
+Arguments are as follows:
+.Bl -tag -width dmam -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa dmam
+The DMA handle to destroy.
+.El
+.Pp
+In the event that the DMA handle contains a valid mapping, the mapping
+will be unloaded via the same mechanism used by
+.Fn bus_dmamap_unload .
+.Pp
+Behavior is not defined if invalid arguments are passed to
+.Fn bus_dmamap_destroy .
+.Pp
+If given valid arguments,
+.Fn bus_dmamap_destroy
+always succeeds.
+.It Fn bus_dmamap_load "tag" "dmam" "buf" "buflen" "p" "flags"
+Loads a DMA handle with mappings for a DMA transfer.
+It assumes that all pages involved in a DMA transfer are wired.
+Arguments are as follows:
+.Bl -tag -width buflen -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa dmam
+The DMA handle with which to map the transfer.
+.It Fa buf
+The buffer to be used for the DMA transfer.
+.It Fa buflen
+The size of the buffer.
+.It Fa p
+Used to indicate the address space in which the buffer is located.
+If
+.Dv NULL ,
+the buffer is assumed to be in kernel space.
+Otherwise, the buffer is assumed to be in process
+.Fa p Ns 's
+address space.
+.It Fa flags
+are defined as follows:
+.Bl -tag -width "BUS_DMA_BUS[1-4]" -compact
+.It Dv BUS_DMA_WAITOK
+It is safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_NOWAIT
+It is not safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_BUS[1-4]
+These flags are placeholders, and may be used by busses to provide
+bus-dependent functionality.
+.El
+.El
+.Pp
+As noted above, if a DMA handle is created with
+.Dv BUS_DMA_ALLOCNOW ,
+.Fn bus_dmamap_load
+will never block.
+.Pp
+If a call to
+.Fn bus_dmamap_load
+fails, the mapping in the DMA handle will be invalid.
+It is the responsibility of the caller to clean up any inconsistent
+device state resulting from incomplete iteration through the uio.
+.Pp
+Behavior is not defined if invalid arguments are passed to
+.Fn bus_dmamap_load .
+.Pp
+Returns 0 on success, or an error code to indicate mode of failure.
+.It Fn bus_dmamap_load_mbuf "tag" "dmam" "chain" "flags"
+This is a variation of
+.Fn bus_dmamap_load
+which maps mbuf chains for DMA transfers.
+Mbuf chains are assumed to be in kernel virtual address space.
+.It Fn bus_dmamap_load_uio "tag" "dmam" "uio" "flags"
+This is a variation of
+.Fn bus_dmamap_load
+which maps buffers pointed to by
+.Fa uio
+for DMA transfers.
+The value of
+.Fa "uio->uio_segflg"
+will determine if the buffers are in user or kernel virtual address
+space.
+If the buffers are in user address space, the buffers are assumed to be
+in
+.Fa "uio->uio_procp" Ns 's
+address space.
+.It Fn bus_dmamap_load_raw "tag" "dmam" "segs" "nsegs" "size" "flags"
+This is a variation of
+.Fn bus_dmamap_load
+which maps buffers allocated by
+.Fn bus_dmamem_alloc
+(see below).
+The
+.Fa segs
+argument is an array of bus_dma_segment_t's filled in by
+.Fn bus_dmamem_alloc .
+The
+.Fa nsegs
+argument is the number of segments in the array.
+The
+.Fa size
+argument is the size of the DMA transfer.
+.It Fn bus_dmamap_unload "tag" "dmam"
+Deletes the mappings for a given DMA handle.
+Arguments are as follows:
+.Bl -tag -width dmam -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa dmam
+The DMA handle containing the mappings which are to be deleted.
+.El
+.Pp
+If the DMA handle was created with
+.Dv BUS_DMA_ALLOCNOW ,
+.Fn bus_dmamap_unload
+will not free the corresponding resources which were allocated by
+.Fn bus_dmamap_create .
+This is to ensure that
+.Fn bus_dmamap_load
+will never block on resources if the handle was created with
+.Dv BUS_DMA_ALLOCNOW .
+.Pp
+Behavior is not defined if invalid arguments are passed to
+.Fn bus_dmamap_unload .
+.Pp
+If given valid arguments,
+.Fn bus_dmamap_unload
+always succeeds.
+.It Fn bus_dmamap_sync "tag" "dmam" "ops"
+Performs pre- and post-DMA operation cache and/or buffer synchronization.
+Arguments are as follows:
+.Bl -tag -width offset -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa dmam
+The DMA mapping to be synchronized.
+.It Fa ops
+One or more synchronization operation to perform.
+The following DMA synchronization operations are defined:
+.Bl -tag -width BUS_DMASYNC_POSTWRITE -compact
+.It Dv BUS_DMASYNC_PREREAD
+Perform any pre-read DMA cache and/or bounce operations.
+.It Dv BUS_DMASYNC_POSTREAD
+Perform any post-read DMA cache and/or bounce operations.
+.It Dv BUS_DMASYNC_PREWRITE
+Perform any pre-write DMA cache and/or bounce operations.
+.It Dv BUS_DMASYNC_POSTWRITE
+Perform any post-write DMA cache and/or bounce operations.
+.El
+.Pp
+More than one operation may performed in a given synchronization call.
+Mixing of
+.Em PRE
+and
+.Em POST
+operations is not allowed, and behavior is undefined if this is attempted.
+.El
+.Pp
+Synchronization operations are expressed from the perspective of the
+host RAM, e.g. a
+.Em "device -> memory"
+operation is a
+.Em READ
+and a
+.Em "memory -> device"
+operation is a
+.Em WRITE .
+.Pp
+.Fn bus_dmamap_sync
+may consult state kept within the DMA map to determine if the memory is
+mapped in a DMA coherent fashion.
+If so,
+.Fn bus_dmamap_sync
+may elect to skip certain expensive operations, such as flushing of the
+data cache.
+See
+.Fn bus_dmamem_map
+for more information on this subject.
+.Pp
+On platforms which implement reordered stores,
+.Fn bus_dmamap_sync
+will always cause the store buffer to be flushed.
+.Pp
+This function exists so that multiple read and write transfers can be
+performed with the same buffer, and so that drivers can explicitly
+inform the
+.Nm
+code when their data is 'ready' in its DMA buffer.
+.Pp
+An example of multiple read-write use of a single mapping
+might look like:
+.Bd -literal
+bus_dmamap_load(...);
+
+while (not done) {
+	/* invalidate soon-to-be-stale cache blocks */
+	bus_dmamap_sync(..., BUS_DMASYNC_PREREAD);
+
+	[ do read DMA ]
+
+	/* copy from bounce */
+	bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD);
+
+	/* read data now in driver-provided buffer */
+
+	[ computation ]
+
+	/* data to be written now in driver-provided buffer */
+
+	/* flush write buffers and writeback, copy to bounce */
+	bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE);
+
+	[ do write DMA ]
+
+	/* probably a no-op, but provided for consistency */
+	bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE);
+}
+
+bus_dmamap_unload(...);
+.Ed
+.Pp
+If DMA read and write operations are not preceded and followed by the
+appropriate synchronization operations, behavior is undefined.
+.Pp
+Behavior is not defined if invalid arguments are passed to
+.Fn bus_dmamap_sync .
+.Pp
+If given valid arguments,
+.Fn bus_dmamap_sync
+always succeeds.
+.\" XXX: This does not work with all the arguments.
+.It Fn bus_dmamem_alloc "tag" "size" "alignment" "boundary" "segs" "..."
+Allocates memory that is "DMA safe" for the bus corresponding to the
+given tag.
+.Pp
+The mapping of this memory is machine-dependent (or "opaque");
+machine-independent code is not to assume that the addresses returned
+are valid in kernel virtual address space, or that the addresses
+returned are system physical addresses.
+The address value returned as part of
+.Fa segs
+can thus not be used to program DMA controller address registers.
+Only the values in the
+.Fa dm_segs
+array of a sucessfully loaded DMA map (using
+.Fn bus_dmamap_load
+) can be used for this purpose.
+.Pp
+Allocations will always be rounded to the hardware page size.
+Callers may wish to take advantage of this, and cluster allocation of
+small data structures.
+Arguments are as follows:
+.Bl -tag -width alignment -compact
+.It Fa tag
+The is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa size
+The amount of memory to allocate.
+.It Fa alignment
+Each segment in the allocated memory will be aligned to this value.
+If the alignment is less than a hardware page size, it will be rounded
+up to the hardware page size.
+This value must be a power of two.
+.It Fa boundary
+Each segment in the allocated memory must not cross this boundary
+(relative to zero).
+This value must be a power of two.
+A boundary value less than the size of the allocation is invalid.
+.It Fa segs
+An array of bus_dma_segment_t's, filled in as memory is allocated,
+representing the opaque addresses of the memory chunks.
+.It Fa nsegs
+Specifies the number of segments in
+.Fa segs ,
+and this is the maximum number of segments that the allocated memory may
+contain.
+.It Fa rsegs
+Used to return the actual number of segments the memory contains.
+.It Fa flags
+Flags are defined as follows:
+.Bl -tag -width BUS_DMA_BUS[1-4] -compact
+.It Dv BUS_DMA_WAITOK
+It is safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_NOWAIT
+It is not safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_BUS[1-4]
+These flags are placeholders, and may be used by busses to provide
+bus-dependent functionality.
+.El
+.El
+.Pp
+All pages allocated by
+.Fn bus_dmamem_alloc
+will be wired down until they are freed by
+.Fn bus_dmamem_free .
+.Pp
+Behavior is undefined if invalid arguments are passed to
+.Fn bus_dmamem_alloc .
+.Pp
+Returns 0 on success, or an error code indicating mode of failure.
+.It Fn bus_dmamem_free "tag" "segs" "nsegs"
+Frees memory previously allocated by
+.Fn bus_dmamem_alloc .
+Any mappings will be invalidated.
+Arguments are as follows:
+.Bl -tag -width nsegs -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa segs
+The array of bus_dma_segment_t's filled in by
+.Fn bus_dmamem_alloc .
+.It Fa nsegs
+The number of segments in
+.Fa segs .
+.El
+.Pp
+Behavior is undefined if invalid arguments are passed to
+.Fn bus_dmamem_free .
+.Pp
+If given valid arguments,
+.Fn bus_dmamem_free
+always succeeds.
+.It Fn bus_dmamem_map "tag" "segs" "nsegs" "size" "kvap" "flags"
+Maps memory allocated with
+.Fn bus_dmamem_alloc
+into kernel virtual address space.
+Arguments are as follows:
+.Bl -tag -width flags -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa segs
+The array of bus_dma_segment_t's filled in by
+.Fn bus_dmamem_alloc ,
+representing the memory regions to map.
+.It Fa nsegs
+The number of segments in
+.Fa segs .
+.It Fa size
+The size of the mapping.
+.It Fa kvap
+Filled in to specify the kernel virtual address where the memory is
+mapped.
+.It Fa flags
+Flags are defined as follows:
+.Bl -tag -width BUS_DMA_COHERENT -compact
+.It Dv BUS_DMA_WAITOK
+It is safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_NOWAIT
+It is not safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_BUS[1-4]
+These flags are placeholders, and may be used by busses to provide
+bus-dependent functionality.
+.It Dv BUS_DMA_COHERENT
+This flag is a
+.Em hint
+to machine-dependent code.
+If possible, map the memory in such a way as it will be DMA coherent.
+This may include mapping the pages into uncached address space or
+setting the cache-inhibit bits in page table entries.
+If implementation of DMA coherent mappings is impossible, this is
+ignored.
+.Pp
+Later, when this memory is loaded into a DMA map, machine-dependent code
+will take whatever steps are necessary to determine if the memory was
+mapped in a DMA coherent fashion.
+This may include checking if the kernel virtual address lies within
+uncached address space or if the cache-inhibit bits are set in page
+table entries.
+If it is determined that the mapping is DMA coherent, state may be
+placed into the DMA map for use by later calls to
+.Fn bus_dmamap_sync .
+.El
+.El
+.Pp
+Behavior is undefined if invalid arguments are passed to
+.Fn bus_dmamem_map .
+.Pp
+Returns 0 on success, or an error code indicating mode of failure.
+.It Fn bus_dmamem_unmap "tag" "kva" "size"
+Unmaps memory previously mapped with
+.Fn bus_dmamem_map ,
+freeing the kernel virtual address space used by the mapping.
+The arguments are as follows:
+.Bl -tag -width size -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa kva
+The kernel virtual address of the mapped memory.
+.It Fa size
+The size of the mapping.
+.El
+.Pp
+Behavior is undefined if invalid arguments are passed to
+.Fn bus_dmamem_unmap .
+.Pp
+If given valid arguments,
+.Fn bus_dmamem_unmap
+always succeeds.
+.It Fn bus_dmamem_mmap "tag" "segs" "nsegs" "off" "prot" "flags"
+Provides support for user
+.Xr mmap 2 Ns 'ing
+of DMA-safe memory.
+This function is to be called by a device driver's (*d_mmap)() entry
+point, which is called by the device pager for each page to be mapped.
+The arguments are
+as follows:
+.Bl -tag -width nsegs -compact
+.It Fa tag
+This is the bus_dma_tag_t passed down from the parent driver via
+.Fa <bus>_attach_args .
+.It Fa segs
+The array of bus_dma_segment_t's filled in by
+.Fn bus_dmamem_alloc ,
+representing the memory to be
+.Xr mmap 2 Ns 'ed.
+.It Fa nsegs
+The number of elements in the
+.Fa segs
+array.
+.It Fa off
+The offset of the page in DMA memory which is to be mapped.
+.It Fa prot
+The protection codes for the mapping.
+.It Fa flags
+Flags are defined as follows:
+.Bl -tag -width BUS_DMA_COHERENT -compact
+.It Dv BUS_DMA_WAITOK
+It is safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_NOWAIT
+It is not safe to wait (sleep) for resources during this call.
+.It Dv BUS_DMA_BUS[1-4]
+These flags are placeholders, and may be used by busses to provide
+bus-dependent functionality.
+.It Dv BUS_DMA_COHERENT
+See
+.Fn bus_dmamem_map
+above for a description of this flag.
+.El
+.El
+.Pp
+Behavior is undefined if invalid arguments are passed
+to
+.Fn bus_dmamem_mmap .
+.Pp
+Returns -1 to indicate failure.
+Otherwise, returns an opaque value to be interpreted by the device
+pager.
+.El
+.Sh SEE ALSO
+.Xr bus_space 9
+.Sh AUTHOR
+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.
+.Sh HISTORY
+The
+.Nm
+interface appeared in
+.Nx 1.3 .