.. SPDX-License-Identifier: GPL-2.0-only

=============
AD4695 driver
=============

ADC driver for Analog Devices Inc. AD4695 and similar devices. The module name
is ``ad4695``.


Supported devices
=================

The following chips are supported by this driver:

* `AD4695 <https://www.analog.com/AD4695>`_
* `AD4696 <https://www.analog.com/AD4696>`_
* `AD4697 <https://www.analog.com/AD4697>`_
* `AD4698 <https://www.analog.com/AD4698>`_


Supported features
==================

SPI wiring modes
----------------

The driver currently supports the following SPI wiring configuration:

4-wire mode
^^^^^^^^^^^

In this mode, CNV and CS are tied together and there is a single SDO line.

.. code-block::

    +-------------+         +-------------+
    |          CS |<-+------| CS          |
    |         CNV |<-+      |             |
    |     ADC     |         |     HOST    |
    |             |         |             |
    |         SDI |<--------| SDO         |
    |         SDO |-------->| SDI         |
    |        SCLK |<--------| SCLK        |
    +-------------+         +-------------+

To use this mode, in the device tree, omit the ``cnv-gpios`` and
``spi-rx-bus-width`` properties.

Channel configuration
---------------------

Since the chip supports multiple ways to configure each channel, this must be
described in the device tree based on what is actually wired up to the inputs.

There are three typical configurations:

An ``INx`` pin is used as the positive input with the ``REFGND``, ``COM`` or
the next ``INx`` pin as the negative input.

Pairing with REFGND
^^^^^^^^^^^^^^^^^^^

Each ``INx`` pin can be used as a pseudo-differential input in conjunction with
the ``REFGND`` pin. The device tree will look like this:

.. code-block::

    channel@0 {
        reg = <0>; /* IN0 */
    };

If no other channel properties are needed (e.g. ``adi,no-high-z``), the channel
node can be omitted entirely.

This will appear on the IIO bus as the ``voltage0`` channel. The processed value
(*raw × scale*) will be the voltage present on the ``IN0`` pin relative to
``REFGND``. (Offset is always 0 when pairing with ``REFGND``.)

Pairing with COM
^^^^^^^^^^^^^^^^

Each ``INx`` pin can be used as a pseudo-differential input in conjunction with
the ``COM`` pin. The device tree will look like this:

.. code-block::

    com-supply = <&vref_div_2>;

    channel@1 {
        reg = <1>; /* IN1 */
        common-mode-channel = <AD4695_COMMON_MODE_COM>;
        bipolar;
    };

This will appear on the IIO bus as the ``voltage1`` channel. The processed value
(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin
relative to ``REFGND``. (The offset is determined by the ``com-supply`` voltage.)

The macro comes from:

.. code-block::

    #include <dt-bindings/iio/adi,ad4695.h>

Pairing two INx pins
^^^^^^^^^^^^^^^^^^^^

An even-numbered ``INx`` pin and the following odd-numbered ``INx`` pin can be
used as a pseudo-differential input. The device tree for using ``IN2`` as the
positive input and ``IN3`` as the negative input will look like this:

.. code-block::

    in3-supply = <&vref_div_2>;

    channel@2 {
        reg = <2>; /* IN2 */
        common-mode-channel = <3>; /* IN3 */
        bipolar;
    };

This will appear on the IIO bus as the ``voltage2`` channel. The processed value
(*(raw + offset) × scale*) will be the voltage measured on the ``IN1`` pin
relative to ``REFGND``. (Offset is determined by the ``in3-supply`` voltage.)

VCC supply
----------

The chip supports being powered by an external LDO via the ``VCC`` input or an
internal LDO via the ``LDO_IN`` input. The driver looks at the device tree to
determine which is being used. If ``ldo-supply`` is present, then the internal
LDO is used. If ``vcc-supply`` is present, then the external LDO is used and
the internal LDO is disabled.

Reference voltage
-----------------

The chip supports an external reference voltage via the ``REF`` input or an
internal buffered reference voltage via the ``REFIN`` input. The driver looks
at the device tree to determine which is being used. If ``ref-supply`` is
present, then the external reference voltage is used and the internal buffer is
disabled. If ``refin-supply`` is present, then the internal buffered reference
voltage is used.

Gain/offset calibration
-----------------------

System calibration is supported using the channel gain and offset registers via
the ``calibscale`` and ``calibbias`` attributes respectively.

Unimplemented features
----------------------

- Additional wiring modes
- Threshold events
- Oversampling
- GPIO support
- CRC support

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

This driver supports hardware triggered buffers. This uses the "advanced
sequencer" feature of the chip to trigger a burst of conversions.

Also see :doc:`iio_devbuf` for more general information.