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@xxxxxxxxxxxx> --- 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@xxxxxxxxxxxx> 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
