On Wed, 29 Jan 2025 16:29:04 +0200 Alisa-Dariana Roman <alisadariana@xxxxxxxxx> wrote: > Add documentation for AD7191 driver. > > Signed-off-by: Alisa-Dariana Roman <alisa.roman@xxxxxxxxxx> 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.
