Re: [PATCH v11 6/6] docs: iio: adc: ad4691: add driver documentation

[David Lechner <dlechner@baylibre.com>]

On 5/15/26 8:31 AM, Radu Sabau via B4 Relay wrote:
> From: Radu Sabau <radu.sabau@analog.com>
> 
> 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>
> ---
>  Documentation/iio/ad4691.rst | 225 +++++++++++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst  |   1 +
>  MAINTAINERS                  |   1 +
>  3 files changed, 227 insertions(+)
> 
> diff --git a/Documentation/iio/ad4691.rst b/Documentation/iio/ad4691.rst
> new file mode 100644
> index 000000000000..84492ef7a5d6
> --- /dev/null
> +++ b/Documentation/iio/ad4691.rst
> @@ -0,0 +1,225 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +=============
> +AD4691 driver
> +=============
> +
> +ADC driver for Analog Devices Inc. AD4691 family of multichannel SAR ADCs.
> +The module name is ``ad4691``.
> +
> +
> +Supported devices
> +=================
> +
> +The following chips are supported by this driver:
> +
> +* `AD4691 <https://www.analog.com/en/products/ad4691.html>`_ — 16-channel, 500 kSPS
> +* `AD4692 <https://www.analog.com/en/products/ad4692.html>`_ — 16-channel, 1 MSPS
> +* `AD4693 <https://www.analog.com/en/products/ad4693.html>`_ — 8-channel, 500 kSPS
> +* `AD4694 <https://www.analog.com/en/products/ad4694.html>`_ — 8-channel, 1 MSPS
> +
> +
> +IIO channels
> +============
> +
> +Each physical ADC input maps to one IIO voltage channel. The AD4691 and AD4692
> +expose 16 channels (``voltage0`` through ``voltage15``); the AD4693 and AD4694
> +expose 8 channels (``voltage0`` through ``voltage7``).
> +
> +All channels share a common scale (``in_voltage_scale``), derived from the
> +reference voltage. Each channel independently exposes:
> +
> +* ``in_voltageN_raw`` — single-shot ADC result
> +* ``in_voltageN_sampling_frequency`` — per-channel effective output rate,
> +  defined as the internal oscillator frequency divided by the channel's
> +  oversampling ratio. Writing this attribute selects the nearest achievable
> +  rate for the current OSR; the value read back reflects the actual rate after
> +  snapping to the closest valid oscillator entry.
> +* ``in_voltageN_sampling_frequency_available`` — list of achievable effective
> +  rates for the channel's current oversampling ratio. The list updates
> +  dynamically when the oversampling ratio changes.
> +
> +The following attributes are only available in CNV Burst Mode:
> +
> +* ``in_voltageN_oversampling_ratio`` — per-channel hardware oversampling depth;
> +  see `Oversampling`_ below.
> +* ``in_voltageN_oversampling_ratio_available`` — valid ratios: 1, 2, 4, 8, 16,
> +  32.
> +
> +
> +Operating modes
> +===============
> +
> +The driver supports two operating modes, selected automatically from the
> +device tree at probe time.
> +
> +Manual Mode
> +-----------
> +
> +Selected when no ``pwms`` property is present in the device tree. The CNV pin
> +is tied to the SPI chip-select: every CS assertion triggers a conversion and
> +returns the previous result. A user-defined IIO trigger (e.g. hrtimer trigger)
> +drives the buffer.
> +
> +Oversampling is not supported in Manual Mode.
> +
> +CNV Burst Mode
> +--------------
> +
> +Selected when a ``pwms`` property is present in the device tree. A PWM drives
> +the CNV pin at the configured conversion rate. A GP pin wired to the SoC and
> +declared in the device tree signals DATA_READY at the end of each burst,
> +triggering a readout of all active channel results into the IIO buffer.
> +
> +The buffer output rate is controlled by the ``sampling_frequency`` attribute
> +on the IIO buffer. In practice the PWM rate should be set low enough to allow
> +the SPI readout to complete before the next conversion burst begins.
> +
> +Autonomous Mode (idle / single-shot)
> +-------------------------------------
> +
> +When the IIO buffer is disabled, ``in_voltageN_raw`` reads perform a single
> +conversion on the requested channel using the internal oscillator. The
> +oscillator is started and stopped around each read to save power.
> +
> +
> +Oversampling
> +============
> +
> +In CNV Burst Mode each channel has an independent hardware accumulator that
> +averages a configurable number of successive conversions. The result is always
> +returned as a 16-bit mean, so ``realbits`` and ``storagebits`` are unaffected

realbits and storagebits are driver implementation details. I would write this
in terms of userpace, which would be the buffer0/*_type attribute.

> +by the oversampling ratio. Valid ratios are 1, 2, 4, 8, 16 and 32; the default
> +is 1 (no averaging). Oversampling is not supported in Manual Mode.
> +
> +.. code-block:: bash
> +
> +    # Set oversampling ratio to 16 on channel 0
> +    echo 16 > /sys/bus/iio/devices/iio:device0/in_voltage0_oversampling_ratio
> +
> +    # Read the resulting effective sampling frequency
> +    cat /sys/bus/iio/devices/iio:device0/in_voltage0_sampling_frequency
> +
> +Writing ``oversampling_ratio`` stores the new depth for that channel and
> +snaps the internal oscillator to the largest valid table entry that is both
> +less than or equal to ``old_effective_rate × new_osr`` and evenly divisible
> +by ``new_osr``. This preserves an integer read-back of
> +``in_voltageN_sampling_frequency`` after the change and keeps the oscillator
> +as close as possible to the previous effective rate.
> +
> +All channels share one internal oscillator. Writing ``sampling_frequency`` for
> +any channel updates the oscillator and therefore affects the effective rate
> +read back from all other channels.
> +
> +
> +Reference voltage
> +=================
> +
> +The driver supports two reference configurations, mutually exclusive:
> +
> +* **External reference** (``ref-supply``): a voltage between 2.4 V and 5.25 V
> +  supplied externally.
> +* **Buffered internal reference** (``refin-supply``): an internal reference
> +  buffer is enabled by the driver.
> +
> +Exactly one of ``ref-supply`` or ``refin-supply`` must be present in the
> +device tree. The reference voltage determines the full-scale range reported
> +via ``in_voltage_scale``.
> +
> +
> +LDO supply
> +==========
> +
> +The chip contains an internal LDO that powers part of the analog front-end.
> +The supply configuration is mutually exclusive:
> +
> +* **External VDD** (``vdd-supply``): an external 1.8 V supply is used directly;
> +  the internal LDO is disabled.
> +* **Internal LDO** (``ldo-in-supply``): the internal LDO is enabled and fed
> +  from the ``ldo-in`` regulator. Use this when no external 1.8 V VDD is present.
> +
> +Exactly one of ``vdd-supply`` or ``ldo-in-supply`` must be provided.
> +
> +
> +Reset
> +=====
> +
> +The driver supports two reset mechanisms:
> +
> +* **Hardware reset** (``reset-gpios`` in device tree): asserted at probe by
> +  the reset controller framework.
> +* **Software reset** (fallback when ``reset-gpios`` is absent): written
> +  automatically at probe.
> +
> +
> +GP pins and interrupts
> +======================
> +
> +The chip exposes up to four general-purpose (GP) pins. In CNV Burst Mode
> +(non-offload), one GP pin must be wired to an interrupt-capable SoC input and
> +declared in the device tree using the ``interrupts`` and ``interrupt-names``
> +properties. The ``interrupt-names`` value identifies which GP pin is used
> +(``"gp0"`` through ``"gp3"``).
> +
> +Example device tree fragment::
> +
> +    adc@0 {
> +        compatible = "adi,ad4692";
> +        ...
> +        interrupts = <17 IRQ_TYPE_LEVEL_HIGH>;
> +        interrupt-parent = <&gpio0>;

Would be more logical to put interrupt-parent before interrupts.

> +        interrupt-names = "gp0";
> +    };
> +
> +
> +SPI offload support
> +===================
> +
> +When a SPI offload engine (e.g. the AXI SPI Engine) is present, the driver
> +uses DMA-backed transfers for CPU-independent, high-throughput data capture.
> +SPI offload is detected automatically at probe; if no offload hardware is
> +available the driver falls back to the software triggered-buffer path.
> +
> +Two SPI offload sub-modes exist:
> +
> +CNV Burst offload
> +-----------------
> +
> +Used when a ``pwms`` property is present and SPI offload is available. The PWM
> +drives CNV at the configured rate; on DATA_READY the offload engine reads all
> +active channel results and streams them directly to the IIO DMA buffer with no
> +CPU involvement. The GP pin used as DATA_READY trigger is supplied by the
> +trigger-source consumer at buffer enable time; no ``interrupt-names`` entry is
> +required.
> +
> +Manual offload
> +--------------
> +
> +Used when no ``pwms`` property is present and SPI offload is available. A
> +periodic SPI offload trigger controls the conversion rate and the offload engine
> +streams results directly to the IIO DMA buffer.
> +
> +The ``sampling_frequency`` attribute on the IIO buffer controls the trigger
> +rate (in Hz). The initial rate is 100 kHz.
> +
> +Oversampling is not supported in Manual Mode.
> +
> +
> +Buffer data format
> +==================
> +
> +The sample format in the IIO buffer depends on whether SPI offload is in use.
> +
> +Software triggered-buffer path (no SPI offload)
> +------------------------------------------------
> +
> +Each active channel occupies one 16-bit big-endian slot (``storagebits=16``,
> +``endianness=be``). Active channels are packed densely in scan-index order,
> +followed by a 64-bit software timestamp appended by the IIO core.
> +
> +SPI offload path
> +----------------
> +
> +Each active channel occupies one 16-bit CPU-native slot (``storagebits=16``,
> +``endianness=cpu``). The SPI offload engine streams 16-bit words directly from
> +the SPI Engine into the DMA buffer; no software timestamp is appended.
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index ba3e609c6a13..007e0a1fcc5a 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -23,6 +23,7 @@ Industrial I/O Kernel Drivers
>     ad4000
>     ad4030
>     ad4062
> +   ad4691
>     ad4695
>     ad7191
>     ad7380
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 24e4502b8292..875ea2455d91 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1490,6 +1490,7 @@ L:	linux-iio@vger.kernel.org
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
>  F:	Documentation/devicetree/bindings/iio/adc/adi,ad4691.yaml
> +F:	Documentation/iio/ad4691.rst
>  F:	drivers/iio/adc/ad4691.c
>  
>  ANALOG DEVICES INC AD4695 DRIVER
>