Re: [PATCH 6/6] docs: iio: ad4030: add documentation

[David Lechner <dlechner@baylibre.com>]

On 8/22/24 7:45 AM, Esteban Blanc wrote:
> This adds a new page to document how to use the ad4030 ADC driver
> 
> Signed-off-by: Esteban Blanc <eblanc@baylibre.com>
> ---
>  Documentation/iio/ad4030.rst | 129 +++++++++++++++++++++++++++++++++++++++++++
>  Documentation/iio/index.rst  |   1 +
>  MAINTAINERS                  |   1 +
>  3 files changed, 131 insertions(+)
> 
> diff --git a/Documentation/iio/ad4030.rst b/Documentation/iio/ad4030.rst
> new file mode 100644
> index 000000000000..56e0ba58b127
> --- /dev/null
> +++ b/Documentation/iio/ad4030.rst
> @@ -0,0 +1,129 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +=============
> +AD4030 driver
> +=============
> +
> +ADC driver for Analog Devices Inc. AD4030 and similar devices. The module name
> +is ``ad4030``.
> +
> +
> +Supported devices
> +=================
> +
> +The following chips are supported by this driver:
> +
> +* `AD4030-24 <https://www.analog.com/AD4030-24>`_
> +* `AD4630-16 <https://www.analog.com/AD4630-16>`_
> +* `AD4630-24 <https://www.analog.com/AD4630-24>`_
> +* `AD4632-16 <https://www.analog.com/AD4632-16>`_
> +* `AD4632-24 <https://www.analog.com/AD4632-24>`_
> +
> +IIO channels
> +============
> +
> +Each "device" channel as described in the datasheet is split in 2 IIO channels,
> +in the following order:
> +
> +- One channel for the differential data
> +- One channel for the common byte.
> +
> +Supported features
> +==================
> +
> +SPI wiring modes
> +----------------
> +
> +The driver currently supports the following SPI wiring configurations:
> +
> +One lane mode
> +^^^^^^^^^^^^^
> +
> +In this mode, each channel has its own SDO line to send the conversion results.
> +At the moment this mode can only be used on AD4030 which has one channel so only
> +one SDO line is used.
> +
> +.. code-block::
> +
> +    +-------------+         +-------------+
> +    |     ADC     |         |     HOST    |
> +    |             |         |             |
> +    |         CNV |<--------| CNV         |
> +    |          CS |<--------| CS          |
> +    |         SDI |<--------| SDO         |
> +    |        SDO0 |-------->| SDI         |
> +    |        SCLK |<--------| SCLK        |
> +    +-------------+         +-------------+
> +
> +Interleaved mode
> +^^^^^^^^^^^^^^^^
> +
> +In this mode, both channels conversion results are bit interleaved one SDO line.
> +As such the wiring is the same as `One lane mode`.
> +
> +SPI Clock mode
> +--------------
> +
> +Only the SPI clocking mode is supported.
> +
> +Output modes
> +------------
> +
> +There is more exposed IIO channels than channels as describe in the devices
> +datasheet. This is due to the `Differential data + 8-bit common-mode` encoding
> +2 types of information in one conversion result. As such a "device" channel
> +provides 2 IIO channels, one for the differential data and one for the common
> +byte.
> +
> +Differential data
> +^^^^^^^^^^^^^^^^^
> +
> +This mode is selected when:
> +
> +- Only differential channels are selected
> +- Oversampling attribute is set to 1
> +
> +Differential data + common-mode
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +This mode is selected when:
> +
> +- Differential and common-mode channels are selected
> +- Oversampling attribute is set to 1
> +
> +For the 24-bits chips, this mode is also available with 16-bits differential
> +data but is not selectable yet.
> +
> +Averaged differential data
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +This mode is selected when:
> +
> +- Only differential channels are selected
> +- Oversampling attribute is greater than 1
> +

Worth mentioning calibration (gain/offset) feature?

> +Reference voltage
> +-----------------
> +
> +The chip supports an external reference voltage via the ``REF`` input or an
> +internal buffered reference voltage via the ``REFIN`` input. The driver looks
> +at the device tree to determine which is being used. If ``ref-supply`` is
> +present, then the external reference voltage is used and the internal buffer is
> +disabled. If ``refin-supply`` is present, then the internal buffered reference
> +voltage is used.
> +
> +Reset
> +-----
> +
> +Both hardware and software reset are supported. The driver looks first at the
> +device tree to see if the `reset-gpio` is populated. If not present, the driver
> +will fallback to a software reset by wiring to the device's registers.
> +
> +Unimplemented features
> +----------------------
> +
> +- ``BUSY`` indication
> +- Additional wiring modes
> +- Additional clock modes
> +- Differential data 16-bits + common-mode for 24-bits chips

- overrange event
- test patterns

> +
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index dfcf9618568a..61faf3a60da6 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -19,6 +19,7 @@ Industrial I/O Kernel Drivers
>     :maxdepth: 1
>  
>     ad4000
> +   ad4030
>     ad4695
>     ad7380
>     ad7944
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 6a5a0e7b7a51..4a076a48648a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -420,6 +420,7 @@ R:	Esteban Blanc <eblanc@baylibre.com>
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
>  F:	Documentation/devicetree/bindings/iio/adc/adi,ad4030.yaml
> +F:	Documentation/iio/ad4030.c
>  F:	drivers/iio/adc/ad4030.c
>  
>  AD5110 ANALOG DEVICES DIGITAL POTENTIOMETERS DRIVER
>