| .. 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. |
| |
| 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. |
| |
| |
| 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; |
| }; |
| }; |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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>; |
| }; |
| }; |
