Re: [PATCH v10 2/2] iio: ABI: Encourage differential voltage ABI usage

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 13 Aug 2026 20:05:33 -0300
Marcelo Schmitt <marcelo.schmitt@analog.com> 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@analog.com>
Hi Marcelo,

I applied earlier version I think. Please send a diff on top.

Too much floating around at the moment so I'm sorry to say
I'm loosing track even with tools to help me!

Jonathan

> ---
> Change log v9 -> v10:
> - Mention the possibility of having same index for diff channels (e.g. voltageX-voltageX)
>   in ABI doc.
> 
> After looking at a few other chips I'm not sure either about having
> voltageX-voltageX in the docs. I worry voltageX-voltageX might not provide a
> clear unambiguous indication of channel properties. Nevertheless, mentioned that
> possibility as a special case.
> 
> For chips that have configurable inputs such that both differential and
> non-differential readings are separately available (current ABI usage),
> voltageX-voltageX can mean both ADC ends connected to the same physical input
> pins (e.g. AIN3 and AIN3, CH3 and CH3, V3 and V3 ...).  That seems to not make
> much sense for most parts. Though, there are corner cases where the same input
> number is used to configure both ADC ends (e.g. to access a temperature sensor
> through an embedded multiplexer).
> 
> For chips that can only do differential measurements, voltageX-voltageX would
> mean the positive and negative inputs of a differential channel to have the same
> index (e.g. IN3+ and IN3-, AI3P and AI3N, AIN3+ and AIN3-, etc). The ABI is the
> same, but the meaning would be different. Even though we have the left-most
> index for the positive end and right-most for the negative end, that's not
> enough to fully tell how a channel works.
> 
> 
>  Documentation/ABI/testing/sysfs-bus-iio | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 5cc2e82c4997..bb17105650ab 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -162,10 +162,12 @@ Contact:	linux-iio@vger.kernel.org
>  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.
> +		Special configurations may have the same index for both Y and Z.
> +		Units after application of scale and offset are millivolts.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_altvoltageY_rms_raw
>  KernelVersion:	6.18