ARK-OS/arkos/kernel/Documentation/iio/ad4695.rst

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

SPI offload wiring
^^^^^^^^^^^^^^^^^^

When used with a SPI offload, the supported wiring configuration is:

.. code-block::

    +-------------+         +-------------+
    |    GP0/BUSY |-------->| TRIGGER     |
    |          CS |<--------| CS          |
    |             |         |             |
    |     ADC     |         |     SPI     |
    |             |         |             |
    |         SDI |<--------| SDO         |
    |         SDO |-------->| SDI         |
    |        SCLK |<--------| SCLK        |
    |             |         |             |
    |             |         +-------------+
    |         CNV |<-----+--| PWM         |
    |             |      +--| GPIO        |
    +-------------+         +-------------+

In this case, both the ``cnv-gpios`` and  ``pwms`` properties are required.
The ``#trigger-source-cells = <2>`` property is also required to connect back
to the SPI offload. The SPI offload will have ``trigger-sources`` property
with cells to indicate the busy signal and which GPx pin is used, e.g
``<&ad4695 AD4695_TRIGGER_EVENT_BUSY AD4695_TRIGGER_PIN_GP0>``.

.. seealso:: `SPI offload support`_

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/adc/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.

Oversampling
------------

The chip supports per-channel oversampling when SPI offload is being used, with
available oversampling ratios (OSR) of 1 (default), 4, 16, and 64.  Enabling
oversampling on a channel raises the effective number of bits of sampled data to
17 (OSR == 4), 18 (16), or 19 (64), respectively. This can be set via the
``oversampling_ratio`` attribute.

Setting the oversampling ratio for a channel also changes the sample rate for
that channel, since it requires multiple conversions per 1 sample. Specifically,
the new sampling frequency is the PWM sampling frequency divided by the
particular OSR. This is set automatically by the driver when setting the
``oversampling_ratio`` attribute. For example, if the device's current
``sampling_frequency`` is 10000 and an OSR of 4 is set on channel ``voltage0``,
the new reported sampling rate for that channel will be 2500 (ignoring PWM API
rounding), while all others will remain at 10000.  Subsequently setting the
sampling frequency to a higher value on that channel will adjust the CNV trigger
period for all channels, e.g. if ``voltage0``'s sampling frequency is adjusted
from 2500 (with an OSR of 4) to 10000, the value reported by
``in_voltage0_sampling_frequency`` will be 10000, but all other channels will
now report 40000.

For simplicity, the sampling frequency of the device should be set (considering
the highest desired OSR value to be used) first, before configuring oversampling
for specific channels.

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

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

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/ad469x_fmc/index.html

.. seealso:: `SPI offload wiring`_

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

* ``trigger`` directory is removed.
* ``in_voltage0_sampling_frequency`` attributes are added for setting the sample
  rate.
* ``in_voltage0_sampling_frequency_available`` attributes are 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 ``buffer0/in_voltage0_type`` attribute.

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.

Effective sample rate for buffered reads
----------------------------------------

When SPI offload is not used, the sample rate is determined by the trigger that
is manually configured in userspace. All enabled channels will be read in a
burst when the trigger is received.

When SPI offload is used, the sample rate is configured per channel. All
channels will have the same rate, so only one ``in_voltageY_sampling_frequency``
attribute needs to be set. Since this rate determines the delay between each
individual conversion, the effective sample rate for each sample is actually
the sum of the periods of each enabled channel in a buffered read. In other
words, it is the value of the ``in_voltageY_sampling_frequency`` attribute
divided by the number of enabled channels. So if 4 channels are enabled, with
the ``in_voltageY_sampling_frequency`` attributes set to 1 MHz, the effective
sample rate is 250 kHz.

With oversampling enabled, the effective sample rate also depends on the OSR
assigned to each channel. For example, if one of the 4 channels mentioned in the
previous case is configured with an OSR of 4, the effective sample rate for that
channel becomes (1 MHz / 4 ) = 250 kHz. The effective sample rate for all
four channels is then 1 / ( (3 / 1 MHz) + ( 1 / 250 kHz) ) ~= 142.9 kHz. Note
that in this case "sample" refers to one read of all enabled channels (i.e. one
full cycle through the auto-sequencer).