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, uint32_t 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...

uint32_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, unsigned int size)
	Perform a DMA read from the EDT device. More...

int	edt_write (EdtDev edt_p, void *buf, unsigned int 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, uint32_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, unsigned int count)
	Start DMA transfers for `count` number of buffers. More...

int	edt_set_buffer_size (EdtDev edt_p, unsigned int index, uint32_t size, uint32_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, unsigned 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, uint32_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, uint32_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, uint32_t desc, uint32_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, uint32_t desc, uint32_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, uint32_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, uint32_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...

uint32_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...

uint32_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_p	The open EDT device handle.
bufsize	Size of each buffer, in bytes.
numbufs	Number of buffers. Must be 1 or greater. Four is recommended for most applications.
write_flag	Whether 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()

◆ edt_ref_tmstamp()

int edt_ref_tmstamp	(	EdtDev	edt_p,
		uint32_t	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
 
edt_ref_tmstamp(edt_p, BEFORE_WAIT);
void* 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_p	The open EDT device handle.
val	An arbitrary value meaningful to the application.

Returns: 0 on success, -1 on failure

◆ edt_get_todo()

uint32_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_p The open EDT device handle.

Returns: Number of buffers started via edt_start_buffers().

◆ edt_read()

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

Perform a DMA read from the EDT device.

Parameters

edt_p	The open EDT device handle.
buf	Buffer to read data in to.
size	Number 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.

◆ edt_write()

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

Perform a DMA write to the EDT device.

Parameters

edt_p	The open EDT device handle.
buf	Data to write to the device.
size	Number 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.

◆ 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_p	The open EDT device handle.
bufsize	Size of individual buffers, in bytes
numbufs	Number of buffers to create in the ring.
write_flag	Either EDT_WRITE or EDT_READ.
header_size	If 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_before	If 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_p	The EDT device handle, opened as a dummy device.
callback	Function to invoke when edt_wait_for_buffers() is called.

Only to be invoked if the EDT device handle is "dmy" or "DMY" i.e. the internal device ID (get with edt_device_id()) is DMY_ID.

In this case, since there is not a real EDT device to supply data, callback provides the user with a hook to allow filling the waiting buffer with test data.

◆ 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_p	The EDT device handle, opened as a dummy device.
callback	Function 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_p	The EDT device handle, opened as a dummy device.
callback	Function 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_p The 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_p The open EDT device handle.

Returns: 0 on success, -1 on failure. Get system error message with edt_perror().

◆ 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_p The 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,
		uint32_t	bufnum
	)

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

Parameters

edt_p	The open EDT device handle.
bufnum	The 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.

◆ 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_p The open EDT device handle.

Returns: 0 on success, -1 on failure.

See also: edt_reset_ring_buffers(), edt_abort_current_dma()

◆ 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_p The open EDT device handle.

Returns: 0 on success, -1 on failure.

See also: edt_reset_ring_buffers(), edt_abort_dma()

◆ 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_p The open EDT device handle.

Returns: 0 on success, -1 on failure.

◆ edt_start_buffers()

int edt_start_buffers	(	EdtDev	edt_p,
		unsigned int	count
	)

Start DMA transfers for count number of buffers.

Parameters

edt_p	The open EDT device handle.
count	Number 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.

◆ edt_set_buffer_size()

int edt_set_buffer_size	(	EdtDev	edt_p,
		unsigned int	index,
		uint32_t	size,
		uint32_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_p	The open EDT device handle.
index	Index of ring buffer to change.
size	New buffer size to use.
write_flag	Direction; 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.

◆ edt_allocated_size()

unsigned int edt_allocated_size	(	EdtDev	edt_p,
		int	buffer_idx
	)

Get the allocated size of the specified buffer.

Parameters

edt_p	The open EDT device handle.
buffer_idx	Index 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_p	The open EDT device handle.
bufsize	Size of a buffer.
header_size	Optional 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_p	The open EDT device handle.
count	Number 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.

◆ edt_get_timestamp()

int edt_get_timestamp	(	EdtDev	edt_p,
		edt_timespec_t *	ts,
		unsigned int	bufnum
	)

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

Parameters

	edt_p	The open EDT device handle.
[out]	ts	Timestamp representing the system time at which the buffer completed.
	bufnum	Either 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:

edt_timespec_t ts;
uint32_t bufnum = edt_done_count(edt_p);
edt_get_timestamp(edt_p, &ts, bufnum);
printf("Timestamp: %s", edt_timestring(&ts));

◆ 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_p The open EDT device handle.

Returns: Returns a pointer to the buffer, or NULL on failure.

◆ 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_p	The open EDT device handle.
[out]	ts	Timestamp representing the system time at which the buffer completed.

Returns: A pointer to the last buffer, or NULL on failure.

Example:

edt_timespec_t ts;

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

◆ 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_p The 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()

◆ 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_p	The open EDT device handle.
	count	Number of buffers for which to block. Completed buffers are numbered cumulatively starting with 0 when the EDT device is opened.
[out]	ts	Timestamp 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()

◆ edt_set_buffer()

int edt_set_buffer	(	EdtDev	edt_p,
		uint32_t	bufnum
	)

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

Parameters

edt_p	The open EDT device handle.
bufnum	The index of the buffer to start next.

Returns: 0 on success, -1 on failure.

Example:

unsigned int curdone;
edt_stop_buffers(edt_p);
curdone = edt_done_count(edt_p);
edt_set_buffer(edt_p, curdone);

See also: edt_stop_buffers, edt_done_count, edt_get_todo

◆ 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_p The 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_p The 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_p The 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().

◆ 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_p The 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.

◆ edt_check_for_buffers()

void * edt_check_for_buffers	(	EdtDev	edt_p,
		uint32_t	count
	)

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

Parameters

edt_p	The open EDT device handle.
count	Number 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_p The open EDT device handle.

Returns: Combined value read from direction registers.

◆ edt_startdma_reg()

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

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

Parameters

edt_p	The open EDT device handle.
desc	Register description of which register to use as in edtreg.h.
val	Value 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,
		uint32_t	desc,
		uint32_t	val
	)

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

Parameters

edt_p	The open EDT device handle.
desc	Register description of which register to use as in edtreg.h.
val	Value 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,
		uint32_t	val
	)

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

Parameters

edt_p	The open EDT device handle.
val	One 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,
		uint32_t	val
	)

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

Parameters

edt_p	The open EDT device handle.
val	One 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:

uint32_t 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_p The 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_p The open EDT device handle.

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

◆ edt_get_timeout_count()

uint32_t edt_get_timeout_count ( EdtDev edt_p )

Get the number of bytes transferred at last timeout.

Parameters

edt_p The open EDT device handle.

Returns: The number of bytes transferred at last timeout.

◆ edt_set_timeout_action()

int edt_set_timeout_action	(	EdtDev	edt_p,
		EdtDmaTimeoutAction	action
	)

Set the driver behavior on a timeout.

Parameters

edt_p	The open EDT device handle.
action	The action to perform when a timeout occurs. Values documented in EdtDmaTimeoutAction.

Returns: 0 on success, -1 on failure.

◆ 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_p The 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_p The 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_p	The open EDT device handle.
event_type	The event that causes the function to be called.
func	The function to call when the event occurs.
data	Data to pass to the `func` function; usually `edt_p`.
continuous	Flag 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_p	The open EDT device handle.
event_type	The 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_p The open EDT device handle.

Returns: 1 (true) when overrun has occurred, 0 (false) otherwise.

◆ 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_p	The open EDT device handle.
enable	A 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_p The open EDT device handle.

Return values

1	if burst transfers are enabled
0	if disabled
-1	on 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_p	The open EDT device handle.
timeout_ms	Milliseconds 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

◆ 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_p	The open EDT device handle.
timeout_ms	Milliseconds 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

◆ 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_p The open EDT device handle.

Returns: The number of milliseconds in the current read timeout period, or -1 on error.

◆ 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_p The open EDT device handle.

Returns: The number of milliseconds in the current write timeout period, or -1 on error.

◆ edt_overflow()

uint32_t edt_overflow ( EdtDev edt_p )

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

Parameters

edt_p The open EDT device handle.

Return values

>=0	Overflow count read from the driver.
-1	Error occurred.

Functions

Detailed Description

Function Documentation

◆ edt_configure_ring_buffers()

◆ edt_ref_tmstamp()

◆ edt_get_todo()

◆ edt_read()

◆ edt_write()

◆ edt_configure_block_buffers()

◆ edt_set_dmy_wait_for_buffers_callback()

◆ edt_set_dmy_reg_read_callback()

◆ edt_set_dmy_reg_write_callback()

◆ edt_map_dmamem()

◆ edt_disable_ring_buffers()

◆ edt_get_numbufs()

◆ edt_reset_ring_buffers()

◆ edt_abort_dma()

◆ edt_abort_current_dma()

◆ edt_stop_buffers()

◆ edt_start_buffers()

◆ edt_set_buffer_size()

◆ edt_allocated_size()

◆ edt_get_total_bufsize()

◆ edt_wait_for_buffers()

◆ edt_get_timestamp()

◆ edt_wait_for_next_buffer()

◆ edt_last_buffer_timed()

◆ edt_last_buffer()

◆ edt_wait_buffers_timed()

◆ edt_set_buffer()

◆ edt_next_writebuf()

◆ edt_dma_buffers_done_waiting()

◆ edt_buffer_addresses()

◆ edt_done_count()

◆ edt_check_for_buffers()

◆ edt_get_direction()

◆ edt_startdma_reg()

◆ edt_enddma_reg()

◆ edt_startdma_action()

◆ edt_enddma_action()

◆ edt_do_timeout()

◆ edt_timeouts()

◆ edt_get_timeout_count()

◆ edt_set_timeout_action()

◆ edt_get_timeout_goodbits()

◆ edt_get_goodbits()

◆ edt_set_event_func()

◆ edt_remove_event_func()

◆ edt_ring_buffer_overrun()

◆ edt_set_burst_enable()

◆ edt_get_burst_enable()

◆ edt_set_rtimeout()

◆ edt_set_wtimeout()

◆ edt_get_rtimeout()

◆ edt_get_wtimeout()

◆ edt_overflow()