[PATCH v4 3/3] docs: iio: add AD7191

[Alisa-Dariana Roman <alisadariana@gmail.com>]

Add documentation for AD7191 driver.

Signed-off-by: Alisa-Dariana Roman <alisa.roman@analog.com>
---
 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