.\" $NetBSD: bus_dma.9,v 1.79 2024/10/09 22:13:21 uwe Exp $
.\"
.\" Copyright (c) 1996, 1997, 1998, 2001, 2005, 2006 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.
.\"
.\" 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 February 17, 2024
.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 ,
.Nm bus_dmatag_subregion ,
.Nm bus_dmatag_destroy
.Nd Bus and Machine Independent DMA Mapping Interface
.
.Sh SYNOPSIS
.
.In sys/bus.h
.
.Ft int
.Fo bus_dmamap_create
.Fa "bus_dma_tag_t tag"
.Fa "bus_size_t size"
.Fa "int nsegments"
.Fa "bus_size_t maxsegsz"
.Fa "bus_size_t boundary"
.Fa "int flags"
.Fa "bus_dmamap_t *dmamp"
.Fc
.
.Ft void
.Fo bus_dmamap_destroy
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fc
.
.Ft int
.Fo bus_dmamap_load
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fa "void *buf"
.Fa "bus_size_t buflen"
.Fa "struct proc *p"
.Fa "int flags"
.Fc
.
.Ft int
.Fo bus_dmamap_load_mbuf
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fa "struct mbuf *chain"
.Fa "int flags"
.Fc
.
.Ft int
.Fo bus_dmamap_load_uio
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fa "struct uio *uio"
.Fa "int flags"
.Fc
.
.Ft int
.Fo bus_dmamap_load_raw
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fa "bus_dma_segment_t *segs"
.Fa "int nsegs"
.Fa "bus_size_t size"
.Fa "int flags"
.Fc
.
.Ft void
.Fo bus_dmamap_unload
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fc
.
.Ft void
.Fo bus_dmamap_sync
.Fa "bus_dma_tag_t tag"
.Fa "bus_dmamap_t dmam"
.Fa "bus_addr_t offset"
.Fa "bus_size_t len"
.Fa "int ops"
.Fc
.
.Ft int
.Fo bus_dmamem_alloc
.Fa "bus_dma_tag_t tag"
.Fa "bus_size_t size"
.Fa "bus_size_t alignment"
.Fa "bus_size_t boundary"
.Fa "bus_dma_segment_t *segs"
.Fa "int nsegs"
.Fa "int *rsegs"
.Fa "int flags"
.Fc
.
.Ft void
.Fo bus_dmamem_free
.Fa "bus_dma_tag_t tag"
.Fa "bus_dma_segment_t *segs"
.Fa "int nsegs"
.Fc
.
.Ft int
.Fo bus_dmamem_map
.Fa "bus_dma_tag_t tag"
.Fa "bus_dma_segment_t *segs"
.Fa "int nsegs"
.Fa "size_t size"
.Fa "void **kvap"
.Fa "int flags"
.Fc
.
.Ft void
.Fo bus_dmamem_unmap
.Fa "bus_dma_tag_t tag"
.Fa "void *kva"
.Fa "size_t size"
.Fc
.
.Ft paddr_t
.Fo bus_dmamem_mmap
.Fa "bus_dma_tag_t tag"
.Fa "bus_dma_segment_t *segs"
.Fa "int nsegs"
.Fa "off_t off"
.Fa "int prot"
.Fa "int flags"
.Fc
.
.Ft int
.Fo bus_dmatag_subregion
.Fa "bus_dma_tag_t tag"
.Fa "bus_addr_t min_addr"
.Fa "bus_addr_t max_addr"
.Fa "bus_dma_tag_t *newtag"
.Fa "int flags"
.Fc
.
.Ft void
.Fo bus_dmatag_destroy
.Fa "bus_dma_tag_t tag"
.Fc
.
.Sh DESCRIPTION
Provide a bus- and machine-independent
.Dq Tn DMA No mapping interface .
.
.Ss Implementation Notes
All data types and constants will be defined
by the port-specific header
.In machine/bus_defs.h .
All functions will be defined
by the port-specific header
.In machine/bus_funcs.h .
Note that this document
assumes the existence of types already defined by the current
.Xr bus_space 9
interface.
.Pp
Unless otherwise noted, all function calls in this interface may be
defined as
.Xr cpp 1
macros.
.Ss Data Types
Individual implementations may name these structures whatever they
wish, providing that the external representations are:
.Bl -tag -width Vt
.It Vt bus_dma_tag_t
A machine-dependent opaque type describing the implementation of
DMA for a given bus.
.It Vt bus_dma_segment_t
A structure with at least the following members:
.Bd -literal -offset indent
bus_addr_t      ds_addr;
bus_size_t      ds_len;
.Ed
.Pp
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 Vt bus_dmamap_t
A pointer to a structure with at least the following members:
.Bd -literal -offset indent
bus_size_t      dm_maxsegsz;
bus_size_t      dm_mapsize;
int             dm_nsegs;
bus_dma_segment_t *dm_segs;
.Ed
.Pp
The structure may have machine-dependent members and arbitrary layout.
The
.Fa dm_maxsegsz
member indicates the maximum number of bytes that may be transferred by
any given DMA segment.
The
.Fa dm_mapsize
member indicates the size of the mapping.
A value of 0 indicates the mapping is invalid.
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
.
.Ss Functions
.Bl -tag -width Ds \" Fn
.It Fn bus_dmamap_create "tag" "size" "nsegments" "maxsegsz" "boundary" "flags" "dmamp"
Allocates a DMA handle and initializes it according to the parameters
provided.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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 and will be assigned to the
.Fa dm_maxsegsz
member.
.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
.Bl -tag -width Ds \" Dv
.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
.Vt bus_dmamap_t .
A DMA map will be allocated and pointed to by
.Fa dmamp
upon successful completion of this routine.
.Fa dmamp
is undefined if this routine fails.
.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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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 proc
.Fa p Ap s
address space.
.It Fa flags
.Bl -tag -width Ds \" Dv
.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
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 No \(-> Em 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 No \(-> Em device
transaction.
The back-end may perform optimizations based on this information.
.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.
Possible error codes include the following:
.Pp
.Bl -tag -width Er
.It Er EFBIG
Too many segments.
.It Er EINVAL
.Fa buflen
is too large for the DMA map.
.It Er ENOMEM
Could not allocate memory for, e.g., a bounce buffer.
.El
.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.
Determination if the buffers are in user or kernel virtual address space
is done internally, according to
.Fa uio\^ Ns Li -> Ns Fa uio_vmspace .
See
.Xr uiomove 9
for details of the
.Dv uio
structure.
.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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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
.Fn bus_dmamap_unload
will not perform any implicit synchronization of DMA buffers.
This must be done explicitly by
.Fn bus_dmamap_sync .
.Pp
.Fn bus_dmamap_unload
will restore the
.Fa dm_maxsegsz
member to its initial value assigned by
.Fn bus_dmamap_create .
.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" "offset" "len" "ops"
Performs pre- and post-DMA operation cache and/or buffer synchronization.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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 offset
The offset into the DMA mapping to synchronize.
.It Fa len
The length of the mapping from
.Fa offset
to synchronize.
.It Fa ops
One or more synchronization operation to perform.
The following DMA synchronization operations are defined:
.Bl -tag -width Ds \" Dv
.It Dv BUS_DMASYNC_PREREAD
Perform any synchronization required prior to an update of host memory by the
device.
.It Dv BUS_DMASYNC_POSTREAD
Perform any synchronization required after an update of host memory by the
device and prior to CPU access to host memory.
.It Dv BUS_DMASYNC_PREWRITE
Perform any synchronization required after an update of host memory by the CPU
and prior to device access to host memory.
.It Dv BUS_DMASYNC_POSTWRITE
Perform any synchronization required after device access to host memory.
.El
.Pp
where each operation may involve cache flush/invalidation, bounce buffer
copying, and/or memory barriers.
.Pp
More than one operation may performed in a given synchronization call.
Mixing of
.Dv PRE
and
.Dv POST
operations is not allowed, and behavior is undefined if this is attempted.
.Pp
Synchronization operations are expressed from the perspective of
the host RAM, i.e., a
.Em device No \(-> Em memory
operation is a
.Dv READ ,
and a
.Em memory No \(-> Em device
operation is a
.Dv WRITE .
.El
.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 a weak memory access ordering model,
.Fn bus_dmamap_sync
will always cause the appropriate memory barriers to be issued.
.Pp
This function exists to ensure that the host and the device have
a consistent view of a range of DMA memory, before and after
a DMA operation.
.Pp
An example of using
.Fn bus_dmamap_sync ,
involving multiple read-write use of a single mapping
might look like this:
.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
This function
.Em must
be called to synchronize DMA buffers before and after a DMA operation.
Other
.Nm
functions can
.Em not
be relied on to do this synchronization implicitly.
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.
.It Fn bus_dmamem_alloc "tag" "size" "alignment" "boundary" "segs" "nsegs" "rsegs" "flags"
Allocates memory that is
.Dq DMA safe
for the bus corresponding to the
given tag.
.Pp
The mapping of this memory is machine-dependent
.Pq or Dq 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
.Pq 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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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.
If no boundary condition needs to be observed, a
.Fa boundary
argument of 0 should be used.
.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
.Bl -tag -width Ds \" Dv
.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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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
.Bl -tag -width Ds \" Dv
.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 DMA coherent mappings are impossible, this flag is silently 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 .
.Pp
Note that a device driver must not rely on
.Dv BUS_DMA_COHERENT
for correct operation.
All calls to
.Fn bus_dmamap_sync
must still be made.
This flag is provided only as an optimization hint to machine-dependent code.
.Pp
Also note that this flag only applies to coherency between the CPU
and memory.
Coherency between memory and the device is controlled with a different flag.
See the description of the
.Fn bus_dmamap_load
function.
.It Dv BUS_DMA_NOCACHE
This flag is a
.Em hint
to machine-dependent code.
If possible, map the memory uncached.
This flag may be useful in the case that the memory cache causes unexpected
behavior of the device.
.Pp
Exclusive with
.Dv BUS_DMA_PREFETCHABLE .
.It Dv BUS_DMA_PREFETCHABLE
This flag is a
.Em hint
to machine-dependent code.
If possible, map the memory prefetchable/write-combining.
.Pp
Exclusive with
.Dv BUS_DMA_NOCACHE .
.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.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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 Ap ing
of DMA-safe memory.
This function is to be called by a device driver's
.Li (* Ns Fa d_mmap Ns Li )()
entry
point, which is called by the device pager for each page to be mapped.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt 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 Ap 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
.Bl -tag -width Ds \" Dv
.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.
.It Dv BUS_DMA_NOCACHE
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.
.It Fn bus_dmatag_subregion "tag" "min_addr" "max_addr" "newtag" "flags"
Given a
.Vt bus_dma_tag_t
create a new
.Vt bus_dma_tag_t
with a limited bus address space.
This function should not normally be used, but is useful for devices
that do not support the full address space of the parent bus.
Not all ports implement this method; on ports where it is unavailable,
.Er EOPNOTSUPP
is returned.
.Bl -tag -width Ds \" Fa
.It Fa tag
This is the
.Vt bus_dma_tag_t
to subregion.
.It Fa min_addr
The smallest address this new tag can address.
.It Fa max_addr
The largest address this new tag can address.
.It Fa newtag
Pointer filled in with the address of the new
.Vt bus_dma_tag_t .
.It Fa flags
.Bl -tag -width Ds \" Dv
.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.
.El
.El
.Pp
The address range
.Fa min_addr
to
.Fa max_addr
is inclusive of both addresses.
.It Fn bus_dmatag_destroy "tag"
Free a tag created by
.Fn bus_dmatag_subregion .
.El
.Sh SEE ALSO
.Xr membar_ops 3 ,
.Xr bus_space 9
.Rs
.%A Jason Thorpe
.%T "A Machine-Independent DMA Framework for NetBSD"
.%I USENIX Association
.%B Proceedings of the FREENIX Track: 1998 USENIX Annual Technical Conference
.%P 1-12
.%D June 15-19, 1998
.%U http://www.usenix.org/publications/library/proceedings/usenix98/freenix/thorpe_dma.pdf
.Re
.Sh HISTORY
The
.Nm
interface appeared in
.Nx 1.3 .
.Sh AUTHORS
.An -nosplit
The
.Nm
interface was designed and implemented by
.An Jason R. Thorpe
of the
Numerical Aerospace Simulation Facility, NASA Ames Research Center.
Additional input on the
.Nm
design was provided by
.An Chris Demetriou ,
.An Charles Hannum ,
.An Ross Harvey ,
.An Matthew Jacob ,
.An Jonathan Stone ,
and
.An Matt Thomas .