Adding documentation for the recently applied ad7944 driver.
Note: this also covers the features added in [1] that hasn't been
applied yet.
[1]: https://lore.kernel.org/linux-iio/20240311-mainline-ad7944-3-wire-mode-v1-1-8e8199efa1f7@baylibre.com/
Also updating the MAINTAINERS file to catch iio documentation since this
seems to have been overlooked.
---
David Lechner (2):
MAINTAINERS: add Documentation/iio/ to IIO subsystem
docs: iio: new docs for ad7944 driver
Documentation/iio/ad7944.rst | 227 +++++++++++++++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
MAINTAINERS | 2 +
3 files changed, 230 insertions(+)
---
base-commit: bbafdb305d6b00934cc09a90ec1bb659d43e5171
change-id: 20240313-mainline-ad7944-doc-285b47ed6d35
Best regards,
--
David Lechner <[email protected]>
Patches touching the IIO subsystem documentation should also be sent to
the IIO mailing list.
Signed-off-by: David Lechner <[email protected]>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 7b1a6f2d0c9c..fb2377bad376 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10466,6 +10466,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git
F: Documentation/ABI/testing/configfs-iio*
F: Documentation/ABI/testing/sysfs-bus-iio*
F: Documentation/devicetree/bindings/iio/
+F: Documentation/iio/
F: drivers/iio/
F: drivers/staging/iio/
F: include/dt-bindings/iio/
--
2.43.2
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 <[email protected]>
---
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.......>[email protected]..|
+ 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 <[email protected]>
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
On Wed, 13 Mar 2024 15:21:52 -0500
David Lechner <[email protected]> wrote:
> 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 <[email protected]>
In many cases I don't think it's useful to have a per driver doc, but
for this particular part the asci art diagrams make it useful - so thanks
for putting this together.
LGTM, but I'll let it sit on the list for others to take a look.
Poke me if it looks like I've forgotten it (which I used to manage
a lot, but patchwork keeps me organized better these days!)
Jonathan
I missed the reply-all on my last reply, so adding back this lists for
the record.
On Thu, Mar 14, 2024 at 10:57 AM Jonathan Cameron <[email protected]> wrote:
>
> On Thu, 14 Mar 2024 10:52:57 -0500
> David Lechner <[email protected]> wrote:
>
> > On Wed, Mar 13, 2024 at 3:28 PM David Lechner <[email protected]> wrote:
> >
> > ...
> >
> > > +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. |
> > > ++---------------------------------------+--------------------------------------------------------------+
> > > +
> >
> > A colleague pointed out that it is perhaps a bit unusual to have
> > per-channel scaling since the scale is determined by a single
> > reference voltage. I guess it is OK here since there is only one
> > channel. But the driver hasn't hit mainline yet, so we could change
> > that if you think it is better to have a "shared" `in_voltage_scale`.
> Lots of devices have per channel scaling (amplifiers on the front end) but
> on a single channel device, it could be shared or per channel without
> it making any practical difference.
>
> It's unusual, but not wrong, so I'm not that fussed either way.
>
> >
> > ...
> >
> > > +
> > > +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
> > > +
> >
> > Typo here. Missing `in_` on the attribute name.
>
Bah, I missed the reply-all on this one to, so for the record...
On Thu, Mar 14, 2024 at 11:01 AM Jonathan Cameron <[email protected]> wrote:
>
> On Thu, 14 Mar 2024 10:47:43 -0500
> David Lechner <[email protected]> wrote:
>
> > On Thu, Mar 14, 2024 at 10:31 AM Jonathan Cameron <jic23@kernelorg> wrote:
> > >
> > > On Wed, 13 Mar 2024 15:21:52 -0500
> > > David Lechner <[email protected]> wrote:
> > >
> > > > 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 <[email protected]>
> > >
> > > In many cases I don't think it's useful to have a per driver doc, but
> >
> > Having upstream docs for each driver is something that Analog Devices
> > has requested. So unless you object, we will be submitting more like
> > this, at least for new drivers.
>
> Keep them focused on the unique aspects and I'm fine with more docs.
> What I don't want to see is too much boilerplate that might rot.
>
> If a whole bunch look very similar see if the docs can be fused even if
> the drivers aren't due to different register interfaces etc (same
> as we do with DT bindings).
>
> >
> > > for this particular part the asci art diagrams make it useful - so thanks
> > > for putting this together.
> > >
> > > LGTM, but I'll let it sit on the list for others to take a look.
> > > Poke me if it looks like I've forgotten it (which I used to manage
> > > a lot, but patchwork keeps me organized better these days!)
> > >
> > > Jonathan
> > >
> > >
>