AD4030 driver

지원 장치와 IIO 채널 매핑

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

지원 칩은 AD4030-24, AD4032-24, AD4630-16, AD4630-24, AD4632-16, AD4632-24입니다.

데이터시트가 말하는 각 하드웨어 채널은 IIO 채널 두 개로 나뉩니다. 하나는 differential 데이터, 다른 하나는 common 바이트입니다.

사용 편의를 위해 IIO 채널은 label을 제공합니다. Differential 채널은 하드웨어 채널 ID `N`에 대해 `differentialN`, common-mode 채널은 `common-modeN`입니다.

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

SPI 배선과 출력 모드

현재 드라이버는 one lane과 interleaved 배선 구성을 설명하며 SPI clocking mode만 지원합니다.

One lane 모드에서는 각 채널이 변환 결과를 보내는 자체 SDO 선을 가집니다. 현재 이 모드는 채널 하나인 AD4030에서만 사용할 수 있으므로 SDO 선 하나만 사용합니다.

Interleaved 모드에서는 두 채널의 변환 결과 비트가 SDO 선 하나에 교차 배치됩니다. 물리 배선은 one lane 모드와 같습니다.

장치 데이터시트의 채널 수보다 노출되는 IIO 채널 수가 많은 이유는 `Differential data + common-mode` 인코딩이 한 변환 결과에 두 종류의 정보를 담기 때문입니다. 장치 채널 하나가 differential 데이터와 common 바이트의 IIO 채널 두 개를 제공합니다.

Differential data 출력 모드는 buffered read에서 differential 채널만 활성화하고 oversampling 속성을 1로 설정할 때 선택됩니다.

Differential data + common-mode 출력 모드는 buffered read에서 differential과 common-mode 채널을 함께 활성화하고 oversampling을 1로 설정할 때 선택됩니다. 24비트 칩에서는 16비트 differential 데이터로도 사용할 수 있지만 아직 선택할 수 없습니다.

Averaged differential data 모드는 buffered read에서 differential 채널만 활성화하고 oversampling 속성을 1보다 크게 설정할 때 선택됩니다.

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·offset, 기준 전압과 reset

각 differential 데이터 채널에는 16비트 unsigned 하드웨어 gain을 설정할 수 있으며 기본값은 1입니다. Gain 적용은 수치 포화를 일으킬 수 있습니다.

각 differential 데이터 채널에는 signed 하드웨어 offset도 설정할 수 있습니다. 원문은 `-24`로 끝나는 ADC의 gain이 24비트, `-16`으로 끝나는 ADC의 gain이 16비트로 인코딩된다고 설명하며, offset 적용 역시 수치 포화를 일으킬 수 있다고 경고합니다.

ADC가 반환하는 최종 differential 데이터는 gain을 먼저 적용하고 offset을 나중에 적용해 계산합니다. Gain은 IIO `calibscale`, offset은 `calibbias` 속성으로 제어합니다.

칩은 `REF` 입력의 외부 기준 전압과 `REFIN` 입력의 내부 buffered 기준 전압을 지원합니다. 드라이버는 Device Tree를 보고 사용할 방식을 결정합니다.

`ref-supply`가 있으면 외부 기준 전압을 사용하고 내부 버퍼를 비활성화합니다. `refin-supply`가 있으면 내부 buffered 기준 전압을 사용합니다.

하드웨어 reset과 소프트웨어 reset을 모두 지원합니다. 드라이버는 먼저 Device Tree에 `reset-gpio`가 있는지 확인하고, 없으면 장치 레지스터를 통한 소프트웨어 reset으로 대체합니다.

아직 구현하지 않은 기능은 `BUSY` 표시, 추가 배선 모드, 추가 clock 모드, 24비트 칩의 16비트 differential data + common-mode, overrange 이벤트와 테스트 패턴입니다.

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