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.
---
Changes in v2:
- Removed some paragraphs that would be redundant for most drivers,
e.g. most of the buffer section.
- Link to v1: https://lore.kernel.org/r/[email protected]
---
David Lechner (2):
MAINTAINERS: add Documentation/iio/ to IIO subsystem
docs: iio: new docs for ad7944 driver
Documentation/iio/ad7944.rst | 130 +++++++++++++++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
MAINTAINERS | 2 +
3 files changed, 133 insertions(+)
---
base-commit: bbafdb305d6b00934cc09a90ec1bb659d43e5171
change-id: 20240313-mainline-ad7944-doc-285b47ed6d35
This adds a new page to document how to use the ad7944 ADC driver.
Signed-off-by: David Lechner <[email protected]>
---
Documentation/iio/ad7944.rst | 130 +++++++++++++++++++++++++++++++++++++++++++
Documentation/iio/index.rst | 1 +
MAINTAINERS | 1 +
3 files changed, 132 insertions(+)
diff --git a/Documentation/iio/ad7944.rst b/Documentation/iio/ad7944.rst
new file mode 100644
index 000000000000..f418ab1288ae
--- /dev/null
+++ b/Documentation/iio/ad7944.rst
@@ -0,0 +1,130 @@
+.. 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
+=================
+
+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. |
++---------------------------------------+--------------------------------------------------------------+
+
+
+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 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 Fri, 22 Mar 2024 16:52:12 -0500
David Lechner <[email protected]> wrote:
> 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.
>
There goes deniability :)
Applied to the togreg-normal branch of iio.git.
Thanks,
Jonathan
> ---
> Changes in v2:
> - Removed some paragraphs that would be redundant for most drivers,
> e.g. most of the buffer section.
> - Link to v1: https://lore.kernel.org/r/[email protected]
>
> ---
> David Lechner (2):
> MAINTAINERS: add Documentation/iio/ to IIO subsystem
> docs: iio: new docs for ad7944 driver
>
> Documentation/iio/ad7944.rst | 130 +++++++++++++++++++++++++++++++++++++++++++
> Documentation/iio/index.rst | 1 +
> MAINTAINERS | 2 +
> 3 files changed, 133 insertions(+)
> ---
> base-commit: bbafdb305d6b00934cc09a90ec1bb659d43e5171
> change-id: 20240313-mainline-ad7944-doc-285b47ed6d35