Skip to content

Commit 4e8327c

Browse files
RaduSabau1jic23
RaduSabau1
authored and
jic23
committed
docs: iio: adc: ad4691: add driver documentation
Add RST documentation for the AD4691 family ADC driver covering supported devices, IIO channels, operating modes, oversampling, reference voltage, LDO supply, reset, GP pins, SPI offload support, and buffer data format. Signed-off-by: Radu Sabau <radu.sabau@analog.com> Signed-off-by: Jonathan Cameron <jic23@kernel.org>
1 parent 6d9e716 commit 4e8327c

3 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎Documentation/iio/ad4691.rst‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
.. SPDX-License-Identifier: GPL-2.0-only
2+
3+
=============
4+
AD4691 driver
5+
=============
6+
7+
ADC driver for Analog Devices Inc. AD4691 family of multichannel SAR ADCs.
8+
The module name is ``ad4691``.
9+
10+
11+
Supported devices
12+
=================
13+
14+
The following chips are supported by this driver:
15+
16+
* `AD4691 <https://www.analog.com/en/products/ad4691.html>`_ — 16-channel, 500 kSPS
17+
* `AD4692 <https://www.analog.com/en/products/ad4692.html>`_ — 16-channel, 1 MSPS
18+
* `AD4693 <https://www.analog.com/en/products/ad4693.html>`_ — 8-channel, 500 kSPS
19+
* `AD4694 <https://www.analog.com/en/products/ad4694.html>`_ — 8-channel, 1 MSPS
20+
21+
22+
IIO channels
23+
============
24+
25+
Each physical ADC input maps to one IIO voltage channel. The AD4691 and AD4692
26+
expose 16 channels (``voltage0`` through ``voltage15``); the AD4693 and AD4694
27+
expose 8 channels (``voltage0`` through ``voltage7``).
28+
29+
All channels share a common scale (``in_voltage_scale``), derived from the
30+
reference voltage. Each channel exposes:
31+
32+
* ``in_voltageN_raw`` — single-shot ADC result
33+
34+
The following attributes are shared across all channels:
35+
36+
* ``in_voltage_sampling_frequency`` — effective output rate, defined as the
37+
internal oscillator frequency divided by the oversampling ratio. Writing this
38+
attribute selects the nearest achievable rate for the current OSR; the value
39+
read back reflects the actual rate after snapping to the closest valid
40+
oscillator entry.
41+
* ``in_voltage_sampling_frequency_available`` — list of achievable effective
42+
rates for the current oversampling ratio. The list updates dynamically when
43+
the oversampling ratio changes.
44+
45+
The following attributes are shared across all channels and only available in
46+
CNV Burst Mode:
47+
48+
* ``in_voltage_oversampling_ratio`` — hardware oversampling depth applied to
49+
all channels; see `Oversampling`_ below.
50+
* ``in_voltage_oversampling_ratio_available`` — valid ratios: 1, 2, 4, 8, 16,
51+
32.
52+
53+
54+
Operating modes
55+
===============
56+
57+
The driver supports two operating modes, selected automatically from the
58+
device tree at probe time.
59+
60+
Manual Mode
61+
-----------
62+
63+
Selected when no ``pwms`` property is present in the device tree. The CNV pin
64+
is tied to the SPI chip-select: every CS assertion triggers a conversion and
65+
returns the previous result. A user-defined IIO trigger (e.g. hrtimer trigger)
66+
drives the buffer.
67+
68+
Oversampling is not supported in Manual Mode.
69+
70+
CNV Burst Mode
71+
--------------
72+
73+
Selected when a ``pwms`` property is present in the device tree. A PWM drives
74+
the CNV pin at the configured conversion rate. A GP pin wired to the SoC and
75+
declared in the device tree signals DATA_READY at the end of each burst,
76+
triggering a readout of all active channel results into the IIO buffer.
77+
78+
The buffer output rate is controlled by the ``sampling_frequency`` attribute
79+
on the IIO buffer. In practice the PWM rate should be set low enough to allow
80+
the SPI readout to complete before the next conversion burst begins.
81+
82+
Autonomous Mode (idle / single-shot)
83+
-------------------------------------
84+
85+
When the IIO buffer is disabled, ``in_voltageN_raw`` reads perform a single
86+
conversion on the requested channel using the internal oscillator. The
87+
oscillator is started and stopped around each read to save power.
88+
89+
90+
Oversampling
91+
============
92+
93+
In CNV Burst Mode a shared hardware accumulator averages a configurable number
94+
of successive conversions across all active channels. The result is always a
95+
16-bit mean, so the buffer data type (shown in ``buffer0/in_voltageN_type``)
96+
is unaffected by the oversampling ratio. Valid ratios are 1, 2, 4, 8, 16 and
97+
32; the default is 1 (no averaging). Oversampling is not supported in Manual
98+
Mode.
99+
100+
.. code-block:: bash
101+
102+
# Set oversampling ratio to 16 (shared across all channels)
103+
echo 16 > /sys/bus/iio/devices/iio:device0/in_voltage_oversampling_ratio
104+
105+
# Read the resulting effective sampling frequency
106+
cat /sys/bus/iio/devices/iio:device0/in_voltage_sampling_frequency
107+
108+
Writing ``in_voltage_oversampling_ratio`` stores the new shared depth and snaps
109+
the internal oscillator to the largest valid table entry that is both less than
110+
or equal to ``old_effective_rate × new_osr`` and evenly divisible by
111+
``new_osr``. This preserves an integer read-back of
112+
``in_voltage_sampling_frequency`` after the change and keeps the oscillator as
113+
close as possible to the previous effective rate.
114+
115+
116+
Reference voltage
117+
=================
118+
119+
The driver supports two reference configurations, mutually exclusive:
120+
121+
* **External reference** (``ref-supply``): a voltage between 2.4 V and 5.25 V
122+
supplied externally.
123+
* **Buffered internal reference** (``refin-supply``): an internal reference
124+
buffer is enabled by the driver.
125+
126+
Exactly one of ``ref-supply`` or ``refin-supply`` must be present in the
127+
device tree. The reference voltage determines the full-scale range reported
128+
via ``in_voltage_scale``.
129+
130+
131+
LDO supply
132+
==========
133+
134+
The chip contains an internal LDO that powers part of the analog front-end.
135+
The supply configuration is mutually exclusive:
136+
137+
* **External VDD** (``vdd-supply``): an external 1.8 V supply is used directly;
138+
the internal LDO is disabled.
139+
* **Internal LDO** (``ldo-in-supply``): the internal LDO is enabled and fed
140+
from the ``ldo-in`` regulator. Use this when no external 1.8 V VDD is present.
141+
142+
Exactly one of ``vdd-supply`` or ``ldo-in-supply`` must be provided.
143+
144+
145+
Reset
146+
=====
147+
148+
The driver supports two reset mechanisms:
149+
150+
* **Hardware reset** (``reset-gpios`` in device tree): the GPIO line is
151+
asserted then deasserted at probe; the driver waits 300 µs for the chip
152+
to complete its internal reset sequence before accepting SPI commands.
153+
* **Software reset** (fallback when ``reset-gpios`` is absent): written
154+
automatically at probe.
155+
156+
157+
GP pins and interrupts
158+
======================
159+
160+
The chip exposes up to four general-purpose (GP) pins. In CNV Burst Mode
161+
(non-offload), one GP pin must be wired to an interrupt-capable SoC input and
162+
declared in the device tree using the ``interrupts`` and ``interrupt-names``
163+
properties. The ``interrupt-names`` value identifies which GP pin is used
164+
(``"gp0"`` through ``"gp3"``).
165+
166+
Example device tree fragment::
167+
168+
adc@0 {
169+
compatible = "adi,ad4692";
170+
...
171+
interrupt-parent = <&gpio0>;
172+
interrupts = <17 IRQ_TYPE_LEVEL_HIGH>;
173+
interrupt-names = "gp0";
174+
};
175+
176+
177+
SPI offload support
178+
===================
179+
180+
When a SPI offload engine (e.g. the AXI SPI Engine) is present, the driver
181+
uses DMA-backed transfers for CPU-independent, high-throughput data capture.
182+
SPI offload is detected automatically at probe; if no offload hardware is
183+
available the driver falls back to the software triggered-buffer path.
184+
185+
Two SPI offload sub-modes exist:
186+
187+
CNV Burst offload
188+
-----------------
189+
190+
Used when a ``pwms`` property is present and SPI offload is available. The PWM
191+
drives CNV at the configured rate; on DATA_READY the offload engine reads all
192+
active channel results and streams them directly to the IIO DMA buffer with no
193+
CPU involvement. The GP pin used as DATA_READY trigger is supplied by the
194+
trigger-source consumer at buffer enable time; no ``interrupt-names`` entry is
195+
required.
196+
197+
Manual offload
198+
--------------
199+
200+
Used when no ``pwms`` property is present and SPI offload is available. A
201+
periodic SPI offload trigger controls the conversion rate and the offload engine
202+
streams results directly to the IIO DMA buffer.
203+
204+
The ``sampling_frequency`` attribute on the IIO buffer controls the trigger
205+
rate (in Hz). The initial rate is 100 kHz.
206+
207+
Oversampling is not supported in Manual Mode.
208+
209+
210+
Buffer data format
211+
==================
212+
213+
The sample format in the IIO buffer depends on whether SPI offload is in use.
214+
215+
Software triggered-buffer path (no SPI offload)
216+
------------------------------------------------
217+
218+
Each active channel occupies one 16-bit big-endian slot (``storagebits=16``,
219+
``endianness=be``). Active channels are packed densely in scan-index order,
220+
followed by a 64-bit software timestamp appended by the IIO core.
221+
222+
SPI offload path
223+
----------------
224+
225+
Each active channel occupies one 16-bit CPU-native slot (``storagebits=16``,
226+
``endianness=cpu``). The SPI offload engine streams 16-bit words directly from
227+
the SPI Engine into the DMA buffer; no software timestamp is appended.

‎Documentation/iio/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Industrial I/O Kernel Drivers
2323
ad4000
2424
ad4030
2525
ad4062
26+
ad4691
2627
ad4695
2728
ad7191
2829
ad7380

‎MAINTAINERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1482,6 +1482,7 @@ L: linux-iio@vger.kernel.org
14821482
S: Supported
14831483
W: https://ez.analog.com/linux-software-drivers
14841484
F: Documentation/devicetree/bindings/iio/adc/adi,ad4691.yaml
1485+
F: Documentation/iio/ad4691.rst
14851486
F: drivers/iio/adc/ad4691.c
14861487

14871488
ANALOG DEVICES INC AD4695 DRIVER

0 commit comments

Comments
 (0)