Block

Classes
struct	iio_block
	A block of memory containing data samples. More...

Functions
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.
void	iio_block_destroy (struct iio_block *block)
	Destroy the given block.
int	iio_block_get_dmabuf_fd (const struct iio_block *block)
	Get the file descriptor of the underlying DMABUF object.
int	iio_block_disable_cpu_access (struct iio_block *block, bool disable)
	Disable CPU access of a given block.
void *	iio_block_start (const struct iio_block *block)
	Get 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.
void *	iio_block_end (const struct iio_block *block)
	Get the address after the last sample in a block.
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.
int	iio_block_enqueue (struct iio_block *block, size_t bytes_used, bool cyclic)
	Enqueue the given iio_block to the buffer's queue.
int	iio_block_dequeue (struct iio_block *block, bool nonblock)
	Dequeue the given iio_block from the buffer's queue.
struct iio_buffer_stream *	iio_block_get_buffer_stream (const struct iio_block *block)
	Retrieve a pointer to the iio_buffer_stream structure.

Detailed Description

Function Documentation

iio_block_dequeue()

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

On error, a negative error code is returned

iio_block_destroy()

void iio_block_destroy

(

struct iio_block *

block

)

Destroy the given block.

Parameters

block

A pointer to an iio_block structure

NOTE: If the block is backed by a DMABUF object, the file descriptor previously returned by iio_block_get_dmabuf_fd is closed by this function.

iio_block_disable_cpu_access()

int iio_block_disable_cpu_access	(	struct iio_block *	block,
		bool	disable )

Disable CPU access of a given block.

Parameters

block	A pointer to an iio_block structure
disable	Whether or not to disable CPU access

Returns

On success, 0 is returned

On error, a negative error code is returned. -ENOSYS is returned if the backend does not implement CPU access control, -EINVAL if the block is not backed by an object for which it can be controlled.

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.

iio_block_end()

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

On success, a pointer corresponding to the address that follows the last sample present in the buffer

On failure, a pointer-encoded error is returned; see iio_block_start

iio_block_enqueue()

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

Enqueue the given iio_block to the buffer's queue.

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

On error, a negative error code is returned

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

iio_block_first()

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

Find the first sample of a channel in a block.

Parameters

block	A pointer to an iio_block structure
chn	A pointer to an iio_channel structure

Returns

On success, 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

On failure, a pointer-encoded error is returned; see iio_block_start

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.

iio_block_foreach_sample()

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.

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

On success, the number of bytes processed

On error, a negative error code is returned

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.

iio_block_get_buffer_stream()

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

iio_block_get_dmabuf_fd()

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.

NOTE: The returned file descriptor is owned by the iio_block. The caller must not close it; it is closed by iio_block_destroy.

iio_block_start()

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

On success, a pointer corresponding to the start address of the block

On failure, a pointer-encoded error is returned

NOTE: Check the returned pointer with iio_err before dereferencing it. A block's memory is not guaranteed to be reachable by the CPU; memory that cannot be mapped or accessed, would be reported this way rather than as a valid address.

iio_buffer_stream_create_block()

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

On failure, a pointer-encoded error is returned