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

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 <[email protected]>
---
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:	[email protected]
 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
-- 
2.53.0