1.. SPDX-License-Identifier: GPL-2.0-only 2 3========================= 4IIO Abstractions for ADCs 5========================= 6 71. Overview 8=========== 9 10The IIO subsystem supports many Analog to Digital Converters (ADCs). Some ADCs 11have features and characteristics that are supported in specific ways by IIO 12device drivers. This documentation describes common ADC features and explains 13how they are supported by the IIO subsystem. 14 151. ADC Channel Types 16==================== 17 18ADCs can have distinct types of inputs, each of them measuring analog voltages 19in a slightly different way. An ADC digitizes the analog input voltage over a 20span that is often given by the provided voltage reference, the input type, and 21the input polarity. The input range allowed to an ADC channel is needed to 22determine the scale factor and offset needed to obtain the measured value in 23real-world units (millivolts for voltage measurement, milliamps for current 24measurement, etc.). 25 26Elaborate designs may have nonlinear characteristics or integrated components 27(such as amplifiers and reference buffers) that might also have to be considered 28to derive the allowed input range for an ADC. For clarity, the sections below 29assume the input range only depends on the provided voltage references, input 30type, and input polarity. 31 32There are three general types of ADC inputs (single-ended, differential, 33pseudo-differential) and two possible polarities (unipolar, bipolar). The input 34type (single-ended, differential, pseudo-differential) is one channel 35characteristic, and is completely independent of the polarity (unipolar, 36bipolar) aspect. A comprehensive article about ADC input types (on which this 37doc is heavily based on) can be found at 38https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html. 39 401.1 Single-ended channels 41------------------------- 42 43Single-ended channels digitize the analog input voltage relative to ground and 44can be either unipolar or bipolar. 45 461.1.1 Single-ended Unipolar Channels 47^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 48 49:: 50 51 ---------- VREF ------------- 52 ´ ` ´ ` _____________ 53 / \ / \ / | 54 / \ / \ --- < IN ADC | 55 \ / \ / \ | 56 `-´ `-´ \ VREF | 57 -------- GND (0V) ----------- +-----------+ 58 ^ 59 | 60 External VREF 61 62The input voltage to a **single-ended unipolar** channel is allowed to swing 63from GND to VREF (where VREF is a voltage reference with electrical potential 64higher than system ground). The maximum input voltage is also called VFS 65(Voltage input Full-Scale), with VFS being determined by VREF. The voltage 66reference may be provided from an external supply or derived from the chip power 67source. 68 69A single-ended unipolar channel could be described in device tree like the 70following example:: 71 72 adc@0 { 73 ... 74 #address-cells = <1>; 75 #size-cells = <0>; 76 77 channel@0 { 78 reg = <0>; 79 }; 80 }; 81 82One is always allowed to include ADC channel nodes in the device tree. Though, 83if the device has a uniform set of inputs (e.g. all inputs are single-ended), 84then declaring the channel nodes is optional. 85 86One caveat for devices that support mixed single-ended and differential channels 87is that single-ended channel nodes also need to provide a ``single-channel`` 88property when ``reg`` is an arbitrary number that doesn't match the input pin 89number. 90 91See ``Documentation/devicetree/bindings/iio/adc/adc.yaml`` for the complete 92documentation of ADC specific device tree properties. 93 94 951.1.2 Single-ended Bipolar Channels 96^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 97 98:: 99 100 ---------- +VREF ------------ 101 ´ ` ´ ` _____________________ 102 / \ / \ / | 103 / \ / \ --- < IN ADC | 104 \ / \ / \ | 105 `-´ `-´ \ +VREF -VREF | 106 ---------- -VREF ------------ +-------------------+ 107 ^ ^ 108 | | 109 External +VREF ------+ External -VREF 110 111For a **single-ended bipolar** channel, the analog voltage input can go from 112-VREF to +VREF (where -VREF is the voltage reference that has the lower 113electrical potential while +VREF is the reference with the higher one). Some ADC 114chips derive the lower reference from +VREF, others get it from a separate 115input. Often, +VREF and -VREF are symmetric but they don't need to be so. When 116-VREF is lower than system ground, these inputs are also called single-ended 117true bipolar. Also, while there is a relevant difference between bipolar and 118true bipolar from the electrical perspective, IIO makes no explicit distinction 119between them. 120 121Here's an example device tree description of a single-ended bipolar channel:: 122 123 adc@0 { 124 ... 125 #address-cells = <1>; 126 #size-cells = <0>; 127 128 channel@0 { 129 reg = <0>; 130 bipolar; 131 }; 132 }; 133 1341.2 Differential channels 135------------------------- 136 137A differential voltage measurement digitizes the voltage level at the positive 138input (IN+) relative to the negative input (IN-) over the -VREF to +VREF span. 139In other words, a differential channel measures the potential difference between 140IN+ and IN-, which is often denoted by the IN+ - IN- formula. 141 1421.2.1 Differential Bipolar Channels 143^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 144 145:: 146 147 -------- +VREF ------ +-------------------+ 148 ´ ` ´ ` / | 149 / \ / \ / --- < IN+ | 150 `-´ `-´ | | 151 -------- -VREF ------ | | 152 | ADC | 153 -------- +VREF ------ | | 154 ´ ` ´ ` | | 155 \ / \ / \ --- < IN- | 156 `-´ `-´ \ +VREF -VREF | 157 -------- -VREF ------ +-------------------+ 158 ^ ^ 159 | +---- External -VREF 160 External +VREF 161 162The analog signals to **differential bipolar** inputs are also allowed to swing 163from -VREF to +VREF. The bipolar part of the name means that the resulting value 164of the difference (IN+ - IN-) can be positive or negative. If -VREF is below 165system GND, these are also called differential true bipolar inputs. 166 167Device tree example of a differential bipolar channel:: 168 169 adc@0 { 170 ... 171 #address-cells = <1>; 172 #size-cells = <0>; 173 174 channel@0 { 175 reg = <0>; 176 bipolar; 177 diff-channels = <0 1>; 178 }; 179 }; 180 181In the ADC driver, ``differential = 1`` is set into ``struct iio_chan_spec`` for 182the channel. Even though, there are three general input types, ``differential`` 183is only used to distinguish between differential and non-differential (either 184single-ended or pseudo-differential) input types. See 185``include/linux/iio/iio.h`` for more information. 186 1871.2.2 Differential Unipolar Channels 188^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 189 190For **differential unipolar** channels, the analog voltage at the positive input 191must also be higher than the voltage at the negative input. Thus, the actual 192input range allowed to a differential unipolar channel is IN- to +VREF. Because 193IN+ is allowed to swing with the measured analog signal and the input setup must 194guarantee IN+ will not go below IN- (nor IN- will raise above IN+), most 195differential unipolar channel setups have IN- fixed to a known voltage that does 196not fall within the voltage range expected for the measured signal. That leads 197to a setup that is equivalent to a pseudo-differential channel. Thus, 198differential unipolar setups can often be supported as pseudo-differential 199unipolar channels. 200 2011.3 Pseudo-differential Channels 202-------------------------------- 203 204There is a third ADC input type which is called pseudo-differential or 205single-ended to differential configuration. A pseudo-differential channel is 206similar to a differential channel in that it also measures IN+ relative to IN-. 207However, unlike bipolar differential channels, the negative input is limited to 208a narrow voltage range (taken as a constant voltage) while only IN+ is allowed 209to swing. A pseudo-differential channel can be made out from a differential pair 210of inputs by restricting the negative input to a known voltage while allowing 211only the positive input to swing. Sometimes, the input provided to IN- is called 212common-mode voltage. Besides, some parts have a COM pin that allows single-ended 213inputs to be referenced to a common-mode voltage, making them 214pseudo-differential channels. Often, the common mode input voltage can be 215described in the device tree as a voltage regulator (e.g. ``com-supply``) since 216it is basically a constant voltage source. 217 2181.3.1 Pseudo-differential Unipolar Channels 219^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 220 221:: 222 223 -------- +VREF ------ +-------------------+ 224 ´ ` ´ ` / | 225 / \ / \ / --- < IN+ | 226 `-´ `-´ | | 227 --------- IN- ------- | ADC | 228 | | 229 Common-mode voltage --> --- < IN- | 230 \ +VREF -VREF | 231 +-------------------+ 232 ^ ^ 233 | +---- External -VREF 234 External +VREF 235 236A **pseudo-differential unipolar** input has the limitations a differential 237unipolar channel would have, meaning the analog voltage to the positive input 238IN+ must stay within IN- to +VREF. The fixed voltage to IN- is often called 239common-mode voltage and it must be within -VREF to +VREF as would be expected 240from the signal to any differential channel negative input. 241 242The voltage measured from IN+ is relative to IN- but, unlike differential 243channels, pseudo-differential setups are intended to gauge single-ended input 244signals. To enable applications to calculate IN+ voltage with respect to system 245ground, the IIO channel may provide an ``_offset`` sysfs attribute to be added 246to ADC output when converting raw data to voltage units. In many setups, the 247common-mode voltage input is at GND level and the ``_offset`` attribute is 248omitted due to being always zero. 249 250Device tree example for pseudo-differential unipolar channel:: 251 252 adc@0 { 253 ... 254 #address-cells = <1>; 255 #size-cells = <0>; 256 257 channel@0 { 258 reg = <0>; 259 single-channel = <0>; 260 common-mode-channel = <1>; 261 }; 262 }; 263 264Do not set ``differential`` in the channel ``iio_chan_spec`` struct of 265pseudo-differential channels. 266 2671.3.2 Pseudo-differential Bipolar Channels 268^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 269 270:: 271 272 -------- +VREF ------ +-------------------+ 273 ´ ` ´ ` / | 274 / \ / \ / --- < IN+ | 275 `-´ `-´ | | 276 -------- -VREF ------ | ADC | 277 | | 278 Common-mode voltage --> --- < IN- | 279 \ +VREF -VREF | 280 +-------------------+ 281 ^ ^ 282 | +---- External -VREF 283 External +VREF 284 285A **pseudo-differential bipolar** input is not limited by the level at IN- but 286it will be limited to -VREF or to GND on the lower end of the input range 287depending on the particular ADC. Similar to their unipolar counter parts, 288pseudo-differential bipolar channels ought to declare an ``_offset`` attribute 289to enable the conversion of raw ADC data to voltage units. For the setup with 290IN- connected to GND, ``_offset`` is often omitted. 291 292Device tree example for pseudo-differential bipolar channel:: 293 294 adc@0 { 295 ... 296 #address-cells = <1>; 297 #size-cells = <0>; 298 299 channel@0 { 300 reg = <0>; 301 bipolar; 302 single-channel = <0>; 303 common-mode-channel = <1>; 304 }; 305 }; 306