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
This commit is contained in:
Hiten Pandya
parent
ffc07c4cf2
commit
2450346579
@ -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
|
||||
|
||||
720
share/man/man9/bus_dma.9
Normal file
720
share/man/man9/bus_dma.9
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user