.. 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 exposes:

* ``in_voltageN_raw`` — single-shot ADC result

The following attributes are shared across all channels:

* ``in_voltage_sampling_frequency`` — effective output rate, defined as the
  internal oscillator frequency divided by the 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_voltage_sampling_frequency_available`` — list of achievable effective
  rates for the current oversampling ratio. The list updates dynamically when
  the oversampling ratio changes.

The following attributes are shared across all channels and only available in
CNV Burst Mode:

* ``in_voltage_oversampling_ratio`` — hardware oversampling depth applied to
  all channels; see `Oversampling`_ below.
* ``in_voltage_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 a shared hardware accumulator averages a configurable number
of successive conversions across all active channels. The result is always a
16-bit mean, so the buffer data type (shown in ``buffer0/in_voltageN_type``)
is unaffected 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 (shared across all channels)
    echo 16 > /sys/bus/iio/devices/iio:device0/in_voltage_oversampling_ratio

    # Read the resulting effective sampling frequency
    cat /sys/bus/iio/devices/iio:device0/in_voltage_sampling_frequency

Writing ``in_voltage_oversampling_ratio`` stores the new shared depth 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_voltage_sampling_frequency`` after the change and keeps the oscillator as
close as possible to the previous effective rate.


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): the GPIO line is
  asserted then deasserted at probe; the driver waits 300 µs for the chip
  to complete its internal reset sequence before accepting SPI commands.
* **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";
        ...
        interrupt-parent = <&gpio0>;
        interrupts = <17 IRQ_TYPE_LEVEL_HIGH>;
        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.