vme_dma_engine(3X)vme_dma_engine(3X)NAME
vme_dma_engine_handle_alloc, vme_dma_engine_buffer_alloc,
vme_dma_engine_buffer_vaddr_get, vme_dma_engine_transfer_alloc,
vme_dma_engine_schedule, vme_dma_engine_commit,
vme_dma_engine_rendezvous, vme_dma_engine_transfer_free,
vme_dma_engine_buffer_free, vme_dma_engine_handle_free - user-level
access to VMEbus DMA engine
SYNOPSIS
#include <vme_dma_engine.h>
vme_dma_engine_handle_t vme_dma_engine_handle_alloc(char *pathname,
unsigned int flags);
vme_dma_engine_buffer_t
vme_dma_engine_buffer_alloc(vme_dma_engine_handle_t handle,
void *addr,
size_t byte_count);
void *
vme_dma_engine_buffer_vaddr_get(vme_dma_engine_buffer_t handle);
vme_dma_engine_transfer_t
vme_dma_engine_transfer_alloc(vme_dma_engine_handle_t handle,
vme_dma_engine_buffer_t buffer,
iopaddr_t vmeaddr,
size_t byte_count,
vme_dma_engine_dir_t direction,
vmeio_am_t am_code,
vme_dma_engine_throttle_t throttle,
vme_dma_engine_release_t release);
int vme_dma_engine_schedule(vme_dma_engine_handle_t handle,
vme_dma_engine_transfer_t transfer);
int vme_dma_engine_commit(vme_dma_engine_handle_t handle,
vme_dma_engine_commit_t commit_mode,
vme_dma_engine_wait_t wait_mode);
int vme_dma_engine_rendezvous(vme_dma_engine_handle_t handle,
vme_dma_engine_wait_t wait_mode);
int vme_dma_engine_transfer_free(vme_dma_engine_handle_t handle,
vme_dma_engine_transfer_t transfer);
void vme_dma_engine_buffer_free(vme_dma_engine_handle_t handle,
vme_dma_engine_buffer_t buffer);
void vme_dma_engine_handle_free(vme_dma_engine_handle_t handle);
Page 1
vme_dma_engine(3X)vme_dma_engine(3X)
Arguments
pathname The pathname of VMEbus DMA engine.
flags Additional options that users can choose.
handle The handle for the DMA engine.
addr The address of the user space which holds the data from/for
DMA.
byte_count Number of bytes.
buffer The handle for the DMA buffer in the user process.
vmeaddr VMEbus address.
direction The direction of the DMA transfer.
am_code address modifier code.
throttle The size of throttle.
release The mode of releasing the VMEbus during the DMA transfer.
transfer The handle for the DMA transfer.
commit_mode The mode to commit the DMA.
wait_mode The mode to wait for the DMA to finish.
DESCRIPTION
These routines form the API for accessing the DMA engine on the VMEbus
service provider. These routines are included in a program by compiling
with the -ludma option. Currently, the API is supported on Origin and
Onyx2 systems.
vme_dma_engine_handle_alloc() allocates a handle of the DMA engine by the
given pathname. If users specify VME_DMA_ENGINE_DEBUG in the flags
field, more integrity checking will be done in the operations on the DMA
engine. If the call is successful, the handle of the DMA engine is
returned. Otherwise, 0 is returned.
vme_dma_engine_buffer_alloc() allocates the host memory buffer according
to the address and byte_count pair. If address is NULL, the library will
get the virtual address range for the user. Otherwise, the library
assumes that the user has got the memory allocated. The handle of the
buffer is returned if the call is successful. Otherwise, 0 is returned.
vme_dma_engine_buffer_vaddr_get() returns the virtual address in user
address space from the handle returned by vme_dma_engine_buffer_alloc().
vme_dma_engine_transfer_alloc() allocates a transfer entity by the given
parameters. Some parameters must be specified, like the buffer handle,
Page 2
vme_dma_engine(3X)vme_dma_engine(3X)
the VMEbus address, how many bytes are going to be transferred, the
VMEbus address space type, and the direction of the transfer. There're
two advisory parameters, the throttle size and the release mode.
There're sets of values associated with each of the those parameters.
Users can submit their preferences to the library. They also could ask
the library to use the default values. It's under the library's
discretion to choose a value by the given hardware and software
constraints. The handle of the transfer is returned if successful,
otherwise 0 is returned.
vme_dma_engine_schedule() schedules a transfer for the actual DMA action.
This call provides the user a way to schedule multiple transfers for
one-time DMA action. Return 0 if successful, -1 if otherwise.
vme_dma_engine_commit() asks the library to commit all the transfers
scheduled. Users can choose which commitment mode would be used,
synchronous or asynchronous mode. If synchronous mode is used, the
library will return when the DMA is finished. In the synch mode, an
advisory parameter is also useful for the user to specify which way he
likes to wait here for the DMA to finish, spin-waiting or sleep-waiting.
If asynchronous mode is used, the library will return instantly.
vme_dma_engine_rendezvous() waits until all the scheduled transfers are
finished, when the user chose to do asynchronous transfer in the
vme_dma_engine_commit() call. Here, users can also prefer to wait by
spinning or sleeping.
vme_dma_engine_transfer_free() frees the transfer handle.
vme_dma_engine_buffer_free() frees the buffer handle.
vme_dma_engine_handle_free() frees the DMA engine handle.
FILES
/hw/vme/<bus_no>/dma_engine - The pathname for DMA engine
/usr/lib/libudma.so - o32bit DSO for VMEbus user level DMA engine API
/usr/lib32/libudma.so - n32bit DSO for VMEbus user level DMA engine API
/usr/lib64/libudma.so - 64bit DSO for VMEbus user level DMA engine API.
NOTES
This library is only provided as a DSO.
Page 3
