MirOS Manual: bus_dma(9), bus_dmamap_create(9), bus_dmamap_destroy(9), bus_dmamap_load(9), bus_dmamap_load_mbuf(9), bus_dmamap_load_raw(9), bus_dmamap_load_uio(9), bus_dmamap_sync(9), bus_dmamap_unload(9), bus_dmamem_alloc(9), bus_dmamem_free(9), bus_dmamem_map(9), bus_dmamem_mmap(9), bus_dmamem_unmap(9)

BUS_DMA(9)                    BSD Kernel Manual                     BUS_DMA(9)

NAME

     bus_dma - bus and machine independent DMA mapping interface

SYNOPSIS

     #include <machine/bus.h>

DESCRIPTION

     The bus_dma interface provides a bus and machine independent mechanism
     for managing DMA data transfers to and from devices.

     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).

     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 dev-
     ice. Taken together the segments exactly and completely describe the
     buffer being used to transfer data.

     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 inter-
     face.

     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 */

DATA TYPES

     Individual implementations may name these structures whatever they wish,
     providing that the external representations are:

     bus_addr_t         A device bus address to be used for CPU access or DMA.

     bus_size_t         The size of a bus address range.

     bus_dma_tag_t      A machine-dependent opaque type describing the imple-
                        mentation of DMA for a given host/bus. Machine-
                        dependent code is responsible for passing these struc-
                        tures to a bus's autoconfiguration machinery, which in
                        turn passes it down to the device drivers.

     bus_dma_segment_t  A structure describing an individual DMA segment. The
                        structure may have machine-dependent members and arbi-
                        trary layout, but has at least the following members:

                                bus_addr_t      ds_addr;
                                bus_size_t      ds_len;

                        The values in ds_addr and ds_len are suitable for pro-
                        gramming into a DMA controller's address and length
                        registers.

     bus_dmamap_t       A pointer to a structure describing an individual DMA
                        mapping. The structure may have machine-dependent
                        members and arbitrary layout, but has at least the
                        following members:

                                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.

DMA MAPS

     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 suc-
     cess, an error code otherwise.

     The bus_dmamap_create() arguments are as follows:
     tag        This is the bus_dma_tag_t passed down from the parent driver
                via <bus>_attach_args.
     size       This is the maximum DMA transfer that can be mapped by the
                handle.
     nsegments  Number of segments the device can support in a single DMA
                transaction. This may be the number of scatter-gather descrip-
                tors supported by the device.
     maxsegsz   The maximum number of bytes that may be transferred by any
                given DMA segment.
     boundary   Some DMA controllers are not able to transfer data that
                crosses a particular boundary. This argument allows this boun-
                dary to be specified. The boundary lines begin at 0, and occur
                every 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 boundary argument of 0
                should be used.
     flags      Flags are defined as follows:
                BUS_DMA_WAITOK    It is safe to wait (sleep) for resources
                                  during this call.
                BUS_DMA_NOWAIT    It is not safe to wait (sleep) for resources
                                  during this call.
                BUS_DMA_ALLOCNOW  Perform any resource allocation this handle
                                  may need now. If this is not specified, the
                                  allocation may be deferred to
                                  bus_dmamap_load(). If this flag is speci-
                                  fied, bus_dmamap_load() will not block on
                                  resource allocation.
                BUS_DMA_BUS[1-4]  These flags are placeholders, and may be
                                  used by busses to provide bus-dependent
                                  functionality.
     dmamp      This is a pointer to a bus_dmamap_t. A DMA map will be allo-
                cated and pointed to by dmamp upon successful completion of
                this routine.

     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:
     tag   This is the bus_dma_tag_t passed down from the parent driver via
           <bus>_attach_args.
     dmam  The DMA handle to destroy.

     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().

DMA MAP SEGMENTS

     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:
     tag     This is the bus_dma_tag_t passed down from the parent driver via
             <bus>_attach_args.
     dmam    The DMA handle with which to map the transfer.
     buf     The buffer to be used for the DMA transfer.
     buflen  The size of the buffer.
     p       Used to indicate the address space in which the buffer is locat-
             ed. If NULL, the buffer is assumed to be in kernel space. Other-
             wise, the buffer is assumed to be in process p's address space.
     flags   Flags are defined as follows:
             BUS_DMA_WAITOK     It is safe to wait (sleep) for resources dur-
                                ing this call.
             BUS_DMA_NOWAIT     It is not safe to wait (sleep) for resources
                                during this call.
             BUS_DMA_BUS[1-4]   These flags are placeholders, and may be used
                                by busses to provide bus-dependent functional-
                                ity.
             BUS_DMA_STREAMING  By default, the bus_dma API assumes that there
                                is coherency between memory and the device
                                performing the DMA transaction. Some plat-
                                forms, 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 dev-
                                ice 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() func-
                                tion.
             BUS_DMA_READ       This is a hint to the machine-dependent back-
                                end that indicates the mapping will be used
                                only for a device -> memory transaction. The
                                back-end may perform optimizations based on
                                this information.
             BUS_DMA_WRITE      This is a hint to the machine-dependent back-
                                end that indicates the mapping will be used
                                only for a memory -> device transaction. The
                                back-end may perform optimizations based on
                                this information.

     As 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 incon-
     sistent 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 vir-
     tual 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 an array of bus_dma_segment_t's 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.

     The bus_dmamap_unload() arguments are as follows:
     tag   This is the bus_dma_tag_t passed down from the parent driver via
           <bus>_attach_args.
     dmam  The DMA handle containing the mappings which are to be deleted.

     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.

SYNCHRONIZATION

     void
     bus_dmamap_sync(bus_dma_tag_t tag, bus_dmamap_t dmam, bus_addr_t offset,
             bus_size_t size, bus_dmasync_op_t 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:
     tag   This is the bus_dma_tag_t passed down from the parent driver via
           <bus>_attach_args.
     dmam  The DMA mapping to be synchronized.
     offset
           Offset in the DMA mapping to be synchronized.
     size  The size of the region to be synchronized.
     ops   One or more synchronization operations to perform. The following
           DMA synchronization operations are defined:
           BUS_DMASYNC_PREREAD    Perform any pre-read DMA cache and/or bounce
                                  operations.
           BUS_DMASYNC_POSTREAD   Perform any post-read DMA cache and/or
                                  bounce operations.
           BUS_DMASYNC_PREWRITE   Perform any pre-write DMA cache and/or
                                  bounce operations.
           BUS_DMASYNC_POSTWRITE  Perform any post-write DMA cache and/or
                                  bounce operations.

           More than one operation may 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 al-
     ways 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_dma 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 ap-
     propriate synchronization operations, behavior is undefined.

DMA-SAFE MEMORY
     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);

     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 suc-
     cess, 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 sys-
     tem 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:
     tag        This is the bus_dma_tag_t passed down from the parent driver
                via <bus>_attach_args.
     size       The amount of memory to allocate.
     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.
     boundary   Each segment in the allocated memory must not cross this boun-
                dary (relative to zero). This value must be a power of two. A
                boundary value less than the size of the allocation is in-
                valid.
     segs       An array of bus_dma_segment_t's, filled in as memory is allo-
                cated, representing the opaque addresses of the memory chunks.
     nsegs      Specifies the number of segments in segs, and this is the max-
                imum number of segments that the allocated memory may contain.
     rsegs      Used to return the actual number of segments the memory con-
                tains.
     flags      Flags are defined as follows:
                BUS_DMA_WAITOK     It is safe to wait (sleep) for resources
                                   during this call.
                BUS_DMA_NOWAIT     It is not safe to wait (sleep) for
                                   resources during this call.
                BUS_DMA_STREAMING  Adjusts, if necessary, the size, alignment,
                                   and boundary constraints to conform to the
                                   platform-dependent requirements for the use
                                   of the BUS_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]   These flags are placeholders, and may be
                                   used by busses to provide bus-dependent
                                   functionality.

     All pages allocated by bus_dmamem_alloc() 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(), invalidating any mapping. This function always
     succeeds if given valid arguments.

     The bus_dmamem_free() arguments are as follows:
     tag    This is the bus_dma_tag_t passed down from the parent driver via
            <bus>_attach_args.
     segs   The array of bus_dma_segment_t's filled in by bus_dmamem_alloc().
     nsegs  The number of segments in segs.

MAPPING DMA-SAFE MEMORY
     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() into kernel virtual address space. This function re-
     turns 0 on success, an error code otherwise, and must not be called from
     an interrupt context.

     The bus_dmamem_map() arguments are as follows:
     tag    This is the bus_dma_tag_t passed down from the parent driver via
            <bus>_attach_args.
     segs   The array of bus_dma_segment_t's filled in by bus_dmamem_alloc(),
            representing the memory regions to map.
     nsegs  The number of segments in segs.
     size   The size of the mapping.
     kvap   Filled in to specify the kernel virtual address where the memory
            is mapped.
     flags  Flags are defined as follows:
            BUS_DMA_WAITOK    It is safe to wait (sleep) for resources during
                              this call.
            BUS_DMA_NOWAIT    It is not safe to wait (sleep) for resources
                              during this call.
            BUS_DMA_BUS[1-4]  These flags are placeholders, and may be used by
                              busses to provide bus-dependent functionality.
            BUS_DMA_COHERENT  This flag is a 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 im-
                              possible, this is ignored.

                              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 en-
                              tries. 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().

     The 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:
     tag   This is the bus_dma_tag_t passed down from the parent driver via
           <bus>_attach_args.
     kva   The kernel virtual address of the mapped memory.
     size  The size of the mapping.

     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 an opaque value to be interpret-
     ed by the device pager, or -1 on failure. bus_dmamem_mmap() arguments are
     as follows:
     tag    This is the bus_dma_tag_t passed down from the parent driver via
            <bus>_attach_args.
     segs   The array of bus_dma_segment_t's filled in by bus_dmamem_alloc(),
            representing the memory to be mmap(2)'ed.
     nsegs  The number of elements in the segs array.
     off    The offset of the page in DMA memory which is to be mapped.
     prot   The protection codes for the mapping.
     flags  Flags are defined as follows:
            BUS_DMA_WAITOK    It is safe to wait (sleep) for resources during
                              this call.
            BUS_DMA_NOWAIT    It is not safe to wait (sleep) for resources
                              during this call.
            BUS_DMA_BUS[1-4]  These flags are placeholders, and may be used by
                              busses to provide bus-dependent functionality.
            BUS_DMA_COHERENT  See bus_dmamem_map() above for a description of
                              this flag.

SEE ALSO

     bus_space(9)

HISTORY

     The bus_dma interface appeared in NetBSD 1.3.

AUTHORS

     The bus_dma interface was designed and implemented by Jason R. Thorpe of
     the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
     Additional input on the bus_dma design was provided by Chris Demetriou,
     Charles Hannum, Ross Harvey, Matthew Jacob, Jonathan Stone, and Matt Tho-
     mas.

MirOS BSD #10-current         November 23, 2000                              7

Generated on 2014-04-02 20:57:59 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.