.. 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 three 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.

This is the only wiring configuration supported when using `SPI offload support`_.

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.

Chain mode, without busy indicator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block::

                                                                 +-------------+
                  +-------------------------+--------------------| CS          |
                  v                         v                    |             |
        +--------------------+    +--------------------+         |     HOST    |
        |        CNV         |    |        CNV         |         |             |
   +--->| SDI   AD7944   SDO |--->| SDI   AD7944   SDO |-------->| SDI         |
   |    |        SCK         |    |        SCK         |         |             |
  GND   +--------------------+    +--------------------+         |             |
                  ^                         ^                    |             |
                  +-------------------------+--------------------| SCLK        |
                                                                 +-------------+

To select this mode in the device tree, set the ``adi,spi-mode`` property to
``"chain"``, add the ``spi-cs-high`` flag, add the ``#daisy-chained-devices``
property, and omit 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


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.                     |
+---------------------------------------+--------------------------------------------------------------+

In "chain" mode, additional chips will appear as additional voltage input
channels, e.g. ``in_voltage1_raw``.

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.                     |
+---------------------------------------+--------------------------------------------------------------+

In "chain" mode, additional chips will appear as additional voltage input
channels, e.g. ``in_voltage2-voltage3_raw``.

SPI offload support
===================

To be able to achieve the maximum sample rate, the driver can be used with the
`AXI SPI Engine`_ to provide SPI offload support.

.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html

When SPI offload is being used, some attributes will be different.

* ``trigger`` directory is removed.
* ``in_voltage0_sampling_frequency`` attribute is added for setting the sample
  rate.
* ``in_voltage0_sampling_frequency_available`` attribute is added for querying
  the max sample rate.
* ``timestamp`` channel is removed.
* Buffer data format may be different compared to when offload is not used,
  e.g. the ``in_voltage0_type`` attribute.

If the ``turbo-gpios`` property is present in the device tree, the driver will
turn on TURBO during buffered reads and turn it off otherwise.

Device buffers
==============

This driver supports IIO triggered buffers.

See :doc:`iio_devbuf` for more information.