AD4695 driver

지원 장치와 일반·offload SPI 배선

이 문서는 Analog Devices Inc. AD4695와 유사 ADC의 드라이버를 설명합니다. 모듈 이름은 `ad4695`이고 지원 칩은 AD4695, AD4696, AD4697, AD4698입니다.

일반 4-wire 모드에서는 CNV와 CS를 서로 묶고 SDO 선 하나를 사용합니다. ADC의 SDI는 호스트 SDO, ADC SDO는 호스트 SDI, SCLK는 서로 연결합니다.

이 모드를 쓰려면 Device Tree에서 `cnv-gpios`와 `spi-rx-bus-width` 속성을 모두 생략합니다.

SPI offload에서는 `GP0/BUSY`가 offload TRIGGER 입력으로 가고, CS·SDI·SDO·SCLK는 일반 SPI처럼 연결합니다. CNV는 PWM과 GPIO가 함께 구동할 수 있게 연결됩니다.

Offload 배선에서는 `cnv-gpios`와 `pwms`가 모두 필수입니다. SPI offload로 이벤트를 되돌려 연결하려면 `#trigger-source-cells = <2>`도 필요합니다.

SPI offload의 `trigger-sources` 셀은 busy 신호와 사용할 GPx 핀을 지정합니다. 예는 `<&ad4695 AD4695_TRIGGER_EVENT_BUSY AD4695_TRIGGER_PIN_GP0>`입니다.

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

채널 pairing과 전원·기준 전압

칩은 채널마다 여러 입력 구성을 지원하므로 실제 입력 배선에 맞춰 Device Tree에 기술해야 합니다. 일반적인 구성은 INx를 positive 입력으로 쓰고 REFGND, COM 또는 다음 INx를 negative 입력으로 짝짓는 세 가지입니다.

REFGND pairing에서는 각 INx가 REFGND와 함께 pseudo-differential 입력으로 동작합니다. `channel@0 { reg = <0>; };`은 IN0을 선택합니다. `adi,no-high-z` 같은 추가 속성이 없다면 채널 노드를 통째로 생략할 수 있습니다.

이 구성은 IIO에서 `voltage0`으로 보입니다. 처리 값 `raw × scale`은 REFGND에 대한 IN0 전압이고, REFGND pairing의 offset은 항상 0입니다.

COM pairing에서는 `com-supply`를 제공하고 채널 노드에 `common-mode-channel = <AD4695_COMMON_MODE_COM>`과 `bipolar`를 지정합니다. 예제의 IN1은 IIO `voltage1`로 보입니다.

처리 값 `(raw + offset) × scale`은 REFGND에 대한 IN1 전압이며 offset은 `com-supply` 전압으로 결정됩니다. 매크로는 `#include <dt-bindings/iio/adc/adi,ad4695.h>`에서 가져옵니다.

두 INx pairing에서는 짝수 INx와 바로 다음 홀수 INx를 pseudo-differential 쌍으로 사용합니다. 예제는 `in3-supply`를 제공하고 `channel@2`의 positive 입력 IN2에 `common-mode-channel = <3>`과 `bipolar`를 지정해 IN3을 negative 입력으로 연결합니다.

이 구성은 IIO `voltage2`로 보입니다. 원문은 처리 값 설명에서 IN1이라고 적고 있으며, offset은 `in3-supply` 전압으로 결정된다고 설명합니다. 원문의 핀 표기와 줄 좌표는 영어 원문 블록에 그대로 보존했습니다.

전원은 `VCC` 입력의 외부 LDO 또는 `LDO_IN` 입력의 내부 LDO를 사용할 수 있습니다. `ldo-supply`가 있으면 내부 LDO, `vcc-supply`가 있으면 외부 LDO를 쓰고 내부 LDO를 비활성화합니다.

기준 전압은 `REF`의 외부 기준 또는 `REFIN`의 내부 buffered 기준을 지원합니다. `ref-supply`가 있으면 외부 기준을 쓰고 내부 버퍼를 끄며, `refin-supply`가 있으면 내부 buffered 기준을 사용합니다.

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.

보정, 채널별 oversampling과 미구현 기능

채널 gain과 offset 레지스터를 통한 시스템 보정을 지원합니다. Gain은 `calibscale`, offset은 `calibbias` 속성으로 제어합니다.

SPI offload를 사용할 때 채널별 oversampling을 지원합니다. OSR은 기본값 1과 4, 16, 64이며 `oversampling_ratio` 속성으로 설정합니다.

Oversampling을 켜면 유효 샘플 비트 수가 OSR 4에서 17비트, 16에서 18비트, 64에서 19비트로 증가합니다.

채널 OSR을 바꾸면 샘플 하나에 여러 변환이 필요하므로 해당 채널 샘플률도 변합니다. 드라이버는 `oversampling_ratio` 설정 때 PWM sampling frequency를 OSR로 나눈 값으로 자동 조정합니다.

예를 들어 장치 `sampling_frequency`가 10000이고 `voltage0`에 OSR 4를 설정하면 PWM API 반올림을 무시할 때 그 채널은 2500, 나머지는 10000을 보고합니다.

그 뒤 OSR 4인 `voltage0`의 샘플률을 2500에서 10000으로 올리면 드라이버가 모든 채널의 CNV trigger 주기를 바꿉니다. `in_voltage0_sampling_frequency`는 10000이지만 다른 채널은 40000을 보고하게 됩니다.

혼동을 줄이려면 사용할 가장 높은 OSR을 고려해 장치 sampling frequency를 먼저 설정한 다음 특정 채널에 oversampling을 구성해야 합니다.

아직 구현되지 않은 기능은 추가 배선 모드, threshold 이벤트, GPIO 지원과 CRC 지원입니다.

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 인터페이스와 buffered 유효 샘플률

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

Offload를 사용하면 일부 IIO 속성이 달라집니다. `trigger` 디렉터리와 `timestamp` 채널을 제거하고, 샘플률 설정용 `in_voltage0_sampling_frequency`와 최대 샘플률 조회용 `in_voltage0_sampling_frequency_available`을 추가합니다.

버퍼 데이터 형식도 offload를 쓰지 않을 때와 다를 수 있으며 `buffer0/in_voltage0_type` 같은 속성에서 확인할 수 있습니다.

드라이버는 하드웨어 triggered buffer를 지원하며 칩의 advanced sequencer로 변환 burst를 시작합니다. 일반 IIO 버퍼 정보는 `iio_devbuf` 문서를 참조합니다.

SPI offload를 사용하지 않을 때는 사용자 공간에서 수동 구성한 trigger가 샘플률을 결정합니다. Trigger를 받으면 활성화한 모든 채널을 burst로 읽습니다.

SPI offload에서는 채널별로 샘플률을 구성합니다. 모든 채널이 같은 rate를 가지므로 `in_voltageY_sampling_frequency` 하나만 설정하면 됩니다. 하지만 이 값은 개별 변환 사이의 지연을 정하므로, 활성 채널 전체를 한 번 읽는 유효 샘플률은 각 채널 주기의 합으로 결정됩니다.

OSR이 모두 1이면 유효 샘플률은 `in_voltageY_sampling_frequency / 활성 채널 수`입니다. 예를 들어 4채널을 활성화하고 속성을 1MHz로 설정하면 전체 cycle의 유효 샘플률은 250kHz입니다.

Oversampling을 사용하면 채널별 OSR도 반영합니다. 4채널 중 하나가 OSR 4이면 해당 채널의 유효 변환률은 `1MHz / 4 = 250kHz`이고 전체 4채널 cycle은 `1 / ((3 / 1MHz) + (1 / 250kHz)) ≈ 142.9kHz`입니다.

여기서 sample은 활성화한 모든 채널을 한 번씩 읽는 것, 즉 auto-sequencer의 한 전체 cycle을 뜻합니다.

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