IIO ABI documentation duplication fixes
Subsystems (5)
Jonathan Cameron
maintainercover 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-icm42600Signature · 1 line
2.30.0
Jonathan Cameron
maintainerRFC 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
@@ -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
@@ -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
Jonathan Cameron
maintainerRe: [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_availablefor 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:399Cc Jean-Baptiste Maneyrol <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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@@ -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_calibscaleDocumentation/ABI/testing/sysfs-bus-iio-icm42600 deleted +0
-20@@ -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).
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_availablefor 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:399Cc Jean-Baptiste Maneyrol <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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@@ -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_calibscaleDocumentation/ABI/testing/sysfs-bus-iio-icm42600 deleted +0
-20@@ -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).
Jonathan Cameron
maintainerRFC PATCH 2/7 iio:ABI docs: Avoid repitition of triggerX/sampling_frequency
In reply to Jonathan CameronFrom: 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
@@ -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
@@ -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
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
Cc Fabrice Gasnier <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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@@ -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_availableDocumentation/ABI/testing/sysfs-bus-iio-timer-stm32 +0
-8@@ -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]
Re: [RFC PATCH 2/7] iio:ABI docs: Avoid repitition of triggerX/sampling_frequency
In reply to Jonathan CameronQuoted 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:45Cc Fabrice Gasnier <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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
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.
Jonathan Cameron
maintainerRe: [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:45Cc Fabrice Gasnier <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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
-0Documentation/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_statecallback. 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
Fabrice Gasnier
maintainerRe: [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:45Cc Fabrice Gasnier <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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
-0Documentation/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_statecallback. 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
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:45Cc Fabrice Gasnier <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>--- 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
-0Documentation/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_statecallback. 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,
FabriceQuoted 8 lines
For now I've dropped the patch until this is resolved.
Thanks,
Jonathan
Jonathan Cameron
maintainerRFC PATCH 3/7 iio:ABI docs: Drop device specific docs for _powerdown for the adf4371
In reply to Jonathan CameronFrom: 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
@@ -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
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:588Cc Alexandru Ardelean <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>
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@@ -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.
Jonathan Cameron
maintainerRFC PATCH 4/7 iio:ABI docs: Fix issue around repeated definition of out_currentY_raw
In reply to Jonathan CameronFrom: 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
@@ -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
@@ -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
@@ -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
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/ad5421This 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:38Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>
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@@ -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@@ -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@@ -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.
Jonathan Cameron
maintainerRFC PATCH 5/7 iio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one file
In reply to Jonathan CameronFrom: 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
@@ -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
@@ -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
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:1Cc Eugene Zaikonnikov <[email protected]>Cc Matt Ranostay <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>
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@@ -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@@ -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
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
Cc Eugene Zaikonnikov <[email protected]>Cc Matt Ranostay <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>Reviewed-by Matt Ranostay <[email protected]>
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@@ -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@@ -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
Jonathan Cameron
maintainerRFC PATCH 6/7 iio:ABI docs: Combine the two instances of docs for sensor_sensitivity
In reply to Jonathan CameronFrom: 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
@@ -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
@@ -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
@@ -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
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:8Cc Matt Ranostay <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>
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@@ -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.11Documentation/ABI/testing/sysfs-bus-iio-proximity +14
-0@@ -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 = outdoorsDocumentation/ABI/testing/sysfs-bus-iio-proximity-as3935 +0
-10@@ -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
Jonathan Cameron
maintainerRFC PATCH 7/7 iio:ABI docs: Move specific description of out_altvoltageX_frequency to main docs.
In reply to Jonathan CameronFrom: 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
@@ -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
@@ -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
Jonathan Cameron
AppliedRe: [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:599Cc Alexandru Ardelean <[email protected]>Reported-by Mauro Carvalho Chehab <[email protected]>Signed-off-by Jonathan Cameron <[email protected]>
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@@ -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.0Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 +0
-25@@ -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]
Jonathan Cameron
maintainerQuoted 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:8This 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 foricm42600iio:ABI docs: Avoid repitition of triggerX/sampling_frequency iio:ABI docs: Drop device specific docs for
_powerdownfor the adf4371 iio:ABI docs: Fix issue around repeated definition ofout_currentY_rawiio:ABI docs: Combine sysfs-bus-iio-humidity-hdc2010/hdc100x into one
file
iio:ABI docs: Combine the two instances of docs forsensor_sensitivityiio:ABI docs: Move specific description ofout_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