.\"	$OpenBSD: bus_dma.9,v 1.10 2002/03/07 18:09:24 jason 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" "bus_dmasync_op_t 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 paddr_t
.Fn bus_dmamem_mmap "bus_dma_tag_t tag" "bus_dma_segment_t *segs" \
"int nsegs" "off_t 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_STREAMING" -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_STREAMING
By default, the
.Nm
API assumes that there is coherency between memory and the device
performing the DMA transaction.  Some platforms, however, have
special hardware, such as an
.Dq I/O cache ,
which may improve performance
of some types of DMA transactions, but which break the assumption
that there is coherency between memory and the device performing
the DMA transaction.
This flag allows the use of this special hardware, provided that
the device is doing sequential, unidirectional transfers which
conform to certain alignment and size constraints defined by the
platform.  If the platform does not support the feature, or if
the buffer being loaded into the DMA map does not conform to the
constraints required for use of the feature, then this flag will
be silently ignored.  Also refer to the use of this flag with the
.Fn bus_dmamem_alloc
function.
.It Dv BUS_DMA_READ
This is a hint to the machine-dependent back-end that indicates the  
mapping will be used only for a
.Em "device -\*[Gt] memory"
transaction.  The back-end may perform optimizations based on this
information.
.It Dv BUS_DMA_WRITE
This is a hint to the machine-dependent back-end that indicates the
mapping will be used only for a
.Em "memory -\*[Gt] device"
transaction.  The back-end may perform optimizations based on this
information.
.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 successfully 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_STREAMING -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_STREAMING
Adjusts, if necessary, the size, alignment, and boundary constrains
to conform to the platform-dependent requirements for the use of the
.Dv BUS_DMA_STREAMING
flag with the
.Fn bus_dmamap_load
function.  If the platform does not support the  
.Dv BUS_DMA_STREAMING
feature, or if the size, alignment, and boundary constraints
would already satisfy the platform's requirements, this flag
is silently ignored.  The
.Dv BUS_DMA_STREAMING
flag will never relax the constraints specified in the 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 .
This function must not be called from an interrupt context.
.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 .
This function must not be called from an interrupt context.
.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 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.
.Sh HISTORY
The
.Nm
interface appeared in
.Nx 1.3 .