udmalib(3X)

NAME
     udmalib: dma_open, dma_close, dma_allocbuf, dma_freebuf, dma_mkparms,
     dma_freeparms, dma_start - user-level access to DMA hardware

SYNOPSIS
     #include <udmalib.h>

     udmaid_t *dma_open (int bus, int adap);
     int dma_close (dmaid_t *dp);
     void *dma_allocbuf (udmaid_t *dp, int size);
     int dma_freebuf (udmaid_t *dp, void *bp);
     udmaprm_t *dma_mkparms (udmaid_t *dp, void *dinfo, void *iobuf, int size);
     int dma_freeparms (udmaid_t *dp, udmaprm_t *dparms);
     int dma_start (udmaid_t *dp, void *busaddr, udmaprm_t *dparms);

DESCRIPTION
     On Challenge and Onyx systems, These routines form the basis for a
     simplified interface to DMA engines, usrdma(7m) devices.  These routines
     are included in a program by compiling with the -ludma option.
     Currently, the only supported DMA engine is for VME on the Challenge/Onyx
     series.  As DMA engines become available for other hardware platforms,
     support will be provided through this interface.

     An application would use the routines dma_open and dma_close to allocate
     and deallocate access to a DMA engine.  The parameters bus and adap are
     used to specify the type and adapter for the bus.  The type of bus is
     specified with the bus definitions found in /usr/include/udmalib.h.
     Currently, the only supported bus is DMA_VMEBUS.  The adapter number is
     used to identify which bus for the case when multiple busses of a
     particular type are available.  This is equivalent to the adapter= field
     of the VECTOR line. See system(4).  dma_open returns an opaque handle
     used by the remaining routines.  This routine may fail if a DMA engine
     does not exist, is in use, or the usrdma(7m) special devices are missing.
     dma_open returns NULL upon error.  dma_close returns a non-zero value
     upon error.  Note:  The allocated DMA buffers associated with the dmaid_t
     must be deallocated before dma_close can be called or it will fail.

     The routines dma_allocbuf and dma_freebuf are used to allocate and free
     up special buffers that will be used for the DMA operations.  DMA
     operations can only take place to these special buffers, since the
     buffers need to be locked down and mapped.  The size specifier is a byte
     count.  It will be rounded up to the nearest multiple of the system page
     size.  The buffer space returned from such an allocation can be divided
     up into many smaller buffers, depending upon the needs of the program.
     The page size of the system can be determined by calling getpagesize(2).
     dma_allocbuf returns NULL upon error.  dma_freebuf returns a non-zero
     value upon error.

     The routines dma_mkparms and dma_freeparms are used to create and free up
     bus-specific and buffer related parameters necessary to perform the DMA
     operation.  The argument dinfo is a bus-specific data structure defined
     in the header file udmalib.h.  For VME, this would be the vmeparms_t
     structure.  The argument iobuf and size specifies the DMA buffer to use
     and the byte count of the DMA operation.  dma_mkparms returns a pointer
     to a udmaprm_t structure.  This is an opaque handle that defines the DMA
     operation and is passed into dma_start, and dma_freeparms.  If a buffer
     is to be both read and written, a separate DMA parameter must be set up
     for each direction.  Note:  udmaprm_t pointers should not be used after
     the corresponding DMA buffer has been freed up.  This may result in a
     system panic.  This routine may fail if the specified buffer has been
     freed or the DMA operation fails basic range checking.  This routine may
     also fail if the combination of bus-specific parameters does not make
     sense.  dma_mkparms returns NULL upon error.  dma_freeparms returns a
     non-zero value upon error.

     The last routine dma_start programs the DMA engine, starts it up, and
     returns when the DMA has completed.  This routine is passed a udmaprm_t
     pointer, which specifies the buffer, size of the DMA, direction of the
     DMA to or from the buffer, and bus-specific information.  This routine is
     also passed the busaddr, the bus address of the device that is involved
     in the DMA operation.  dma_start returns a non-zero value upon error.

FILES
     /dev/vme/dma*
     /usr/lib/libudma.so

SEE ALSO
     MAKEDEV(1M)
     vme_dma_engine(3X) for Origin and Onyx2 VME option.

NOTES
     This library is only provided as a DSO.