From nobody Thu Apr 9 23:26:38 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 91D433E1215; Thu, 9 Apr 2026 15:28:29 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775748509; cv=none; b=nFbqG2Mr/Pz7td0Nc8XQLt2RI9zakruCHDERPyD0QGeo0ZpW37tx5k7jkuB3i3WEIEp55xPYbT24GObN+MVBxlkrWKAG/XV7KlpCJU+tSRrYcdw+roI0gVYdaqpjpaCge730khwIURepCud/RXHzMA9q0XL9JnxRBwRAOf7yX2A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1775748509; c=relaxed/simple; bh=UKUNZNcLrasERkVlHShR61ZM9paPsd4OyfoQALpvaI8=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=T1Y37YdhHbJv1DCD+P97vCrEHPwFAv7tHcO/UoMTH/z+NL9P0b3HKEHqifPIdg19jGGjCAZjXeiM6oc1im4erauKZG2DDwNUb4PHVv6Bx5P7wzS+n6w7DvAXVboj20hOc1PsqyrMheiBahkrRzmDZdg109pbLc9s807UNi7y4TE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=rvjyhgJm; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="rvjyhgJm" Received: by smtp.kernel.org (Postfix) with ESMTPS id 69D7FC2BCFC; Thu, 9 Apr 2026 15:28:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1775748509; bh=UKUNZNcLrasERkVlHShR61ZM9paPsd4OyfoQALpvaI8=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=rvjyhgJmYlIzlaWA7zSO1McTmw4D0MdA/jPxe+Zo/B3/4UyOo2f0BAUX1yDKetAuN IMnJZfs7uzopulWDUvFyjQgRw7CpH1QNpYC9QoIF6xwdsZM65EzhwVo5ffK62BCNY7 kAxasTNJi0BrvRG7PZTq+ScKK0LoBuCxg0W5qzo/M7+kVcOKxHHeT6YS6PJsD+2cfI uQhjwDoitNT5xfw93o6ex7LhGu2fO7pHzkM1m5f00NxPpONqs3+lKrhcgKN0LW3n+q 7+E2I4lm3WLUvt9wkVz3Q/nLZX1QpV68lZLmsqg8mDamIDesAf5luRDF+07aQEZNPD jErVuSM6pr8GA== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5E231F31E29; Thu, 9 Apr 2026 15:28:29 +0000 (UTC) From: Radu Sabau via B4 Relay Date: Thu, 09 Apr 2026 18:28:27 +0300 Subject: [PATCH v7 6/6] docs: iio: adc: ad4691: add driver documentation Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260409-ad4692-multichannel-sar-adc-driver-v7-6-be375d4df2c5@analog.com> References: <20260409-ad4692-multichannel-sar-adc-driver-v7-0-be375d4df2c5@analog.com> In-Reply-To: <20260409-ad4692-multichannel-sar-adc-driver-v7-0-be375d4df2c5@analog.com> To: Lars-Peter Clausen , Michael Hennerich , Jonathan Cameron , David Lechner , =?utf-8?q?Nuno_S=C3=A1?= , Andy Shevchenko , Rob Herring , Krzysztof Kozlowski , Conor Dooley , =?utf-8?q?Uwe_Kleine-K=C3=B6nig?= , Liam Girdwood , Mark Brown , Linus Walleij , Bartosz Golaszewski , Philipp Zabel , Jonathan Corbet , Shuah Khan Cc: linux-iio@vger.kernel.org, devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-pwm@vger.kernel.org, linux-gpio@vger.kernel.org, linux-doc@vger.kernel.org, Radu Sabau X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1775748505; l=13101; i=radu.sabau@analog.com; s=20260220; h=from:subject:message-id; bh=IptN2OXLuNKyo/j556/GPrsAWPRNvypfZxc/oV4K/08=; b=yxWNyMKAMFayikY2a8aPmPC4cimWIh1kYwt4nLnqEZ9DNF8VoWaaJarr5ZW6UCY0He4TzRChQ WrEhManA9QIBRGiv61DldWe7xEDDPeSa9eLlyz8yQ+vSnm6CaUtcPGM X-Developer-Key: i=radu.sabau@analog.com; a=ed25519; pk=lDPQHgn9jTdt0vo58Na9lLxLaE2mb330if71Cn+EvFU= X-Endpoint-Received: by B4 Relay for radu.sabau@analog.com/20260220 with auth_id=642 X-Original-From: Radu Sabau Reply-To: radu.sabau@analog.com From: Radu Sabau 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 --- Documentation/iio/ad4691.rst | 283 +++++++++++++++++++++++++++++++++++++++= ++++ Documentation/iio/index.rst | 1 + MAINTAINERS | 1 + 3 files changed, 285 insertions(+) diff --git a/Documentation/iio/ad4691.rst b/Documentation/iio/ad4691.rst new file mode 100644 index 000000000000..a1012c8b78a3 --- /dev/null +++ b/Documentation/iio/ad4691.rst @@ -0,0 +1,283 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +AD4691 driver +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +ADC driver for Analog Devices Inc. AD4691 family of multichannel SAR ADCs. +The module name is ``ad4691``. + + +Supported devices +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The following chips are supported by this driver: + +* `AD4691 `_ =E2=80=94 16-= channel, 500 kSPS +* `AD4692 `_ =E2=80=94 16-= channel, 1 MSPS +* `AD4693 `_ =E2=80=94 8-c= hannel, 500 kSPS +* `AD4694 `_ =E2=80=94 8-c= hannel, 1 MSPS + + +IIO channels +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Each physical ADC input maps to one IIO voltage channel. The AD4691 and AD= 4692 +expose 16 channels (``voltage0`` through ``voltage15``); the AD4693 and AD= 4694 +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`` =E2=80=94 single-shot ADC result +* ``in_voltageN_sampling_frequency`` =E2=80=94 per-channel effective conve= rsion rate. + In CNV Burst Mode this equals the internal oscillator frequency divided = by + the channel's oversampling ratio. In Manual Mode (where oversampling is = not + supported) it equals the oscillator frequency directly. +* ``in_voltageN_sampling_frequency_available`` =E2=80=94 list of valid osc= illator + frequencies + +The following attributes are only available in CNV Burst Mode: + +* ``in_voltageN_oversampling_ratio`` =E2=80=94 per-channel hardware accumu= lation depth +* ``in_voltageN_oversampling_ratio_available`` =E2=80=94 list of valid rat= ios: 1, 2, 4, + 8, 16, 32 + + +Operating modes +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver supports two operating modes, auto-detected from the device tre= e at +probe time. Both modes transition to and from an internal Autonomous Mode = idle +state when the IIO buffer is enabled and disabled. + +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 both triggers a new +conversion and returns the result of the previous one (pipelined N+1 schem= e). + +To read N channels the driver issues N+1 SPI transfers in a single optimis= ed +message: + +* Transfers 0 to N-1 each carry ``AD4691_ADC_CHAN(n)`` in the TX byte to + select the next channel; the RX byte of transfer ``k+1`` contains the re= sult + of the channel selected in transfer ``k``. +* Transfer N is a NOOP (0x00) to flush the last conversion result out of t= he + pipeline. + +A user-defined IIO trigger (e.g. hrtimer trigger) drives the trigger handl= er, +which executes the pre-built SPI message and pushes the scan to the buffer. + +Oversampling is not supported in Manual Mode. + +CNV Burst Mode +-------------- + +Selected when a ``pwms`` property is present in the device tree. The PWM d= rives +the CNV pin independently of SPI at the configured conversion rate, and a = GP +pin (identified by ``interrupt-names``) asserts DATA_READY at end-of-burst= to +signal that the AVG_IN result registers are ready to be read. + +The IRQ handler fires the IIO trigger without stopping the PWM, then disab= les +itself to prevent a second DATA_READY assertion while the trigger handler = is +running. The trigger handler reads all active ``AVG_IN(n)`` registers in a +single optimised SPI message, pushes the scan to the buffer, and re-enables +the IRQ. + +The buffer sampling frequency (i.e. the PWM rate) is controlled by the +``sampling_frequency`` attribute on the IIO buffer. Valid values span from= the +chip's minimum oscillator rate up to its maximum conversion rate (500 kSPS= for +AD4691/AD4693, 1 MSPS for AD4692/AD4694). In practice, without SPI offload, +the SPI read overhead between DATA_READY and the start of the next PWM per= iod +limits the achievable rate; the PWM frequency should be set low enough to +accommodate the SPI transfer time. + +Autonomous Mode (idle / single-shot) +------------------------------------- + +The chip idles in Autonomous Mode whenever the IIO buffer is disabled. In = this +state, ``read_raw`` requests (``in_voltageN_raw``) use the internal oscill= ator +to perform a single conversion on the requested channel and read back the +result from the ``AVG_IN(N)`` register. The oscillator is started and stop= ped +for each read to save power. + + +Oversampling +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +In CNV Burst Mode each channel has an independent hardware accumulator +(ACC_DEPTH_IN) that averages a configurable number of successive conversio= ns +before DATA_READY asserts. The result is always returned as a 16-bit mean = from +the ``AVG_IN`` register, so the IIO ``realbits`` and ``storagebits`` are +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 on channel 0 + echo 16 > /sys/bus/iio/devices/iio:device0/in_voltage0_oversampling_ra= tio + +When OSR > 1 the effective conversion rate reported by +``in_voltageN_sampling_frequency`` and used for ``read_raw`` is reduced +accordingly, since each output sample requires OSR successive conversions. + + +Reference voltage +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The driver supports two reference configurations, mutually exclusive: + +* **External reference** (``ref-supply``): a voltage between 2.4 V and 5.2= 5 V + supplied externally. The internal reference buffer is disabled. +* **Buffered internal reference** (``refin-supply``): An internal reference + buffer is used. The driver enables ``REFBUF_EN`` in the REF_CTRL register + when this supply is used. + +Exactly one of ``ref-supply`` or ``refin-supply`` must be present in the +device tree. + +The reference voltage determines the full-scale range: + +.. code-block:: + + full-scale =3D Vref / 2^16 (per LSB) + + +LDO supply +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The chip contains an internal LDO that powers part of the analog front-end. +The LDO input can be driven externally via the ``ldo-in-supply`` regulator= . If +that supply is absent, the driver enables the internal LDO path (``LDO_EN`` +bit in DEVICE_SETUP). + + +Reset +=3D=3D=3D=3D=3D + +The driver supports two reset mechanisms: + +* **Hardware reset** (``reset-gpios`` in device tree): the GPIO is already + asserted at driver probe by the reset controller framework. The driver w= aits + for the required 300 =C2=B5s reset pulse width and then deasserts. +* **Software reset** (fallback when ``reset-gpios`` is absent): the driver + writes the software-reset pattern to the SPI_CONFIG_A register. + + +GP pins and interrupts +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The chip exposes up to four general-purpose (GP) pins that can be configur= ed as +interrupt or trigger-source outputs. In CNV Burst Mode (non-offload), one = GP +pin must be wired to an interrupt-capable SoC input and declared in the de= vice +tree using the ``interrupts`` and ``interrupt-names`` properties. + +The ``interrupt-names`` value identifies which GP pin is used (``"gp0"`` +through ``"gp3"``). The driver configures that pin as a DATA_READY output = in +the GPIO_MODE register. + +Example device tree fragment:: + + adc@0 { + compatible =3D "adi,ad4692"; + ... + interrupts =3D <17 IRQ_TYPE_LEVEL_HIGH>; + interrupt-parent =3D <&gpio0>; + interrupt-names =3D "gp0"; + }; + + +SPI offload support +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 captur= e. +SPI offload is detected automatically at probe via ``devm_spi_offload_get(= )``; +if no offload hardware is available the driver falls back to the software +triggered-buffer path. + +Two SPI offload sub-modes exist, corresponding to the two operating modes: + +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 SPI offload +engine automatically executes a pre-built message that reads all active +``AVG_IN`` registers and streams the data directly to an IIO DMA buffer wi= th +no CPU involvement. A final state-reset transfer re-arms DATA_READY for the +next burst. + +The GP pin used as DATA_READY trigger is supplied by the trigger-source +consumer (via ``#trigger-source-cells``) at buffer enable time; no +``interrupt-names`` entry is required in this path. + +The buffer sampling frequency is controlled by the ``sampling_frequency`` +attribute on the IIO buffer (same as the non-offload CNV Burst path). + +Manual offload +-------------- + +Used when no ``pwms`` property is present and SPI offload is available. + +A periodic SPI offload trigger controls the conversion rate. On each trigg= er +period, the SPI engine executes an N+1 transfer message (same pipelined sc= heme +as software Manual Mode) and streams the 16-bit ADC results directly to the +IIO DMA buffer. Each transfer sends a 16-bit TX word (channel command byte= in +the upper byte, zero in the lower byte); the chip returns the 16-bit ADC +result on MISO. The first transfer's RX is discarded (pipeline flush); res= ults +from transfers 1 through N are streamed to the DMA buffer. + +The ``sampling_frequency`` attribute on the IIO buffer controls the trigger +rate (in Hz). The initial rate is 100 kHz =E2=80=94 a conservative default= chosen +because the N+1 SPI transfer overhead in this mode limits the achievable r= ate +relative to the chip's maximum conversion rate. + +Oversampling is not supported in Manual Mode. + + +Buffer data format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +The IIO buffer data format (``in_voltageN_type``) is the same across all +paths: 16-bit unsigned big-endian samples with no shift. + ++-------------------------+-------------+----------+-------+ +| Path | storagebits | realbits | shift | ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+= =3D=3D=3D=3D=3D=3D=3D+ +| Triggered buffer | 16 | 16 | 0 | ++-------------------------+-------------+----------+-------+ +| CNV Burst offload (DMA) | 16 | 16 | 0 | ++-------------------------+-------------+----------+-------+ +| Manual offload (DMA) | 16 | 16 | 0 | ++-------------------------+-------------+----------+-------+ + +In the triggered-buffer path the SPI rx_buf for each transfer points direc= tly +into the scan buffer, so the 16-bit big-endian result is written in place = with +no additional copying. + +In the DMA offload paths the SPI offload engine streams 16-bit words (one = per +active channel) directly into the IIO DMA buffer: + +* **CNV Burst offload**: each channel read uses a 16-bit address phase fol= lowed + by a 16-bit data phase; only the data phase is flagged for DMA streaming= , so + the 16-bit result lands directly in the buffer. +* **Manual offload**: each 16-bit SPI transfer carries the channel command= on + TX and receives the 16-bit ADC result on RX; results are streamed to the + DMA buffer one 16-bit word per channel. + +The ``in_voltageN_type`` sysfs attribute reflects the active scan type. + + +Unimplemented features +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +* GPIO controller functionality of the GP pins +* Clamp status and overrange events +* Raw accumulator (ACC_IN) and accumulator status registers +* ADC_BUSY and overrun status interrupts 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..819d8b6eb6bb 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1491,6 +1491,7 @@ S: Supported W: https://ez.analog.com/linux-software-drivers F: Documentation/devicetree/bindings/iio/adc/adi,ad4691.yaml F: drivers/iio/adc/ad4691.c +F: drivers/iio/adc/ad4691.rst =20 ANALOG DEVICES INC AD4695 DRIVER M: Michael Hennerich --=20 2.43.0