1.. SPDX-License-Identifier: GPL-2.0-only 2 3============= 4AD4691 driver 5============= 6 7ADC driver for Analog Devices Inc. AD4691 family of multichannel SAR ADCs. 8The module name is ``ad4691``. 9 10 11Supported devices 12================= 13 14The 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 22IIO channels 23============ 24 25Each physical ADC input maps to one IIO voltage channel. The AD4691 and AD4692 26expose 16 channels (``voltage0`` through ``voltage15``); the AD4693 and AD4694 27expose 8 channels (``voltage0`` through ``voltage7``). 28 29All channels share a common scale (``in_voltage_scale``), derived from the 30reference voltage. Each channel exposes: 31 32* ``in_voltageN_raw`` — single-shot ADC result 33 34The 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 45The following attributes are shared across all channels and only available in 46CNV 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 54Operating modes 55=============== 56 57The driver supports two operating modes, selected automatically from the 58device tree at probe time. 59 60Manual Mode 61----------- 62 63Selected when no ``pwms`` property is present in the device tree. The CNV pin 64is tied to the SPI chip-select: every CS assertion triggers a conversion and 65returns the previous result. A user-defined IIO trigger (e.g. hrtimer trigger) 66drives the buffer. 67 68Oversampling is not supported in Manual Mode. 69 70CNV Burst Mode 71-------------- 72 73Selected when a ``pwms`` property is present in the device tree. A PWM drives 74the CNV pin at the configured conversion rate. A GP pin wired to the SoC and 75declared in the device tree signals DATA_READY at the end of each burst, 76triggering a readout of all active channel results into the IIO buffer. 77 78The buffer output rate is controlled by the ``sampling_frequency`` attribute 79on the IIO buffer. In practice the PWM rate should be set low enough to allow 80the SPI readout to complete before the next conversion burst begins. 81 82Autonomous Mode (idle / single-shot) 83------------------------------------- 84 85When the IIO buffer is disabled, ``in_voltageN_raw`` reads perform a single 86conversion on the requested channel using the internal oscillator. The 87oscillator is started and stopped around each read to save power. 88 89 90Oversampling 91============ 92 93In CNV Burst Mode a shared hardware accumulator averages a configurable number 94of successive conversions across all active channels. The result is always a 9516-bit mean, so the buffer data type (shown in ``buffer0/in_voltageN_type``) 96is unaffected by the oversampling ratio. Valid ratios are 1, 2, 4, 8, 16 and 9732; the default is 1 (no averaging). Oversampling is not supported in Manual 98Mode. 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 108Writing ``in_voltage_oversampling_ratio`` stores the new shared depth and snaps 109the internal oscillator to the largest valid table entry that is both less than 110or 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 113close as possible to the previous effective rate. 114 115 116Reference voltage 117================= 118 119The 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 126Exactly one of ``ref-supply`` or ``refin-supply`` must be present in the 127device tree. The reference voltage determines the full-scale range reported 128via ``in_voltage_scale``. 129 130 131LDO supply 132========== 133 134The chip contains an internal LDO that powers part of the analog front-end. 135The 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 142Exactly one of ``vdd-supply`` or ``ldo-in-supply`` must be provided. 143 144 145Reset 146===== 147 148The 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 157GP pins and interrupts 158====================== 159 160The 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 162declared in the device tree using the ``interrupts`` and ``interrupt-names`` 163properties. The ``interrupt-names`` value identifies which GP pin is used 164(``"gp0"`` through ``"gp3"``). 165 166Example 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 177SPI offload support 178=================== 179 180When a SPI offload engine (e.g. the AXI SPI Engine) is present, the driver 181uses DMA-backed transfers for CPU-independent, high-throughput data capture. 182SPI offload is detected automatically at probe; if no offload hardware is 183available the driver falls back to the software triggered-buffer path. 184 185Two SPI offload sub-modes exist: 186 187CNV Burst offload 188----------------- 189 190Used when a ``pwms`` property is present and SPI offload is available. The PWM 191drives CNV at the configured rate; on DATA_READY the offload engine reads all 192active channel results and streams them directly to the IIO DMA buffer with no 193CPU involvement. The GP pin used as DATA_READY trigger is supplied by the 194trigger-source consumer at buffer enable time; no ``interrupt-names`` entry is 195required. 196 197Manual offload 198-------------- 199 200Used when no ``pwms`` property is present and SPI offload is available. A 201periodic SPI offload trigger controls the conversion rate and the offload engine 202streams results directly to the IIO DMA buffer. 203 204The ``sampling_frequency`` attribute on the IIO buffer controls the trigger 205rate (in Hz). The initial rate is 100 kHz. 206 207Oversampling is not supported in Manual Mode. 208 209 210Buffer data format 211================== 212 213The sample format in the IIO buffer depends on whether SPI offload is in use. 214 215Software triggered-buffer path (no SPI offload) 216------------------------------------------------ 217 218Each active channel occupies one 16-bit big-endian slot (``storagebits=16``, 219``endianness=be``). Active channels are packed densely in scan-index order, 220followed by a 64-bit software timestamp appended by the IIO core. 221 222SPI offload path 223---------------- 224 225Each active channel occupies one 16-bit CPU-native slot (``storagebits=16``, 226``endianness=cpu``). The SPI offload engine streams 16-bit words directly from 227the SPI Engine into the DMA buffer; no software timestamp is appended. 228