EDT PDV SDK Documentation 6.1.0
Input/Output
Collaboration diagram for Input/Output:

Functions

int edt_configure_ring_buffers (EdtDev edt_p, unsigned int bufsize, unsigned int numbufs, unsigned int write_flag)
 Prepare and configure ring buffers for DMA to/from the EDT device. More...
 
int edt_ref_tmstamp (EdtDev edt_p, u_int val)
 Causes application-defined events to show up in the same timeline as driver events when the event history is listed by running setdebug -g. More...
 
uint_t edt_get_todo (EdtDev edt_p)
 Get the number of buffers that the driver has been told to acquire. More...
 
int edt_read (EdtDev edt_p, void *buf, uint_t size)
 Perform a DMA read from the EDT device. More...
 
int edt_write (EdtDev edt_p, void *buf, uint_t size)
 Perform a DMA write to the EDT device. More...
 
int edt_configure_block_buffers (EdtDev edt_p, int bufsize, int numbufs, int write_flag, int header_size, int header_before)
 Prepare and configure ring buffers for DMA, allocating buffers as a single large block, setting the buffer addresses from within that block. More...
 
void edt_set_dmy_wait_for_buffers_callback (EdtDev edt_p, void(*callback)(EdtDev edt_p, void *buf))
 Register a callback to populate the ring buffer with data when edt_wait_for_buffers() is called. More...
 
void edt_set_dmy_reg_read_callback (EdtDev edt_p, uint32_t(*callback)(EdtDev edt_p, uint32_t reg_desc))
 Register a callback to read a simulated register when edt_reg_read() is called. More...
 
void edt_set_dmy_reg_write_callback (EdtDev edt_p, void(*callBack)(EdtDev edt_p, uint32_t reg_desc, uint32_t reg_value))
 Register a callback to write a simulated register when edt_reg_write() is called. More...
 
EDT_CHECK_RETURN void * edt_map_dmamem (EdtDev edt_p)
 Memory-map the entire DMA channel's ring of buffers. More...
 
int edt_disable_ring_buffers (EdtDev edt_p)
 Disable EDT device ring buffers. Pending DMA is cancelled and all data buffers are released. More...
 
int edt_get_numbufs (EdtDev edt_p)
 Get the number of buffers allocated even if by other process (for monitoring from a separate call to edt_open()). More...
 
int edt_reset_ring_buffers (EdtDev edt_p, uint_t bufnum)
 Stop any active DMA then set the ring buffer to restart on buffer bufnum. More...
 
int edt_abort_dma (EdtDev edt_p)
 Stop any active DMA then set the ring buffer to restart on the current buffer. More...
 
int edt_abort_current_dma (EdtDev edt_p)
 Stop any active DMA then set the ring buffer to restart on the next buffer. More...
 
int edt_stop_buffers (EdtDev edt_p)
 Stop DMA transfer after the current buffer has completed. Ring buffer mode remains active, and transfers may be resumed by calling edt_start_buffers(). More...
 
int edt_start_buffers (EdtDev edt_p, uint_t count)
 Start DMA transfers for count number of buffers. More...
 
int edt_set_buffer_size (EdtDev edt_p, uint_t index, uint_t size, uint_t write_flag)
 Change the size or direction of one buffer in a ring. More...
 
unsigned int edt_allocated_size (EdtDev edt_p, int buffer_idx)
 Get the allocated size of the specified buffer. More...
 
int edt_get_total_bufsize (EdtDev edt_p, int bufsize, int header_size)
 Get the total buffer size for block of buffers, in which the memory allocation size is rounded up so all buffers start on a page boundary. This is used to allocate a single contiguous block of DMA buffers. More...
 
void * edt_wait_for_buffers (EdtDev edt_p, int count)
 Blocks until the specified number of buffers have completed. More...
 
int edt_get_timestamp (EdtDev edt_p, edt_timespec_t *ts, u_int bufnum)
 Get the seconds and nanoseconds timestamp of when DMA was completed on the buffer specified by bufnum. More...
 
void * edt_wait_for_next_buffer (EdtDev edt_p)
 Wait for the next buffer that finishes DMA. Depending on how often this routine is called, buffers that have already completed DMA might be skipped. More...
 
void * edt_last_buffer_timed (EdtDev edt_p, edt_timespec_t *ts)
 Like edt_last_buffer() but also returns the time at which the DMA was complete on this buffer. More...
 
void * edt_last_buffer (EdtDev edt_p)
 Wait for the last buffer that has been transferred. Useful if an application cannot keep up with buffer transfer. If this routine is called a second time before another buffer has been transferred, it will block waiting for the next transfer to complete. More...
 
void * edt_wait_buffers_timed (EdtDev edt_p, int count, edt_timespec_t *ts)
 Block until the specified number of buffers have completed. More...
 
int edt_set_buffer (EdtDev edt_p, uint_t bufnum)
 Set which buffer should be started next. Usually done to recover after a timeout, interrupt, or error. More...
 
void * edt_next_writebuf (EdtDev edt_p)
 Get a pointer to the next buffer scheduled for output DMA, in order to fill the buffer with data. More...
 
uint32_t edt_dma_buffers_done_waiting (EdtDev edt_p)
 Get the number of DMA buffers that have been waited for. More...
 
void ** edt_buffer_addresses (EdtDev edt_p)
 Get an array of ring buffer pointers. More...
 
uint32_t edt_done_count (EdtDev edt_p)
 Returns the cumulative count of completed buffer transfers in ring buffer mode. More...
 
void * edt_check_for_buffers (EdtDev edt_p, uint_t count)
 Checks, without blocking, if the specified number of buffers have completed. More...
 
uint16_t edt_get_direction (EdtDev edt_p)
 Get the value of the PCD_DIRA and PCD_DIRB registers. The value from PCD_DIRB is shifted up 8 bits. More...
 
void edt_startdma_reg (EdtDev edt_p, uint_t desc, uint_t val)
 Set the register and value to use at the start of DMA, as set by edt_startdma_action(). More...
 
void edt_enddma_reg (EdtDev edt_p, uint_t desc, uint_t val)
 Sets the register and value to use at the end of dma, as set by edt_enddma_action(). More...
 
void edt_startdma_action (EdtDev edt_p, uint_t val)
 Specifies when to perform the action at the start of a DMA transfer as specified by edt_startdma_reg(). More...
 
void edt_enddma_action (EdtDev edt_p, uint_t val)
 Specifies when to perform the action at the end of a DMA transfer as specified by edt_enddma_reg(). More...
 
int edt_do_timeout (EdtDev edt_p)
 Cause the driver to perform the same actions as it would on a timeout. Partially filled FIFOs will be flushed and DMA will be aborted. More...
 
int edt_timeouts (EdtDev edt_p)
 Get the number of read and write timeouts that have occurred since the last call of edt_open(). More...
 
uint_t edt_get_timeout_count (EdtDev edt_p)
 Get the number of bytes transferred at last timeout. More...
 
int edt_set_timeout_action (EdtDev edt_p, EdtDmaTimeoutAction action)
 Set the driver behavior on a timeout. More...
 
int edt_get_timeout_goodbits (EdtDev edt_p)
 Get the number of good bits in the last long word of a read buffer after the last timeout. This routine is called after a timeout if the timeout action is set to EDT_TIMEOUT_BIT_STROBE. More...
 
int edt_get_goodbits (EdtDev edt_p)
 Get the current number of good bits in the last long word of a read buffer (0 through 31). More...
 
int edt_set_event_func (EdtDev edt_p, enum edt_kernel_event event_type, EdtEventFunc func, void *data, int continuous)
 Define a function to call when an event occurs. More...
 
int edt_remove_event_func (EdtDev edt_p, enum edt_kernel_event event_type)
 Remove an event function previously set with edt_set_event_func(). More...
 
int edt_ring_buffer_overrun (EdtDev edt_p)
 Determine if DMA has written to more buffers in the ring than user space code has "waited" (edt_wait_for_buffers()) for. Indicates user space code cannot keep up with the DMA transfer rate. More...
 
int edt_set_burst_enable (EdtDev edt_p, int enable)
 Set the burst enable flag, determining whether the DMA master transfers as many words as possible at once, or transfers them one at a time as soon as the data is acquired. More...
 
int edt_get_burst_enable (EdtDev edt_p)
 Get the value of the burst enable flag. More...
 
int edt_set_rtimeout (EdtDev edt_p, int timeout_ms)
 Set the timeout for data receive calls. More...
 
int edt_set_wtimeout (EdtDev edt_p, int timeout_ms)
 Set the timeout for data transmit calls. More...
 
int edt_get_rtimeout (EdtDev edt_p)
 Gets the current read timeout value: the number of milliseconds to wait for DMA reads to complete before returning. More...
 
int edt_get_wtimeout (EdtDev edt_p)
 Gets the current write timeout value: the number of milliseconds to wait for DMA reads to complete before returning. More...
 
uint_t edt_overflow (EdtDev edt_p)
 Get DMA overflow counter from the driver. Reset by edt_reset_counts(). More...
 

Detailed Description

These functions are used to perform and control DMA transfers.

Function Documentation

◆ edt_configure_ring_buffers()

int edt_configure_ring_buffers ( EdtDev  edt_p,
unsigned int  bufsize,
unsigned int  numbufs,
unsigned int  write_flag 
)

Prepare and configure ring buffers for DMA to/from the EDT device.

Any previous configuration is replaced, and previously allocated buffers are released. Buffers are allocated and maintained within the EDT device library.

For optimal efficiency, allocate a bufsize value approximating throughput divided by 20: that is, if transfer occurs at 20 MB per second, allocate 1 MB per buffer. Buffers significantly larger or smaller can overuse memory or lock the system up in processing interrupts at this speed.

Parameters
edt_pThe open EDT device handle.
bufsizeSize of each buffer, in bytes.
numbufsNumber of buffers. Must be 1 or greater. Four is recommended for most applications.
write_flagWhether this DMA channel is configured for input (read from device) or output (write to device). Pass either EDT_READ or EDT_WRITE.
Returns
0 on success, -1 on failure. Get system error message with edt_perror()
Here is the caller graph for this function:

◆ edt_ref_tmstamp()

int edt_ref_tmstamp ( EdtDev  edt_p,
u_int  val 
)

Causes application-defined events to show up in the same timeline as driver events when the event history is listed by running setdebug -g.

This may be useful for debugging.

Example:

#define BEFORE_WAIT 0x1212aaaa
#define AFTER_WAIT 0x3434bbbb
u_char *buf;
edt_ref_tmstamp(edt_p, BEFORE_WAIT);
buf=edt_wait_for_buffer(edt_p);
edt_ref_tmstamp(edt_p, AFTER_WAIT);
// now look at output of setdebug -g and you'll see something like:
// 0: 0001ca0 REFTMSTAMP : 1212aaaa 324.422071 (0.004189)
// ... other events from edt_wait_for_buffer() shown, like START_BUF, SETUP_DMA, FLUSH, etc
// 0: 0001d08 REFTMSTAMP : 3434bbbb 324.518885 (0.000045)
Parameters
edt_pThe open EDT device handle.
valAn arbitrary value meaningful to the application.
Returns
0 on success, -1 on failure

◆ edt_get_todo()

uint_t edt_get_todo ( EdtDev  edt_p)

Get the number of buffers that the driver has been told to acquire.

This is not normally needed.

This allows an application to know the state of the ring buffers within an interrupt, timeout, or when cleaning up on close. It also allows the application to know how close it is getting behind the acquisition.

int curdone;
int curtodo;
curdone = edt_done_count(edt_p);
curtodo = edt_get_todo(edt_p);
// curtodo - curdone is how close the DMA is to catching up with our
// processing
See also
edt_done_count, edt_start_buffers, edt_wait_for_buffers
Parameters
edt_pThe open EDT device handle.
Returns
Number of buffers started via edt_start_buffers().
Here is the caller graph for this function:

◆ edt_read()

int edt_read ( EdtDev  edt_p,
void *  buf,
uint_t  size 
)

Perform a DMA read from the EDT device.

Parameters
edt_pThe open EDT device handle.
bufBuffer to read data in to.
sizeNumber of bytes to read. buf must be equal to or greater than this size.
Returns
Number of bytes read if successful. -1 on failure.

For those on UNIX systems, the UNIX 2 GB file offset bug is avoided during large amounts of input or output. That is, reading past 2^31 bytes does not fail. This call is not multibuffering, and no transfer is active when it completes.

Note
If using timeouts, call edt_timeouts() after this returns to see if the number of timeouts has incremented. If it has incremented, call edt_get_timeout_count() to get the number of bytes transferred into the buffer.
Here is the call graph for this function:

◆ edt_write()

int edt_write ( EdtDev  edt_p,
void *  buf,
uint_t  size 
)

Perform a DMA write to the EDT device.

Parameters
edt_pThe open EDT device handle.
bufData to write to the device.
sizeNumber of bytes to write. buf must be equal to or greater than this size.
Returns
Number of bytes written if successful. -1 on failure.

For those on UNIX systems, the UNIX 2 GB file offset bug is avoided during large amounts of input or output. That is, reading past 2^31 bytes does not fail. This call is not multibuffering, and no transfer is active when it completes.

Note
If using timeouts, call edt_timeouts() after this returns to see if the number of timeouts has incremented. If it has incremented, call edt_get_timeout_count() to get the number of bytes transferred into the buffer.
Here is the call graph for this function:

◆ edt_configure_block_buffers()

int edt_configure_block_buffers ( EdtDev  edt_p,
int  bufsize,
int  numbufs,
int  write_flag,
int  header_size,
int  header_before 
)

Prepare and configure ring buffers for DMA, allocating buffers as a single large block, setting the buffer addresses from within that block.

Parameters
edt_pThe open EDT device handle.
bufsizeSize of individual buffers, in bytes
numbufsNumber of buffers to create in the ring.
write_flagEither EDT_WRITE or EDT_READ.
header_sizeIf non-zero, additional memory will be allocated for each buffer for Header data. The location of this header region is determined by the argument header_before.
header_beforeIf non-zero, the header region is placed before the DMA buffer. Otherwise it comes after the DMA buffer.
Returns
0 on success, -1 on failure.

This allows reading or writing buffers from/to a file in single chunks larger than the buffer size, which is sometimes considerable more efficient.

Primarily used by pdv_multibuf() in PDV library.

Buffer sizes are rounded up by PAGE_SIZE so that DMA occurs on a page boundary.

Note
The buffer pointer returned by edt_wait_for_buffers() is always the DMA buffer.
See also
edt_configure_ring_buffers(), edt_get_total_bufsize()

◆ edt_set_dmy_wait_for_buffers_callback()

void edt_set_dmy_wait_for_buffers_callback ( EdtDev  edt_p,
void(*)(struct edt_device *edt_p, void *buf)  callBack 
)

Register a callback to populate the ring buffer with data when edt_wait_for_buffers() is called.

Parameters
edt_pThe EDT device handle, opened as a dummy device.
callbackFunction to invoke when edt_wait_for_buffers() is called.

When "dmy" or "DMY" is passed as the first argument to edt_open*(), the internal device ID (get with edt_device_id()() is set to DMY_ID and all attempted interaction with EDT hardware is ignored.

◆ edt_set_dmy_reg_read_callback()

void edt_set_dmy_reg_read_callback ( EdtDev  edt_p,
uint32_t(*)(EdtDev edt_p, uint32_t reg_desc)  callback 
)

Register a callback to read a simulated register when edt_reg_read() is called.

Parameters
edt_pThe EDT device handle, opened as a dummy device.
callbackFunction to invoke when edt_reg_read() is called.

◆ edt_set_dmy_reg_write_callback()

void edt_set_dmy_reg_write_callback ( EdtDev  edt_p,
void(*)(EdtDev edt_p, uint32_t reg_desc, uint32_t reg_value)  callBack 
)

Register a callback to write a simulated register when edt_reg_write() is called.

Parameters
edt_pThe EDT device handle, opened as a dummy device.
callbackFunction to invoke when edt_reg_write() is called.

◆ edt_map_dmamem()

EDT_CHECK_RETURN void * edt_map_dmamem ( EdtDev  edt_p)

Memory-map the entire DMA channel's ring of buffers.

Parameters
edt_pThe open EDT device handle.
Returns
On success, a pointer to the mapped area. On failure, NULL.

◆ edt_disable_ring_buffers()

int edt_disable_ring_buffers ( EdtDev  edt_p)

Disable EDT device ring buffers. Pending DMA is cancelled and all data buffers are released.

Parameters
edt_pThe open EDT device handle.
Returns
0 on success, -1 on failure. Get system error message with edt_perror().
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_get_numbufs()

int edt_get_numbufs ( EdtDev  edt_p)

Get the number of buffers allocated even if by other process (for monitoring from a separate call to edt_open()).

Parameters
edt_pThe open EDT device handle.
Returns
Number of allocated buffers, or -1 on failure.

◆ edt_reset_ring_buffers()

int edt_reset_ring_buffers ( EdtDev  edt_p,
uint_t  bufnum 
)

Stop any active DMA then set the ring buffer to restart on buffer bufnum.

Parameters
edt_pThe open EDT device handle.
bufnumThe index of the ring buffer at which to start the next DMA. A number larger than the number of buffers will set current done count to bufnum modulo the number of buffers.
Returns
0 on success, -1 on failure.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_abort_dma()

int edt_abort_dma ( EdtDev  edt_p)

Stop any active DMA then set the ring buffer to restart on the current buffer.

Parameters
edt_pThe open EDT device handle.
Returns
0 on success, -1 on failure.
See also
edt_reset_ring_buffers(), edt_abort_current_dma()
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_abort_current_dma()

int edt_abort_current_dma ( EdtDev  edt_p)

Stop any active DMA then set the ring buffer to restart on the next buffer.

Parameters
edt_pThe open EDT device handle.
Returns
0 on success, -1 on failure.
See also
edt_reset_ring_buffers(), edt_abort_dma()
Here is the call graph for this function:

◆ edt_stop_buffers()

int edt_stop_buffers ( EdtDev  edt_p)

Stop DMA transfer after the current buffer has completed. Ring buffer mode remains active, and transfers may be resumed by calling edt_start_buffers().

Parameters
edt_pThe open EDT device handle.
Returns
0 on success, -1 on failure.
Here is the call graph for this function:

◆ edt_start_buffers()

int edt_start_buffers ( EdtDev  edt_p,
uint_t  count 
)

Start DMA transfers for count number of buffers.

Parameters
edt_pThe open EDT device handle.
countNumber of buffers in a ring to release to the driver for transfer. A value of 0 starts "free running" mode where transfers run continuously until edt_stop_buffers() is called. If count is greater than the number of buffers in the ring, DMA continues looping through the buffers until the total count has been satisfied.
Returns
0 on success, -1 on failure.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_set_buffer_size()

int edt_set_buffer_size ( EdtDev  edt_p,
uint_t  index,
uint_t  size,
uint_t  write_flag 
)

Change the size or direction of one buffer in a ring.

Warning
Improper use can have nasty side effects. Prefer to use separate DMA channels with different size or direction configuration, instead of modifying a channel's individual buffer.
Parameters
edt_pThe open EDT device handle.
indexIndex of ring buffer to change.
sizeNew buffer size to use.
write_flagDirection; either EDT_WRITE or EDT_READ.
Returns
0 on success, -1 on failure.

Mixing directions requires detailed knowledge of the interface since pending preloaded DMA transfers need to be coordinated with the interface fifo direction. For example, a DMA write will complete when the data is in the output fifo, but the DMA read should not be started until the data is out to the external device. Most applications requiring fast mixed reads/writes have worked out more cleanly using seperate, simultaneous, read and write dma transfers using different DMA channels.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_allocated_size()

unsigned int edt_allocated_size ( EdtDev  edt_p,
int  buffer_idx 
)

Get the allocated size of the specified buffer.

Parameters
edt_pThe open EDT device handle.
buffer_idxIndex of the buffer.
Returns
The buffer size in bytes, or 0 if the specified index is invalid.

◆ edt_get_total_bufsize()

int edt_get_total_bufsize ( EdtDev  edt_p,
int  bufsize,
int  header_size 
)

Get the total buffer size for block of buffers, in which the memory allocation size is rounded up so all buffers start on a page boundary. This is used to allocate a single contiguous block of DMA buffers.

Note
The total size of a ring buffer is this value multiplied by the number of buffers in the ring.
Parameters
edt_pThe open EDT device handle.
bufsizeSize of a buffer.
header_sizeOptional size of an additional header region.
Returns
Full buffer size, in bytes.
See also
edt_configure_block_buffers()

◆ edt_wait_for_buffers()

void * edt_wait_for_buffers ( EdtDev  edt_p,
int  count 
)

Blocks until the specified number of buffers have completed.

Parameters
edt_pThe open EDT device handle.
countNumber of buffers to block for. Completed buffers are numbered relatively; start each call with 1.
Returns
Address of last completed buffer on success; NULL on failure.
Note
If using timeouts, call edt_timeouts() after edt_wait_for_buffers() returns to see if the number of timeouts has incremented. If it has incremented, call edt_get_timeout_count() to get the number of bytes transferred into the buffer. When not in free run mode, DMA will not automatically continue on to the next buffer, so you need to call edt_start_buffers() to move on to the next buffer in the ring.
If the ring buffer is in free run mode and the application cannot process data as fast as it is acquired, DMA will wrap around and overwrite the referenced buffer (an "overrun" condition). The application must ensure that the data in the buffer is processed or copied out in time to prevent overrun. Use edt_ring_buffer_overrun() to check for overruns.
Here is the caller graph for this function:

◆ edt_get_timestamp()

int edt_get_timestamp ( EdtDev  edt_p,
edt_timespec_t ts,
u_int  bufnum 
)

Get the seconds and nanoseconds timestamp of when DMA was completed on the buffer specified by bufnum.

Parameters
edt_pThe open EDT device handle.
[out]tsTimestamp representing the system time at which the buffer completed.
bufnumEither buffer index or, if greater than number of buffers in the ring, number of buffers completed.
Returns
On success, fills in timestamp ts and returns 0. On failure, returns -1.

Example:

u_int bufnum = edt_done_count(edt_p);
edt_get_timestamp(edt_p, &ts, bufnum);
printf("Timestamp: %s", edt_timestring(&ts));
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_wait_for_next_buffer()

void * edt_wait_for_next_buffer ( EdtDev  edt_p)

Wait for the next buffer that finishes DMA. Depending on how often this routine is called, buffers that have already completed DMA might be skipped.

Parameters
edt_pThe open EDT device handle.
Returns
Returns a pointer to the buffer, or NULL on failure.
Here is the call graph for this function:

◆ edt_last_buffer_timed()

void * edt_last_buffer_timed ( EdtDev  edt_p,
edt_timespec_t ts 
)

Like edt_last_buffer() but also returns the time at which the DMA was complete on this buffer.

Parameters
edt_pThe open EDT device handle.
[out]tsTimestamp representing the system time at which the buffer completed.
Returns
A pointer to the last buffer, or NULL on failure.

Example:

uint8_t *buf = edt_last_buffer_timed(edt_p, &ts);
Returns
Address of the image.
See also
edt_wait_for_buffers, edt_last_buffer, edt_wait_buffers_timed
Here is the call graph for this function:

◆ edt_last_buffer()

void * edt_last_buffer ( EdtDev  edt_p)

Wait for the last buffer that has been transferred. Useful if an application cannot keep up with buffer transfer. If this routine is called a second time before another buffer has been transferred, it will block waiting for the next transfer to complete.

Parameters
edt_pThe open EDT device handle.
Returns
A pointer to the last buffer, or NULL on failure.
See also
edt_wait_for_buffers(), edt_last_buffer_timed()
Here is the call graph for this function:

◆ edt_wait_buffers_timed()

void * edt_wait_buffers_timed ( EdtDev  edt_p,
int  count,
edt_timespec_t ts 
)

Block until the specified number of buffers have completed.

Parameters
edt_pThe open EDT device handle.
countNumber of buffers for which to block. Completed buffers are numbered cumulatively starting with 0 when the EDT device is opened.
[out]tsTimestamp representing the system time at which the last buffer completed.
Returns
A pointer to the last completed buffer, or NULL on failure.
Note
If the ring buffer is in free-running mode and the application cannot process data as fast as it is acquired, DMA will wrap around and overwrite the referenced buffer . The application must ensure that the data in the buffer is processed or copied out in time to prevent overrun.
See also
edt_wait_for_buffers(), edt_last_buffer(), edt_ring_buffer_overrun()
Here is the call graph for this function:
Here is the caller graph for this function:

◆ edt_set_buffer()

int edt_set_buffer ( EdtDev  edt_p,
uint_t  bufnum 
)

Set which buffer should be started next. Usually done to recover after a timeout, interrupt, or error.

Parameters
edt_pThe open EDT device handle.
bufnumThe index of the buffer to start next.
Returns
0 on success, -1 on failure.

\Example

u_int curdone;
curdone = edt_done_count(edt_p);
edt_set_buffer(edt_p, curdone);
See also
edt_stop_buffers, edt_done_count, edt_get_todo
Here is the caller graph for this function:

◆ edt_next_writebuf()

void * edt_next_writebuf ( EdtDev  edt_p)

Get a pointer to the next buffer scheduled for output DMA, in order to fill the buffer with data.

Parameters
edt_pThe open EDT device handle.
Returns
A pointer to the buffer, or NULL on failure.

◆ edt_dma_buffers_done_waiting()

uint32_t edt_dma_buffers_done_waiting ( EdtDev  edt_p)

Get the number of DMA buffers that have been waited for.

Parameters
edt_pThe open EDT device handle.
Returns
Number of buffers that userspace has waited for.

This value is updated by edt_wait_for_buffers() or edt_wait_for_next_buffer(). It indicates the (total) number of buffers that have been "waited" on and successfully finished transferring.

◆ edt_buffer_addresses()

void ** edt_buffer_addresses ( EdtDev  edt_p)

Get an array of ring buffer pointers.

Parameters
edt_pThe open EDT device handle.
Returns
An array of pointers to the ring buffers for this DMA channel. The array is indexed from zero to n-1 where n is the number of ring buffers set in edt_configure_ring_buffers().
Here is the caller graph for this function:

◆ edt_done_count()

uint32_t edt_done_count ( EdtDev  edt_p)

Returns the cumulative count of completed buffer transfers in ring buffer mode.

Parameters
edt_pThe open EDT device handle.
Returns
The number of completed buffer transfers. -1 is returned if ring buffer mode is not configured or some other error occurred.

Completed buffers are numbered consecutively starting with 0 when edt_configure_ring_buffers() is invoked. The index of the ring buffer most recently completed by the driver equals the number returned modulo the number of ring buffers.

If an error occurs, call edt_perror() to get the system error message.

Here is the caller graph for this function:

◆ edt_check_for_buffers()

void * edt_check_for_buffers ( EdtDev  edt_p,
uint_t  count 
)

Checks, without blocking, if the specified number of buffers have completed.

Parameters
edt_pThe open EDT device handle.
countNumber of buffers. Must be 1 or greater.
Returns
Returns the address of the ring buffer corresponding to count if it has completed DMA, or NULL if count buffers are not yet complete.
Note
If the ring buffer is in free-running mode and the application cannot process data as fast as it is acquired, DMA will wrap around and overwrite the referenced buffer. The application must ensure that the data in the buffer is processed or copied out in time to prevent overrun.

◆ edt_get_direction()

uint16_t edt_get_direction ( EdtDev  edt_p)

Get the value of the PCD_DIRA and PCD_DIRB registers. The value from PCD_DIRB is shifted up 8 bits.

Parameters
edt_pThe open EDT device handle.
Returns
Combined value read from direction registers.
Here is the call graph for this function:

◆ edt_startdma_reg()

void edt_startdma_reg ( EdtDev  edt_p,
uint_t  desc,
uint_t  val 
)

Set the register and value to use at the start of DMA, as set by edt_startdma_action().

Parameters
edt_pThe open EDT device handle.
descRegister description of which register to use as in edtreg.h.
valValue to write to register described by desc.
See also
edt_startdma_action(), edt_enddma_action() for an example.

◆ edt_enddma_reg()

void edt_enddma_reg ( EdtDev  edt_p,
uint_t  desc,
uint_t  val 
)

Sets the register and value to use at the end of dma, as set by edt_enddma_action().

Parameters
edt_pThe open EDT device handle.
descRegister description of which register to use as in edtreg.h.
valValue to write to register described by desc.
See also
edt_enddma_action() for an example.

◆ edt_startdma_action()

void edt_startdma_action ( EdtDev  edt_p,
uint_t  val 
)

Specifies when to perform the action at the start of a DMA transfer as specified by edt_startdma_reg().

Parameters
edt_pThe open EDT device handle.
valOne of EDT_ACT_NEVER, EDT_ACT_ONCE, or EDT_ACT_ALWAYS.

A common use of this is to write a register which signals an external device that DMA has started, to trigger the device to start sending. The default is no DMA action.

The PDV library uses this function to send a trigger to a camera at the start of DMA. This function allows the register write to occur in a critical section with the start of DMA and at the same time.

Example:

edt_startdma_action(edt_p, EDT_ACT_ALWAYS);
edt_startdma_reg(edt_p, PDV_CMD, PDV_ENABLE_GRAB);
See also
edt_startdma_reg(), edt_enddma_action(), edt_reg_write(), edt_reg_read()

◆ edt_enddma_action()

void edt_enddma_action ( EdtDev  edt_p,
uint_t  val 
)

Specifies when to perform the action at the end of a DMA transfer as specified by edt_enddma_reg().

Parameters
edt_pThe open EDT device handle.
valOne of EDT_ACT_NEVER, EDT_ACT_ONCE, or EDT_ACT_ALWAYS.

A common use of this is to write to a register which signals an external device that DMA is complete, or to change the state of a signal which will be changed at the start of DMA, so the external device can look for an edge. The default is no end of DMA action.

Most applications can set the output signal, if needed, from the application with edt_reg_write(). This routine is only needed if the action must happen within microseconds of the end of DMA.

Example:

u_int fnct_value = 0x1;
edt_enddma_action(edt_p, EDT_ACT_ALWAYS);
edt_enddma_reg(edt_p, PCD_FUNCT, fnct_value);
See also
edt_startdma_action(), edt_startdma_reg(), edt_reg_write(), edt_reg_read()

◆ edt_do_timeout()

int edt_do_timeout ( EdtDev  edt_p)

Cause the driver to perform the same actions as it would on a timeout. Partially filled FIFOs will be flushed and DMA will be aborted.

Parameters
edt_pThe open EDT device handle.
Returns
0 on success; -1 on failure

Used when the application has knowledge that no more data will be sent/accepted. Used when a common timeout cannot be known, such as when acquiring (image) data from a telescope CCD array where the amount of data sent depends on unknown future celestial events. Also used by the library when the operating system can not otherwise wait for an interrupt and timeout at the same time.

◆ edt_timeouts()

int edt_timeouts ( EdtDev  edt_p)

Get the number of read and write timeouts that have occurred since the last call of edt_open().

Parameters
edt_pThe open EDT device handle.
Returns
The number of read and write timeouts that have occurred since the last call of edt_open().
Here is the caller graph for this function:

◆ edt_get_timeout_count()

uint_t edt_get_timeout_count ( EdtDev  edt_p)

Get the number of bytes transferred at last timeout.

Parameters
edt_pThe open EDT device handle.
Returns
The number of bytes transferred at last timeout.
Here is the caller graph for this function:

◆ edt_set_timeout_action()

int edt_set_timeout_action ( EdtDev  edt_p,
EdtDmaTimeoutAction  action 
)

Set the driver behavior on a timeout.

Parameters
edt_pThe open EDT device handle.
actionThe action to perform when a timeout occurs. Values documented in EdtDmaTimeoutAction.
Returns
0 on success, -1 on failure.
Here is the call graph for this function:

◆ edt_get_timeout_goodbits()

int edt_get_timeout_goodbits ( EdtDev  edt_p)

Get the number of good bits in the last long word of a read buffer after the last timeout. This routine is called after a timeout if the timeout action is set to EDT_TIMEOUT_BIT_STROBE.

Parameters
edt_pThe open EDT device handle.
Returns
Number 0-31 represents the number of good bits in the last 32-bit word of the read buffer associated with the last timeout. 0 on failure.
See also
edt_set_timeout_action(), edt_get_goodbits()

◆ edt_get_goodbits()

int edt_get_goodbits ( EdtDev  edt_p)

Get the current number of good bits in the last long word of a read buffer (0 through 31).

Parameters
edt_pThe open EDT device handle.
Returns
Number 0-31 representing the number of good bits in the last 32-bit word of the current read buffer. 0 on failure.

◆ edt_set_event_func()

int edt_set_event_func ( EdtDev  edt_p,
enum edt_kernel_event  event_type,
EdtEventFunc  func,
void *  data,
int  continuous 
)

Define a function to call when an event occurs.

Use this routine to send an application-specific function when required; for example, when DMA completes, allowing the application to continue executing until the event of interest occurs.

If you wish to receive notification of one event only, and then disable further event notification, send a final argument of 0 (see the continue parameter described below). This disables event notification at the time of the callback to your function.

Parameters
edt_pThe open EDT device handle.
event_typeThe event that causes the function to be called.
funcThe function to call when the event occurs.
dataData to pass to the func function; usually edt_p.
continuousFlag to enable or disable continued event notification. A value of 0 causes edt_remove_event_func() to be called as the event is triggered.
Returns
0 on success, -1 on failure.

◆ edt_remove_event_func()

int edt_remove_event_func ( EdtDev  edt_p,
enum edt_kernel_event  event_type 
)

Remove an event function previously set with edt_set_event_func().

Parameters
edt_pThe open EDT device handle.
event_typeThe event that causes the function to be called. Valid events are listed in edt_set_event_func().
Returns
0 on success, -1 on failure.

◆ edt_ring_buffer_overrun()

int edt_ring_buffer_overrun ( EdtDev  edt_p)

Determine if DMA has written to more buffers in the ring than user space code has "waited" (edt_wait_for_buffers()) for. Indicates user space code cannot keep up with the DMA transfer rate.

Parameters
edt_pThe open EDT device handle.
Returns
1 (true) when overrun has occurred, 0 (false) otherwise.
Here is the call graph for this function:

◆ edt_set_burst_enable()

int edt_set_burst_enable ( EdtDev  edt_p,
int  onoff 
)

Set the burst enable flag, determining whether the DMA master transfers as many words as possible at once, or transfers them one at a time as soon as the data is acquired.

Parameters
edt_pThe open EDT device handle.
enableA value of 1 turns the flag on (the default); 0 turns it off.
Returns
0 if successful.

Burst transfers are enabled by default to optimize use of the bus; however, you may wish to disable them if data latency is an issue, or for diagnosing DMA problems.

◆ edt_get_burst_enable()

int edt_get_burst_enable ( EdtDev  edt_p)

Get the value of the burst enable flag.

See also
edt_set_burst_enable()
Parameters
edt_pThe open EDT device handle.
Return values
1if burst transfers are enabled
0if disabled
-1on error

◆ edt_set_rtimeout()

int edt_set_rtimeout ( EdtDev  edt_p,
int  timeout_ms 
)

Set the timeout for data receive calls.

Affects edt_wait_for_buffers() and edt_read().

Parameters
edt_pThe open EDT device handle.
timeout_msMilliseconds to wait before timing out. A value of 0 disables the timeout, causing read calls to wait forever (blocking).
Returns
0 on success; -1 on error
Here is the call graph for this function:

◆ edt_set_wtimeout()

int edt_set_wtimeout ( EdtDev  edt_p,
int  timeout_ms 
)

Set the timeout for data transmit calls.

Affects edt_wait_for_buffers() and edt_write().

Parameters
edt_pThe open EDT device handle.
timeout_msMilliseconds to wait before timing out. A value of 0 disables the timeout, causing write calls to wait forever (blocking).
Returns
0 on success; -1 on error
Here is the call graph for this function:

◆ edt_get_rtimeout()

int edt_get_rtimeout ( EdtDev  edt_p)

Gets the current read timeout value: the number of milliseconds to wait for DMA reads to complete before returning.

Parameters
edt_pThe open EDT device handle.
Returns
The number of milliseconds in the current read timeout period, or -1 on error.
Here is the caller graph for this function:

◆ edt_get_wtimeout()

int edt_get_wtimeout ( EdtDev  edt_p)

Gets the current write timeout value: the number of milliseconds to wait for DMA reads to complete before returning.

Parameters
edt_pThe open EDT device handle.
Returns
The number of milliseconds in the current write timeout period, or -1 on error.

◆ edt_overflow()

uint_t edt_overflow ( EdtDev  edt_p)

Get DMA overflow counter from the driver. Reset by edt_reset_counts().

Parameters
edt_pThe open EDT device handle.
Return values
>=0Overflow count read from the driver.
-1Error occurred.