| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20250131183930.00003f52@huawei.com>
Date: Fri, 31 Jan 2025 18:39:30 +0000
From: Jonathan Cameron <Jonathan.Cameron@...wei.com>
To: Alisa-Dariana Roman <alisadariana@...il.com>
CC: Alisa-Dariana Roman <alisa.roman@...log.com>, David Lechner
<dlechner@...libre.com>, <linux-iio@...r.kernel.org>,
<devicetree@...r.kernel.org>, <linux-kernel@...r.kernel.org>,
<linux-doc@...r.kernel.org>, Lars-Peter Clausen <lars@...afoo.de>, "Michael
Hennerich" <Michael.Hennerich@...log.com>, Jonathan Cameron
<jic23@...nel.org>, Rob Herring <robh@...nel.org>, Krzysztof Kozlowski
<krzk+dt@...nel.org>, Conor Dooley <conor+dt@...nel.org>, Jonathan Corbet
<corbet@....net>
Subject: Re: [PATCH v3 3/3] docs: iio: add AD7191
On Wed, 29 Jan 2025 16:29:04 +0200
Alisa-Dariana Roman <alisadariana@...il.com> wrote:
> Add documentation for AD7191 driver.
>
> Signed-off-by: Alisa-Dariana Roman <alisa.roman@...log.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.
Powered by blists - more mailing lists