Message-ID: <Z7ZDzg0KHZhfiLo3@debian-BULLSEYE-live-builder-AMD64>
Date: Wed, 19 Feb 2025 17:49:18 -0300
From: Marcelo Schmitt <marcelo.schmitt1@...il.com>
To: David Lechner <dlechner@...libre.com>
Cc: Marcelo Schmitt <marcelo.schmitt@...log.com>, linux-iio@...r.kernel.org,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	jic23@...nel.org, lars@...afoo.de, corbet@....net
Subject: Re: [PATCH v3 1/1] Documentation: iio: Add ADC documentation

A very slow re-spin time from my side but here we go ...
I addressed most of the suggestions and am about to send a v4.
Replying inline to the points I disagree with.

Thanks,
Marcelo

On 02/05, David Lechner wrote:
> On 2/5/25 6:53 AM, Marcelo Schmitt wrote:
> > ADC inputs can be classified into a few different types according to how
> > they measure the input signal, how restrained the signal is, and number of
> > input pins. Even though datasheets tend to provide many details about their
> > inputs and measurement procedures, it may not always be clear how to model
> > those inputs into IIO channels.
> > 
> > For example, some differential ADCs can have their inputs configured into
> > 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.
> > 
> > Document consolidated ADC input types and how they are usually described
> > and supported in device tree and IIO, respectively.
> > 
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@...log.com>
> > ---
...
> > +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.
> 
> It could be worth reiterating here that although there are 3 different input
> types, in IIO, differential is only a bool, so there is no special distinction
> between single-ended and pseduo-differential (other than possibly having a
> common mode voltage input). And unipolar/bipolar is only considered on the
> difference between the two inputs and not the individual input, so in IIO there
> is no special distinction between bipolar and true biploar - they are modeled
> the same.
For v4, I'll be mentioning the differential field meaning and the bipolar / true
bipolar (in)disctinction in other subsections bellow. Hope that will make those
points more clear.

...
> > +1.2 Differential channels
> > +-------------------------
> > +
> 
> Suggest to insert here:
> 
> > +A differential voltage measurement,
> 
> sometimes also called "fully differential" or "true differential",

I think adding that would make the sentence harder to read and somewhat incorrect.
The differential measurement has to do with how the ADC takes the input signals
into account to generate an output code. The "true differential" has to do with
the expected limits for the input signals. Fully differential input is yet
another thing that I've been avoiding to describe because I think those can be
supported as differential bipolar channels.

> 
> > 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.2 Differential Unipolar Channels
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +For **differential unipolar** channels, 
> 
> I think it would be nice to have a short first paragraph that just says that
> this configuration is quite unusual and that the difference would have to always
> be positive. Then follow with the rest of the info for the curious in a separate
> paragraph. Then it will be easy for those not interested in the unusual case to
> skip over that part.

I think, reordering would make the explanation harder to follow.
Even though currently not using those exact words, it can be inferred that the
difference is expected to be always positive:
"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+)"
The last phrase also somewhat hints that the differential unipolar setup is not usual.
"Thus, differential unipolar setups can often be supported as pseudo-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.
> 
> I think we should just leave out the sentence about being supported as pseudo-
> differential. There is already a different section that describes that and it
> would be simpler to just stick with describing the fully differential case here.
> The differential bipolar section also only describes the fully differential case
> so mentioning pseduo-differential here seems inconsistent.

I also disagree with that one. A differential unipolar setup is uncommon
(at least) so the mention of pseduo-differential is to point to what would be
the usual way of supporting those input configurations. Differential bipolar
inputs are common so no need to mention other input types when talking about
differential bipolar.

Though, I'm fine with changing the explanations if Jonathan prefers so.

Powered by blists - more mailing lists