Re: [PATCH v9 6/6] iio: ABI: Encourage differential voltage ABI usage

[Marcelo Schmitt]

On 08/12, Jonathan Cameron wrote:
> On Mon, 27 Jul 2026 18:32:18 -0300
> Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx> wrote:
> 
> > So far, parts that could only do differential voltage measurements were
> > only required to have a consistent labeling of their channels by complying
> > either to voltageY or to voltageY-voltageZ ABI. Over time, code maintainers
> > came to the conclusion that the voltageY-voltageZ ABI is better suited for
> > differential-only chips as it provides a simple indication to users that
> > the channels measure the difference of two inputs.
> > 
> > Adjust the ABI documentation to recommend using the voltageY-voltageZ ABI
> > for chips that do only differential voltage measurements.
> > 
> > Signed-off-by: Marcelo Schmitt <marcelo.schmitt@xxxxxxxxxx>
> Hi Marcelo
> 
> Whilst looking at another series, I noticed we did something different
> again in the devicetree bindings for those devices that have
> restrictive muxes that means the positive and negative lines
> always change together.  For those we let
> 
> diff-channels = <1 1> 
> which tends to map to
> 
> in_voltageX-voltageX_raw

Hmm, that sounds awesome. Probably a much more accurate way of presenting the
channel(s) to user space. Wish I had realized that earlier.

> 
> I'm not sure if we want to explicitly call that out as an option.
> There is nothing in your new text saying we can't do that.

I'd say probably best to mention the voltageX-X case. These fully differential
inputs (that have the positive and negative lines changing together) are not uncommon.
Sure, let me write something more comprehensive.

It would also be best to use that notation for ltc2378. IIRC, it's okay to not
specify the ADC channels in dt if all channels have the same properties so no
need to update the dt-doc. For the IIO driver, we have the channel sysfs entries
changing name. Will send v10 in case there's still any chance to get it updated.
Also okay to wait for the next release cycle if possible.

> 
> Worth also noting there are short circuit parts where you
> really do connect both ends of the differential ADC to the
> same input pin. I think it can be useful for testing / calibration?
> 
> Jonathan
> 

Thanks,
Marcelo

> 
> > ---
> > No changes in v9.
> > 
> >  Documentation/ABI/testing/sysfs-bus-iio | 9 +++++----
> >  1 file changed, 5 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index 5cc2e82c4997..7446e07b9ab2 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -162,10 +162,11 @@ Contact:	linux-iio@xxxxxxxxxxxxxxx
> >  Description:
> >  		Raw (unscaled) differential voltage measurement equivalent to
> >  		channel Y - channel Z where these channel numbers apply to the
> > -		physically equivalent inputs when non differential readings are
> > -		separately available. In differential only parts, then all that
> > -		is required is a consistent labeling.  Units after application
> > -		of scale and offset are millivolts.
> > +		physically equivalent inputs when non-differential readings are
> > +		separately available. Even though differential-only parts had
> > +		been merely required to have consistent channel labeling, this
> > +		ABI is preferred over the non-differential one for those chips.
> > +		Units after application of scale and offset are millivolts.
> >  
> >  What:		/sys/bus/iio/devices/iio:deviceX/in_altvoltageY_rms_raw
> >  KernelVersion:	6.18
>