Re: [RFC PATCH 4/4] Documentation: iio: Add ADC documentation

[Jonathan Cameron <jic23@kernel.org>]

On Wed, 18 Dec 2024 14:46:14 -0600
David Lechner <dlechner@baylibre.com> 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@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>
> > ---  
> 
> 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  
> 
>