228 lines
8.0 KiB
ReStructuredText
228 lines
8.0 KiB
ReStructuredText
.. 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.
|