[PATCH v4 3/3] docs: iio: add AD7191
From: Alisa-Dariana Roman
Date: Mon Feb 03 2025 - 08:34:54 EST
Add documentation for AD7191 driver.
Signed-off-by: Alisa-Dariana Roman <alisa.roman@xxxxxxxxxx>
---
Documentation/iio/ad7191.rst | 250 +++++++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
2 files changed, 251 insertions(+)
create mode 100644 Documentation/iio/ad7191.rst
diff --git a/Documentation/iio/ad7191.rst b/Documentation/iio/ad7191.rst
new file mode 100644
index 000000000000..b55f3c13e45a
--- /dev/null
+++ b/Documentation/iio/ad7191.rst
@@ -0,0 +1,250 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+==============
+AD7191 driver
+==============
+
+Device driver for Analog Devices AD7191 ADC.
+
+==================
+Supported devices
+==================
+
+* `AD7191 <https://www.analog.com/AD7191>`_
+
+The AD7191 is a high precision, low noise, 24-bit Σ-Δ ADC with integrated PGA.
+It features two differential input channels, an internal temperature sensor, and
+configurable sampling rates.
+
+=====================
+Device Configuration
+=====================
+
+--------------------
+Pin Configuration
+--------------------
+
+The driver supports both pin-strapped and GPIO-controlled configurations for ODR
+(Output Data Rate) and PGA (Programmable Gain Amplifier) settings. These
+configurations are mutually exclusive - you must use either pin-strapped or GPIO
+control for each setting, not both.
+
+^^^^^^^^^^^^^^^^^^^^
+ODR Configuration
+^^^^^^^^^^^^^^^^^^^^
+
+The ODR can be configured either through GPIO control or pin-strapping:
+
+- When using GPIO control, specify the "odr-gpios" property in the device tree
+- For pin-strapped configuration, specify the "adi,odr-value" property in the
+ device tree
+
+Available ODR settings:
+
+ - 120 Hz (ODR1=0, ODR2=0)
+ - 60 Hz (ODR1=0, ODR2=1)
+ - 50 Hz (ODR1=1, ODR2=0)
+ - 10 Hz (ODR1=1, ODR2=1)
+
+^^^^^^^^^^^^^^^^^^^
+PGA Configuration
+^^^^^^^^^^^^^^^^^^^
+
+The PGA can be configured either through GPIO control or pin-strapping:
+
+- When using GPIO control, specify the "pga-gpios" property in the device tree
+- For pin-strapped configuration, specify the "adi,pga-value" property in the
+ device tree
+
+Available PGA gain settings:
+
+ - 1x (PGA1=0, PGA2=0)
+ - 8x (PGA1=0, PGA2=1)
+ - 64x (PGA1=1, PGA2=0)
+ - 128x (PGA1=1, PGA2=1)
+
+--------------------
+Clock Configuration
+--------------------
+
+The AD7191 supports both internal and external clock sources:
+
+- When CLKSEL pin is tied LOW: Uses internal 4.92MHz clock (no clock property
+ needed)
+- When CLKSEL pin is tied HIGH: Requires external clock source
+ - Can be a crystal between MCLK1 and MCLK2 pins
+ - Or a CMOS-compatible clock driving MCLK2 pin
+ - Must specify the "clocks" property in device tree when using external clock
+
+--------------------------
+SPI Interface Requirements
+--------------------------
+
+The AD7191 has specific SPI interface requirements:
+
+- The DOUT/RDY output is dual-purpose and requires SPI bus locking
+- DOUT/RDY must be connected to an interrupt-capable GPIO
+- The SPI controller's chip select must be connected to the PDOWN pin of the ADC
+- When CS (PDOWN) is high, the device powers down and resets internal circuitry
+- SPI mode 3 operation (CPOL=1, CPHA=1) is required
+
+-------------------------
+Power Supply Requirements
+-------------------------
+
+The device requires the following power supplies:
+
+- AVdd: Analog power supply
+- DVdd: Digital power supply
+- Vref: Reference voltage supply (external)
+
+All power supplies must be specified in the device tree.
+
+===================
+Device Attributes
+===================
+
+The AD7191 provides several attributes through the IIO sysfs interface:
+
+-----------------------------------
+Voltage Input Differential Channels
+-----------------------------------
+
++-------------------+----------------------------------------------------------+
+| Attribute | Description |
++===================+==========================================================+
+| raw | Raw ADC output value |
++-------------------+----------------------------------------------------------+
+| scale | Scale factor to convert raw value to voltage |
++-------------------+----------------------------------------------------------+
+| offset | Voltage offset |
++-------------------+----------------------------------------------------------+
+| sampling_frequency| Current sampling frequency setting |
++-------------------+----------------------------------------------------------+
+
+--------------------
+Temperature Sensor
+--------------------
+
++-------------------+----------------------------------------------------------+
+| Attribute | Description |
++===================+==========================================================+
+| raw | Raw temperature sensor output value |
++-------------------+----------------------------------------------------------+
+| scale | Scale factor to convert raw value to temperature |
++-------------------+----------------------------------------------------------+
+| offset | Temperature calibration offset |
++-------------------+----------------------------------------------------------+
+
+--------------------
+Available Attributes
+--------------------
+
+The following attributes show available configuration options:
+
+- sampling_frequency_available: List of supported sampling frequencies
+- scale_available: List of supported scale factors (based on PGA settings)
+
+=====================
+Channel Configuration
+=====================
+
+The device provides three channels:
+
+1. Temperature Sensor
+ - 24-bit unsigned
+ - Internal temperature measurement
+ - Temperature in millidegrees Celsius
+
+2. Differential Input (AIN1-AIN2)
+ - 24-bit unsigned
+ - Differential voltage measurement
+ - Configurable gain via PGA
+
+3. Differential Input (AIN3-AIN4)
+ - 24-bit unsigned
+ - Differential voltage measurement
+ - Configurable gain via PGA
+
+=====================
+Device Tree Bindings
+=====================
+
+-------------------
+Required Properties
+-------------------
+
+- compatible: Should be "adi,ad7191"
+- reg: SPI chip select number
+- spi-max-frequency: Maximum SPI clock frequency
+- spi-cpol: Must be present (set to 1)
+- spi-cpha: Must be present (set to 1)
+- interrupts: Interrupt mapping for DOUT/RDY pin
+- avdd-supply: Analog power supply
+- dvdd-supply: Digital power supply
+- vref-supply: Reference voltage supply
+- temp-gpios: GPIO for temperature channel selection
+- chan-gpios: GPIO for input channel selection
+
+-------------------
+Optional Properties
+-------------------
+
+- clocks: Required when using external clock (CLKSEL=1), must be absent for
+ internal clock
+- adi,odr-value: Pin-strapped ODR configuration (120, 60, 50, or 10)
+- adi,pga-value: Pin-strapped PGA configuration (1, 8, 64, or 128)
+- odr-gpios: GPIOs for ODR control (mutually exclusive with adi,odr-value)
+- pga-gpios: GPIOs for PGA control (mutually exclusive with adi,pga-value)
+
+-------------------
+Example Device Tree
+-------------------
+
+.. code-block:: dts
+
+ #include <dt-bindings/gpio/gpio.h>
+ #include <dt-bindings/interrupt-controller/irq.h>
+
+ spi {
+ #address-cells = <1>;
+ #size-cells = <0>;
+
+ ad7191@0 {
+ compatible = "adi,ad7191";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+
+ /* Required SPI mode 3 */
+ spi-cpol;
+ spi-cpha;
+
+ /* Interrupt for DOUT/RDY pin */
+ interrupts = <25 IRQ_TYPE_EDGE_FALLING>;
+ interrupt-parent = <&gpio>;
+
+ /* Power supplies */
+ avdd-supply = <&avdd>;
+ dvdd-supply = <&dvdd>;
+ vref-supply = <&vref>;
+
+ /* Optional external clock */
+ clocks = <&ad7191_mclk>;
+
+ /* Configuration - either use GPIO control or pin-strapped values */
+ adi,pga-value = <1>;
+ odr-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>,
+ <&gpio 24 GPIO_ACTIVE_HIGH>;
+
+ /* Required GPIO controls */
+ temp-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
+ chan-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>;
+ };
+ };
+
+================
+Buffer Support
+================
+
+This driver supports IIO triggered buffers. See Documentation/iio/iio_devbuf.rst
+for more information about IIO triggered buffers.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 5710f5b9e958..9235f38f47a1 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -20,6 +20,7 @@ Industrial I/O Kernel Drivers
ad4000
ad4695
+ ad7191
ad7380
ad7606
ad7625
--
2.43.0