libiio Documentation

License

Libiio has been developed and is released under the terms of the GNU Lesser General Public License, version 2. This open-source license allows anyone to use the library for proprietary or open-source, commercial or non-commercial applications. This choice was motivated by the fact that Analog Devices is a company that principally sells hardware, and this library provides the clients with a better and easier way of using this hardware.

The full terms of the license can be found here: http://opensource.org/licenses/LGPL-2.1

Code Model

The basic bricks of the libiio API are the iio_context, iio_device, iio_channel and iio_buffer classes.


• A iio_context object may contain zero or more iio_device objects. A iio_device object is associated with only one iio_context. This object represents an instance of the library.
• A iio_device object may contain zero or more iio_channel objects. A iio_channel object is associated with only one iio_device.
• A iio_device object may be associated with one iio_buffer object, and a iio_buffer object is associated with only one iio_device.

Creating a context

Different functions are available to create the iio_context object. Depending on what backends were enabled when compiling the library, some of them may not be available. Each function will result in a different backend being used.

Those functions are:

• iio_create_local_context(): Create a "local" context, to use the IIO devices connected to the system (typically for cross-compiled applications).
• iio_create_network_context(): Create a "network" context that will work with a remotely connected target.

Note that every function that compose the API of libiio will work independently of the function that was used to create the iio_context object.

The iio_context object can later be destroyed with iio_context_destroy().

Navigation

Device objects

• From the iio_context object, you can obtain the number of available devices with iio_context_get_devices_count().
• Then, each iio_device object can be accessed with iio_context_get_device().
• Alternatively, it is possible to lookup for a device name or ID with iio_context_find_device().

Each iio_device object has an ID that can be used as identifier. This ID can be retrieved with iio_device_get_id(). It optionally also has a name, that can be retrieved with iio_device_get_name().

Channel objects

• From the iio_device object, you can obtain the number of available channels with iio_device_get_channels_count().
• Then, each iio_channel object can be accessed with iio_device_get_channel().
• Alternatively, it is possible to lookup for a channel name or ID with iio_device_find_channel().

Each iio_channel can be either input, or output. This information can be retrieved with iio_channel_is_output(). As for the Device objects, the iio_channel object features an ID and optionally a name. The ID can be obtained with iio_channel_get_id(), and the name can be obtained with iio_channel_get_name(). Important note: two iio_channel can have the same ID, as long as one is input and the other is output.

Parameters

Different kinds of parameters are available: parameters that apply to a iio_device, and parameters that apply to one or more iio_channel.

• The number of device-specific parameters can be obtained with iio_device_get_attrs_count(). Each attribute name can be obtained with iio_device_get_attr().
• The number of channel-specific attributes can be obtained with iio_channel_get_attrs_count(). Each attribute name can be obtained with iio_channel_get_attr().

Alternatively, it is possible to lookup for the name of an attribute with iio_device_find_attr() and iio_channel_find_attr().

Reading and modifying parameters

Reading a parameter

Read device-specific attributes with those functions:

• iio_device_attr_read()
• iio_device_attr_read_all()
• iio_device_attr_read_bool()
• iio_device_attr_read_longlong()
• iio_device_attr_read_double()

Read channel-specific attributes with those functions:

• iio_channel_attr_read()
• iio_channel_attr_read_all()
• iio_channel_attr_read_bool()
• iio_channel_attr_read_longlong()
• iio_channel_attr_read_double()

Read debug attributes with those functions:

• iio_device_debug_attr_read()
• iio_device_debug_attr_read_all()
• iio_device_debug_attr_read_bool()
• iio_device_debug_attr_read_longlong()
• iio_device_debug_attr_read_double()

Modifying a parameter

Write device-specific attributes with those functions:

• iio_device_attr_write()
• iio_device_attr_write_all()
• iio_device_attr_write_bool()
• iio_device_attr_write_longlong()
• iio_device_attr_write_double()

Write channel-specific attributes with those functions:

• iio_channel_attr_write()
• iio_channel_attr_write_all()
• iio_channel_attr_write_bool()
• iio_channel_attr_write_longlong()
• iio_channel_attr_write_double()

Write debug attributes with those functions:

• iio_device_debug_attr_write()
• iio_device_debug_attr_write_all()
• iio_device_debug_attr_write_bool()
• iio_device_debug_attr_write_longlong()
• iio_device_debug_attr_write_double()

Triggers

Some devices, mostly low-speed ADCs and DACs, require a trigger to be set for the capture or upload process to work.

In libiio, triggers are just regular iio_device objects. To check if a iio_buffer can be used as a trigger, you can use iio_device_is_trigger().

To see if one device is associated with a trigger, use iio_device_get_trigger().

To assign one trigger to a iio_device, you can use iio_device_set_trigger(). If you want to disassociate a iio_device from its trigger, pass NULL to the "trigger" parameter of this function.

Capturing or uploading samples

The process of capturing samples from the hardware and uploading samples to the hardware is done using the functions that apply to the iio_buffer object.

Enabling channels and creating the Buffer object

The very first step is to enable the capture channels that we want to use, and disable those that we don't need. This is done with the functions iio_channel_enable() and iio_channel_disable(). Note that the channels will really be enabled or disabled when the iio_buffer object is created.

Also, not all channels can be enabled. To know whether or not one channel can be enabled, use iio_channel_is_scan_element().

Once the channels have been enabled, the iio_buffer object can be created from the iio_device object that will be used, with the function iio_device_create_buffer(). This call will fail if no channels have been enabled.

When the object is no more needed, it can be destroyed with iio_buffer_destroy().

Refilling the Buffer (input devices only)

If the Buffer object has been created from a device with input channels, then it must be updated first. This is done with the iio_buffer_refill() function.

Reading or writing samples to the Buffer

Libiio offers various ways to interact with the iio_buffer object.

Direct copy

If you already have a buffer of samples, correctly interleaved and in the format that the hardware expects, it is possible to copy the samples directly into the iio_buffer object using `memcpy`:

~~~{.c} size_t iio_buf_size = iio_buffer_end(buffer) - iio_buffer_start(buffer); size_t count = MAX(sizeof(samples_buffer), iio_buf_size); memcpy(iio_buffer_start(buffer), samples_buffer, count); ~~~

Using `memcpy` to copy samples from the iio_buffer is not recommended. When capturing samples from an input device, you cannot assume that the iio_buffer object contains only the samples you're interested in.

Iterating over the buffer with a callback

Libiio provides a way to iterate over the buffer by registering a callback function, with the iio_buffer_foreach_sample() function.

The callback function will be called for each "sample slot" of the buffer, which will contain a valid sample if the buffer has been refilled, or correspond to an area where a sample should be stored if using an output device.

~~~{.c} ssize_t sample_cb(const struct iio_channel *chn, void *src, size_t bytes, void *d) { /* Use "src" to read or write a sample for this channel