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