| BUS_DMAMAP_CREATE(9) | Kernel Developer's Manual | BUS_DMAMAP_CREATE(9) |
bus_dmamap_create,
bus_dmamap_destroy,
bus_dmamap_load,
bus_dmamap_load_mbuf,
bus_dmamap_load_uio,
bus_dmamap_load_raw,
bus_dmamap_unload,
bus_dmamap_sync,
bus_dmamem_alloc,
bus_dmamem_alloc_range,
bus_dmamem_free,
bus_dmamem_map,
bus_dmamem_unmap,
bus_dmamem_mmap — bus and
machine independent DMA mapping interface
#include
<machine/bus.h>
The bus_dmamap_create interface provides a
bus and machine independent mechanism for managing DMA data transfers to and
from devices.
The basic abstraction is bus_dmamap_t, a pointer to a structure describing an individual DMA mapping. The structure contains an array of segments (dm_segs), and a count of segments (dm_nsegs).
Each segment in dm_segs describes a single physical area of memory suitable for DMA, 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.
bus_dma_tag_t is an opaque type. bus_dma_tag_t values are received from higher software layers and are never created, changed, deleted or even examined in this interface.
The basic cycle to transfer data to/from a DMA device is:
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 */
Individual implementations may name these structures whatever they wish, providing that the external representations are:
bus_addr_t ds_addr;
bus_size_t ds_len;
The values in ds_addr and ds_len are suitable for programming into a DMA controller's address and length registers.
int dm_nsegs;
bus_dma_segment_t *dm_segs;
The dm_segs member may be an array of segments or a pointer to an array of segments. The dm_nsegs member indicates the number of segments in dm_segs.
int
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);
void
bus_dmamap_destroy(bus_dma_tag_t
tag, bus_dmamap_t
dmam);
The bus_dmamap_create() function allocates
a DMA handle and initializes it according to the parameters provided. This
function returns 0 on success, an error code otherwise.
The bus_dmamap_create() arguments are as
follows:
BUS_DMA_WAITOKBUS_DMA_NOWAITBUS_DMA_ALLOCNOWbus_dmamap_load(). If this flag is specified,
bus_dmamap_load() will not block on resource
allocation.BUS_DMA_BUS[1-4]The bus_dmamap_destroy() function frees
all resources associated with a given DMA handle. This function always
succeeds if given valid arguments.
The bus_dmamap_destroy() arguments are as
follows:
In the event that the DMA handle contains a valid mapping, the
mapping will be unloaded via the same mechanism used by
bus_dmamap_unload().
int
bus_dmamap_load(bus_dma_tag_t
tag, bus_dmamap_t
dmam, void *buf,
bus_size_t buflen,
struct proc *p,
int flags);
int
bus_dmamap_load_mbuf(bus_dma_tag_t
tag, bus_dmamap_t
dmam, struct mbuf
*chain, int
flags);
int
bus_dmamap_load_uio(bus_dma_tag_t
tag, bus_dmamap_t
dmam, struct uio
*uio, int
flags);
int
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);
void
bus_dmamap_unload(bus_dma_tag_t
tag, bus_dmamap_t
dmam);
The bus_dmamap_load() function loads a DMA
handle with mappings for a DMA transfer. It assumes that all pages involved
in a DMA transfer are wired. This function returns 0 on success, an error
code otherwise.
The bus_dmamap_load() arguments are as
follows:
NULL, the buffer is assumed to be in kernel space.
Otherwise, the buffer is assumed to be in process
p's address space.BUS_DMA_WAITOKBUS_DMA_NOWAITBUS_DMA_BUS[1-4]BUS_DMA_STREAMINGbus_dmamap_create API assumes
that there is coherency between memory and the device performing the
DMA transaction. Some platforms, however, have special hardware, such
as an “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
bus_dmamem_alloc() function.BUS_DMA_READBUS_DMA_WRITEAs noted above, if a DMA handle is created with
BUS_DMA_ALLOCNOW,
bus_dmamap_load() will never block.
If a call to 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.
The bus_dmamap_load_mbuf() function is a
variation of bus_dmamap_load() which maps mbuf
chains for DMA transfers. Mbuf chains are assumed to be in kernel virtual
address space.
The bus_dmamap_load_uio() function is a
variation of bus_dmamap_load() which maps buffers
pointed to by uio for DMA transfers. The value of
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
uio->uio_procp's address space.
The bus_dmamap_load_raw() function is a
variation of bus_dmamap_load() which maps buffers
allocated by bus_dmamem_alloc() (see below). The
segs argument is a
bus_dma_segment_t array filled in by
bus_dmamem_alloc(). The nsegs
argument is the number of segments in the array. The
size argument is the size of the DMA transfer.
The bus_dmamap_unload() function deletes
the mappings for a given DMA handle. This function always succeeds if given
valid arguments. Attempting to unload a map that is already unloaded is not
valid.
The bus_dmamap_unload() arguments are as
follows:
If the DMA handle was created with
BUS_DMA_ALLOCNOW,
bus_dmamap_unload() will not free the corresponding
resources which were allocated by
bus_dmamap_create(). This is to ensure that
bus_dmamap_load() will never block on resources if
the handle was created with BUS_DMA_ALLOCNOW.
void
bus_dmamap_sync(bus_dma_tag_t
tag, bus_dmamap_t
dmam, bus_addr_t
offset, bus_size_t
size, int ops);
The bus_dmamap_sync() function performs
pre- and post-DMA operation cache and/or buffer synchronization. This
function always succeeds if given valid arguments.
The bus_dmamap_sync() arguments are as
follows:
BUS_DMASYNC_PREREADBUS_DMASYNC_POSTREADBUS_DMASYNC_PREWRITEBUS_DMASYNC_POSTWRITEMore than one operation may be performed in a given synchronization call. Mixing of PRE and POST operations is not allowed, and behavior is undefined if this is attempted.
Synchronization operations are expressed from the perspective of the host RAM, e.g., a device -> memory operation is a READ and a memory -> device operation is a WRITE.
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, bus_dmamap_sync() may elect to skip
certain expensive operations, such as flushing of the data cache. See
bus_dmamem_map() for more information on this
subject.
On platforms which implement reordered stores,
bus_dmamap_sync() will always cause the store buffer
to be flushed.
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 bus_dmamap_create code when their data is
“ready” in its DMA buffer.
An example of multiple read-write use of a single mapping might look like:
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(...);
If DMA read and write operations are not preceded and followed by the appropriate synchronization operations, behavior is undefined.
int
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);
int
bus_dmamem_alloc_range(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,
bus_addr_t low,
bus_addr_t high);
void
bus_dmamem_free(bus_dma_tag_t
tag, bus_dma_segment_t
*segs, int
nsegs);
The bus_dmamem_alloc() function allocates
memory that is "DMA safe" for the bus corresponding to the given
tag. This function returns 0 on success, or an error code indicating mode of
failure.
The mapping of this memory is machine-dependent (or
"opaque"); machine-independent code should not 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 segs can thus not be used to program DMA
controller address registers. Only the values in the
dm_segs array of a successfully loaded DMA map (using
bus_dmamap_load()) can be used for this purpose.
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.
The bus_dmamem_alloc() arguments are as
follows:
BUS_DMA_WAITOKBUS_DMA_NOWAITBUS_DMA_ZEROBUS_DMA_STREAMINGBUS_DMA_STREAMING flag with the
bus_dmamap_load() function. If the platform
does not support the 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 BUS_DMA_STREAMING flag will never
relax the constraints specified in the call.BUS_DMA_BUS[1-4]The bus_dmamem_alloc_range() function is a
variation of bus_dmamem_alloc() that allows
specification of the "DMA safe" bus address range supported by the
device. The additional low and
high arguments specify the lowest and highest bus
address that the device can use for DMA transfers. This function should only
be used if that address range differs from the default address range for the
bus.
All pages allocated by bus_dmamem_alloc()
and bus_dmameme_alloc_range() will be wired down
until they are freed by bus_dmamem_free().
The bus_dmamem_free() function frees
memory previously allocated by bus_dmamem_alloc() or
bus_dmamem_alloc_range(), invalidating any mapping.
This function always succeeds if given valid arguments.
The bus_dmamem_free() arguments are as
follows:
bus_dmamem_alloc().int
bus_dmamem_map(bus_dma_tag_t
tag, bus_dma_segment_t
*segs, int nsegs,
size_t size,
caddr_t *kvap,
int flags);
void
bus_dmamem_unmap(bus_dma_tag_t
tag, caddr_t kva,
size_t size);
paddr_t
bus_dmamem_mmap(bus_dma_tag_t
tag, bus_dma_segment_t
*segs, int nsegs,
off_t off,
int prot,
int flags);
The bus_dmamem_map() function maps memory
allocated with bus_dmamem_alloc() or
bus_dmamem_alloc_range() into kernel virtual address
space. This function returns 0 on success, an error code otherwise, and must
not be called from an interrupt context.
The bus_dmamem_map() arguments are as
follows:
bus_dmamem_alloc(), representing the memory
regions to map.BUS_DMA_WAITOKBUS_DMA_NOWAITBUS_DMA_BUS[1-4]BUS_DMA_COHERENTLater, 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
bus_dmamap_sync().
BUS_DMA_NOCACHEThe bus_dmamem_unmap() function unmaps
memory previously mapped with bus_dmamem_map(),
freeing the kernel virtual address space used by the mapping. This function
always succeeds if given valid arguments, but must not be called from an
interrupt context.
bus_dmamem_unmap() arguments are as
follows:
The bus_dmamem_mmap() function provides
support for user mmap(2)'ing of DMA-safe
memory. bus_dmamem_mmap() 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. This function returns
a physical address to be passed to pmap_enter() by
the device pager, or -1 on failure.
bus_dmamem_mmap() arguments are as follows:
bus_dmamem_alloc(), representing the memory to be
mmap(2)'ed.BUS_DMA_WAITOKBUS_DMA_NOWAITBUS_DMA_BUS[1-4]BUS_DMA_COHERENTbus_dmamem_map() above for a description
of this flag.BUS_DMA_NOCACHEbus_dmamem_map() above for a description
of this flag.The bus_dmamap_create interface appeared
in NetBSD 1.3.
The bus_dmamap_create interface was
designed and implemented by Jason R. Thorpe of the
Numerical Aerospace Simulation Facility, NASA Ames Research Center.
Additional input on the bus_dmamap_create design was
provided by Chris Demetriou, Charles Hannum, Ross Harvey, Matthew Jacob,
Jonathan Stone, and Matt Thomas.
| November 23, 2015 | OpenBSD-current |