Skip to contentSkip to conversation

IIO ABI documentation duplication fixes

RFC PATCH Applied Jonathan Cameron 6 participants 22 messages Jan 17, 2021 – Apr 27, 2021

Subsystems (5)
lore
Share & tools
lore

Jonathan Cameron

author maintainer
#0 lore raw

cover IIO ABI documentation duplication fixes

From: Jonathan Cameron <[email protected]>

The nature of IIO devices is that they are highly varied and occaisonly ABI is used in somewhat of a 'best fit' fashion. This has lead to a situation where we had additional more specific ABI docs for some sysfs parameters in certain drivers. Unfortunately the automated documentation building doesn't work well with this both issuing warnings and building a less than ideal output.

So this series attempts to fix that up, mostly by moving the application specific parts, of properties that are documented in more than one place, into a higher level documentation file, sometimes with a device specific note. In a few cases this the result is a bit non-obvious hence the RFC. Roughly speaking I've put the more 'interesting' cases towards the end of the series.

It's worth noting that a general reorganzation, audit of missing docs etc is needed for the IIO ABI docs, but as that's a big job it may well take sometime to get it done. In the meantime let's deal with these issues. Some of the drivers have complex enough ABI that we should probably have detailed docs for them in addition to Documentation/ABI.

Note I haven't yet touched the remaining case of
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times: ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100 ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 2 times: ./Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2 ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8

This is mainly because I don't really know enough about these devices to conclude exactly what a fused bit of docs should look like. Also worth noting that those are probably deprecated ABI anyway given the move of counters into their own subsystem.

Jonathan Cameron (7):
iio:ABI docs: Fix up duplicate *_calibbias_* documentation for

    icm42600

iio:ABI docs: Avoid repitition of triggerX/sampling_frequency iio:ABI docs: Drop device specific docs for _powerdown for the adf4371 iio:ABI docs: Fix issue around repeated definition of out_currentY_raw iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one
file
iio:ABI docs: Combine the two instances of docs for sensor_sensitivity iio:ABI docs: Move specific description of out_altvoltageX_frequency
to main docs.

 Documentation/ABI/testing/sysfs-bus-iio       | 45 +++++++++++++++++++
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |  8 ----
 .../testing/sysfs-bus-iio-frequency-adf4371   | 33 --------------
 .../ABI/testing/sysfs-bus-iio-health-afe440x  | 10 +----
 ...umidity-hdc2010 => sysfs-bus-iio-humidity} |  3 +-
 .../testing/sysfs-bus-iio-humidity-hdc100x    |  9 ----
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 ---------
 .../testing/sysfs-bus-iio-light-lm3533-als    | 11 ++---
 .../ABI/testing/sysfs-bus-iio-proximity       | 14 ++++++
 .../testing/sysfs-bus-iio-proximity-as3935    |  9 ----
 .../ABI/testing/sysfs-bus-iio-timer-stm32     |  8 ----
 11 files changed, 66 insertions(+), 104 deletions(-)
 rename Documentation/ABI/testing/{sysfs-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} (79%)
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-icm42600
Signature · 1 line
2.30.0
author maintainer
#1 lore raw

RFC PATCH 1/7 iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

From: Jonathan Cameron <[email protected]>

This device has the unusual characteristic that the calibbias values have well defined units (more commonly they are tweaks to a DAC) Unfortunately the previous approach of having more specific documentation in sysfs-bus-iio-icm42600 results in warnings during the documentation build and random ordering in the resulting documentation.

To avoid this, add a note to the main documentation on this special
characteristic for the icm42600. The _available for calibbias was
missing from the main sysfs-bus-iio docs so also add that, allowing us to drop the icm42600 specific file.

Fixes

$ scripts/get_abi.pl validate warning:
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399
---
 Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
 2 files changed, 13 insertions(+), 20 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +13 -0
index d957f5da5c04..d2dd9cc280f9 100644
@@ -408,6 +408,19 @@ Contact:	[email protected]
 Description:
 		Hardware applied calibration offset (assumed to fix production
 		inaccuracies).
+		icm42600: For this device values are real physical offsets
+		expressed in SI units (m/s^2 for accelerometers and rad/s
+		for gyroscope)/
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+KernelVersion:  5.8
+Contact:        [email protected]
+Description:
+		Available values of calibbias. Maybe expressed as either of:
+
+		- a small discrete set of values like "0 2 4 6 8"
+		- a range specified as "[min step max]"
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
Documentation/ABI/testing/sysfs-bus-iio-icm42600 deleted +0 -20
deleted file mode 100644
index 0bf1fd4f5bf1..000000000000
@@ -1,20 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Hardware applied calibration offset (assumed to fix production
-		inaccuracies). Values represent a real physical offset expressed
-		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Range of available values for hardware offset. Values in SI
-		units (m/s^2 for accelerometer and rad/s for gyroscope).
Signature · 1 line
2.30.0
author maintainer
#2 lore raw

Re: [RFC PATCH 1/7] iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

Quoted 1 line · On Sun, 17 Jan 2021 15:38:10 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

@Jean-Baptiste.

Whilst this is 'fairly obviously' fine, could you take a quick glance at it. I'm never keen to take my own patches without someone having agreed I haven't done anything particularly silly ;)

Jonathan

Quoted 79 lines

This device has the unusual characteristic that the calibbias values have well defined units (more commonly they are tweaks to a DAC) Unfortunately the previous approach of having more specific documentation in sysfs-bus-iio-icm42600 results in warnings during the documentation build and random ordering in the resulting documentation.

To avoid this, add a note to the main documentation on this special
characteristic for the icm42600. The _available for calibbias was
missing from the main sysfs-bus-iio docs so also add that, allowing us to drop the icm42600 specific file.

Fixes

$ scripts/get_abi.pl validate warning:
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399
---
 Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
 2 files changed, 13 insertions(+), 20 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +13 -0
index d957f5da5c04..d2dd9cc280f9 100644
@@ -408,6 +408,19 @@ Contact:	[email protected]
 Description:
 		Hardware applied calibration offset (assumed to fix production
 		inaccuracies).
+		icm42600: For this device values are real physical offsets
+		expressed in SI units (m/s^2 for accelerometers and rad/s
+		for gyroscope)/
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+KernelVersion:  5.8
+Contact:        [email protected]
+Description:
+		Available values of calibbias. Maybe expressed as either of:
+
+		- a small discrete set of values like "0 2 4 6 8"
+		- a range specified as "[min step max]"
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
Documentation/ABI/testing/sysfs-bus-iio-icm42600 deleted +0 -20
deleted file mode 100644
index 0bf1fd4f5bf1..000000000000
@@ -1,20 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Hardware applied calibration offset (assumed to fix production
-		inaccuracies). Values represent a real physical offset expressed
-		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Range of available values for hardware offset. Values in SI
-		units (m/s^2 for accelerometer and rad/s for gyroscope).
#3 lore raw

Re: [RFC PATCH 1/7] iio:ABI docs: Fix up duplicate *_calibbias_* documentation for icm42600

Quoted 9 lines · On Sun, 21 Feb 2021 16:05:29 +0000 Jonathan Cameron <[email protected]> wrote:
Quoted 1 line · On Sun, 17 Jan 2021 15:38:10 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

@Jean-Baptiste.

Whilst this is 'fairly obviously' fine, could you take a quick glance at it. I'm never keen to take my own patches without someone having agreed I haven't done anything particularly silly ;)

As these are still frustrating Mauro's attempt to get the docs to build cleanly and it should be safe enough.

Applied to the togreg branch of iio.git and pushed out as testing for the autobuilders to poke at it.

Jonathan

Quoted 83 lines

Jonathan

Quoted 79 lines

This device has the unusual characteristic that the calibbias values have well defined units (more commonly they are tweaks to a DAC) Unfortunately the previous approach of having more specific documentation in sysfs-bus-iio-icm42600 results in warnings during the documentation build and random ordering in the resulting documentation.

To avoid this, add a note to the main documentation on this special
characteristic for the icm42600. The _available for calibbias was
missing from the main sysfs-bus-iio docs so also add that, allowing us to drop the icm42600 specific file.

Fixes

$ scripts/get_abi.pl validate warning:
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Documentation/ABI/testing/sysfs-bus-iio:394
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Documentation/ABI/testing/sysfs-bus-iio:399
---
 Documentation/ABI/testing/sysfs-bus-iio       | 13 ++++++++++++
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 -------------------
 2 files changed, 13 insertions(+), 20 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +13 -0
index d957f5da5c04..d2dd9cc280f9 100644
@@ -408,6 +408,19 @@ Contact:	[email protected]
 Description:
 		Hardware applied calibration offset (assumed to fix production
 		inaccuracies).
+		icm42600: For this device values are real physical offsets
+		expressed in SI units (m/s^2 for accelerometers and rad/s
+		for gyroscope)/
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
+KernelVersion:  5.8
+Contact:        [email protected]
+Description:
+		Available values of calibbias. Maybe expressed as either of:
+
+		- a small discrete set of values like "0 2 4 6 8"
+		- a range specified as "[min step max]"
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
Documentation/ABI/testing/sysfs-bus-iio-icm42600 deleted +0 -20
deleted file mode 100644
index 0bf1fd4f5bf1..000000000000
@@ -1,20 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Hardware applied calibration offset (assumed to fix production
-		inaccuracies). Values represent a real physical offset expressed
-		in SI units (m/s^2 for accelerometer and rad/s for gyroscope).
-
-What:		/sys/bus/iio/devices/iio:deviceX/in_accel_calibbias_available
-What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_calibbias_available
-KernelVersion:  5.8
-Contact:        [email protected]
-Description:
-		Range of available values for hardware offset. Values in SI
-		units (m/s^2 for accelerometer and rad/s for gyroscope).  
author maintainer
#4 lore raw

RFC PATCH 2/7 iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
---
 Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
 Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
 2 files changed, 2 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +2 -0
index d2dd9cc280f9..9b5ceb22363d 100644
@@ -55,6 +55,8 @@ Description:
 		direct access interfaces, it may be found in any of the
 		relevant directories.  If it affects all of the above
 		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.
 
 What:		/sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +0 -8
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]
Signature · 1 line
2.30.0
maintainer Acked-by on v1 2/7
#5 lore raw

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

Quoted 11 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
Quoted 7 lines
---
 Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
 Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
 2 files changed, 2 insertions(+), 8 deletions(-)

Hi Jonathan,

Thanks,

Fabrice

Quoted 33 lines
Documentation/ABI/testing/sysfs-bus-iio +2 -0
index d2dd9cc280f9..9b5ceb22363d 100644
@@ -55,6 +55,8 @@ Description:
 		direct access interfaces, it may be found in any of the
 		relevant directories.  If it affects all of the above
 		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.
 
 What:		/sys/bus/iio/devices/iio:deviceX/sampling_frequency_available
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available
Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 +0 -8
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]
#6 lore raw

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

In reply to Jonathan Cameron
Quoted 24 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
---
  Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
  2 files changed, 2 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +0 -0
index d2dd9cc280f9..9b5ceb22363d 100644

Documentation/ABI/testing/sysfs-bus-iio Description: · line 59

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-iio +2 -0
@@ -55,6 +55,8 @@ Description:
  		direct access interfaces, it may be found in any of the
  		relevant directories.  If it affects all of the above
  		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.

Hm, I don't like this. 0 should be an invalid value for the standard ABI. Enabling/disabling of the trigger should be controlled by whether there are any active trigger consumers.

The stm32-timer-trigger implements a non-standard ABI and I think we need to document this explicitly. The driver does not have a set_state callback. So the frequency property is used to enable/disable the trigger, but as said above, for standard compliant triggers that should not be the case.

author maintainer
#7 lore raw

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

Quoted 35 lines · On Sun, 7 Mar 2021 10:40:18 +0100 Lars-Peter Clausen <[email protected]> wrote:
Quoted 24 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
---
  Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
  2 files changed, 2 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +0 -0
index d2dd9cc280f9..9b5ceb22363d 100644

Documentation/ABI/testing/sysfs-bus-iio Description: · line 59

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-iio +2 -0
@@ -55,6 +55,8 @@ Description:
  		direct access interfaces, it may be found in any of the
  		relevant directories.  If it affects all of the above
  		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.  

Hm, I don't like this. 0 should be an invalid value for the standard ABI. Enabling/disabling of the trigger should be controlled by whether there are any active trigger consumers.

Quoted 6 lines

The stm32-timer-trigger implements a non-standard ABI and I think we need to document this explicitly. The driver does not have a set_state callback. So the frequency property is used to enable/disable the trigger, but as said above, for standard compliant triggers that should not be the case.

Good point. Ideally we'd also fix the stm32-timer-trigger to have an explicit enable / disable (even if that works by setting the frequency to 0 under the hook)

For now I've dropped the patch until this is resolved.

Thanks,

Jonathan

maintainer
#8 lore raw

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

Quoted 44 lines · Jonathan Cameron
Quoted 35 lines · On Sun, 7 Mar 2021 10:40:18 +0100 Lars-Peter Clausen <[email protected]> wrote:
Quoted 24 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
---
  Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
  2 files changed, 2 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +0 -0
index d2dd9cc280f9..9b5ceb22363d 100644

Documentation/ABI/testing/sysfs-bus-iio Description: · line 59

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-iio +2 -0
@@ -55,6 +55,8 @@ Description:
  		direct access interfaces, it may be found in any of the
  		relevant directories.  If it affects all of the above
  		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.  

Hm, I don't like this. 0 should be an invalid value for the standard ABI. Enabling/disabling of the trigger should be controlled by whether there are any active trigger consumers.

Quoted 6 lines

The stm32-timer-trigger implements a non-standard ABI and I think we need to document this explicitly. The driver does not have a set_state callback. So the frequency property is used to enable/disable the trigger, but as said above, for standard compliant triggers that should not be the case.

Quoted 3 lines

Good point. Ideally we'd also fix the stm32-timer-trigger to have an explicit enable / disable (even if that works by setting the frequency to 0 under the hook)

Hi Jonathan,

I'd like to come up with something here...
The trivial use case is: the stm32-timer triggers the stm32-adc (by HW). In this case, "set_trigger_state" perfectly fits the needs (looks like).

But such change doesn't seems trivial when considering one timer can trig another timer in hardware here. The "set_trigger_state" isn't called in such a case.
So, I'm not sure what could be suitable to implement explicit enable/disable of the timer trigger ?

Just to share some thoughts here: For sure the stm32-timer-trigger would need additional changes (I haven't forget other mail thread on the preset attribute). I believe also some functionalities should be moved to the counter framework. But, even provided this, I think there will still be a need for an enable or disable attribute, for the trigger part.

Perhaps adding an enable/disable attribute could be a way here ? If yes, would you have some suggestion on the naming ?

Please advice,
Thanks in advance,
Fabrice

Quoted 8 lines

For now I've dropped the patch until this is resolved.

Thanks,

Jonathan

#9 lore raw

Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency

Quoted 51 lines · On Fri, 12 Mar 2021 17:56:50 +0100 Fabrice Gasnier…
Quoted 44 lines · Jonathan Cameron
Quoted 35 lines · On Sun, 7 Mar 2021 10:40:18 +0100 Lars-Peter Clausen <[email protected]> wrote:
Quoted 24 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The timer-stm32 provided a little more specific information than the main docs about the value of 0 corresponding to stopping sampling. Given that this makes sense in general, move that statement over to the main docs and drop the version in sysfs-bus-iio-timer-stm32

Fixes

$ scripts/get_abi.pl validate
/sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  ./Documentation/ABI/testing/sysfs-bus-iio:45
---
  Documentation/ABI/testing/sysfs-bus-iio             | 2 ++
  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
  2 files changed, 2 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +0 -0
index d2dd9cc280f9..9b5ceb22363d 100644

Documentation/ABI/testing/sysfs-bus-iio Description: · line 59

Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-iio +2 -0
@@ -55,6 +55,8 @@ Description:
  		direct access interfaces, it may be found in any of the
  		relevant directories.  If it affects all of the above
  		then it is to be found in the base device directory.
+		Note a value 0 where supported, will correspond to sampling
+		stopping.    

Hm, I don't like this. 0 should be an invalid value for the standard ABI. Enabling/disabling of the trigger should be controlled by whether there are any active trigger consumers.

Quoted 6 lines

The stm32-timer-trigger implements a non-standard ABI and I think we need to document this explicitly. The driver does not have a set_state callback. So the frequency property is used to enable/disable the trigger, but as said above, for standard compliant triggers that should not be the case.

Quoted 3 lines

Good point. Ideally we'd also fix the stm32-timer-trigger to have an explicit enable / disable (even if that works by setting the frequency to 0 under the hook)

Hi Jonathan,

Quoted 7 lines

I'd like to come up with something here...
The trivial use case is: the stm32-timer triggers the stm32-adc (by HW). In this case, "set_trigger_state" perfectly fits the needs (looks like).

But such change doesn't seems trivial when considering one timer can trig another timer in hardware here. The "set_trigger_state" isn't called in such a case.

Ah. I'd forgotten that complexity.

Quoted 2 lines

So, I'm not sure what could be suitable to implement explicit enable/disable of the timer trigger ?

Perhaps we should just document this one as non standard. We already have a few ABI docs that reflect devices that do something that is kind of 'in the spirit' of the ABI, but stretches in a little in an unusual direction. For those we just say what parts they apply to. It is existing ABI anyway so there is no disadvantage in keeping it around if we can't come up with something better.

Quoted 8 lines

Just to share some thoughts here: For sure the stm32-timer-trigger would need additional changes (I haven't forget other mail thread on the preset attribute). I believe also some functionalities should be moved to the counter framework. But, even provided this, I think there will still be a need for an enable or disable attribute, for the trigger part.

Perhaps adding an enable/disable attribute could be a way here ?

Hmm. At least based on limited caffeine in my system this morning I think that we may be better off with it just being as it is now and a slightly 'stretch' of the ABI.

What do others think?

Jonathan

Quoted 14 lines

If yes, would you have some suggestion on the naming ?

Please advice,
Thanks in advance,
Fabrice

Quoted 8 lines

For now I've dropped the patch until this is resolved.

Thanks,

Jonathan

author maintainer
#10 lore raw

RFC PATCH 3/7 iio:ABI docs: Drop device specific docs for _powerdown for the adf4371

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The interface is standard and the extra info provided on exactly what is being powered down is not of interest to most users. Hence this doesn't need it's own documentation and can rely on the docs in sysfs-bus-iio

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  ./Documentation/ABI/testing/sysfs-bus-iio:588
---
 Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 | 8 --------
 1 file changed, 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +0 -8
index 544548ee794c..457f75903963 100644
@@ -34,11 +34,3 @@ Description:
 		  out_altvoltage2_name: RF16x
 		  out_altvoltage3_name: RF32x
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
-KernelVersion:
-Contact:	[email protected]
-Description:
-		This attribute allows the user to power down the PLL and it's
-		RFOut buffers.
-		Writing 1 causes the specified channel to power down.
-		Clearing returns to normal operation.
Signature · 1 line
2.30.0
#11 lore raw

Re: [RFC PATCH 3/7] iio:ABI docs: Drop device specific docs for _powerdown for the adf4371

Quoted 6 lines · On Sun, 17 Jan 2021 15:38:12 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

The interface is standard and the extra info provided on exactly what is being powered down is not of interest to most users. Hence this doesn't need it's own documentation and can rely on the docs in sysfs-bus-iio

Quoted 7 lines

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  ./Documentation/ABI/testing/sysfs-bus-iio:588

I'm guessing I can't make a mistake removing docs :)

Applied to the togreg branch of iio.git and pushed out as testing for the autobuilders to do nothing with it.

Thanks,

Jonathan

Quoted 20 lines
---
 Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 | 8 --------
 1 file changed, 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +0 -8
index 544548ee794c..457f75903963 100644
@@ -34,11 +34,3 @@ Description:
 		  out_altvoltage2_name: RF16x
 		  out_altvoltage3_name: RF32x
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
-KernelVersion:
-Contact:	[email protected]
-Description:
-		This attribute allows the user to power down the PLL and it's
-		RFOut buffers.
-		Writing 1 causes the specified channel to power down.
-		Clearing returns to normal operation.
author maintainer
#12 lore raw

RFC PATCH 4/7 iio:ABI docs: Fix issue around repeated definition of out_currentY_raw

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

This one is challenging as both the places this appears in specific drivers are making 'unusual' uses of what looks like a simple output current channel.
As a side note, this was particular bit of ABI occurs in other drivers where the use is much more straight forward e.g. dac/ad5421

This patch attempts to make a best effort of adding it to the main docs but retaining enough information. Both of these drivers probably need specific documents being written to describe their unusual interfaces, but those should be in the main documentation, not under Documentation/ABI. That is a non trivial job so left for another time.

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  ./Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
---
 Documentation/ABI/testing/sysfs-bus-iio               | 11 +++++++++++
 .../ABI/testing/sysfs-bus-iio-health-afe440x          | 10 ++--------
 .../ABI/testing/sysfs-bus-iio-light-lm3533-als        | 11 +++--------
 3 files changed, 16 insertions(+), 16 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +11 -0
index 9b5ceb22363d..ed50f4b21dcc 100644
@@ -631,6 +631,17 @@ Description:
 		specified and unique if the output corresponds to a single
 		channel.
 
+What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
+Date:		May 2012
+KernelVersion:	3.5
+Contact:	Johan Hovold <[email protected]>
+Description:
+		Set/get output current for channel Y. Units after application
+		of scale and offset are milliamps.
+		For some devices current channels are used to specify
+		current supplied to elements used in taking a measurement
+		of a different type. E.g. LED currents.
+
 What:		/sys/bus/iio/devices/iio:deviceX/events
 KernelVersion:	2.6.35
 Contact:	[email protected]
Documentation/ABI/testing/sysfs-bus-iio-health-afe440x +2 -8
index 66b621f10223..a8e04b41d9ff 100644
@@ -18,6 +18,8 @@ Description:
 		respectively which simply helper channels containing the
 		calculated difference in the value of stage 1 - 2 and 3 - 4.
 		The values are expressed in 24-bit twos complement.
+		The LED current for the stage is controlled via
+		out_currentY_raw.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensityY_offset
 Date:		May 2016
@@ -35,11 +37,3 @@ Contact:	Andrew F. Davis <[email protected]>
 Description:
 		Get and set the resistance and the capacitance settings for the
 		Transimpedance Amplifier during the associated stage.
-
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2016
-KernelVersion:
-Contact:	Andrew F. Davis <[email protected]>
-Description:
-		Get and set the LED current for the specified LED active during
-		this stage. Y is the specific stage number.
Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als +3 -8
index 22c5ea670971..c476d48d0f82 100644
@@ -41,14 +41,6 @@ Description:
 		Get the current light zone (0..4) as defined by the
 		in_illuminance0_threshY_{falling,rising} thresholds.
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2012
-KernelVersion:	3.5
-Contact:	Johan Hovold <[email protected]>
-Description:
-		Get output current for channel Y (0..255), that is,
-		out_currentY_currentZ_raw, where Z is the current zone.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw
 Date:		May 2012
 KernelVersion:	3.5
@@ -59,3 +51,6 @@ Description:
 
 		These values correspond to the ALS-mapper target registers for
 		ALS-mapper Y + 1.
+
+		Note that out_currentY_raw provides the current for the
+		current zone.
Signature · 1 line
2.30.0
#13 lore raw

Re: [RFC PATCH 4/7] iio:ABI docs: Fix issue around repeated definition of out_currentY_raw

Quoted 14 lines · On Sun, 17 Jan 2021 15:38:13 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

This one is challenging as both the places this appears in specific drivers are making 'unusual' uses of what looks like a simple output current channel.
As a side note, this was particular bit of ABI occurs in other drivers where the use is much more straight forward e.g. dac/ad5421

This patch attempts to make a best effort of adding it to the main docs but retaining enough information. Both of these drivers probably need specific documents being written to describe their unusual interfaces, but those should be in the main documentation, not under Documentation/ABI. That is a non trivial job so left for another time.

Quoted 6 lines

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  ./Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38

Another one I think I can't have gotten wrong. Hence whilst I like to know they've had eyes on them, I'll take this one anyway.

Applied to the togreg branch of iio.git and pushed out as testing.

Thanks,

Jonathan

Quoted 79 lines
---
 Documentation/ABI/testing/sysfs-bus-iio               | 11 +++++++++++
 .../ABI/testing/sysfs-bus-iio-health-afe440x          | 10 ++--------
 .../ABI/testing/sysfs-bus-iio-light-lm3533-als        | 11 +++--------
 3 files changed, 16 insertions(+), 16 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +11 -0
index 9b5ceb22363d..ed50f4b21dcc 100644
@@ -631,6 +631,17 @@ Description:
 		specified and unique if the output corresponds to a single
 		channel.
 
+What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
+Date:		May 2012
+KernelVersion:	3.5
+Contact:	Johan Hovold <[email protected]>
+Description:
+		Set/get output current for channel Y. Units after application
+		of scale and offset are milliamps.
+		For some devices current channels are used to specify
+		current supplied to elements used in taking a measurement
+		of a different type. E.g. LED currents.
+
 What:		/sys/bus/iio/devices/iio:deviceX/events
 KernelVersion:	2.6.35
 Contact:	[email protected]
Documentation/ABI/testing/sysfs-bus-iio-health-afe440x +2 -8
index 66b621f10223..a8e04b41d9ff 100644
@@ -18,6 +18,8 @@ Description:
 		respectively which simply helper channels containing the
 		calculated difference in the value of stage 1 - 2 and 3 - 4.
 		The values are expressed in 24-bit twos complement.
+		The LED current for the stage is controlled via
+		out_currentY_raw.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensityY_offset
 Date:		May 2016
@@ -35,11 +37,3 @@ Contact:	Andrew F. Davis <[email protected]>
 Description:
 		Get and set the resistance and the capacitance settings for the
 		Transimpedance Amplifier during the associated stage.
-
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2016
-KernelVersion:
-Contact:	Andrew F. Davis <[email protected]>
-Description:
-		Get and set the LED current for the specified LED active during
-		this stage. Y is the specific stage number.
Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als +3 -8
index 22c5ea670971..c476d48d0f82 100644
@@ -41,14 +41,6 @@ Description:
 		Get the current light zone (0..4) as defined by the
 		in_illuminance0_threshY_{falling,rising} thresholds.
 
-What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_raw
-Date:		May 2012
-KernelVersion:	3.5
-Contact:	Johan Hovold <[email protected]>
-Description:
-		Get output current for channel Y (0..255), that is,
-		out_currentY_currentZ_raw, where Z is the current zone.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw
 Date:		May 2012
 KernelVersion:	3.5
@@ -59,3 +51,6 @@ Description:
 
 		These values correspond to the ALS-mapper target registers for
 		ALS-mapper Y + 1.
+
+		Note that out_currentY_raw provides the current for the
+		current zone.
author maintainer
#14 lore raw

RFC PATCH 5/7 iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

These contain only one entry for out_current_heater_raw (_available). Document this in a new sysfs-bus-iio-humidity file, and make it a little more generic by allowing for non 0/1 values.

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
---
 ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
 2 files changed, 2 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-humidity renamed from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 +2 -1
similarity index 79%
rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
index 5b78af5f341d..cb0d7e75d297 100644
@@ -6,4 +6,5 @@ Description:
 		Controls the heater device within the humidity sensor to get
 		rid of excess condensation.
 
-		Valid control values are 0 = OFF, and 1 = ON.
+		In some devices, this is just a switch in which case 0 = OFF,
+		and 1 = ON.
Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x deleted +0 -9
deleted file mode 100644
index b72bb62552cf..000000000000
@@ -1,9 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
-What:		/sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
-KernelVersion:	4.3
-Contact:	[email protected]
-Description:
-		Controls the heater device within the humidity sensor to get
-		rid of excess condensation.
-
-		Valid control values are 0 = OFF, and 1 = ON.
Signature · 1 line
2.30.0
Reviewed-by on v1 5/7
#15 lore raw

Re: [RFC PATCH 5/7] iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

Quoted 8 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

These contain only one entry for out_current_heater_raw (_available). Document this in a new sysfs-bus-iio-humidity file, and make it a little more generic by allowing for non 0/1 values.

Fixes:

Quoted 8 lines
$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
Quoted 37 lines
---
 ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
 2 files changed, 2 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-humidity renamed from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 +2 -1
similarity index 79%
rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
index 5b78af5f341d..cb0d7e75d297 100644
@@ -6,4 +6,5 @@ Description:
                Controls the heater device within the humidity sensor to get
                rid of excess condensation.
 
-               Valid control values are 0 = OFF, and 1 = ON.
+               In some devices, this is just a switch in which case 0 = OFF,
+               and 1 = ON.
Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x deleted +0 -10
deleted file mode 100644
index b72bb62552cf..000000000000
@@ -1,9 +0,0 @@
-What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
-What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
-KernelVersion: 4.3
-Contact:       [email protected]
-Description:
-               Controls the heater device within the humidity sensor to get
-               rid of excess condensation.
-
-               Valid control values are 0 = OFF, and 1 = ON.
--

2.30.0

author maintainer Applied
#16 lore raw

Re: [RFC PATCH 5/7] iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file

Quoted 13 lines · On Sun, 17 Jan 2021 15:12:40 -0800 Matt Ranostay <[email protected]>…
Quoted 12 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

These contain only one entry for out_current_heater_raw (_available). Document this in a new sysfs-bus-iio-humidity file, and make it a little more generic by allowing for non 0/1 values.

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
Quoted 6 lines
Quoted 4 lines

Applied, thanks

J

Quoted 38 lines
Quoted 38 lines
---
 ...s-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} | 3 ++-
 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x | 9 ---------
 2 files changed, 2 insertions(+), 10 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-humidity renamed from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010 +2 -1
similarity index 79%
rename from Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
rename to Documentation/ABI/testing/sysfs-bus-iio-humidity
index 5b78af5f341d..cb0d7e75d297 100644
@@ -6,4 +6,5 @@ Description:
                Controls the heater device within the humidity sensor to get
                rid of excess condensation.
 
-               Valid control values are 0 = OFF, and 1 = ON.
+               In some devices, this is just a switch in which case 0 = OFF,
+               and 1 = ON.
Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x deleted +0 -10
deleted file mode 100644
index b72bb62552cf..000000000000
@@ -1,9 +0,0 @@
-What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw
-What:          /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available
-KernelVersion: 4.3
-Contact:       [email protected]
-Description:
-               Controls the heater device within the humidity sensor to get
-               rid of excess condensation.
-
-               Valid control values are 0 = OFF, and 1 = ON.
--

2.30.0

author maintainer
#17 lore raw

RFC PATCH 6/7 iio:ABI docs: Combine the two instances of docs for sensor_sensitivity

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

This control on the gain of a measurement used for time of flight sensing is standard but the expected values for different enviroments may not be. As we cannot have the same ABI element documented in two files, add a generic version to sysfs-bus-iio-proximity and a note on the expected value vs measuring environment for the as3935.

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  ./Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
---
 .../ABI/testing/sysfs-bus-iio-distance-srf08       |  8 --------
 Documentation/ABI/testing/sysfs-bus-iio-proximity  | 14 ++++++++++++++
 .../ABI/testing/sysfs-bus-iio-proximity-as3935     |  9 ---------
 3 files changed, 14 insertions(+), 17 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +0 -8
index 40df5c9fef99..9dae94aa880b 100644
@@ -1,11 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:		January 2017
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Show or set the gain boost of the amp, from 0-31 range.
-		default 31
-
 What:		/sys/bus/iio/devices/iio:deviceX/sensor_max_range
 Date:		January 2017
 KernelVersion:	4.11
Documentation/ABI/testing/sysfs-bus-iio-proximity +14 -0
index 2172f3bb9c64..3aac6dab8775 100644
@@ -8,3 +8,17 @@ Description:
 		considered close to the device. If the value read from the
 		sensor is above or equal to the value in this file an object
 		should typically be considered near.
+
+What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+Date:		March 2014
+KernelVersion:	3.15
+Contact:	[email protected]
+Description:
+		Proximity sensors sometimes have a controllable amplifier
+		on the signal from which time of flight measurements are
+		taken.
+		The appropriate values to take is dependent on both the
+		sensor and it's operating environment:
+		* as3935 (0-31 range)
+		18 = indoors (default)
+		14 = outdoors
Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +0 -9
index c59d95346341..1e5c40775a6c 100644
@@ -6,15 +6,6 @@ Description:
 		Get the current distance in meters of storm (1km steps)
 		1000-40000 = distance in meters
 
-What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:		March 2014
-KernelVersion:	3.15
-Contact:	Matt Ranostay <[email protected]>
-Description:
-		Show or set the gain boost of the amp, from 0-31 range.
-		18 = indoors (default)
-		14 = outdoors
-
 What		/sys/bus/iio/devices/iio:deviceX/noise_level_tripped
 Date:		May 2017
 KernelVersion:	4.13
Signature · 1 line
2.30.0
Reviewed-by on v1 6/7
#18 lore raw

Re: [RFC PATCH 6/7] iio:ABI docs: Combine the two instances of docs for sensor_sensitivity

Quoted 9 lines · Jonathan Cameron

From: Jonathan Cameron <[email protected]>

This control on the gain of a measurement used for time of flight sensing is standard but the expected values for different enviroments may not be. As we cannot have the same ABI element documented in two files, add a generic version to sysfs-bus-iio-proximity and a note on the expected value vs measuring environment for the as3935.

Quoted 7 lines

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  ./Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
Quoted 67 lines
---
 .../ABI/testing/sysfs-bus-iio-distance-srf08       |  8 --------
 Documentation/ABI/testing/sysfs-bus-iio-proximity  | 14 ++++++++++++++
 .../ABI/testing/sysfs-bus-iio-proximity-as3935     |  9 ---------
 3 files changed, 14 insertions(+), 17 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 +0 -8
index 40df5c9fef99..9dae94aa880b 100644
@@ -1,11 +1,3 @@
-What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:          January 2017
-KernelVersion: 4.11
-Contact:       [email protected]
-Description:
-               Show or set the gain boost of the amp, from 0-31 range.
-               default 31
-
 What:          /sys/bus/iio/devices/iio:deviceX/sensor_max_range
 Date:          January 2017
 KernelVersion: 4.11
Documentation/ABI/testing/sysfs-bus-iio-proximity +14 -0
index 2172f3bb9c64..3aac6dab8775 100644
@@ -8,3 +8,17 @@ Description:
                considered close to the device. If the value read from the
                sensor is above or equal to the value in this file an object
                should typically be considered near.
+
+What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+Date:          March 2014
+KernelVersion: 3.15
+Contact:       [email protected]
+Description:
+               Proximity sensors sometimes have a controllable amplifier
+               on the signal from which time of flight measurements are
+               taken.
+               The appropriate values to take is dependent on both the
+               sensor and it's operating environment:
+               * as3935 (0-31 range)
+               18 = indoors (default)
+               14 = outdoors
Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +0 -10
index c59d95346341..1e5c40775a6c 100644
@@ -6,15 +6,6 @@ Description:
                Get the current distance in meters of storm (1km steps)
                1000-40000 = distance in meters
 
-What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
-Date:          March 2014
-KernelVersion: 3.15
-Contact:       Matt Ranostay <[email protected]>
-Description:
-               Show or set the gain boost of the amp, from 0-31 range.
-               18 = indoors (default)
-               14 = outdoors
-
 What           /sys/bus/iio/devices/iio:deviceX/noise_level_tripped
 Date:          May 2017
 KernelVersion: 4.13
--

2.30.0

author maintainer
#19 lore raw

RFC PATCH 7/7 iio:ABI docs: Move specific description of out_altvoltageX_frequency to main docs.

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

The adf4371 has channels that are very closely coupled, so additional documentation is needed to express these constraints. Unfortunately having the same sysfs filename in multiple documentation does not work well when generating automated documentation. To avoid this issue, we add a new device specific description to the main docs and remove the one in the device specific file.

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  ./Documentation/ABI/testing/sysfs-bus-iio:599
---
 Documentation/ABI/testing/sysfs-bus-iio       | 19 ++++++++++++++
 .../testing/sysfs-bus-iio-frequency-adf4371   | 25 -------------------
 2 files changed, 19 insertions(+), 25 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +19 -0
index ed50f4b21dcc..515c4290d43d 100644
@@ -620,6 +620,25 @@ Description:
 		Output frequency for channel Y in Hz. The number must always be
 		specified and unique if the output corresponds to a single
 		channel.
+		Some drivers have additional constraints:
+		ADF4371 has an integrated VCO with fundamendal output
+		frequency ranging from 4000000000 Hz 8000000000 Hz.
+
+		out_altvoltage0_frequency:
+			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
+			frequencies from 62500000 Hz to 8000000000 Hz.
+		out_altvoltage1_frequency:
+			This channel duplicates the channel 0 frequency
+		out_altvoltage2_frequency:
+			A frequency doubler generates frequencies from
+			8000000000 Hz to 16000000000 Hz.
+		out_altvoltage3_frequency:
+			A frequency quadrupler generates frequencies from
+			16000000000 Hz to 32000000000 Hz.
+
+		Note: writes to one of the channels will affect the frequency of
+		all the other channels, since it involves changing the VCO
+		fundamental output frequency.
 
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
 KernelVersion:	3.4.0
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +0 -25
index 457f75903963..7fe6935d1448 100644
@@ -1,28 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
-KernelVersion:
-Contact:	[email protected]
-Description:
-		Stores the PLL frequency in Hz for channel Y.
-		Reading returns the actual frequency in Hz.
-		The ADF4371 has an integrated VCO with fundamendal output
-		frequency ranging from 4000000000 Hz 8000000000 Hz.
-
-		out_altvoltage0_frequency:
-			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
-			frequencies from 62500000 Hz to 8000000000 Hz.
-		out_altvoltage1_frequency:
-			This channel duplicates the channel 0 frequency
-		out_altvoltage2_frequency:
-			A frequency doubler generates frequencies from
-			8000000000 Hz to 16000000000 Hz.
-		out_altvoltage3_frequency:
-			A frequency quadrupler generates frequencies from
-			16000000000 Hz to 32000000000 Hz.
-
-		Note: writes to one of the channels will affect the frequency of
-		all the other channels, since it involves changing the VCO
-		fundamental output frequency.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
 KernelVersion:
 Contact:	[email protected]
Signature · 1 line
2.30.0
#20 lore raw

Re: [RFC PATCH 7/7] iio:ABI docs: Move specific description of out_altvoltageX_frequency to main docs.

Quoted 9 lines · On Sun, 17 Jan 2021 15:38:16 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

The adf4371 has channels that are very closely coupled, so additional documentation is needed to express these constraints. Unfortunately having the same sysfs filename in multiple documentation does not work well when generating automated documentation. To avoid this issue, we add a new device specific description to the main docs and remove the one in the device specific file.

Quoted 7 lines

Fixes:

$ scripts/get_abi.pl validate
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  ./Documentation/ABI/testing/sysfs-bus-iio:599

Applied.

Thanks,

Jonathan

Quoted 68 lines
---
 Documentation/ABI/testing/sysfs-bus-iio       | 19 ++++++++++++++
 .../testing/sysfs-bus-iio-frequency-adf4371   | 25 -------------------
 2 files changed, 19 insertions(+), 25 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +19 -0
index ed50f4b21dcc..515c4290d43d 100644
@@ -620,6 +620,25 @@ Description:
 		Output frequency for channel Y in Hz. The number must always be
 		specified and unique if the output corresponds to a single
 		channel.
+		Some drivers have additional constraints:
+		ADF4371 has an integrated VCO with fundamendal output
+		frequency ranging from 4000000000 Hz 8000000000 Hz.
+
+		out_altvoltage0_frequency:
+			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
+			frequencies from 62500000 Hz to 8000000000 Hz.
+		out_altvoltage1_frequency:
+			This channel duplicates the channel 0 frequency
+		out_altvoltage2_frequency:
+			A frequency doubler generates frequencies from
+			8000000000 Hz to 16000000000 Hz.
+		out_altvoltage3_frequency:
+			A frequency quadrupler generates frequencies from
+			16000000000 Hz to 32000000000 Hz.
+
+		Note: writes to one of the channels will affect the frequency of
+		all the other channels, since it involves changing the VCO
+		fundamental output frequency.
 
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase
 KernelVersion:	3.4.0
Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +0 -25
index 457f75903963..7fe6935d1448 100644
@@ -1,28 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
-KernelVersion:
-Contact:	[email protected]
-Description:
-		Stores the PLL frequency in Hz for channel Y.
-		Reading returns the actual frequency in Hz.
-		The ADF4371 has an integrated VCO with fundamendal output
-		frequency ranging from 4000000000 Hz 8000000000 Hz.
-
-		out_altvoltage0_frequency:
-			A divide by 1, 2, 4, 8, 16, 32 or circuit generates
-			frequencies from 62500000 Hz to 8000000000 Hz.
-		out_altvoltage1_frequency:
-			This channel duplicates the channel 0 frequency
-		out_altvoltage2_frequency:
-			A frequency doubler generates frequencies from
-			8000000000 Hz to 16000000000 Hz.
-		out_altvoltage3_frequency:
-			A frequency quadrupler generates frequencies from
-			16000000000 Hz to 32000000000 Hz.
-
-		Note: writes to one of the channels will affect the frequency of
-		all the other channels, since it involves changing the VCO
-		fundamental output frequency.
-
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
 KernelVersion:
 Contact:	[email protected]
author maintainer
#21 lore raw
In reply to Jonathan Cameron
Quoted 1 line · On Sun, 17 Jan 2021 15:38:09 +0000 Jonathan Cameron <[email protected]> wrote:

From: Jonathan Cameron <[email protected]>

Hi All,

Suffering from "maintainer's" curse on these of there being no one I can
generically moan at over lack of reviews :) If someone could just
cast their eyes over patches 1, 3, 4 and 7 to check I haven't done anything exceedingly stupid that would be great.

Thanks,

Jonathan

Quoted 58 lines

The nature of IIO devices is that they are highly varied and occaisonly ABI is used in somewhat of a 'best fit' fashion. This has lead to a situation where we had additional more specific ABI docs for some sysfs parameters in certain drivers. Unfortunately the automated documentation building doesn't work well with this both issuing warnings and building a less than ideal output.

So this series attempts to fix that up, mostly by moving the application specific parts, of properties that are documented in more than one place, into a higher level documentation file, sometimes with a device specific note. In a few cases this the result is a bit non-obvious hence the RFC. Roughly speaking I've put the more 'interesting' cases towards the end of the series.

It's worth noting that a general reorganzation, audit of missing docs etc is needed for the IIO ABI docs, but as that's a big job it may well take sometime to get it done. In the meantime let's deal with these issues. Some of the drivers have complex enough ABI that we should probably have detailed docs for them in addition to Documentation/ABI.

Note I haven't yet touched the remaining case of
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times: ./Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100 ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 2 times: ./Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2 ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8

This is mainly because I don't really know enough about these devices to conclude exactly what a fused bit of docs should look like. Also worth noting that those are probably deprecated ABI anyway given the move of counters into their own subsystem.

Jonathan Cameron (7):
iio:ABI docs: Fix up duplicate *_calibbias_* documentation for

    icm42600

iio:ABI docs: Avoid repitition of triggerX/sampling_frequency iio:ABI docs: Drop device specific docs for _powerdown for the adf4371 iio:ABI docs: Fix issue around repeated definition of out_currentY_raw iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one
file
iio:ABI docs: Combine the two instances of docs for sensor_sensitivity iio:ABI docs: Move specific description of out_altvoltageX_frequency
to main docs.

 Documentation/ABI/testing/sysfs-bus-iio       | 45 +++++++++++++++++++
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |  8 ----
 .../testing/sysfs-bus-iio-frequency-adf4371   | 33 --------------
 .../ABI/testing/sysfs-bus-iio-health-afe440x  | 10 +----
 ...umidity-hdc2010 => sysfs-bus-iio-humidity} |  3 +-
 .../testing/sysfs-bus-iio-humidity-hdc100x    |  9 ----
 .../ABI/testing/sysfs-bus-iio-icm42600        | 20 ---------
 .../testing/sysfs-bus-iio-light-lm3533-als    | 11 ++---
 .../ABI/testing/sysfs-bus-iio-proximity       | 14 ++++++
 .../testing/sysfs-bus-iio-proximity-as3935    |  9 ----
 .../ABI/testing/sysfs-bus-iio-timer-stm32     |  8 ----
 11 files changed, 66 insertions(+), 104 deletions(-)
 rename Documentation/ABI/testing/{sysfs-bus-iio-humidity-hdc2010 => sysfs-bus-iio-humidity} (79%)
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-icm42600