AD7380 driver

지원 장치, SDO와 reference 선택

이 문서는 Analog Devices Inc. AD7380과 유사 ADC의 드라이버를 설명합니다. 모듈 이름은 `ad7380`입니다.

지원 장치는 AD7380, AD7381, AD7383, AD7384, AD7386, AD7387, AD7388과 4채널 변형 AD7380-4, AD7381-4, AD7383-4, AD7384-4, AD7386-4, AD7387-4, AD7388-4, AD7389-4, 그리고 ADAQ4370-4, ADAQ4380-4, ADAQ4381-4입니다.

AD738x ADC는 1·2·4개의 SDO 선으로 데이터를 출력할 수 있지만 현재 드라이버는 SDO 한 선만 지원합니다.

AD7380-4는 2.5~3.3V 외부 reference만 지원하며 Device Tree의 `refin-supply`로 선언해야 합니다.

AD7389-4는 내부 reference만 지원하므로 `refin-supply`와 `refio-supply`를 모두 생략합니다.

ADAQ 장치는 외부 reference가 없고 supply 중 하나인 `refin-supply`에서 유도한 내부 3.3V reference를 사용합니다.

그 밖의 AD738x 장치는 내부 2.5V 또는 외부 2.5~3.3V reference를 지원합니다. `refio-supply`가 있으면 외부 reference, 없으면 내부 reference를 사용합니다.

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

=============
AD7380 driver
=============

ADC driver for Analog Devices Inc. AD7380 and similar devices. The module name
is ``ad7380``.


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

The following chips are supported by this driver:

* `AD7380 <https://www.analog.com/en/products/ad7380.html>`_
* `AD7381 <https://www.analog.com/en/products/ad7381.html>`_
* `AD7383 <https://www.analog.com/en/products/ad7383.html>`_
* `AD7384 <https://www.analog.com/en/products/ad7384.html>`_
* `AD7386 <https://www.analog.com/en/products/ad7386.html>`_
* `AD7387 <https://www.analog.com/en/products/ad7387.html>`_
* `AD7388 <https://www.analog.com/en/products/ad7388.html>`_
* `AD7380-4 <https://www.analog.com/en/products/ad7380-4.html>`_
* `AD7381-4 <https://www.analog.com/en/products/ad7381-4.html>`_
* `AD7383-4 <https://www.analog.com/en/products/ad7383-4.html>`_
* `AD7384-4 <https://www.analog.com/en/products/ad7384-4.html>`_
* `AD7386-4 <https://www.analog.com/en/products/ad7386-4.html>`_
* `AD7387-4 <https://www.analog.com/en/products/ad7387-4.html>`_
* `AD7388-4 <https://www.analog.com/en/products/ad7388-4.html>`_
* `AD7389-4 <https://www.analog.com/en/products/ad7389-4.html>`_
* `ADAQ4370-4 <https://www.analog.com/en/products/adaq4370-4.html>`_
* `ADAQ4380-4 <https://www.analog.com/en/products/adaq4380-4.html>`_
* `ADAQ4381-4 <https://www.analog.com/en/products/adaq4381-4.html>`_


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

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

ad738x ADCs can output data on several SDO lines (1/2/4). The driver currently
supports only 1 SDO line.

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

ad7380-4
~~~~~~~~

ad7380-4 supports only an external reference voltage (2.5V to 3.3V). It must be
declared in the device tree as ``refin-supply``.

ad7389-4
~~~~~~~~

ad7389-4 supports only an internal reference voltage. ``refin-supply`` and
``refio-supply`` properties are both omitted in this case.

ADAQ devices
~~~~~~~~~~~~

ADAQ devices don't have an external reference, but use a 3.3V internal reference
derived from one of its supplies (``refin-supply``)

All other devices from ad738x family
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All other devices from ad738x support 2 possible reference voltage sources:

- Internal reference (2.5V)
- External reference (2.5V to 3.3V)

The source is determined by the device tree. If ``refio-supply`` is present,
then it is used as external reference, else the internal reference is used.

Oversampling, resolution boost와 alert

이 계열은 normal average와 rolling average 두 oversampling 방식을 지원합니다. 드라이버는 normal average만 지원합니다. Rolling average는 캡처한 데이터 버퍼를 후처리해 구현할 수 있습니다.

사용 가능한 비율은 oversampling을 끄는 1과 2, 4, 8, 16, 32입니다.

온칩 oversampling을 켜면 기본 해상도를 넘는 성능을 낼 수 있어 추가 2비트 resolution boost를 사용할 수 있습니다. Boost는 oversampling을 켰을 때만 가능하고 boost 없는 oversampling의 효용도 낮으므로 드라이버는 oversampling과 정확히 함께 boost를 자동으로 켜거나 끕니다.

16비트 칩에서 resolution boost를 사용하면 데이터가 18비트가 되어 storagebits를 16에서 32로 바꿔야 합니다. 드라이버는 새 `ext_scan_type` 기능으로 runtime에 `scan_type`을 바꿉니다.

현재 libiio는 `ext_scan_type`을 지원하지 않습니다. Oversampling을 켜거나 끈 뒤 사용자는 `systemctl restart iiod`로 iiod를 다시 시작해야 합니다.

root:~# systemctl restart iiod

2채널 AD738x는 SDO 한 선 모드에서 SDOB를 alert 핀으로 사용할 수 있습니다. 4채널 변형은 SDO 한 선 또는 두 선 모드에서 SDOD를 alert로 사용할 수 있지만 현재 드라이버는 SDO 한 선만 지원합니다.

변환이 끝났을 때 결과가 alert high limit를 넘거나 low limit 아래로 내려가면 active-low alert가 assert됩니다. CS falling edge에서 해제되며 alert 핀은 모든 채널이 공유합니다.

일반 IIO event 속성 `events/thresh_either_en`으로 alert를 켭니다. 모든 채널이 공유하는 low·high threshold는 `events/in_thresh_falling_value`와 `events/in_thresh_rising_value`로 설정합니다.

Debugfs가 있으면 ALERT 레지스터를 읽어 문제 채널과 방향을 확인할 수 있습니다. 일반적인 사용에서는 alert 핀을 shutdown 트리거에 직접 배선합니다.

Oversampling and resolution boost
---------------------------------

This family supports 2 types of oversampling: normal average and rolling
average. Only normal average is supported by the driver, as rolling average can
be achieved by processing a captured data buffer. The following ratios are
available: 1 (oversampling disabled)/2/4/8/16/32.

When the on-chip oversampling function is enabled the performance of the ADC can
exceed the default resolution. To accommodate the performance boost achievable,
it is possible to enable an additional two bits of resolution. Because the
resolution boost feature can only be enabled when oversampling is enabled and
oversampling is not as useful without the resolution boost, the driver
automatically enables the resolution boost if and only if oversampling is
enabled.

Since the resolution boost feature causes 16-bit chips to now have 18-bit data
which means the storagebits has to change from 16 to 32 bits, we use the new
ext_scan_type feature to allow changing the scan_type at runtime. Unfortunately
libiio does not support it. So when enabling or disabling oversampling, user
must restart iiod using the following command:

.. code-block:: bash

        root:~# systemctl restart iiod

Alert
-----

2 channels variants of the ad738x family, can use the SDOB line as an alert pin
when configured in 1 SDO line mode. 4 channels variants, can use SDOD as an
alert pin when configured in 1 or 2 SDO line(s) mode, although only 1 SDO line
mode is currently supported by the driver (see `SPI wiring modes`_).

At the end of a conversion the active-low alert pin gets asserted if the
conversion result exceeds the alert high limit or falls below the alert low
limit. It is cleared, on a falling edge of CS. The alert pin is common to all
channels.

User can enable alert using the regular iio events attribute:

.. code-block:: bash

        events/thresh_either_en

The high and low thresholds are common to all channels and can also be set using
regular iio events attributes:

.. code-block:: bash

        events/in_thresh_falling_value
        events/in_thresh_rising_value

If debugfs is available, user can read the ALERT register to determine the
faulty channel and direction.

In most use cases, user will hardwire the alert pin to trigger a shutdown.

Single-ended mux 채널과 sequencer

Single-ended AD7386·AD7387·AD7388 및 `-4` 변형은 각 ADC 앞에 2:1 multiplexer를 갖습니다. 추가 구성 레지스터로 입력을 수동 선택하거나 sequencer 모드에서 자동 전환할 수 있습니다.

IIO 관점에서는 모든 입력을 노출합니다. 2채널 부품 AD7386·AD7387·AD7388은 4 IIO 채널, 4채널 부품 AD7386-4·AD7387-4·AD7388-4는 8 IIO 채널을 내보냅니다.

각 mux의 `AinX0` 입력은 IIO 채널 전반부, 즉 2채널 부품에서는 0~1이고 4채널 부품에서는 0~3입니다. `AinX1`은 후반부인 2~3 또는 4~7입니다.

Sequencer 모드를 켜면 mux 입력 두 세트를 번갈아 변환하므로 유효 샘플률이 2로 나뉩니다.

ADAQ 장치는 각 ADC 앞에 핀으로 선택하는 gain을 제공합니다. Device Tree의 `adi,gain-milli` 속성으로 적절한 gain을 선택하며 핀 배선은 데이터시트의 typical connection diagrams를 참조합니다.

아직 구현하지 않은 기능은 2·4 SDO 선, rolling average oversampling, power-down 모드와 CRC indication입니다.

Channel selection and sequencer (single-end chips only)
-------------------------------------------------------

Single-ended chips of this family (ad7386/7/8(-4)) have a 2:1 multiplexer in
front of each ADC. They also include additional configuration registers that
allow for either manual selection or automatic switching (sequencer mode), of
the multiplexer inputs.

From an IIO point of view, all inputs are exported, i.e ad7386/7/8
export 4 channels and ad7386-4/7-4/8-4 export 8 channels.

Inputs ``AinX0`` of multiplexers correspond to the first half of IIO channels (i.e
0-1 or 0-3) and inputs ``AinX1`` correspond to second half (i.e 2-3 or 4-7).
Example for AD7386/7/8 (2 channels parts):

.. code-block::

           IIO   | AD7386/7/8
                 |         +----------------------------
                 |         |     _____        ______
                 |         |    |     |      |      |
        voltage0 | AinA0 --|--->|     |      |      |
                 |         |    | mux |----->| ADCA |---
        voltage2 | AinA1 --|--->|     |      |      |
                 |         |    |_____|      |_____ |
                 |         |     _____        ______
                 |         |    |     |      |      |
        voltage1 | AinB0 --|--->|     |      |      |
                 |         |    | mux |----->| ADCB |---
        voltage3 | AinB1 --|--->|     |      |      |
                 |         |    |_____|      |______|
                 |         |
                 |         +----------------------------


When enabling sequencer mode, the effective sampling rate is divided by two.

Gain (ADAQ devices only)
~~~~~~~~~~~~~~~~~~~~~~~~

ADAQ devices have a pin selectable gain in front of each ADC. The appropriate
gain is selectable from device tree using the ``adi,gain-milli`` property.
Refer to the typical connection diagrams section of the datasheet for pin
wiring.

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

- 2/4 SDO lines
- Rolling average oversampling
- Power down mode
- CRC indication

SPI offload와 IIO 버퍼

최대 샘플 속도를 위해 드라이버를 `AXI SPI Engine`과 함께 사용해 SPI offload를 제공할 수 있습니다.

Offload에서는 `trigger` 디렉터리와 `timestamp` 채널을 제거합니다. 샘플률 설정용 `in_voltage0_sampling_frequency`, 최대 샘플률 조회용 `in_voltage0_sampling_frequency_available`을 추가합니다.

버퍼 데이터 형식은 일반 경로와 다를 수 있으며 `in_voltage0_type` 같은 속성으로 확인합니다.

드라이버는 IIO triggered buffer를 지원합니다. 자세한 일반 정보는 `iio_devbuf`를 참조합니다.

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.

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

This driver supports IIO triggered buffers.

See :doc:`iio_devbuf` for more information.