Help: ICE_ICELIB_PIC_DMAFUNC

Starts, Stops, Polls, or Waits on a DMA transfer

Function PIC_DMAFUNC - Starts, Stops, Polls, or Waits on a DMA transfer

PIC	p	Handle to Device 
int	dmac	DMA Channel - usually returned from PIC_IOPORT
int	mode	Action to perform (ONESHOT,CONTINUOUS,STOP,WAIT,STATUS,CANCEL,MISS)

Utility functions for DMA's set up by PIC_DMA.  The mode field supports the
following function identifiers (defined in ICELIB.INC/H):

  DMA_ONESHOT	- Starts a once-through DMA to the user buffer and quits.
  DMA_CONTINUOUS- Starts a continuous circular DMA to the user buffer.
  DMA_STATUS	- Returns the current buffer read/write byte index (0 based)
  DMA_CYCLE	- Returns the current cycle through the host buffer (0 based)
  DMA_POLL	- Returns 1 if DMA is active, 0 if DMA is completed.
  DMA_WAIT	- Waits for the DMA to complete.
  DMA_RESHOT	- ReStarts a once-through DMA to the user buffer and quits.
  DMA_STOP	- Stops the current DMA immediately.
  DMA_RESET	- Resets DMA buffer pointers after a DMA_STOP.
  DMA_CANCEL	- Removes the DMA control block from the active list.
  DMA_LOST	- Reports number of Processor buffers missed.
  DMA_ACTIVE	- Reports number of channels active on this dmac's input module

The DMA_ONESHOT and DMA_CONTINUOUS options are used to start a DMA.  The 
DMA_STATUS option is used to track the current DMA pointer.  

For data snapshots, the user code should use DMA_ONESHOT followed by a
DMA_WAIT, and finally issue a DMA_CANCEL before closing the device.
The DMA_WAIT return status is 0 for normal completion, -1 for timed out, 
and -2 if buffers were dropped in this transfer (DMA_MISS returns how many).
If the routine is cancelled by McBreak or a card error, a -3 is returned.

To perform multiple ONESHOTs, use an initial DMA_ONESHOT/DMA_WAIT pair
followed by any number of DMA_RESHOT/DMA_WAIT pairs. This allows output
streams to flush output fifos in a contiguous manner.

To perform multiple DMA_CONTINUOUS or non-contiguous DMA_ONESHOT transfers, 
each transfer must be followed by a DMA_STOP and DMA_RESET to prepare the
resources for a clean restart.

For continuous acquisition/playback, use DMA_CONTINUOUS followed by a 
polling loop that uses DMA_STATUS to monitor the current read/write pointer.
Acquisition programs must read data out of the DMA buffer before the write 
pointer wraps around to overwrite the old data.  Playback programs will need 
to feed the data buffer close behind the read pointer to ensure the read 
pointer always has fresh data.  User programs can typically be 'swapped' out 
for 1-10 msec at times.  The DMA buffer needs to be large enough to cover any 
latencies caused by the system scheduler or the program itself.

The DMA_STATUS function returns an integer containing the offset from the top 
of the circular buffer (in bytes) of the current DMA read/write pointer.  At 
the start of an acquisition/playback, the status will be 0, and increment 
through the number of bytes in the buffer minus one DMA transfer length, 
(typically 1Kbyte) before returning to zero.

If separate calls are made to DMA_INDEX and DMA_CYCLE to find the current
data sample number, the index may wrap around between the two calls
giving erroneous results.  If you do not wish to monitor the index pointer
for this situation, use pic_dmastat().  It is a bit slower, but easier to use.