Received-SPF: pass (google.com: domain of linux-kernel+bounces-102493-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
From: David Lechner <dlechner@baylibre.com>
To: Jonathan Cameron <jic23@kernel.org>
Cc: David Lechner <dlechner@baylibre.com>,
	Michael Hennerich <michael.hennerich@analog.com>,
	=?utf-8?q?Nuno_S=C3=A1?= <nuno.sa@analog.com>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-doc@vger.kernel.org,
	linux-iio@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: [PATCH 2/2] docs: iio: new docs for ad7944 driver
Date: Wed, 13 Mar 2024 15:21:52 -0500
Message-ID: <20240313-mainline-ad7944-doc-v1-2-7860416726e4@baylibre.com>
In-Reply-To: <20240313-mainline-ad7944-doc-v1-0-7860416726e4@baylibre.com>
References: <20240313-mainline-ad7944-doc-v1-0-7860416726e4@baylibre.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

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

Credit: the basic structure and some of the text is copied from the
adis16475 docs.

Signed-off-by: David Lechner <dlechner@baylibre.com>
---
 Documentation/iio/ad7944.rst | 227 +++++++++++++++++++++++++++++++++++++++++++
 Documentation/iio/index.rst  |   1 +
 MAINTAINERS                  |   1 +
 3 files changed, 229 insertions(+)

diff --git a/Documentation/iio/ad7944.rst b/Documentation/iio/ad7944.rst
new file mode 100644
index 000000000000..dbe2153b415a
--- /dev/null
+++ b/Documentation/iio/ad7944.rst
@@ -0,0 +1,227 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+=============
+AD7944 driver
+=============
+
+ADC driver for Analog Devices Inc. AD7944 and similar devices. The module name
+is ``ad7944``.
+
+
+Supported devices
+=================
+
+The following chips are supported by this driver:
+
+* `AD7944 <https://www.analog.com/AD7944>`_
+* `AD7985 <https://www.analog.com/AD7985>`_
+* `AD7986 <https://www.analog.com/AD7986>`_
+
+
+Supported features
+==================
+
+SPI wiring modes
+----------------
+
+The driver currently supports two of the many possible SPI wiring configurations.
+
+CS mode, 3-wire, without busy indicator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+                                         +-------------+
+                    +--------------------| CS          |
+                    v                    |             |
+    VIO   +--------------------+         |     HOST    |
+     |    |        CNV         |         |             |
+     +--->| SDI   AD7944   SDO |-------->| SDI         |
+          |        SCK         |         |             |
+          +--------------------+         |             |
+                    ^                    |             |
+                    +--------------------| SCLK        |
+                                         +-------------+
+
+To select this mode in the device tree, set the ``adi,spi-mode`` property to
+``"single"`` and omit the ``cnv-gpios`` property.
+
+CS mode, 4-wire, without busy indicator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block::
+
+                                         +-------------+
+     +-----------------------------------| CS          |
+     |                                   |             |
+     |              +--------------------| GPIO        |
+     |              v                    |             |
+     |    +--------------------+         |     HOST    |
+     |    |        CNV         |         |             |
+     +--->| SDI   AD7944   SDO |-------->| SDI         |
+          |        SCK         |         |             |
+          +--------------------+         |             |
+                    ^                    |             |
+                    +--------------------| SCLK        |
+                                         +-------------+
+
+To select this mode in the device tree, omit the ``adi,spi-mode`` property and
+provide the ``cnv-gpios`` property.
+
+Reference voltage
+-----------------
+
+All 3 possible reference voltage sources are supported:
+
+- Internal reference
+- External 1.2V reference and internal buffer
+- External reference
+
+The source is determined by the device tree. If ``ref-supply`` is present, then
+the external reference is used. If ``refin-supply`` is present, then the internal
+buffer is used. If neither is present, then the internal reference is used.
+
+Unimplemented features
+----------------------
+
+- ``BUSY`` indication
+- ``TURBO`` mode
+- Daisy chain mode
+
+
+Device attributes
+=================
+
+Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
+where ``X`` is the IIO index of the device. Under these folders reside a set of
+device attribute files, depending on the characteristics and features of the
+hardware device in question. These files are consistently generalized and
+documented in the IIO ABI documentation.
+
+There are two types of ADCs in this family, pseudo-differential and fully
+differential. The channel name is different depending on the type of ADC.
+
+Pseudo-differential ADCs
+------------------------
+
+AD7944 and AD7985 are pseudo-differential ADCs and have the following attributes:
+
++---------------------------------------+--------------------------------------------------------------+
+| Attribute                             | Description                                                  |
++=======================================+==============================================================+
+| ``in_voltage0_raw``                   | Raw ADC voltage value (*IN+* referenced to ground sense).    |
++---------------------------------------+--------------------------------------------------------------+
+| ``in_voltage0_scale``                 | Scale factor to convert raw value to mV.                     |
++---------------------------------------+--------------------------------------------------------------+
+
+Fully-differential ADCs
+-----------------------
+
+AD7986 is a fully-differential ADC and has the following attributes:
+
++---------------------------------------+--------------------------------------------------------------+
+| Attribute                             | Description                                                  |
++=======================================+==============================================================+
+| ``in_voltage0-voltage1_raw``          | Raw ADC voltage value (*IN+* - *IN-*).                       |
++---------------------------------------+--------------------------------------------------------------+
+| ``in_voltage0-voltage1_scale``        | Scale factor to convert raw value to mV.                     |
++---------------------------------------+--------------------------------------------------------------+
+
+Processed values
+----------------
+
+A channel value can be read from its ``_raw`` attribute. The value returned is
+the raw value as reported by the devices. To get the processed value of the
+channel, apply the following formula:
+
+.. code-block::
+
+    processed value (mV) = _raw * _scale
+
+Where ``_raw`` and ``_scale`` are the values read from the corresponding device
+attributes and the result is in millivolts.
+
+For pseudo-differential chips, the processed value is the voltage of the *IN+*
+input referenced to ground. For fully-differential chips, the processed value
+is the voltage difference between the *IN+* and *IN-* inputs.
+
+
+Usage examples
+--------------
+
+Show device name:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# cat name
+    ad7986
+
+Show voltage input channel values:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# cat voltage0-voltage1_raw
+    -101976
+    root:/sys/bus/iio/devices/iio:device0# cat voltage0-voltage1_scale
+    0.038146972
+
+The actual measured voltage between *IN+* and *IN-* is:
+
+.. math:: -101976 \times 0.038146972 \approx -3890.08~\mathrm{mV}
+
+
+Device buffers
+==============
+
+This driver supports IIO triggered buffers.
+
+Usage examples
+--------------
+
+Create a trigger if one doesn't already exist:
+
+.. code-block:: console
+
+    root:/# mkdir /sys/kernel/config/iio/triggers/hrtimer/ad7986-trigger
+
+Set device trigger in current_trigger, if not already set:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# cat trigger/current_trigger
+
+    root:/sys/bus/iio/devices/iio:device0# echo ad7986-trigger > trigger/current_trigger
+    root:/sys/bus/iio/devices/iio:device0# cat trigger/current_trigger
+    ad7986-trigger
+
+Select channels for buffer read:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# echo 1 > buffer0/in_voltage0-voltage1_raw_en
+    root:/sys/bus/iio/devices/iio:device0# echo 1 > buffer0/in_timestamp_en
+
+Set the number of samples to be stored in the buffer:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# echo 4 > buffer0/length
+
+Enable the buffer:
+
+.. code-block:: console
+
+    root:/sys/bus/iio/devices/iio:device0# echo 1 > buffer0/enable
+
+Obtain buffered data:
+
+.. code-block:: console
+
+    root:/# hexdump -C -n 64 /dev/iio\:device0
+    00000000  5a 72 03 00 00 00 00 00  c5 b9 da 3f d1 61 bc 17  |Zr.........?.a..|
+    00000010  14 79 02 00 00 00 00 00  d1 3e 73 40 d1 61 bc 17  |.y.......>s@.a..|
+    00000020  7f 77 02 00 00 00 00 00  63 d7 0b 41 d1 61 bc 17  |.w......c..A.a..|
+    00000030  9b 84 02 00 00 00 00 00  af 70 a4 41 d1 61 bc 17  |.........p.A.a..|
+    00000040
+
+See :doc:`iio_devbuf` for more information about how buffered data is structured.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
index 30b09eefe75e..fb6f9d743211 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -16,6 +16,7 @@ Industrial I/O Kernel Drivers
 .. toctree::
    :maxdepth: 1
 
+   ad7944
    adis16475
    bno055
    ep93xx_adc
diff --git a/MAINTAINERS b/MAINTAINERS
index fb2377bad376..40813d9ec38f 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -448,6 +448,7 @@ R:	David Lechner <dlechner@baylibre.com>
 S:	Supported
 W:	https://ez.analog.com/linux-software-drivers
 F:	Documentation/devicetree/bindings/iio/adc/adi,ad7944.yaml
+F:	Documentation/iio/ad7944.rst
 F:	drivers/iio/adc/ad7944.c
 
 ADAFRUIT MINI I2C GAMEPAD

-- 
2.43.2