Skip to content

Commit 1373835

Browse files
machschmittmachschmitt
committed
Documentation: iio: Add ADC documentation
ADCs can have different input configurations such that developers can get confused when trying to model some of them into IIO channels. For example, some differential ADCs can have their channels configured as pseudo-differential channels. In that configuration, only one input connects to the signal of interest as opposed to using two inputs of a differential input configuration. Datasheets sometimes also refer to pseudo-differential inputs as single-ended inputs even though they have distinct physical configuration and measurement procedure. There has been some previous discussion in the mailing list about pseudo-differential and single-ended channels [1]. Documenting the many possible ADC channel configurations should provide two benefits: A) Consolidate the knowledge from [2] and from [1], and hopefully reduce the reviewing time of forthcoming ADC drivers. B) Help Linux developers figure out quicker how to better support differential ADCs, specially those that can have channels configured as pseudo-differential inputs. Add documentation about common ADC characteristics and IIO support for them. [1]: https://lore.kernel.org/linux-iio/0fef36f8-a7db-40cc-86bd-9449cb4ab46e@gmail.com/ [2]: https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html. Signed-off-by: Marcelo Schmitt <marcelo.schmitt@analog.com>
1 parent e64e901 commit 1373835

File tree

2 files changed

+281
-0
lines changed

2 files changed

+281
-0
lines changed

‎Documentation/iio/iio_adc.rst

+280
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
=========================
4+
IIO Abstractions for ADCs
5+
=========================
6+
7+
1. Overview
8+
===========
9+
10+
The IIO subsystem supports many Analog to Digital Converters (ADCs). Some ADCs
11+
have features and characteristics that are supported in specific ways by IIO
12+
device drivers. This documentation describes common ADC features and explains
13+
how they are (should be?) supported by the IIO subsystem.
14+
15+
1. ADC Channel Types
16+
====================
17+
18+
ADCs can have distinct types of inputs, each of them measuring analog voltages
19+
in a slightly different way. An ADC digitizes the analog input voltage over a
20+
span given by the provided voltage reference, the input type, and the input
21+
polarity. The input range allowed to an ADC channel is needed to determine the
22+
scale factor and offset needed to obtain the measured value in real-world
23+
units (millivolts for voltage measurement, milliamps for current measurement,
24+
etc.).
25+
26+
There are three types of ADC inputs (single-ended, differential,
27+
pseudo-differential) and two possible polarities (unipolar, bipolar). The input
28+
type (single-ended, differential, pseudo-differential) is one channel
29+
characteristic, and is completely independent of the polarity (unipolar,
30+
bipolar) aspect. A comprehensive article about ADC input types (on which this
31+
doc is heavily based on) can be found at
32+
https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html.
33+
34+
1.1 Single-ended channels
35+
-------------------------
36+
37+
Single-ended channels digitize the analog input voltage relative to ground and
38+
can be either unipolar or bipolar.
39+
40+
1.1.1 Single-ended Unipolar Channels
41+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
42+
43+
::
44+
45+
---------- VREF -------------
46+
´ ` ´ ` _____________
47+
/ \ / \ / |
48+
/ \ / \ --- < IN ADC |
49+
\ / \ / \ |
50+
`-´ `-´ \ VREF |
51+
-------- GND (0V) ----------- +-----------+
52+
^
53+
|
54+
External VREF
55+
56+
The input voltage to a **single-ended unipolar** channel is allowed to swing
57+
from GND to VREF (where VREF is a voltage reference with electrical potential
58+
higher than system ground). The maximum input voltage is also called VFS
59+
(full-scale input voltage), with VFS being determined by VREF. The voltage
60+
reference may be provided from an external supply or derived from the chip power
61+
source.
62+
63+
A single-ended unipolar channel could be described in device tree like the
64+
following example::
65+
66+
adc@0 {
67+
...
68+
#address-cells = <1>;
69+
#size-cells = <0>;
70+
71+
channel@0 {
72+
reg = <0>;
73+
};
74+
};
75+
76+
See ``Documentation/devicetree/bindings/iio/adc/adc.yaml`` for the complete
77+
documentation of ADC specific device tree properties.
78+
79+
80+
1.1.2 Single-ended Bipolar Channels
81+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
82+
83+
::
84+
85+
---------- +VREF ------------
86+
´ ` ´ ` _____________________
87+
/ \ / \ / |
88+
/ \ / \ --- < IN ADC |
89+
\ / \ / \ |
90+
`-´ `-´ \ +VREF -VREF |
91+
---------- -VREF ------------ +-------------------+
92+
^ ^
93+
| |
94+
External +VREF ------+ External -VREF
95+
96+
For a **single-ended bipolar** channel, the analog voltage input can go from
97+
-VREF to +VREF (where -VREF is the voltage reference that has the lower
98+
electrical potential while +VREF is the reference with the higher one). Some ADC
99+
chips derive the lower reference from +VREF, others get it from a separate
100+
input. Often, +VREF and -VREF are symmetric but they don't need to be so. When
101+
-VREF is lower than system ground, these inputs are also called single-ended
102+
true bipolar.
103+
104+
Here's an example device tree description of a single-ended bipolar channel.
105+
::
106+
107+
adc@0 {
108+
...
109+
#address-cells = <1>;
110+
#size-cells = <0>;
111+
112+
channel@0 {
113+
reg = <0>;
114+
bipolar;
115+
};
116+
};
117+
118+
1.2 Differential channels
119+
-------------------------
120+
121+
A differential voltage measurement digitizes the voltage level at the positive
122+
input (IN+) relative to the negative input (IN-) over the -VREF to +VREF span.
123+
In other words, a differential channel measures how many volts IN+ is away from
124+
IN- (IN+ - IN-).
125+
126+
1.2.1 Differential Bipolar Channels
127+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
128+
129+
::
130+
131+
-------- +VREF ------
132+
´ ` ´ ` +-------------------+
133+
/ \ / \ / / |
134+
`-´ `-´ --- < IN+ |
135+
-------- -VREF ------ | |
136+
| ADC |
137+
-------- +VREF ------ | |
138+
´ ` ´ ` --- < IN- |
139+
\ / \ / \ \ +VREF -VREF |
140+
`-´ `-´ +-------------------+
141+
-------- -VREF ------ ^ ^
142+
| +---- External -VREF
143+
External +VREF
144+
145+
The analog signals to **differential bipolar** inputs are also allowed to swing
146+
from -VREF to +VREF. If -VREF is below system GND, these are also called
147+
differential true bipolar inputs.
148+
149+
Device tree example of a differential bipolar channel::
150+
151+
adc@0 {
152+
...
153+
#address-cells = <1>;
154+
#size-cells = <0>;
155+
156+
channel@0 {
157+
reg = <0>;
158+
bipolar;
159+
diff-channels = <0 1>;
160+
};
161+
};
162+
163+
In the ADC driver, `differential = 1` is set into `struct iio_chan_spec` for the
164+
channel. See ``include/linux/iio/iio.h`` for more information.
165+
166+
1.2.2 Differential Unipolar Channels
167+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
168+
169+
For **differential unipolar** channels, the analog voltage at the positive input
170+
must also be higher than the voltage at the negative input. Thus, the actual
171+
input range allowed to a differential unipolar channel is IN- to +VREF. Because
172+
IN+ is allowed to swing with the measured analog signal and the input setup must
173+
guarantee IN+ will not go below IN- (nor IN- will raise above IN+), most
174+
differential unipolar channel setups have IN- fixed to a known voltage that does
175+
not fall within the voltage range expected for the measured signal. This leads
176+
to a setup that is equivalent to a pseudo-differential channel. Thus,
177+
differential unipolar channels are actually pseudo-differential unipolar
178+
channels.
179+
180+
1.3 Pseudo-differential Channels
181+
--------------------------------
182+
183+
There is a third ADC input type which is called pseudo-differential or
184+
single-ended to differential configuration. A pseudo-differential channel is
185+
similar to a differential channel in that it also measures IN+ relative to IN-.
186+
However, unlike differential channels, the negative input is limited to a narrow
187+
voltage range while only IN+ is allowed to swing. A pseudo-differential channel
188+
can be made out from a differential pair of inputs by restricting the negative
189+
input to a known voltage while allowing only the positive input to swing. Aside
190+
from that, some parts have a COM pin that allows single-ended inputs to be
191+
referenced to a common-mode voltage, making them pseudo-differential channels.
192+
193+
1.3.1 Pseudo-differential Unipolar Channels
194+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
195+
196+
::
197+
198+
-------- +VREF ------ +-------------------+
199+
´ ` ´ ` / |
200+
/ \ / \ / --- < IN+ |
201+
`-´ `-´ | |
202+
--------- IN- ------- | ADC |
203+
| |
204+
Common-mode voltage --> --- < IN- |
205+
\ +VREF -VREF |
206+
+-------------------+
207+
^ ^
208+
| +---- External -VREF
209+
External +VREF
210+
211+
A **pseudo-differential unipolar** input has the limitations a differential
212+
unipolar channel would have, meaning the analog voltage to the positive input
213+
IN+ must stay within IN- to +VREF. The fixed voltage to IN- is sometimes called
214+
common-mode voltage and it must be within -VREF to +VREF as would be expected
215+
from the signal to any differential channel negative input.
216+
217+
In pseudo-differential configuration, the voltage measured from IN+ is not
218+
relative to GND (as it would be for a single-ended channel) but to IN-, which
219+
causes the measurement to always be offset by IN- volts. To allow applications
220+
to calculate IN+ voltage with respect to system ground, the IIO channel may
221+
provide an `_offset` attribute to report the channel offset to user space.
222+
223+
Device tree example for pseudo-differential unipolar channel::
224+
225+
adc@0 {
226+
...
227+
#address-cells = <1>;
228+
#size-cells = <0>;
229+
230+
channel@0 {
231+
reg = <0>;
232+
single-channel = <0>;
233+
common-mode-channel = <1>;
234+
};
235+
};
236+
237+
Do not set `differential` in the channel `iio_chan_spec` struct of
238+
pseudo-differential channels.
239+
240+
1.3.2 Pseudo-differential Bipolar Channels
241+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
242+
243+
::
244+
245+
-------- +VREF ------ +-------------------+
246+
´ ` ´ ` / |
247+
/ \ / \ / --- < IN+ |
248+
`-´ `-´ | |
249+
-------- -VREF ------ | ADC |
250+
| |
251+
Common-mode voltage --> --- < IN- |
252+
\ +VREF -VREF |
253+
+-------------------+
254+
^ ^
255+
| +---- External -VREF
256+
External +VREF
257+
258+
A **pseudo-differential bipolar** input is not limited by the level at IN- but
259+
it will be limited to -VREF or to GND on the lower end of the input range
260+
depending on the particular ADC. Similar to their unipolar counter parts,
261+
pseudo-differential bipolar channels may define an `_offset` attribute to
262+
provide the read offset relative to GND.
263+
264+
Device tree example for pseudo-differential bipolar channel::
265+
266+
adc@0 {
267+
...
268+
#address-cells = <1>;
269+
#size-cells = <0>;
270+
271+
channel@0 {
272+
reg = <0>;
273+
bipolar;
274+
single-channel = <0>;
275+
common-mode-channel = <1>;
276+
};
277+
};
278+
279+
Again, the `differential` field of `struct iio_chan_spec` is not set for
280+
pseudo-differential channels.

‎Documentation/iio/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Industrial I/O
77
.. toctree::
88
:maxdepth: 1
99

10+
iio_adc
1011
iio_configfs
1112
iio_devbuf
1213
iio_tools

0 commit comments

Comments
 (0)