libiio  0.18
Library for interfacing with IIO devices
Data Structures | Functions
Buffer

Data Structures

struct  iio_buffer
 An input or output buffer, used to read or write samples. More...
 

Functions

__api __pure const struct iio_deviceiio_buffer_get_device (const struct iio_buffer *buf)
 Retrieve a pointer to the iio_device structure. More...
 
__api struct iio_bufferiio_device_create_buffer (const struct iio_device *dev, size_t samples_count, bool cyclic)
 Create an input or output buffer associated to the given device. More...
 
__api void iio_buffer_destroy (struct iio_buffer *buf)
 Destroy the given buffer. More...
 
__api int iio_buffer_get_poll_fd (struct iio_buffer *buf)
 Get a pollable file descriptor. More...
 
__api int iio_buffer_set_blocking_mode (struct iio_buffer *buf, bool blocking)
 Make iio_buffer_refill() and iio_buffer_push() blocking or not. More...
 
__api ssize_t iio_buffer_refill (struct iio_buffer *buf)
 Fetch more samples from the hardware. More...
 
__api ssize_t iio_buffer_push (struct iio_buffer *buf)
 Send the samples to the hardware. More...
 
__api ssize_t iio_buffer_push_partial (struct iio_buffer *buf, size_t samples_count)
 Send a given number of samples to the hardware. More...
 
__api void iio_buffer_cancel (struct iio_buffer *buf)
 Cancel all buffer operations. More...
 
__api void * iio_buffer_start (const struct iio_buffer *buf)
 Get the start address of the buffer. More...
 
__api void * iio_buffer_first (const struct iio_buffer *buf, const struct iio_channel *chn)
 Find the first sample of a channel in a buffer. More...
 
__api ptrdiff_t iio_buffer_step (const struct iio_buffer *buf)
 Get the step size between two samples of one channel. More...
 
__api void * iio_buffer_end (const struct iio_buffer *buf)
 Get the address that follows the last sample in a buffer. More...
 
__api ssize_t iio_buffer_foreach_sample (struct iio_buffer *buf, ssize_t(*callback)(const struct iio_channel *chn, void *src, size_t bytes, void *d), void *data)
 Call the supplied callback for each sample found in a buffer. More...
 
__api void iio_buffer_set_data (struct iio_buffer *buf, void *data)
 Associate a pointer to an iio_buffer structure. More...
 
__api void * iio_buffer_get_data (const struct iio_buffer *buf)
 Retrieve a previously associated pointer of an iio_buffer structure. More...
 

Detailed Description

Function Documentation

__api void iio_buffer_cancel ( struct iio_buffer buf)

Cancel all buffer operations.

Parameters
bufThe buffer for which operations should be canceled

This function cancels all outstanding buffer operations previously scheduled. This means any pending iio_buffer_push() or iio_buffer_refill() operation will abort and return immediately, any further invocations of these functions on the same buffer will return immediately with an error.

Usually iio_buffer_push() and iio_buffer_refill() will block until either all data has been transferred or a timeout occurs. This can depending on the configuration take a significant amount of time. iio_buffer_cancel() is useful to bypass these conditions if the buffer operation is supposed to be stopped in response to an external event (e.g. user input).

To be able to capture additional data after calling this function the buffer should be destroyed and then re-created.

This function can be called multiple times for the same buffer, but all but the first invocation will be without additional effect.

This function is thread-safe, but not signal-safe, i.e. it must not be called from a signal handler.

__api void iio_buffer_destroy ( struct iio_buffer buf)

Destroy the given buffer.

Parameters
bufA pointer to an iio_buffer structure

NOTE: After that function, the iio_buffer pointer shall be invalid.

__api void* iio_buffer_end ( const struct iio_buffer buf)

Get the address that follows the last sample in a buffer.

Parameters
bufA pointer to an iio_buffer structure
Returns
A pointer corresponding to the address that follows the last sample present in the buffer

Here is the caller graph for this function:

__api void* iio_buffer_first ( const struct iio_buffer buf,
const struct iio_channel chn 
)

Find the first sample of a channel in a buffer.

Parameters
bufA pointer to an iio_buffer structure
chnA pointer to an iio_channel structure
Returns
A pointer to the first sample found, or to the end of the buffer if no sample for the given channel is present in the buffer

NOTE: This function, coupled with iio_buffer_step and iio_buffer_end, can be used to iterate on all the samples of a given channel present in the buffer, doing the following:

for (void *ptr = iio_buffer_first(buffer, chn); ptr < iio_buffer_end(buffer); ptr += iio_buffer_step(buffer)) {
   ....
}

Here is the call graph for this function:

Here is the caller graph for this function:

__api ssize_t iio_buffer_foreach_sample ( struct iio_buffer buf,
ssize_t(*)(const struct iio_channel *chn, void *src, size_t bytes, void *d)  callback,
void *  data 
)

Call the supplied callback for each sample found in a buffer.

Parameters
bufA pointer to an iio_buffer structure
callbackA pointer to a function to call for each sample found
dataA user-specified pointer that will be passed to the callback
Returns
number of bytes processed.

NOTE: The callback receives four arguments:

  • A pointer to the iio_channel structure corresponding to the sample,
  • A pointer to the sample itself,
  • The length of the sample in bytes,
  • The user-specified pointer passed to iio_buffer_foreach_sample.

Here is the caller graph for this function:

__api void* iio_buffer_get_data ( const struct iio_buffer buf)

Retrieve a previously associated pointer of an iio_buffer structure.

Parameters
bufA pointer to an iio_buffer structure
Returns
The pointer previously associated if present, or NULL
__api __pure const struct iio_device* iio_buffer_get_device ( const struct iio_buffer buf)

Retrieve a pointer to the iio_device structure.

Parameters
bufA pointer to an iio_buffer structure
Returns
A pointer to an iio_device structure
__api int iio_buffer_get_poll_fd ( struct iio_buffer buf)

Get a pollable file descriptor.

Can be used to know when iio_buffer_refill() or iio_buffer_push() can be called

Parameters
bufA pointer to an iio_buffer structure
Returns
On success, valid file descriptor
On error, a negative errno code is returned
__api ssize_t iio_buffer_push ( struct iio_buffer buf)

Send the samples to the hardware.

Parameters
bufA pointer to an iio_buffer structure
Returns
On success, the number of bytes written is returned
On error, a negative errno code is returned

NOTE: Only valid for output buffers

Here is the caller graph for this function:

__api ssize_t iio_buffer_push_partial ( struct iio_buffer buf,
size_t  samples_count 
)

Send a given number of samples to the hardware.

Parameters
bufA pointer to an iio_buffer structure
samples_countThe number of samples to submit
Returns
On success, the number of bytes written is returned
On error, a negative errno code is returned

NOTE: Only valid for output buffers

Here is the call graph for this function:

__api ssize_t iio_buffer_refill ( struct iio_buffer buf)

Fetch more samples from the hardware.

Parameters
bufA pointer to an iio_buffer structure
Returns
On success, the number of bytes read is returned
On error, a negative errno code is returned

NOTE: Only valid for input buffers

__api int iio_buffer_set_blocking_mode ( struct iio_buffer buf,
bool  blocking 
)

Make iio_buffer_refill() and iio_buffer_push() blocking or not.

After this function has been called with blocking == false, iio_buffer_refill() and iio_buffer_push() will return -EAGAIN if no data is ready. A device is blocking by default.

Parameters
bufA pointer to an iio_buffer structure
blockingtrue if the buffer API should be blocking, else false
Returns
On success, 0
On error, a negative errno code is returned
__api void iio_buffer_set_data ( struct iio_buffer buf,
void *  data 
)

Associate a pointer to an iio_buffer structure.

Parameters
bufA pointer to an iio_buffer structure
dataThe pointer to be associated
__api void* iio_buffer_start ( const struct iio_buffer buf)

Get the start address of the buffer.

Parameters
bufA pointer to an iio_buffer structure
Returns
A pointer corresponding to the start address of the buffer
__api ptrdiff_t iio_buffer_step ( const struct iio_buffer buf)

Get the step size between two samples of one channel.

Parameters
bufA pointer to an iio_buffer structure
Returns
the difference between the addresses of two consecutive samples of one same channel

Here is the caller graph for this function:

__api struct iio_buffer* iio_device_create_buffer ( const struct iio_device dev,
size_t  samples_count,
bool  cyclic 
)

Create an input or output buffer associated to the given device.

Parameters
devA pointer to an iio_device structure
samples_countThe number of samples that the buffer should contain
cyclicIf True, enable cyclic mode
Returns
On success, a pointer to an iio_buffer structure
On error, NULL is returned, and errno is set to the error code

NOTE: Channels that have to be written to / read from must be enabled before creating the buffer.

Here is the call graph for this function: