On Wed, 18 Dec 2024 14:46:14 -0600 David Lechner <dlechner@xxxxxxxxxxxx> wrote: > On 12/18/24 8:38 AM, Marcelo Schmitt wrote: > > 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@xxxxxxxxx/ > > [2]: https://www.analog.com/en/resources/technical-articles/sar-adc-input-types.html. > > > > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx> > > --- > > This is really nice to have! Agreed. I end up looking this up from time to time, so a local set of definitions makes complete sense to have. Thanks for doing this! A few really minor additions to David's comments inline. Thanks Jonathan > > > Documentation/iio/iio_adc.rst | 280 ++++++++++++++++++++++++++++++++++ > > Documentation/iio/index.rst | 1 + > > 2 files changed, 281 insertions(+) > > create mode 100644 Documentation/iio/iio_adc.rst > > > > diff --git a/Documentation/iio/iio_adc.rst b/Documentation/iio/iio_adc.rst > > new file mode 100644 > > index 000000000000..43b8cad547c9 > > --- /dev/null > > +++ b/Documentation/iio/iio_adc.rst > > @@ -0,0 +1,280 @@ > > +.. 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 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.). Add some 'weasel' words in here. There are more complex non linear ADCs and ones only capable of reaching some fraction of the reference voltage. Maybe throw in a "generally" somewhere. > > + > > +There are three types of ADC inputs (single-ended, differential, > ^ > | general > > > +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.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 > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > > To be consistent with the other sections, move unipolar before bipolar. I'm not sure I agree on this. It's the 'weird one', so some logic in introducing it after bipolar differential. > > diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst > > index 074dbbf7ba0a..15f62d304eaa 100644 > > --- a/Documentation/iio/index.rst > > +++ b/Documentation/iio/index.rst > > @@ -7,6 +7,7 @@ Industrial I/O > > .. toctree:: > > :maxdepth: 1 > > > > + iio_adc > > Maybe make this iio_adc_inputs in case we make a general adc page in the future. Can rename if we do. > > > iio_configfs > > iio_devbuf > > iio_dmabuf_api > >
