IIO Abstractions for ADCs

ADC 추상화와 입력 유형

이 문서는 GPL-2.0-only 라이선스가 적용되는 IIO ADC 추상화 설명서입니다. IIO 하위 시스템은 많은 아날로그-디지털 변환기(ADC)를 지원하며, 장치 드라이버가 공통 ADC 기능과 특성을 어떤 방식으로 제공하는지 설명합니다.

ADC 입력은 서로 다른 유형을 가질 수 있고 각 유형은 아날로그 전압을 조금씩 다른 방식으로 측정합니다. ADC가 디지털화하는 전압 범위는 보통 제공된 기준 전압, 입력 유형, 입력 극성으로 정해집니다.

ADC 채널의 허용 입력 범위를 알아야 실제 단위의 측정값을 얻는 데 필요한 scale factor와 offset을 정할 수 있습니다. 실제 단위의 예는 전압 측정의 millivolts, 전류 측정의 milliamps 등입니다.

복잡한 설계에는 비선형 특성이나 amplifier·reference buffer 같은 통합 부품이 있어 허용 입력 범위를 계산할 때 함께 고려해야 할 수 있습니다. 설명을 명확하게 하기 위해 아래 절에서는 입력 범위가 기준 전압·입력 유형·입력 극성에만 의존한다고 가정합니다.

ADC 입력의 일반 유형은 single-ended, differential, pseudo-differential 세 가지이고 극성은 unipolar와 bipolar 두 가지입니다. 입력 유형과 극성은 서로 완전히 독립적인 채널 특성입니다.

이 문서가 크게 참고한 ADC 입력 유형 종합 문서는 `https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html`에서 볼 수 있습니다.

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

=========================
IIO Abstractions for ADCs
=========================

1. Overview
===========

The IIO subsystem supports many Analog to Digital Converters (ADCs). Some ADCs
have features and characteristics that are supported in specific ways by IIO
device drivers. This documentation describes common ADC features and explains
how they are supported by the IIO subsystem.

1. ADC Channel Types
====================

ADCs can have distinct types of inputs, each of them measuring analog voltages
in a slightly different way. An ADC digitizes the analog input voltage over a
span that is often given by the provided voltage reference, the input type, and
the input polarity. The input range allowed to an ADC channel is needed to
determine the scale factor and offset needed to obtain the measured value in
real-world units (millivolts for voltage measurement, milliamps for current
measurement, etc.).

Elaborate designs may have nonlinear characteristics or integrated components
(such as amplifiers and reference buffers) that might also have to be considered
to derive the allowed input range for an ADC. For clarity, the sections below
assume the input range only depends on the provided voltage references, input
type, and input polarity.

There are three general types of ADC inputs (single-ended, differential,
pseudo-differential) and two possible polarities (unipolar, bipolar). The input
type (single-ended, differential, pseudo-differential) is one channel
characteristic, and is completely independent of the polarity (unipolar,
bipolar) aspect. A comprehensive article about ADC input types (on which this
doc is heavily based on) can be found at
https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html.

Single-ended unipolar 채널

Single-ended 채널은 ground를 기준으로 아날로그 입력 전압을 디지털화하며 unipolar 또는 bipolar일 수 있습니다.

Single-ended unipolar 채널의 입력 전압은 GND부터 VREF까지 변화할 수 있습니다. 여기서 VREF는 system ground보다 전위가 높은 기준 전압입니다.

최대 입력 전압은 VFS(Voltage input Full-Scale)라고도 하며 VREF가 결정합니다. 기준 전압은 외부 전원에서 공급하거나 칩 전원에서 유도할 수 있습니다.

Single-ended unipolar 채널은 Device Tree에서 다음과 같이 기술할 수 있습니다.

adc@0 {
    ...
    #address-cells = <1>;
    #size-cells = <0>;

    channel@0 {
        reg = <0>;
    };
};

ADC 채널 노드는 Device Tree에 언제나 포함할 수 있습니다. 그러나 장치의 모든 입력이 single-ended인 경우처럼 입력 구성이 균일하면 채널 노드 선언은 선택 사항입니다.

Single-ended와 differential 채널이 섞인 장치에는 주의점이 있습니다. `reg` 값이 입력 pin 번호와 일치하지 않는 임의의 번호라면 single-ended 채널 노드에도 `single-channel` 속성을 제공해야 합니다.

ADC 전용 Device Tree 속성의 전체 설명은 `Documentation/devicetree/bindings/iio/adc/adc.yaml`을 참고합니다.

1.1 Single-ended channels
-------------------------

Single-ended channels digitize the analog input voltage relative to ground and
can be either unipolar or bipolar.

1.1.1 Single-ended Unipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

  ---------- VREF -------------
      ´ `           ´ `                  _____________
    /     \       /     \               /             |
   /       \     /       \         --- <  IN    ADC   |
            \   /         \   /         \             |
             `-´           `-´           \       VREF |
  -------- GND (0V) -----------           +-----------+
                                                  ^
                                                  |
                                             External VREF

The input voltage to a **single-ended unipolar** channel is allowed to swing
from GND to VREF (where VREF is a voltage reference with electrical potential
higher than system ground). The maximum input voltage is also called VFS
(Voltage input Full-Scale), with VFS being determined by VREF. The voltage
reference may be provided from an external supply or derived from the chip power
source.

A single-ended unipolar channel could be described in device tree like the
following example::

    adc@0 {
        ...
        #address-cells = <1>;
        #size-cells = <0>;

        channel@0 {
            reg = <0>;
        };
    };

One is always allowed to include ADC channel nodes in the device tree. Though,
if the device has a uniform set of inputs (e.g. all inputs are single-ended),
then declaring the channel nodes is optional.

One caveat for devices that support mixed single-ended and differential channels
is that single-ended channel nodes also need to provide a ``single-channel``
property when ``reg`` is an arbitrary number that doesn't match the input pin
number.

See ``Documentation/devicetree/bindings/iio/adc/adc.yaml`` for the complete
documentation of ADC specific device tree properties.

Single-ended bipolar 채널

Single-ended bipolar 채널의 아날로그 입력 전압은 -VREF부터 +VREF까지 갈 수 있습니다. -VREF는 더 낮은 전위의 기준 전압이고 +VREF는 더 높은 전위의 기준 전압입니다.

일부 ADC 칩은 +VREF에서 낮은 기준 전압을 유도하고, 다른 칩은 별도 입력으로 받습니다. +VREF와 -VREF는 흔히 대칭이지만 반드시 그래야 하는 것은 아닙니다.

-VREF가 system ground보다 낮으면 이 입력을 single-ended true bipolar라고도 합니다. 전기적으로 bipolar와 true bipolar에는 중요한 차이가 있지만 IIO는 둘을 명시적으로 구분하지 않습니다.

Single-ended bipolar 채널의 Device Tree 예제는 `bipolar` 속성을 추가합니다.

adc@0 {
    ...
    #address-cells = <1>;
    #size-cells = <0>;

    channel@0 {
        reg = <0>;
        bipolar;
    };
};

1.1.2 Single-ended Bipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

  ---------- +VREF ------------
      ´ `           ´ `                  _____________________
    /     \       /     \               /                     |
   /       \     /       \         --- <  IN          ADC     |
            \   /         \   /         \                     |
             `-´           `-´           \       +VREF  -VREF |
  ---------- -VREF ------------           +-------------------+
                                                  ^       ^
                                                  |       |
                             External +VREF ------+  External -VREF

For a **single-ended bipolar** channel, the analog voltage input can go from
-VREF to +VREF (where -VREF is the voltage reference that has the lower
electrical potential while +VREF is the reference with the higher one). Some ADC
chips derive the lower reference from +VREF, others get it from a separate
input. Often, +VREF and -VREF are symmetric but they don't need to be so. When
-VREF is lower than system ground, these inputs are also called single-ended
true bipolar. Also, while there is a relevant difference between bipolar and
true bipolar from the electrical perspective, IIO makes no explicit distinction
between them.

Here's an example device tree description of a single-ended bipolar channel::

    adc@0 {
        ...
        #address-cells = <1>;
        #size-cells = <0>;

        channel@0 {
            reg = <0>;
            bipolar;
        };
    };

Differential bipolar 채널

Differential 전압 측정은 -VREF부터 +VREF까지의 범위에서 음의 입력 IN-를 기준으로 양의 입력 IN+의 전압 수준을 디지털화합니다. 즉 IN+와 IN- 사이의 전위차를 측정하며 보통 `IN+ - IN-` 공식으로 나타냅니다.

Differential bipolar 입력의 아날로그 신호도 -VREF부터 +VREF까지 변화할 수 있습니다. 이름의 bipolar는 차이값 `IN+ - IN-`이 양수 또는 음수가 될 수 있음을 뜻합니다. -VREF가 system GND 아래이면 differential true bipolar 입력이라고도 합니다.

Differential bipolar 채널의 Device Tree 예제는 `bipolar`와 `diff-channels = <0 1>`을 함께 지정합니다.

adc@0 {
    ...
    #address-cells = <1>;
    #size-cells = <0>;

    channel@0 {
        reg = <0>;
        bipolar;
        diff-channels = <0 1>;
    };
};

ADC 드라이버는 이 채널의 `struct iio_chan_spec`에 `differential = 1`을 설정합니다. 일반 입력 유형은 세 가지이지만 `differential` 필드는 differential과 non-differential을 구분하는 데만 쓰입니다. Non-differential에는 single-ended와 pseudo-differential이 모두 포함됩니다.

자세한 내용은 `include/linux/iio/iio.h`를 참고합니다.

1.2 Differential channels
-------------------------

A differential voltage measurement digitizes the voltage level at the positive
input (IN+) relative to the negative input (IN-) over the -VREF to +VREF span.
In other words, a differential channel measures the potential difference between
IN+ and IN-, which is often denoted by the IN+ - IN- formula.

1.2.1 Differential Bipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

  -------- +VREF ------         +-------------------+
    ´ `       ´ `              /                    |
  /     \   /     \   /   --- <  IN+                |
         `-´       `-´         |                    |
  -------- -VREF ------        |                    |
                               |            ADC     |
  -------- +VREF ------        |                    |
        ´ `       ´ `          |                    |
  \   /     \   /     \   --- <  IN-                |
   `-´       `-´               \       +VREF  -VREF |
  -------- -VREF ------         +-------------------+
                                         ^       ^
                                         |       +---- External -VREF
                                  External +VREF

The analog signals to **differential bipolar** inputs are also allowed to swing
from -VREF to +VREF. The bipolar part of the name means that the resulting value
of the difference (IN+ - IN-) can be positive or negative. If -VREF is below
system GND, these are also called differential true bipolar inputs.

Device tree example of a differential bipolar channel::

    adc@0 {
        ...
        #address-cells = <1>;
        #size-cells = <0>;

        channel@0 {
            reg = <0>;
            bipolar;
            diff-channels = <0 1>;
        };
    };

In the ADC driver, ``differential = 1`` is set into ``struct iio_chan_spec`` for
the channel. Even though, there are three general input types, ``differential``
is only used to distinguish between differential and non-differential (either
single-ended or pseudo-differential) input types. See
``include/linux/iio/iio.h`` for more information.

Differential unipolar 채널

Differential unipolar 채널에서는 양의 입력 전압이 음의 입력 전압보다 높아야 합니다. 따라서 실제 허용 입력 범위는 IN-부터 +VREF까지입니다.

IN+는 측정하는 아날로그 신호에 따라 변화할 수 있지만 IN+가 IN- 아래로 내려가거나 IN-가 IN+ 위로 올라가지 않도록 입력 구성이 보장해야 합니다.

이 때문에 대부분의 differential unipolar 구성은 IN-를 측정 신호의 예상 전압 범위에 들어가지 않는 알려진 전압에 고정합니다. 이런 구성은 pseudo-differential 채널과 동등해집니다.

1.2.2 Differential Unipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For **differential unipolar** channels, the analog voltage at the positive input
must also be higher than the voltage at the negative input. Thus, the actual
input range allowed to a differential unipolar channel is IN- to +VREF. Because
IN+ is allowed to swing with the measured analog signal and the input setup must
guarantee IN+ will not go below IN- (nor IN- will raise above IN+), most
differential unipolar channel setups have IN- fixed to a known voltage that does
not fall within the voltage range expected for the measured signal. That leads
to a setup that is equivalent to a pseudo-differential channel. Thus,
differential unipolar setups can often be supported as pseudo-differential
unipolar channels.

Pseudo-differential 입력 개요

세 번째 ADC 입력 유형은 pseudo-differential 또는 single-ended-to-differential 구성이라고 부릅니다.

Pseudo-differential 채널은 IN-를 기준으로 IN+를 측정한다는 점에서 differential 채널과 비슷합니다. 그러나 bipolar differential과 달리 음의 입력은 상수로 취급하는 좁은 전압 범위로 제한되고 IN+만 변화할 수 있습니다.

Differential 입력 쌍에서 음의 입력을 알려진 전압으로 제한하고 양의 입력만 변화시키면 pseudo-differential 채널을 만들 수 있습니다. IN-에 제공하는 입력을 common-mode voltage라고 부르기도 합니다.

일부 부품에는 single-ended 입력이 공통 모드 전압을 기준으로 동작하게 하는 COM pin이 있어 이를 pseudo-differential 채널로 만듭니다.

Common-mode 입력 전압은 본질적으로 일정한 전압원이므로 Device Tree에서 `com-supply` 같은 voltage regulator로 기술할 수 있습니다.

1.3 Pseudo-differential Channels
--------------------------------

There is a third ADC input type which is called pseudo-differential or
single-ended to differential configuration. A pseudo-differential channel is
similar to a differential channel in that it also measures IN+ relative to IN-.
However, unlike bipolar differential channels, the negative input is limited to
a narrow voltage range (taken as a constant voltage) while only IN+ is allowed
to swing. A pseudo-differential channel can be made out from a differential pair
of inputs by restricting the negative input to a known voltage while allowing
only the positive input to swing. Sometimes, the input provided to IN- is called
common-mode voltage. Besides, some parts have a COM pin that allows single-ended
inputs to be referenced to a common-mode voltage, making them
pseudo-differential channels. Often, the common mode input voltage can be
described in the device tree as a voltage regulator (e.g. ``com-supply``) since
it is basically a constant voltage source.

Pseudo-differential unipolar 채널

Pseudo-differential unipolar 입력은 differential unipolar 채널과 같은 제한을 갖습니다. 양의 입력 IN+의 아날로그 전압은 IN-부터 +VREF 사이에 있어야 합니다.

IN-의 고정 전압은 보통 common-mode voltage라고 하며, differential 채널의 음의 입력 신호에 기대되는 것처럼 -VREF부터 +VREF 사이에 있어야 합니다.

IN+에서 측정한 전압은 IN- 기준이지만, differential 채널과 달리 pseudo-differential 구성은 single-ended 입력 신호를 측정하려는 목적입니다.

응용 프로그램이 system ground 기준의 IN+ 전압을 계산할 수 있도록 IIO 채널은 ADC 출력을 전압 단위로 변환할 때 더할 `_offset` sysfs 속성을 제공할 수 있습니다.

많은 구성에서 common-mode 입력 전압은 GND 수준이고 `_offset`은 항상 0이므로 이 속성을 생략합니다.

Pseudo-differential unipolar 채널의 Device Tree 예제는 `single-channel`과 `common-mode-channel`을 지정합니다.

adc@0 {
    ...
    #address-cells = <1>;
    #size-cells = <0>;

    channel@0 {
        reg = <0>;
        single-channel = <0>;
        common-mode-channel = <1>;
    };
};

Pseudo-differential 채널의 `iio_chan_spec` 구조체에는 `differential`을 설정하지 않습니다.

1.3.1 Pseudo-differential Unipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

  -------- +VREF ------          +-------------------+
    ´ `       ´ `               /                    |
  /     \   /     \   /    --- <  IN+                |
         `-´       `-´          |                    |
  --------- IN- -------         |            ADC     |
                                |                    |
  Common-mode voltage -->  --- <  IN-                |
                                \       +VREF  -VREF |
                                 +-------------------+
                                         ^       ^
                                         |       +---- External -VREF
                                  External +VREF

A **pseudo-differential unipolar** input has the limitations a differential
unipolar channel would have, meaning the analog voltage to the positive input
IN+ must stay within IN- to +VREF. The fixed voltage to IN- is often called
common-mode voltage and it must be within -VREF to +VREF as would be expected
from the signal to any differential channel negative input.

The voltage measured from IN+ is relative to IN- but, unlike differential
channels, pseudo-differential setups are intended to gauge single-ended input
signals. To enable applications to calculate IN+ voltage with respect to system
ground, the IIO channel may provide an ``_offset`` sysfs attribute to be added
to ADC output when converting raw data to voltage units. In many setups, the
common-mode voltage input is at GND level and the ``_offset`` attribute is
omitted due to being always zero.

Device tree example for pseudo-differential unipolar channel::

    adc@0 {
        ...
        #address-cells = <1>;
        #size-cells = <0>;

        channel@0 {
            reg = <0>;
            single-channel = <0>;
            common-mode-channel = <1>;
        };
    };

Do not set ``differential`` in the channel ``iio_chan_spec`` struct of
pseudo-differential channels.

Pseudo-differential bipolar 채널

Pseudo-differential bipolar 입력은 IN- 수준에 의해 제한되지 않지만, 입력 범위의 하한은 특정 ADC에 따라 -VREF 또는 GND로 제한됩니다.

Unipolar 구성과 마찬가지로 pseudo-differential bipolar 채널도 원시 ADC 데이터를 전압 단위로 변환할 수 있도록 `_offset` 속성을 선언해야 합니다. IN-가 GND에 연결된 구성에서는 `_offset`을 흔히 생략합니다.

Pseudo-differential bipolar 채널의 Device Tree 예제는 `bipolar`, `single-channel`, `common-mode-channel`을 함께 지정합니다.

adc@0 {
    ...
    #address-cells = <1>;
    #size-cells = <0>;

    channel@0 {
        reg = <0>;
        bipolar;
        single-channel = <0>;
        common-mode-channel = <1>;
    };
};

1.3.2 Pseudo-differential Bipolar Channels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

  -------- +VREF ------          +-------------------+
    ´ `       ´ `               /                    |
  /     \   /     \   /    --- <  IN+                |
         `-´       `-´          |                    |
  -------- -VREF ------         |            ADC     |
                                |                    |
  Common-mode voltage -->  --- <  IN-                |
                                \       +VREF  -VREF |
                                 +-------------------+
                                          ^       ^
                                          |       +---- External -VREF
                                   External +VREF

A **pseudo-differential bipolar** input is not limited by the level at IN- but
it will be limited to -VREF or to GND on the lower end of the input range
depending on the particular ADC. Similar to their unipolar counter parts,
pseudo-differential bipolar channels ought to declare an ``_offset`` attribute
to enable the conversion of raw ADC data to voltage units. For the setup with
IN- connected to GND, ``_offset`` is often omitted.

Device tree example for pseudo-differential bipolar channel::

    adc@0 {
        ...
        #address-cells = <1>;
        #size-cells = <0>;

        channel@0 {
            reg = <0>;
            bipolar;
            single-channel = <0>;
            common-mode-channel = <1>;
        };
    };