udmalib(3X)							   udmalib(3X)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #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    [Toc]    [Back]

     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



									Page 1






udmalib(3X)							   udmalib(3X)



     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    [Toc]    [Back]

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

SEE ALSO    [Toc]    [Back]

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

NOTES    [Toc]    [Back]

     This library is only provided as a	DSO.


									PPPPaaaaggggeeee 2222