Buffer Functions

FILE *out

Handle to the standard output. If NULL, defaults to stdout.

FILE *err

Handle to the error output. If NULL, defaults to stderr.

enum iio_log_level log_level

Log level to use. Defaults to the log level that was specified at compilation.

enum iio_log_level stderr_level

Under this log level (included), messages are sent to the error output ; above this log level (excluded), messages are sent to the standard output. If zero, defaults to LEVEL_WARNING.

enum iio_log_level timestamp_level

Under this log level (excluded), messages are sent without timestamp; above this log level (included), messages are sent with a timestamp. If set to LEVEL_NOLOG, messages at all log levels are sent without a timestamp. If zero, defaults to LEVEL_DEBUG.

int timeout_ms

Timeout for I/O operations in milliseconds.

  • IIO_TIMEOUT_BACKEND (0): use backend default timeout

  • IIO_TIMEOUT_INFINITE (-1): no timeout (wait indefinitely)

  • IIO_TIMEOUT_NONBLOCK (INT_MIN): non-blocking

  • Positive values: timeout after specified milliseconds

  • Other negative values: invalid (returns -EINVAL)

unsigned int flags

Flags that control context behavior. Bitmask of values from enum iio_context_flags.

char __rsrv[32]

Reserved for future fields.

uint64_t id
int64_t timestamp
unsigned int length

Total length of the sample, in bits.

unsigned int bits

Length of valuable data in the sample, in bits.

unsigned int shift

Right-shift to apply when converting sample.

bool is_signed

Contains True if the sample is signed.

bool is_fully_defined

Contains True if the sample is fully defined, sign extended, etc.

bool is_be

Contains True if the sample is in big-endian format.

bool with_scale

Contains True if the sample should be scaled when converted.

double scale

Contains the scale to apply if with_scale is set.

unsigned int repeat

Number of times length repeats (added in v0.8)

double offset

Contains a value to be added to the raw sample before applying the scale.

const struct iio_device *iio_buffer_get_device(const struct iio_buffer *buf)

Retrieve a pointer to the iio_device structure.

Parameters:

buf – A pointer to an iio_buffer structure

Returns:

A pointer to an iio_device structure

unsigned int iio_buffer_get_attrs_count(const struct iio_buffer *buf)

Enumerate the attributes of the given buffer.

Parameters:

buf – A pointer to an iio_buffer structure

Returns:

The number of buffer-specific attributes found

const struct iio_attr *iio_buffer_get_attr(const struct iio_buffer *buf, unsigned int index)

Get the buffer-specific attribute present at the given index.

Parameters:

  • buf – A pointer to an iio_buffer structure

  • index – The index corresponding to the attribute

Returns:

On success, a pointer to an iio_attr structure

Returns:

If the index is invalid, NULL is returned

unsigned int iio_buffer_get_scan_elements_count(const struct iio_buffer *buf)

Enumerate the scan elements of the given buffer.

Parameters:

buf – A pointer to an iio_buffer structure

Returns:

The number of scan elements associated with the buffer

const struct iio_channel *iio_buffer_get_scan_element(const struct iio_buffer *buf, unsigned int index)

Get the scan element present at the given index.

Parameters:

  • buf – A pointer to an iio_buffer structure

  • index – The index corresponding to the scan element

Returns:

On success, a pointer to an iio_channel structure

Returns:

If the index is invalid, NULL is returned

const struct iio_attr *iio_buffer_find_attr(const struct iio_buffer *buf, const char *name)

Try to find a buffer-specific attribute by its name.

Parameters:

  • buf – A pointer to an iio_buffer structure

  • name – A NULL-terminated string corresponding to the name of the attribute

Returns:

On success, a pointer to an iio_attr structure

Returns:

If the name does not correspond to any known attribute of the given buffer, NULL is returned

bool iio_buffer_is_output(const struct iio_buffer *buf)

Returns true if the buffer is an output buffer.

Parameters:

buf – A pointer to an iio_buffer structure

Returns:

True if the buffer is an output (TX) buffer, false otherwise

void iio_buffer_set_data(struct iio_buffer *buf, void *data)

Associate a pointer to an iio_buffer structure.

Parameters:

  • buf – A pointer to an iio_buffer structure

  • data – The pointer to be associated

void *iio_buffer_get_data(const struct iio_buffer *buf)

Retrieve a previously associated pointer of an iio_buffer structure.

Parameters:

buf – A pointer to an iio_buffer structure

Returns:

The pointer previously associated if present, or NULL

int iio_attr_read_bool(const struct iio_attr *attr, bool *val)
int iio_attr_read_longlong(const struct iio_attr *attr, long long *val)
int iio_attr_read_double(const struct iio_attr *attr, double *val)
ssize_t iio_attr_write_string(const struct iio_attr *attr, const char *src)
int iio_attr_write_bool(const struct iio_attr *attr, bool val)
int iio_attr_write_longlong(const struct iio_attr *attr, long long val)
int iio_attr_write_double(const struct iio_attr *attr, double val)
struct iio_buffer
#include <iio.h>

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

struct iio_block *iio_buffer_stream_create_block(struct iio_buffer_stream *buf_stream, size_t size)

Create a data block for the given buffer stream.

Parameters:

  • buf_stream – A pointer to an iio_buffer_stream structure

  • size – The size of the block to create, in bytes

Returns:

On success, a pointer to an iio_block structure

Returns:

On failure, a pointer-encoded error is returned

void iio_block_destroy(struct iio_block *block)

Destroy the given block.

Parameters:

block – A pointer to an iio_block structure

int iio_block_get_dmabuf_fd(const struct iio_block *block)

Get the file descriptor of the underlying DMABUF object.

Parameters:

block – A pointer to an iio_block structure

Returns:

The file descriptor of the underlying DMABUF object. If the iio_block is not backed by a DMABUF object, -EINVAL is returned. Otherwise, the file descriptor will be valid until the block is destroyed.

int iio_block_disable_cpu_access(struct iio_block *block, bool disable)

Disable CPU access of a given block.

NOTE:Disabling CPU access is useful when manipulating DMABUF objects. If CPU access is disabled, the block’s internal buffer of samples should not be accessed. Therefore, the following functions should not be called: iio_block_start, iio_block_first, iio_block_end, iio_block_foreach_sample.

Parameters:

  • block – A pointer to an iio_block structure

  • disable – Whether or not to disable CPU access

void *iio_block_start(const struct iio_block *block)

Get the start address of the block.

Parameters:

block – A pointer to an iio_block structure

Returns:

A pointer corresponding to the start address of the block

void *iio_block_first(const struct iio_block *block, const struct iio_channel *chn)

Find the first sample of a channel in a block.

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

for (void *ptr = iio_block_first(block, chn);
     ptr < iio_block_end(block);
     ptr += iio_device_get_sample_size(dev, mask)) {
   ....
}

The iio_channel passed as argument must be from the iio_device that was used to create the iio_buffer and then the iio_block, otherwise the result is undefined.

Parameters:
Returns:

A pointer to the first sample found, or to the end of the block if no sample for the given channel is present in the block

void *iio_block_end(const struct iio_block *block)

Get the address after the last sample in a block.

Parameters:

block – A pointer to an iio_block structure

Returns:

A pointer corresponding to the address that follows the last sample present in the buffer

ssize_t iio_block_foreach_sample(const struct iio_block *block, const struct iio_channels_mask *mask, 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 block.

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

Parameters:

  • block – A pointer to an iio_block structure

  • mask – A pointer to the iio_channels_mask structure that represents the list of channels for which we want samples

  • callback – A pointer to a function to call for each sample found

  • data – A user-specified pointer that will be passed to the callback

Returns:

number of bytes processed.

int iio_block_enqueue(struct iio_block *block, size_t bytes_used, bool cyclic)

Enqueue the given iio_block to the buffer’s queue.

NOTE: After iio_block_enqueue is called, the block’s data must not be accessed until iio_block_dequeue successfully returns.

Parameters:

  • block – A pointer to an iio_block structure

  • bytes_used – The amount of data in bytes to be transferred (either transmitted or received). If zero, the size of the block is used.

  • cyclic – If True, enable cyclic mode. The block’s content will be repeated on the hardware’s output until the buffer is cancelled or destroyed.

Returns:

On success, 0 is returned

Returns:

On error, a negative error code is returned

int iio_block_dequeue(struct iio_block *block, bool nonblock)

Dequeue the given iio_block from the buffer’s queue.

Parameters:

  • block – A pointer to an iio_block structure

  • nonblock – if True, the operation won’t block and return -EBUSY if the block is not ready for dequeue.

Returns:

On success, 0 is returned

Returns:

On error, a negative error code is returned

struct iio_buffer_stream *iio_block_get_buffer_stream(const struct iio_block *block)

Retrieve a pointer to the iio_buffer_stream structure.

Parameters:

block – A pointer to an iio_block structure

Returns:

A pointer to an iio_buffer_stream structure

struct iio_block
#include <iio.h>

A block of memory containing data samples.

struct iio_stream *iio_buffer_create_stream(struct iio_buffer *buffer, size_t nb_blocks, size_t samples_count, struct iio_channels_mask *mask)

Create a iio_stream object for the given iio_buffer.

Parameters:

  • buffer – A pointer to an iio_buffer structure

  • nb_blocks – The number of iio_block objects to create, internally. In doubt, a good value is 4.

  • samples_count – The size of the iio_block objects, in samples

  • mask – A pointer to the iio_channels_mask structure

Returns:

On success, a pointer to an iio_stream structure

Returns:

On failure, a pointer-encoded error is returned

void iio_stream_cancel(struct iio_stream *stream)

Cancel all stream operations.

Parameters:

stream – A pointer to an iio_stream structure

void iio_stream_destroy(struct iio_stream *stream)

Destroy the given stream object.

Parameters:

stream – A pointer to an iio_stream structure

const struct iio_block *iio_stream_get_next_block(struct iio_stream *stream)

Get a pointer to the next data block.

Parameters:

stream – A pointer to an iio_stream structure

Returns:

On success, a pointer to an iio_block structure

Returns:

On failure, a pointer-encoded error is returned

struct iio_stream
#include <iio.h>

A helper object to simplify reading/writing to a iio_buffer.