analogdevicesinc/libiio v1.0.0

Libiio release v1.0.0

on GitHub

Libiio v1.0.0

First stable release of Libiio. This release breaks both the API and the ABI
of the v0.x series: an application built against Libiio v0.x will not run
against Libiio v1.x, and source changes are required to rebuild against it.

Two guides cover everything that needs to change:

• Libiio 0.x to 1.x API update guide
• Libiio 0.x to 1.x command-line tools migration guide

Backward compatibility

Even though the API and the ABI both changed, existing v0.x deployments keep
working — on the wire and at the binary level:

• IIOD still serves v0.x clients. The server is built with
  WITH_IIOD_V0_COMPAT enabled by default, so it starts up speaking the v0.x
  text protocol and only switches to the new binary protocol when a v1.x client
  asks for it. An unmodified v0.26 client can talk to a v1.0 IIOD.
• A compatibility layer keeps existing v0.x binaries running. The
  LIBIIO_COMPAT option, also enabled by default, builds a libiio.so.0
  library that exposes the old v0.x ABI and forwards every call to the v1.x
  library, which it loads at runtime. Applications that were compiled and
  linked against Libiio v0.x therefore continue to run against a v1.0
  installation without being recompiled or relinked.

Breaking changes

• iio.h moved into an iio subdirectory: include <iio/iio.h> instead of <iio.h>.
• Functions returning a pointer no longer return NULL on error; they return a
  pointer-encoded error code, retrieved with iio_err. errno is no longer used
  to report errors.
• Attributes are now accessed through a dedicated iio_attr object rather than
  by index and name.
• Buffers are pre-existing objects owned by the driver, enumerated with
  iio_device_get_buffers_count / iio_device_get_buffer and opened for
  streaming with iio_buffer_open, which returns an iio_buffer_stream.
• The low-level streaming API is now block based.
• Context behaviour is configured through a public iio_context_params structure.
• iio_readdev and iio_writedev were merged into a single iio_rwdev tool.
• SONAME is now libiio.so.1, and the exported ABI is frozen by a linker
  version script (libiio.map).

Highlights

• New binary IIOD protocol, negotiated at connection time. The client probes
  the server with a BINARY command on connect and upgrades to the binary
  protocol when the server accepts it, transparently falling back to the v0.x
  text protocol when it does not. The binary protocol multiplexes commands and
  data over one connection instead of serialising ASCII exchanges.
• Multi-buffer support. A device may expose more than one buffer; they are
  enumerated with iio_device_get_buffers_count and retrieved by index with
  iio_device_get_buffer, so several buffers of the same device can be streamed
  independently.
• Blocks are now exposed to applications. Where v0.x only handed out a
  buffer and refilled it in place, v1.x lets applications create individual
  blocks with iio_buffer_stream_create_block and manage them explicitly via
  iio_block_enqueue / iio_block_dequeue. Several blocks can be kept in
  flight at once, which gives far more control over memory and throughput than
  the single implicit buffer of v0.x.
• DMA-BUF support. Blocks can be backed by DMA-BUF objects, so capture and
  transmit memory can be shared with other DMA-BUF aware drivers and subsystems
  without copying it through user space. iio_block_get_dmabuf_fd returns the
  file descriptor of the underlying object, and iio_block_disable_cpu_access
  hands a block over to the device without the CPU touching its samples. It is
  enabled by default in the local backend (WITH_LOCAL_DMABUF_API), and IIOD
  can carry it over USB with WITH_IIOD_USB_DMABUF.
• Non-blocking capture and transmit. iio_block_dequeue takes a nonblock
  flag and returns -EBUSY instead of waiting when no block is ready, so data
  paths can be driven from an event loop rather than a dedicated thread.
  IIO_TIMEOUT_NONBLOCK provides the same behaviour for context-level timeouts.
• New IIO events API. iio_device_create_event_stream opens a stream of
  hardware events (threshold crossings, and so on), read with
  iio_event_stream_read, which is also able to operate without blocking.
  iio_event_get_type, iio_event_get_direction and iio_event_get_channel
  decode the events, and the new iio_event tool exposes them on the command
  line.
• Event attributes, a new family of attributes alongside the regular and
  debug ones, expose the controls that configure IIO events — enabling an
  event and setting its threshold, for instance. They exist on both devices and
  channels, enumerated with iio_device_get_event_attrs_count /
  iio_device_get_event_attr and iio_channel_get_event_attrs_count /
  iio_channel_get_event_attr, with iio_device_find_event_attr and
  iio_channel_find_event_attr for lookup by name.
• New public headers: <iio/iio-debug.h> (logging macros), <iio/iio-lock.h>
  (OS-independent mutex and thread helpers), <iio/iio-backend.h> and
  <iio/iiod-client.h> (for out-of-tree plug-in backends).
• Backends can now be built as loadable modules, including a new emulation
  backend (WITH_EMU_BACKEND) and the iiod-emu server.
• Zephyr support, for running Libiio and IIOD on RTOS targets.
• tinyiiod, a minimal IIOD implementation for constrained devices.
• New command-line tools: iio_ping and iio_event.
• Reworked C++, Python and C# bindings tracking the new API.
• Much of the core library was relicensed from LGPL-2.1 to MIT (see
  COPYING_MIT.txt), including the public headers (iio.h, iio-backend.h,
  iio-debug.h, iio-lock.h), the core object implementations (attr,
  backend, block, buffer, channel, context, device, events,
  mask, scan, stream, task, xml and others), parts of IIOD, and the
  whole of tinyiiod. This makes static linking practical on microcontroller,
  baremetal/no-OS and Zephyr targets. The library as a whole remains
  LGPL-2.1-or-later, and the utils and the examples remain GPL-2.0-or-later.
• The C# bindings were relicensed from LGPL-2.1 to the MIT license, making
  them easier to reuse in closed-source and commercially licensed applications.

Changes:

• 9a92966 iiod-client: Validate data chunk received for cmd READBUF
• 128625d doc: fix Doxygen group nesting hiding public API docs
• 8c3f172 CI: prepare_assets.sh: fix the release asset preparation
• 8146fae iio-debug: don't pass a null pointer to a "%s" directive
• 3e5c55f zephyr: iiod: uart: migrate off deprecated ring_buf claim/finish API
• bb0d832 zephyr: iiod: usb: update get_desc() return type for zephyr bump
• 083eb3a bindings: csharp: build a .NET 5+ target so the resolver actually ships
• 0813e90 bindings: csharp: Load the native library by its real name on .NET
• 8633598 bindings: csharp: Fix UTF-8 string marshaling on .NET
• 90be4d0 doc: document tool changes from v0.26 to v1.0