[PATCH] docs: iio: new docs for ad7380 driver

[PATCH] docs: iio: new docs for ad7380 driver

[Julien Stephan]

This adds a new page to document how to use the ad7380 ADC driver.

Credit: this docs is based on ad7944 docs.

Signed-off-by: Julien Stephan <jstephan@baylibre.com>
---
This commit adds documentation page for ad738x ADC family
---
 Documentation/iio/ad7380.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++
 Documentation/iio/index.rst  |  1 +
 MAINTAINERS                  |  1 +
 3 files changed, 90 insertions(+)

diff --git a/Documentation/iio/ad7380.rst b/Documentation/iio/ad7380.rst
new file mode 100644
index 000000000000..061cd632b5df
--- /dev/null
+++ b/Documentation/iio/ad7380.rst
@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=============
+AD7380 driver
+=============
+
+ADC driver for Analog Devices Inc. AD7380 and similar devices. The module name
+is ``ad7380``.
+
+
+Supported devices
+=================
+
+The following chips are supported by this driver:
+
+* `AD7380 <https://www.analog.com/en/products/ad7380.html>`_
+* `AD7381 <https://www.analog.com/en/products/ad7381.html>`_
+* `AD7383 <https://www.analog.com/en/products/ad7383.html>`_
+* `AD7384 <https://www.analog.com/en/products/ad7384.html>`_
+* `AD7380-4 <https://www.analog.com/en/products/ad7380-4.html>`_
+* `AD7381-4 <https://www.analog.com/en/products/ad7381-4.html>`_
+* `AD7383-4 <https://www.analog.com/en/products/ad7383-4.html>`_
+* `AD7384-4 <https://www.analog.com/en/products/ad7384-4.html>`_
+
+
+Supported features
+==================
+
+SPI wiring modes
+----------------
+
+ad738x ADCs can output data on several SDO lines (1/2/4). The driver currently
+supports only 1 SDO line.
+
+Reference voltage
+-----------------
+
+2 possible reference voltage sources are supported:
+
+- Internal reference (2.5V)
+- External reference (2.5V to 3.3V)
+
+The source is determined by the device tree. If ``refio-supply`` is present,
+then the external reference is used, else the internal reference is used.
+
+Oversampling and resolution boost
+---------------------------------
+
+This family supports 2 types of oversampling: normal average and rolling
+average. Only normal average is supported by the driver, as rolling average can
+be achieved by processing a captured data buffer. The following ratios are
+available: 1 (oversampling disabled)/2/4/8/16/32.
+
+When the on-chip oversampling function is enabled the performance of the ADC can
+exceed the default resolution. To accommodate the performance boost achievable,
+it is possible to enable an additional two bits of resolution. Because the
+resolution boost feature can only be enabled when oversampling is enabled and
+oversampling is not as useful without the resolution boost, the driver
+automatically enables the resolution boost if and only if oversampling is
+enabled.
+
+Since the resolution boost feature causes 16-bit chips to now have 18-bit data
+which means the storagebits has to change from 16 to 32 bits, we use the new
+ext_scan_type feature to allow changing the scan_type at runtime. Unfortunately
+libiio does not support it. So when enabling or disabling oversampling, user
+must restart iiod using the following command:
+
+.. code-block:: bash
+
+	root:~# systemctl restart iiod
+
+
+Unimplemented features
+----------------------
+
+- 2/4 SDO lines
+- Rolling average oversampling
+- Power down mode
+- CRC indication
+- Alert
+
+
+Device buffers
+==============
+
+This driver supports IIO triggered buffers.
+
+See :doc:`iio_devbuf` for more information.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 9cb4c50cb20d..b0385a9ee5a7 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -18,6 +18,7 @@ Industrial I/O Kernel Drivers
 .. toctree::
    :maxdepth: 1
 
+   ad7380
    ad7944
    adis16475
    adis16480
diff --git a/MAINTAINERS b/MAINTAINERS
index 06ecfa64a39a..40cf58c2f884 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -447,6 +447,7 @@ S:	Supported
 W:	https://wiki.analog.com/resources/tools-software/linux-drivers/iio-adc/ad738x
 W:	https://ez.analog.com/linux-software-drivers
 F:	Documentation/devicetree/bindings/iio/adc/adi,ad7380.yaml
+F:	Documentation/iio/ad7380.rst
 F:	drivers/iio/adc/ad7380.c
 
 AD7877 TOUCHSCREEN DRIVER

---
base-commit: 986da024b99a72e64f6bdb3f3f0e52af024b1f50
change-id: 20240708-ad7380-add-docs-42a9296e5cd3

Best regards,
-- 
Julien Stephan <jstephan@baylibre.com>

Re: [PATCH] docs: iio: new docs for ad7380 driver

[Jonathan Cameron]

On Tue, 09 Jul 2024 17:16:46 +0200
Julien Stephan <jstephan@baylibre.com> wrote:

> This adds a new page to document how to use the ad7380 ADC driver.
> 
> Credit: this docs is based on ad7944 docs.
> 
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
Only thing in here I wondered about is talking about what libiio supports.
That is likely to change if we get lots of devices with the sort of resolution
changing that occurs with this one.  Ah well, I guess we will probably get
stale docs if no one is paying attention.   That happens anyway for so
many other reasons I'm not that worried about one more.

Applied to the testing branch of iio.git for now as I'll be rebasing on rc1
once available.

Thanks,

Jonathan


> +Since the resolution boost feature causes 16-bit chips to now have 18-bit data
> +which means the storagebits has to change from 16 to 32 bits, we use the new
> +ext_scan_type feature to allow changing the scan_type at runtime. Unfortunately
> +libiio does not support it. So when enabling or disabling oversampling, user
> +must restart iiod using the following command:
> +
> +.. code-block:: bash
> +
> +	root:~# systemctl restart iiod
> +
> +