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

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

=============
AD4030 driver
=============

ADC driver for Analog Devices Inc. AD4030 and similar devices. The module name
is ``ad4030``.


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

The following chips are supported by this driver:

* `AD4030-24 <https://www.analog.com/AD4030-24>`_
* `AD4032-24 <https://www.analog.com/AD4032-24>`_
* `AD4630-16 <https://www.analog.com/AD4630-16>`_
* `AD4630-24 <https://www.analog.com/AD4630-24>`_
* `AD4632-16 <https://www.analog.com/AD4632-16>`_
* `AD4632-24 <https://www.analog.com/AD4632-24>`_

IIO channels
============

Each "hardware" channel as described in the datasheet is split in 2 IIO
channels:

- One channel for the differential data
- One channel for the common byte.

The possible IIO channels depending on the numbers of "hardware" channel are:

+------------------------------------+------------------------------------+
| 1 channel ADC                      | 2 channels ADC                     |
+====================================+====================================+
| - voltage0-voltage1 (differential) | - voltage0-voltage1 (differential) |
| - voltage2 (common-mode)           | - voltage2-voltage3 (differential) |
|                                    | - voltage4 (common-mode)           |
|                                    | - voltage5 (common-mode)           |
+------------------------------------+------------------------------------+

Labels
------

For ease of use, the IIO channels provide a label. For a differential channel,
the label is ``differentialN`` where ``N`` is the "hardware" channel id. For a
common-mode channel, the label is ``common-modeN`` where ``N`` is the
"hardware" channel id.

The possible labels are:

+-----------------+-----------------+
| 1 channel ADC   | 2 channels ADC  |
+=================+=================+
| - differential0 | - differential0 |
| - common-mode0  | - differential1 |
|                 | - common-mode0  |
|                 | - common-mode1  |
+-----------------+-----------------+

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

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

The driver currently supports the following SPI wiring configurations:

One lane mode
^^^^^^^^^^^^^

In this mode, each channel has its own SDO line to send the conversion results.
At the moment this mode can only be used on AD4030 which has one channel so only
one SDO line is used.

.. code-block::

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

Interleaved mode
^^^^^^^^^^^^^^^^

In this mode, both channels conversion results are bit interleaved one SDO line.
As such the wiring is the same as `One lane mode`_.

SPI Clock mode
--------------

Only the SPI clocking mode is supported.

Output modes
------------

There are more exposed IIO channels than channels as describe in the devices
datasheet. This is due to the `Differential data + common-mode`_ encoding
2 types of information in one conversion result. As such a "device" channel
provides 2 IIO channels, one for the differential data and one for the common
byte.

Differential data
^^^^^^^^^^^^^^^^^

This mode is selected when:

- Only differential channels are enabled in a buffered read
- Oversampling attribute is set to 1

Differential data + common-mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This mode is selected when:

- Differential and common-mode channels are enabled in a buffered read
- Oversampling attribute is set to 1

For the 24-bits chips, this mode is also available with 16-bits differential
data but is not selectable yet.

Averaged differential data
^^^^^^^^^^^^^^^^^^^^^^^^^^

This mode is selected when:

- Only differential channels are selected enabled in a buffered read
- Oversampling attribute is greater than 1

Digital Gain and Offset
-----------------------

Each differential data channel has a 16-bits unsigned configurable hardware
gain applied to it. By default it's equal to 1. Note that applying gain can
cause numerical saturation.

Each differential data channel has a signed configurable hardware offset.
For the ADCs ending in ``-24``, the gain is encoded on 24-bits.
Likewise, the ADCs ending in ``-16`` have a gain encoded on 16-bits. Note that
applying an offset can cause numerical saturation.

The final differential data returned by the ADC is computed by first applying
the gain, then the offset.

The gain is controlled by the ``calibscale`` IIO attribute while the offset is
controlled by the ``calibbias`` attribute.

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.

Reset
-----

Both hardware and software reset are supported. The driver looks first at the
device tree to see if the ``reset-gpio`` is populated.
If not present, the driver will fallback to a software reset by wiring to the
device's registers.

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

- ``BUSY`` indication
- Additional wiring modes
- Additional clock modes
- Differential data 16-bits + common-mode for 24-bits chips
- Overrange events
- Test patterns