Hi Jonathan,
Thanks for having another look at this.
I'll do the changes suggested.
Thanks,
Marcelo
On 01/18, Jonathan Cameron wrote:
> On Wed, 15 Jan 2025 11:23:24 -0600
> David Lechner <dlechner@xxxxxxxxxxxx> wrote:
>
...
> > > +1.1 Single-ended channels
> > > +-------------------------
> > > +
> > > +Single-ended channels digitize the analog input voltage relative to ground and
> > > +can be either unipolar or bipolar.
> > > +
> > > +1.1.1 Single-ended Unipolar Channels
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +::
> > > +
> > > + ---------- VREF -------------
> > > + ´ ` ´ ` _____________
> > > + / \ / \ / |
> > > + / \ / \ --- < IN ADC |
> > > + \ / \ / \ |
> > > + `-´ `-´ \ VREF |
> > > + -------- GND (0V) ----------- +-----------+
> > > + ^
> > > + |
> > > + External VREF
> > > +
> > > +The input voltage to a **single-ended unipolar** channel is allowed to swing
> > > +from GND to VREF (where VREF is a voltage reference with electrical potential
> > > +higher than system ground). The maximum input voltage is also called VFS
> > > +(full-scale input voltage), with VFS being determined by VREF. The voltage
>
> Just to align with acronym perhaps
> Voltage input Full-Scale
>
Okay, will do.
> > > +reference may be provided from an external supply or derived from the chip power
> > > +source.
> > > +
> > > +A single-ended unipolar channel could be described in device tree like the
> > > +following example::
> >
> > We should probably mention somewhere that channel@ nodes are only needed for
> > chips that don't have uniform inputs.
>
> They are allowed in all cases. For SoCs ADCs it's not unusual to have them even
> if nothing exciting going on because they want to hide channels that aren't
> wired to anything. For stand along ADCs that is less common because people
> don't buy a device with lots of channels intending to only use a few.
>
> But sure, mention they may not be provided.
Sure, will mention that.
>
> >
> > > +
> > > + adc@0 {
> > > + ...
> > > + #address-cells = <1>;
> > > + #size-cells = <0>;
> > > +
> > > + channel@0 {
> > > + reg = <0>;
> >
> > If a chip has mixed differential and single-ended, single-channel could also
> > be needed here in the case where reg is an arbitrary number and doesn't match
> > the input pin number.
>
> Indeed - that is a weird corner that would be good to highlight.
Ack, will add a word about that too.
>
> >
> > > + };
> > > + };
> > > +
> > > +See ``Documentation/devicetree/bindings/iio/adc/adc.yaml`` for the complete
> > > +documentation of ADC specific device tree properties.
> > > +
> > > +
...
> > > +1.2.2 Differential Unipolar Channels
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +For **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. This leads
> > > +to a setup that is equivalent to a pseudo-differential channel. Thus,
> > > +differential unipolar channels are actually pseudo-differential unipolar
> > > +channels.
> >
> > I don't think this is equevent to pseudo-differential unipolar. That one has
> > a common mode voltage supply on the negative input. This one has a full range
> > signal on the negative input. This is the diagram I was expecting here.
> >
> > ::
> >
> > -------- VREF -------
> > ´ ` ´ ` +-------------------+
> > / \ / \ / / |
> > `-´ `-´ --- < IN+ |
> > ------ GND (0V) ----- | |
> > | ADC |
> > -------- VREF ------- | |
> > ´ ` ´ ` --- < IN- |
> > \ / \ / \ \ VREF |
> > `-´ `-´ +-------------------+
> > ------ GND (0V) ----- ^
> > |
> > External VREF
>
> If it's unipolar, output must be positive which isn't true here.
> Do we actually see differential unipolar except for the pseudo case with
> common mode voltage? Seems like a weird device.
I don't think we have differential unipolar with IN- allowed to float (i.e. not
set to a constant voltage). Haven't seen any of those. Can't think of how we
would support such thing either. See my reply to David for more thoughts on this.
>
> >
> > > +
> > > +1.3 Pseudo-differential Channels
> > > +--------------------------------
> > > +
> > > +There is a third ADC input type which is called pseudo-differential or
> > > +single-ended to differential configuration. A pseudo-differential channel is
> > > +similar to a differential channel in that it also measures IN+ relative to IN-.
> > > +However, unlike differential channels, the negative input is limited to a narrow
> > > +(taken as constant) voltage range while only IN+ is allowed to swing. A
> > > +pseudo-differential channel can be made out from a differential pair of inputs
> > > +by restricting the negative input to a known voltage while allowing only the
> > > +positive input to swing. Aside from that, some parts have a COM pin that allows
> > > +single-ended inputs to be referenced to a common-mode voltage, making them
> > > +pseudo-differential channels. Often, the common mode input voltage
> > > +can be nicely described in the device tree as a voltage regulator (e.g.
> > > +``com-supply``) since it is basically a constant voltage source.
> > > +
> > > +1.3.1 Pseudo-differential Unipolar Channels
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +::
> > > +
> > > + -------- +VREF ------ +-------------------+
> > > + ´ ` ´ ` / |
> > > + / \ / \ / --- < IN+ |
> > > + `-´ `-´ | |
> > > + --------- IN- ------- | ADC |
> >
> > The bottom rail should be GND (or -VREF), not IN-. Making it GND in the diagram
> > would be consistent with the other unipolar diagrams and reflect most typical
> > cases. I think the counterexample you gave of AD4170-4 is the unusual case
> > rather than the typical case.
> >
> > FWIW, when I was first learning this stuff, I didn't really understand bipolar
> > vs. unipolar until I saw diagrams that showed 0V as the bottom rail for unipolar
> > and negative VREF as the bottom rail for bipolar. Even if it isn't strictly
> > true in all cases, seeing the pattern was more helpful. Hard to say if most
> > other people think like me though. :-)
>
> Maybe IN- (typically GND) is appropriate?
Sounds good to me.
Can also add a typical case (with IN- at GND) example if desired.
> >
...
> > > +
> > > +1.3.2 Pseudo-differential Bipolar Channels
> > > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > +
> > > +::
> > > +
> > > + -------- +VREF ------ +-------------------+
> > > + ´ ` ´ ` / |
> > > + / \ / \ / --- < IN+ |
> > > + `-´ `-´ | |
> > > + -------- -VREF ------ | ADC |
> > > + | |
> > > + Common-mode voltage --> --- < IN- |
> > > + \ +VREF -VREF |
> > > + +-------------------+
> > > + ^ ^
> > > + | +---- External -VREF
> > > + External +VREF
> > > +
> > > +A **pseudo-differential bipolar** input is not limited by the level at IN- but
> > > +it will be limited to -VREF or to GND on the lower end of the input range
> >
> >
> > If it was limited to GND, then it would be uniploar. It is only bipolar if
> > -VREF is less than 0V.
>
> I'm not sure on that. See comment on your example above. That is
> what I think a Pseudo-differential bipolar channel is (and it matches the
> first thing google gave me).
>
> Key here is that common mode voltage on IN- is between -VREF and +VREF so
> we can swing past it and get both positive an negative.
Yes, exactly.
>
> >
...
> > > --- a/Documentation/iio/index.rst
> > > +++ b/Documentation/iio/index.rst
> > > @@ -7,6 +7,7 @@ Industrial I/O
> > > .. toctree::
> > > :maxdepth: 1
> > >
> > > + iio_adc
> > > iio_configfs
> > > iio_devbuf
> > > iio_dmabuf_api
> > >
> > > base-commit: 9b75dd1b7d6b98699a104c6b1eec0c8817e5fd4b
> >
>
