[v3,1/1] Documentation: iio: Add ADC documentation

Message ID	c21b89367510c3d56d8d17adc24b46c7c63a14b2.1738759798.git.marcelo.schmitt@analog.com (mailing list archive)
State	New
Headers	show Received: from mx0a-00128a01.pphosted.com (mx0a-00128a01.pphosted.com [148.163.135.77]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 408D0C8C7; Wed, 5 Feb 2025 12:53:58 +0000 (UTC) From: Marcelo Schmitt <marcelo.schmitt@analog.com> To: <linux-iio@vger.kernel.org>, <linux-doc@vger.kernel.org>, <linux-kernel@vger.kernel.org> CC: <jic23@kernel.org>, <lars@metafoo.de>, <corbet@lwn.net>, <dlechner@baylibre.com>, <marcelo.schmitt1@gmail.com> Subject: [PATCH v3 1/1] Documentation: iio: Add ADC documentation Date: Wed, 5 Feb 2025 09:53:13 -0300 Message-ID: <c21b89367510c3d56d8d17adc24b46c7c63a14b2.1738759798.git.marcelo.schmitt@analog.com> Precedence: bulk MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 8bit
Series	[v3,1/1] Documentation: iio: Add ADC documentation \| expand [v3,1/1] Documentation: iio: Add ADC documentation

diff --git a/Documentation/iio/iio_adc.rst b/Documentation/iio/iio_adc.rst new file mode 100644 index 000000000000..08447cd5e62f --- /dev/null +++ b/Documentation/iio/iio_adc.rst @@ -0,0 +1,299 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +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 (should be?) 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.). + +Elaborated 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. + +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. 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. 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 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>; + }; + }; diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 5710f5b9e958..48b88044d7cb 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -7,6 +7,7 @@ Industrial I/O .. toctree:: :maxdepth: 1 + iio_adc iio_configfs iio_devbuf iio_dmabuf_api

[v3,1/1] Documentation: iio: Add ADC documentation

Commit Message

Patch