Re: [PATCH v3 3/3] docs: iio: add AD7191

[Jonathan Cameron <Jonathan.Cameron@huawei.com>]

On Wed, 29 Jan 2025 16:29:04 +0200
Alisa-Dariana Roman <alisadariana@gmail.com> wrote:

> Add documentation for AD7191 driver.
> 
> Signed-off-by: Alisa-Dariana Roman <alisa.roman@analog.com>
Hi Alisa-Dariana,

Please could you build this with make html_docs

It needs to be added to the index as well to build.

Then check formatting of titles and bullet points etc. Looks like
a few bits of formatting of the rst aren't quite right but I haven't
built it to be sure of that.

Content looks fine to me.

Thanks,

Jonathan

> ---
>  Documentation/iio/ad7191.rst | 230 +++++++++++++++++++++++++++++++++++
>  1 file changed, 230 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..78aa5fefe128
> --- /dev/null
> +++ b/Documentation/iio/ad7191.rst
> @@ -0,0 +1,230 @@
> +.. 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

This doesn't look like correct rst for bullet points. Please
build the docs and sanity check this.  I believe it needs to be aligned
and you may nee some blank lines in a few places.

> +
> +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
> +===============

Not enough =

Check all these as well after make html_docs


> +
> +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.