| Message ID | 20250129143054.225322-4-alisa.roman@analog.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Headers | show |
| Series | Add support for AD7191 | expand |
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.
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 + +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.
Add documentation for AD7191 driver. Signed-off-by: Alisa-Dariana Roman <alisa.roman@analog.com> --- Documentation/iio/ad7191.rst | 230 +++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 Documentation/iio/ad7191.rst