IIO Buffered Acquisition and DMA Integration¶
Overview¶
The Linux Industrial I/O (IIO) subsystem provides a common framework for data-conversion and sensor devices such as ADCs, DACs, accelerometers, gyroscopes, and other measurement devices.
For buffered input devices, the acquisition path must solve two different problems:
- Move samples efficiently from hardware into memory.
- Describe those samples using the logical layout expected by IIO and userspace.
DMA can solve the first problem, but it does not define the meaning or layout of the transferred samples.
A useful separation is:
Hardware
↓
Hardware Sample Layout
↓
DMA Transport
↓
IIO Buffer Management
↓
Logical IIO Scan Layout
↓
Userspace
Understanding this boundary is especially important when the hardware produces a fixed sample format while the IIO scan configuration allows userspace to enable only selected channels.
Architecture¶
IIO buffered acquisition can use different producer architectures depending on the device and driver.
A triggered acquisition path commonly involves the CPU constructing or pushing each scan:
A DMA-backed acquisition path instead moves larger amounts of data with less per-sample CPU involvement:
The two paths share the same higher-level requirement: the data exposed through the IIO buffer must match the configured scan representation.
IIO Device and Channels¶
An IIO device represents a physical or logical data-acquisition device.
A multi-channel ADC may expose channels such as:
Each channel has metadata that describes how the corresponding data is represented.
For buffered acquisition, important properties include:
| Property | Meaning |
|---|---|
| Channel | Identifies the logical or physical channel |
scan_index |
Determines the element's position in the scan model |
| Real data width | Number of meaningful data bits |
| Storage width | Number of bits occupied by the buffered representation |
The channel number and scan_index are separate concepts.
A simple device may use:
but drivers should not assume that the channel number always determines the scan-mask bit position.
Scan Elements¶
A buffered IIO sample is represented as a scan containing the enabled scan elements.
For a four-channel ADC:
If each channel occupies 16 bits of storage, one full scan occupies:
The storage width is not necessarily the same as the ADC resolution.
For example:
The sample contains 12 meaningful bits but still occupies 2 bytes in the scan representation.
Therefore the buffered layout is based on the storage representation rather than simply dividing the ADC resolution by eight.
Active Scan Mask¶
The active scan mask describes which scan elements participate in the current buffered configuration.
For a device whose scan indices are 0 through 3:
A full scan may use:
A sparse scan may use:
The active scan mask therefore describes the logical scan configuration.
It does not necessarily reconfigure the physical data format produced by the hardware.
Logical Scan Size¶
The logical size of one configured scan is commonly referred to as scan_bytes.
For the simplified four-channel example with 16-bit storage:
For:
This simple sum is sufficient for the conceptual model used here.
Real IIO scan layouts may also need to account for additional scan elements, timestamp storage, alignment, and padding.
Hardware Layout vs Logical IIO Layout¶
One of the most important design issues appears when the hardware frame format is fixed.
Consider an ADC that always produces:
Disabling CH1 in the IIO scan configuration does not necessarily cause the hardware interface to emit:
The hardware may continue to produce a fixed frame, for example:
DMA transfers the hardware-visible bytes.
Therefore:
may need to become:
before the compact logical representation is exposed to the consumer.
This gives the central distinction:
Scan Repacking¶
When the hardware and logical layouts differ, software may need to repack the scan.
For example:
with:
becomes:
A simple repacking algorithm maintains two independent offsets:
| Offset | Advances When |
|---|---|
| Hardware offset | Every hardware element |
| Logical offset | Only an enabled element is copied |
Conceptually:
Hardware
+-----+-----+-----+-----+
| CH0 | CH1 | CH2 | CH3 |
+-----+-----+-----+-----+
| | |
+-----+-----+-----+
|
| selected elements
v
Logical
+-----+-----+-----+
| CH0 | CH2 | CH3 |
+-----+-----+-----+
The operation changes the representation of the data and therefore normally requires CPU work and memory copying.
Block-Level Conversion¶
DMA transfers frequently contain multiple hardware scans rather than one scan at a time.
Suppose one hardware scan occupies 8 bytes and a DMA block contains four scans:
If the logical scan contains only CH0, CH2, and CH3:
repacking four scans produces:
Therefore:
The number of hardware scans must remain well defined.
For a fixed-width hardware scan:
ensures that the block contains only complete scans.
DMA-Compatible Layout¶
Repacking is not always required.
If the active logical scan contains every element in exactly the same representation and ordering as the hardware stream:
the layouts are compatible.
Conceptually:
Fixed Hardware Layout
│
▼
Active Scan Configuration
│
┌────┴─────┐
│ │
compatible incompatible
│ │
▼ ▼
Direct Repack
layout or reject
This creates an important driver design choice.
A driver may:
- Support software repacking for incompatible scan configurations.
- Restrict DMA-backed acquisition to layouts that match the hardware stream.
- Use different acquisition paths depending on the selected scan configuration.
The appropriate policy depends on the hardware and performance requirements.
Direct DMA Does Not Automatically Mean Zero Copy¶
Layout compatibility is a prerequisite for an efficient direct DMA path, but it does not by itself guarantee zero-copy delivery to userspace.
Several layers may still participate in buffer management:
Whether additional copies occur depends on the actual IIO buffer implementation and driver architecture.
Therefore:
The useful conclusion is narrower:
A matching hardware and logical layout avoids the need for channel-removal repacking.
Triggered Buffer Acquisition¶
Triggered buffers are useful when acquisition is naturally associated with a trigger event.
A conceptual path is:
Because the CPU participates in constructing each scan, software can naturally perform operations such as:
- Reading individual registers
- Selecting channel values
- Reordering data
- Adding a software timestamp
- Pushing the completed scan into the IIO buffer
This path is flexible but introduces CPU work for each acquisition event.
DMA-Backed Acquisition¶
DMA-backed acquisition is useful when hardware can produce a continuous or block-oriented stream.
Conceptually:
Peripheral / ADC
↓
DMA Controller
↓
DMA Buffer Block
↓
Completion
↓
IIO Buffer Management
↓
Consumer
The CPU does not need to move each individual sample from the peripheral.
However, the data arriving in memory follows the hardware representation.
This is why DMA-backed acquisition makes hardware-to-IIO layout compatibility especially important.
IIO DMA Buffer Layers¶
The IIO DMA buffer architecture separates generic buffer-block management from the DMA Engine backend.
Conceptually:
IIO Buffer Core
↓
IIO DMA Buffer Queue
↓
DMAengine Backend
↓
DMA Engine
↓
DMA Controller Driver
↓
Hardware
The responsibilities are different:
| Layer | Responsibility |
|---|---|
| IIO Buffer | Provides buffered data semantics to the subsystem |
| IIO DMA Buffer Queue | Manages buffer blocks and their lifecycle |
| DMAengine Backend | Converts buffer work into DMA transactions |
| DMA Engine | Provides the generic DMA transaction API |
| DMA Controller Driver | Programs the actual DMA hardware |
An IIO buffer block and a DMA descriptor are therefore not the same object.
The DMA backend connects these two lifecycles.
DMA Submission and Completion¶
A DMA-backed block follows the familiar DMA Engine transaction lifecycle.
Conceptually:
IIO Buffer Block
↓
Prepare DMA Transaction
↓
dmaengine_submit()
↓
dma_async_issue_pending()
↓
DMA Transfer
↓
Completion Callback
↓
IIO Block Completion
Completion may also use DMA residue information to determine how many bytes were actually transferred.
Conceptually:
This is useful when a block completes with fewer valid bytes than its total capacity.
Buffer Ownership¶
A DMA-backed streaming buffer can remain mapped while individual blocks repeatedly change ownership.
A useful conceptual lifecycle is:
This means two different lifetimes must remain separate:
A buffer can remain DMA-mapped while a particular block is temporarily owned by the CPU or userspace-facing buffer framework.
This is the same ownership principle used by continuous DMA ring-buffer designs.
Completion and Consumer Wakeup¶
DMA completion alone does not finish the buffered acquisition path.
The completed block must become visible to the buffer consumer.
Conceptually:
DMA Completion
↓
Update Block State
↓
Mark Data Available
↓
Wake Waiters
↓
read() / poll()
↓
Userspace
The exact implementation belongs to the IIO buffer framework and depends on the buffer backend, but the architectural boundary is important:
DMA completion transfers ownership back toward the software buffer path; it does not directly represent a userspace read.
Timestamp Semantics¶
Timestamp handling must be considered separately from DMA completion.
For a single triggered scan, the trigger or acquisition event may provide a useful timestamp reference.
FIFO and DMA block acquisition are different.
Suppose a device samples periodically:
The DMA completion time describes when the transfer completed.
It does not mean all four samples were acquired at that exact time.
Therefore:
A driver that needs accurate per-sample timestamps may reconstruct them using:
- Known sample intervals
- FIFO sample rate
- Hardware counters
- Hardware timestamps
- Trigger timing
- Interrupt timing
The correct timestamp model depends on the device.
Design Considerations¶
Prefer Hardware-Compatible Layouts When Possible¶
If the hardware can be configured to emit exactly the enabled channels, direct DMA integration becomes easier.
If the hardware format is fixed, the driver must decide whether sparse scans justify software repacking.
Keep Transport and Representation Separate¶
DMA configuration answers questions such as:
IIO scan configuration answers:
Mixing these responsibilities makes buffer design harder to reason about.
Treat Buffer Capacity and Valid Data Size Separately¶
A destination block may have more capacity than the amount of logical data produced.
For example:
These values should not be treated as interchangeable.
Reject Incomplete Hardware Scans¶
When converting fixed-size scans, an input block ending in a partial scan should not silently expose that trailing data as a complete sample.
Do Not Infer Scan Bits From Channel Count¶
The active scan-mask bit position is defined by scan_index.
A device with three channels does not necessarily imply that valid scan bits are simply bits 0 through 2.
Related Labs¶
Related Topics¶
- DMA Client Architecture
- DMA Cyclic Transfers
- DMA Completion and Callback
- DMA Slave Transfers
- DMA Scatter-Gather Transfers
Summary¶
IIO buffered acquisition adds data semantics and buffer management above the raw DMA transport layer.
The central relationship is:
An active scan mask determines which scan elements belong to the logical buffered representation, while the hardware may continue to generate a fixed physical frame.
When:
a direct DMA-compatible path is possible without channel-removal repacking.
When:
the driver must either transform the data or reject that configuration from the direct DMA path.
This distinction is fundamental when integrating high-throughput ADCs and sensors with IIO DMA-backed buffering.