IIO: Some documentation error and warning fixes.
Subsystems (3)
Jonathan Cameron
maintainercover IIO: Some documentation error and warning fixes.
From: Jonathan Cameron <[email protected]>
Mauro Carvalho Chehab highlighted some outstanding IIO documentation issues in a thread on generally reducing the warning splat that is a documentation build.
The fixes aren't exactly ideal, but they are necessary to get these last few cases in IIO to not generate warnings.
https://lore.kernel.org/all/[email protected]/
Jonathan Cameron (4):
iio: ABI: temperature: Unify documentation for thermocouple fault
detection.
iio: ABI: max31865: Drop in_filter_notch_centre_frequency as in main
docs.
iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
iio: ABI: sx9324: Squash some formatting to keep scripting happy.
Documentation/ABI/testing/sysfs-bus-iio | 3 ++ .../ABI/testing/sysfs-bus-iio-sx9324 | 2 +- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 20 ------------ .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ .../ABI/testing/sysfs-bus-iio-timer-stm32 | 8 ----- 6 files changed, 22 insertions(+), 60 deletions(-) delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 delete mode 100644 Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-thermocouple
Signature · 1 line
2.36.1
Jonathan Cameron
maintainerPATCH 1/4 iio: ABI: temperature: Unify documentation for thermocouple fault detection.
From: Jonathan Cameron <[email protected]>
The kernel build docs do not support having multiple definitions for the same sysfs filename. Hence generalize the documentation a little and pull it out of device specific files and into sysfs-bus-iio-thermocouple
These may well be more general and need pulling into a more generic file in the future, but we can do that when it is needed.
--- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 12 ------- .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ 3 files changed, 18 insertions(+), 43 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 deleted +0 -31
@@ -1,31 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_oc -KernelVersion: 5.1 -Contact: [email protected] -Description: - Open-circuit fault. The detection of open-circuit faults, - such as those caused by broken thermocouple wires. - Reading returns either '1' or '0'. - - === ======================================================= - '1' An open circuit such as broken thermocouple wires - has been detected. - '0' No open circuit or broken thermocouple wires are detected - === ======================================================= - -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.1 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input Fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables by integrated MOSFETs at the T+ and T- inputs, and the - BIAS output. These MOSFETs turn off when the input voltage is - negative or greater than VDD. - - Reading returns either '1' or '0'. - - === ======================================================= - '1' The input voltage is negative or greater than VDD. - '0' The input voltage is positive and less than VDD (normal - state). - === =======================================================
Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 +0 -12
@@ -1,15 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.11 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables at FORCE+, FORCE2, RTDIN+ & RTDIN-. This circuitry turn - off when the input voltage is negative or greater than VDD. - - Reading returns '1' if input voltage is negative or greater - than VDD, otherwise '0'. - What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency KernelVersion: 5.11 Contact: [email protected]
Documentation/ABI/testing/sysfs-bus-iio-thermocouple new file +18 -0
@@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: [email protected] +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables. The device can also detect if such a condition occurs. + + Reading returns '1' if input voltage is negative or greater + than VDD, otherwise '0'. + +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: [email protected] +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns '1' if fault, '0' otherwise.
Signature · 1 line
2.36.1
Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.
Em Sun, 26 Jun 2022 17:55:08 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 4 lines
From: Jonathan Cameron <[email protected]>
The kernel build docs do not support having multiple definitions for the same sysfs filename.
Actually, this is not a matter of the docs build system not supporting. It is, instead, how the ABI were supposed to work: a given ABI symbol should have consistent behavior on all drivers that use it. Failing to do that is asking for troubles.
So, having duplicated symbols either mean that:
a) both have the same meaning. They can/should be unified in order to remove redundant documentation;
b) the same ABI symbol have different meanings depending on the driver(s) that use it. This makes very hard for userspace, as it is harder to write a program using it, as the behavior/meaning starts to be driver-dependent.
Quoted 10 lines
Hence generalize the documentation a little
and pull it out of device specific files and into
sysfs-bus-iio-thermocoupleThese may well be more general and need pulling into a more generic file in the future, but we can do that when it is needed.
Signed-off-by Jonathan Cameron <[email protected]>Cc Navin Sankar Velliangiri <[email protected]>Cc Paresh Chaudhary <[email protected]>
Except for the above correction, the patch looks OK to me.
Quoted 87 lines
--- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 12 ------- .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ 3 files changed, 18 insertions(+), 43 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 deleted +0
-31@@ -1,31 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_oc -KernelVersion: 5.1 -Contact: [email protected] -Description: - Open-circuit fault. The detection of open-circuit faults, - such as those caused by broken thermocouple wires. - Reading returns either '1' or '0'. - - === ======================================================= - '1' An open circuit such as broken thermocouple wires - has been detected. - '0' No open circuit or broken thermocouple wires are detected - === ======================================================= - -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.1 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input Fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables by integrated MOSFETs at the T+ and T- inputs, and the - BIAS output. These MOSFETs turn off when the input voltage is - negative or greater than VDD. - - Reading returns either '1' or '0'. - - === ======================================================= - '1' The input voltage is negative or greater than VDD. - '0' The input voltage is positive and less than VDD (normal - state). - === =======================================================Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 +0
-12@@ -1,15 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.11 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables at FORCE+, FORCE2, RTDIN+ & RTDIN-. This circuitry turn - off when the input voltage is negative or greater than VDD. - - Reading returns '1' if input voltage is negative or greater - than VDD, otherwise '0'. - What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency KernelVersion: 5.11 Contact: [email protected]Documentation/ABI/testing/sysfs-bus-iio-thermocouple new file +18
-0@@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: [email protected] +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables. The device can also detect if such a condition occurs. + + Reading returns '1' if input voltage is negative or greater + than VDD, otherwise '0'. + +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: [email protected] +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns '1' if fault, '0' otherwise.
Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.
Quoted 15 lines · On Sun, 26 Jun 2022 23:33:31 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:08 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 4 lines
From: Jonathan Cameron <[email protected]>
The kernel build docs do not support having multiple definitions for the same sysfs filename.
Actually, this is not a matter of the docs build system not supporting. It is, instead, how the ABI were supposed to work: a given ABI symbol should have consistent behavior on all drivers that use it. Failing to do that is asking for troubles.
So, having duplicated symbols either mean that:
Quoted 7 lines
a) both have the same meaning. They can/should be unified in order to remove redundant documentation;
b) the same ABI symbol have different meanings depending on the driver(s) that use it. This makes very hard for userspace, as it is harder to write a program using it, as the behavior/meaning starts to be driver-dependent.
I think we'll disagree on this.
There are circumstances where a particular ABI in a particular driver benefits from additional documentation that would be in the 'impdef category' for the generic ABI.
For this particular case it extends the info available from 'wire disconnected' in the generic case, to 'which possible wires are disconnected' in the specific case. Neither affects what userspace does with it, but they are useful if you are debugging the hardware. They are probably not worth expanding the ABI to provide a debugging guide, so it that info was in the documentation but is now lost (in this case, non critical as it's probably a case of go read the
datasheet if the hanging wire isn't obvious).
I don't mind just making this patch description vague:
Kernel documentation for a given ABI element should not be duplicated in multiple files, so pull them into one higher level documentation file.
Quoted 104 lines
Quoted 6 lines
Hence generalize the documentation a little
and pull it out of device specific files and into
sysfs-bus-iio-thermocoupleQuoted 6 lines
These may well be more general and need pulling into a more generic file in the future, but we can do that when it is needed.
Signed-off-by Jonathan Cameron <[email protected]>Cc Navin Sankar Velliangiri <[email protected]>Cc Paresh Chaudhary <[email protected]>Except for the above correction, the patch looks OK to me.
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 87 lines
--- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 12 ------- .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ 3 files changed, 18 insertions(+), 43 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 deleted +0
-31@@ -1,31 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_oc -KernelVersion: 5.1 -Contact: [email protected] -Description: - Open-circuit fault. The detection of open-circuit faults, - such as those caused by broken thermocouple wires. - Reading returns either '1' or '0'. - - === ======================================================= - '1' An open circuit such as broken thermocouple wires - has been detected. - '0' No open circuit or broken thermocouple wires are detected - === ======================================================= - -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.1 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input Fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables by integrated MOSFETs at the T+ and T- inputs, and the - BIAS output. These MOSFETs turn off when the input voltage is - negative or greater than VDD. - - Reading returns either '1' or '0'. - - === ======================================================= - '1' The input voltage is negative or greater than VDD. - '0' The input voltage is positive and less than VDD (normal - state). - === =======================================================Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 +0
-12@@ -1,15 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.11 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables at FORCE+, FORCE2, RTDIN+ & RTDIN-. This circuitry turn - off when the input voltage is negative or greater than VDD. - - Reading returns '1' if input voltage is negative or greater - than VDD, otherwise '0'. - What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency KernelVersion: 5.11 Contact: [email protected]Documentation/ABI/testing/sysfs-bus-iio-thermocouple new file +18
-0@@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: [email protected] +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables. The device can also detect if such a condition occurs. + + Reading returns '1' if input voltage is negative or greater + than VDD, otherwise '0'. + +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: [email protected] +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns '1' if fault, '0' otherwise.
Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.
Em Mon, 27 Jun 2022 15:18:12 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 26 lines
Quoted 15 lines · On Sun, 26 Jun 2022 23:33:31 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:08 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 4 lines
From: Jonathan Cameron <[email protected]>
The kernel build docs do not support having multiple definitions for the same sysfs filename.
Actually, this is not a matter of the docs build system not supporting. It is, instead, how the ABI were supposed to work: a given ABI symbol should have consistent behavior on all drivers that use it. Failing to do that is asking for troubles.
So, having duplicated symbols either mean that:
Quoted 7 lines
a) both have the same meaning. They can/should be unified in order to remove redundant documentation;
b) the same ABI symbol have different meanings depending on the driver(s) that use it. This makes very hard for userspace, as it is harder to write a program using it, as the behavior/meaning starts to be driver-dependent.
Quoted 5 lines
I think we'll disagree on this.
There are circumstances where a particular ABI in a particular driver benefits from additional documentation that would be in the 'impdef category' for the generic ABI.
If a particular driver needs something different, either:
1. the ABI definition was loose or too tight, not being generic enough to cover other hardware needing ABI for the same feature;
2. a different ABI symbol would need, as the two symbols with the same name are mapping completely different ABIs.
Quoted 3 lines
For this particular case it extends the info available from 'wire disconnected' in the generic case, to 'which possible wires are disconnected' in the specific case.
In the specific case of device faults, it could be mapped in a way that would be generic enough, yet providing hardware-specific information, when the hardware supports it.
In this specific case, I would probably create a generic ABI (or ABI set) to report hardware issues in a way that it would be more generic.
One possibility for this case would be to use something like this:
$ cat /sys/bus/iio/devices/iio:deviceX/fault no faults
On hardware that can't pinpoint what wire(s) the problem is occurring:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuit
or
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: excessive voltage
On more sophisticated hardware that can pinpoint what wires have issues, it may report, instead:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuit fault at thermocouple wire #2
or
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: excessive voltage at thermocouple wires #0 and #1
or even:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuit fault at thermocouple wire #2 fault: excessive voltage at thermocouple wires #0 and #1
The above should be generic enough for a program to identify if there isn't any failures if such "fault" ABI would return "no faults". Any value different than that means that there's a fault, and the read value telling what happened could be output to the user before such program aborts due to a hardware error.
-
The point is that, when the ABI is made to be subsystem-wide since the beginning, it tends to be more generic, as the ABI design should consider that other devices may have different capabilities.
Quoted 11 lines
Neither affects what userspace
does with it, but they are useful if you are debugging the hardware. They are probably not worth expanding the ABI to provide a debugging guide, so it that info was in the documentation but is now lost (in this case, non critical as it's probably a case of go read the
datasheet if the hanging wire isn't obvious).I don't mind just making this patch description vague:
Kernel documentation for a given ABI element should not be duplicated in multiple files, so pull them into one higher level documentation file.
Works for me. With that, feel free to add my reviewed-by.
Regards,
Mauro
Quoted 103 lines
Quoted 102 lines
Quoted 10 lines
Hence generalize the documentation a little
and pull it out of device specific files and into
sysfs-bus-iio-thermocoupleThese may well be more general and need pulling into a more generic file in the future, but we can do that when it is needed.
Signed-off-by Jonathan Cameron <[email protected]>Cc Navin Sankar Velliangiri <[email protected]>Cc Paresh Chaudhary <[email protected]>Except for the above correction, the patch looks OK to me.
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 87 lines
--- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 12 ------- .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ 3 files changed, 18 insertions(+), 43 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 deleted +0
-31@@ -1,31 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_oc -KernelVersion: 5.1 -Contact: [email protected] -Description: - Open-circuit fault. The detection of open-circuit faults, - such as those caused by broken thermocouple wires. - Reading returns either '1' or '0'. - - === ======================================================= - '1' An open circuit such as broken thermocouple wires - has been detected. - '0' No open circuit or broken thermocouple wires are detected - === ======================================================= - -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.1 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input Fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables by integrated MOSFETs at the T+ and T- inputs, and the - BIAS output. These MOSFETs turn off when the input voltage is - negative or greater than VDD. - - Reading returns either '1' or '0'. - - === ======================================================= - '1' The input voltage is negative or greater than VDD. - '0' The input voltage is positive and less than VDD (normal - state). - === =======================================================Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 +0
-12@@ -1,15 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.11 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables at FORCE+, FORCE2, RTDIN+ & RTDIN-. This circuitry turn - off when the input voltage is negative or greater than VDD. - - Reading returns '1' if input voltage is negative or greater - than VDD, otherwise '0'. - What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency KernelVersion: 5.11 Contact: [email protected]Documentation/ABI/testing/sysfs-bus-iio-thermocouple new file +18
-0@@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: [email protected] +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables. The device can also detect if such a condition occurs. + + Reading returns '1' if input voltage is negative or greater + than VDD, otherwise '0'. + +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: [email protected] +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns '1' if fault, '0' otherwise.
Jonathan Cameron
maintainerRe: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.
Quoted 103 lines · On Tue, 28 Jun 2022 07:44:09 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Mon, 27 Jun 2022 15:18:12 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 26 lines
Quoted 15 lines · On Sun, 26 Jun 2022 23:33:31 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:08 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 4 lines
From: Jonathan Cameron <[email protected]>
The kernel build docs do not support having multiple definitions for the same sysfs filename.
Actually, this is not a matter of the docs build system not supporting. It is, instead, how the ABI were supposed to work: a given ABI symbol should have consistent behavior on all drivers that use it. Failing to do that is asking for troubles.
So, having duplicated symbols either mean that:
Quoted 7 lines
a) both have the same meaning. They can/should be unified in order to remove redundant documentation;
b) the same ABI symbol have different meanings depending on the driver(s) that use it. This makes very hard for userspace, as it is harder to write a program using it, as the behavior/meaning starts to be driver-dependent.
Quoted 5 lines
I think we'll disagree on this.
There are circumstances where a particular ABI in a particular driver benefits from additional documentation that would be in the 'impdef category' for the generic ABI.
If a particular driver needs something different, either:
1. the ABI definition was loose or too tight, not being generic enough to cover other hardware needing ABI for the same feature;
2. a different ABI symbol would need, as the two symbols with the same name are mapping completely different ABIs.Quoted 3 lines
For this particular case it extends the info available from 'wire disconnected' in the generic case, to 'which possible wires are disconnected' in the specific case.
In the specific case of device faults, it could be mapped in a way that would be generic enough, yet providing hardware-specific information, when the hardware supports it.
In this specific case, I would probably create a generic ABI (or ABI set) to report hardware issues in a way that it would be more generic.
One possibility for this case would be to use something like this:
$ cat /sys/bus/iio/devices/iio:deviceX/fault no faultsOn hardware that can't pinpoint what wire(s) the problem is occurring:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuitor
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: excessive voltageOn more sophisticated hardware that can pinpoint what wires have issues, it may report, instead:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuit fault at thermocouple wire #2or
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: excessive voltage at thermocouple wires #0 and #1or even:
$ cat /sys/bus/iio/devices/iio:deviceX/fault fault: open circuit fault at thermocouple wire #2 fault: excessive voltage at thermocouple wires #0 and #1The above should be generic enough for a program to identify if there isn't any failures if such "fault" ABI would return "no faults". Any value different than that means that there's a fault, and the read value telling what happened could be output to the user before such program aborts due to a hardware error.
-
The point is that, when the ABI is made to be subsystem-wide since the beginning, it tends to be more generic, as the ABI design should consider that other devices may have different capabilities.
Quoted 7 lines
Neither affects what userspace
does with it, but they are useful if you are debugging the hardware. They are probably not worth expanding the ABI to provide a debugging guide, so it that info was in the documentation but is now lost (in this case, non critical as it's probably a case of go read the
datasheet if the hanging wire isn't obvious).
Quoted 6 lines
Quoted 4 lines
I don't mind just making this patch description vague:
Kernel documentation for a given ABI element should not be duplicated in multiple files, so pull them into one higher level documentation file.
Works for me. With that, feel free to add my reviewed-by.
Applied - hopefully I'll sneak out a pull request later this week. Apologies for delay. I blame Covid.
J
Quoted 107 lines
Regards,
MauroQuoted 103 lines
Quoted 102 lines
Quoted 10 lines
Hence generalize the documentation a little
and pull it out of device specific files and into
sysfs-bus-iio-thermocoupleThese may well be more general and need pulling into a more generic file in the future, but we can do that when it is needed.
Signed-off-by Jonathan Cameron <[email protected]>Cc Navin Sankar Velliangiri <[email protected]>Cc Paresh Chaudhary <[email protected]>Except for the above correction, the patch looks OK to me.
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 87 lines
--- .../sysfs-bus-iio-temperature-max31856 | 31 ------------------- .../sysfs-bus-iio-temperature-max31865 | 12 ------- .../ABI/testing/sysfs-bus-iio-thermocouple | 18 +++++++++++ 3 files changed, 18 insertions(+), 43 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 deleted +0
-31@@ -1,31 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_oc -KernelVersion: 5.1 -Contact: [email protected] -Description: - Open-circuit fault. The detection of open-circuit faults, - such as those caused by broken thermocouple wires. - Reading returns either '1' or '0'. - - === ======================================================= - '1' An open circuit such as broken thermocouple wires - has been detected. - '0' No open circuit or broken thermocouple wires are detected - === ======================================================= - -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.1 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input Fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables by integrated MOSFETs at the T+ and T- inputs, and the - BIAS output. These MOSFETs turn off when the input voltage is - negative or greater than VDD. - - Reading returns either '1' or '0'. - - === ======================================================= - '1' The input voltage is negative or greater than VDD. - '0' The input voltage is positive and less than VDD (normal - state). - === =======================================================Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 +0
-12@@ -1,15 +1,3 @@ -What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv -KernelVersion: 5.11 -Contact: [email protected] -Description: - Overvoltage or Undervoltage Input fault. The internal circuitry - is protected from excessive voltages applied to the thermocouple - cables at FORCE+, FORCE2, RTDIN+ & RTDIN-. This circuitry turn - off when the input voltage is negative or greater than VDD. - - Reading returns '1' if input voltage is negative or greater - than VDD, otherwise '0'. - What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency KernelVersion: 5.11 Contact: [email protected]Documentation/ABI/testing/sysfs-bus-iio-thermocouple new file +18
-0@@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/iio:deviceX/fault_ovuv +KernelVersion: 5.1 +Contact: [email protected] +Description: + Overvoltage or Undervoltage Input Fault. The internal circuitry + is protected from excessive voltages applied to the thermocouple + cables. The device can also detect if such a condition occurs. + + Reading returns '1' if input voltage is negative or greater + than VDD, otherwise '0'. + +What: /sys/bus/iio/devices/iio:deviceX/fault_oc +KernelVersion: 5.1 +Contact: [email protected] +Description: + Open-circuit fault. The detection of open-circuit faults, + such as those caused by broken thermocouple wires. + Reading returns '1' if fault, '0' otherwise.
Jonathan Cameron
maintainerPATCH 2/4 iio: ABI: max31865: Drop in_filter_notch_centre_frequency as in main docs.
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
As this is the last element in the file, also delete the file.
--- .../ABI/testing/sysfs-bus-iio-temperature-max31865 | 8 -------- 1 file changed, 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 deleted +0 -8
@@ -1,8 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency -KernelVersion: 5.11 -Contact: [email protected] -Description: - Notch frequency in Hz for a noise rejection filter. Used i.e for - line noise rejection. - - Valid notch filter values are 50 Hz and 60 Hz.
Signature · 1 line
2.36.1
Re: [PATCH 2/4] iio: ABI: max31865: Drop in_filter_notch_centre_frequency as in main docs.
Em Sun, 26 Jun 2022 17:55:09 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 5 lines
From: Jonathan Cameron <[email protected]>
As this is the last element in the file, also delete the file.
Signed-off-by Jonathan Cameron <[email protected]>
Quoted 19 lines
Cc Navin Sankar Velliangiri <[email protected]>--- .../ABI/testing/sysfs-bus-iio-temperature-max31865 | 8 -------- 1 file changed, 8 deletions(-)Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 deleted +0
-8@@ -1,8 +0,0 @@ -What: /sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency -KernelVersion: 5.11 -Contact: [email protected] -Description: - Notch frequency in Hz for a noise rejection filter. Used i.e for - line noise rejection. - - Valid notch filter values are 50 Hz and 60 Hz.
Jonathan Cameron
maintainerPATCH 3/4 iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
We can't duplicate the description of sampling_frequency. This device has some unusual requirements which we solved by giving a sampling_frequency of 0 special meaning. As such add a note about this unusual usage to the main documentation.
Whilst I don't particularly like this resolution, it is the best I could come up with given earlier discussion on this topic.
--- Documentation/ABI/testing/sysfs-bus-iio | 3 +++ Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +3 -0
@@ -107,6 +107,9 @@ Description: relevant directories. If it affects all of the above then it is to be found in the base device directory. + The stm32-timer-trigger has the additional characteristic that + a sampling_frequency of 0 is defined to stop sampling. + What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_proximity_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.36.1
Re: [PATCH 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 23 lines
From: Jonathan Cameron <[email protected]>
We can't duplicate the description of
sampling_frequency. This device has some unusual requirements which we solved by giving asampling_frequencyof 0 special meaning. As such add a note about this unusual usage to the main documentation.Whilst I don't particularly like this resolution, it is the best I could come up with given earlier discussion on this topic.
Signed-off-by Jonathan Cameron <[email protected]>Cc Fabrice Gasnier <[email protected]>--- Documentation/ABI/testing/sysfs-bus-iio | 3 +++ Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-)Documentation/ABI/testing/sysfs-bus-iio +0
-0
Documentation/ABI/testing/sysfs-bus-iio Description: · line 112
Quoted 6 lines
Documentation/ABI/testing/sysfs-bus-iio +3
-0@@ -107,6 +107,9 @@ Description: relevant directories. If it affects all of the above then it is to be found in the base device directory. + The stm32-timer-trigger has the additional characteristic that + a sampling_frequency of 0 is defined to stop sampling. +
I would actually say something like:
A ampling_frequency of 0 means to stop sampling, if supported by the driver.
Either way:
Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0
-0What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_proximity_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: [PATCH 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
Quoted 29 lines · On Sun, 26 Jun 2022 23:37:45 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 26 lines
From: Jonathan Cameron <[email protected]>
We can't duplicate the description of
sampling_frequency. This device has some unusual requirements which we solved by giving asampling_frequencyof 0 special meaning. As such add a note about this unusual usage to the main documentation.Whilst I don't particularly like this resolution, it is the best I could come up with given earlier discussion on this topic.
Signed-off-by Jonathan Cameron <[email protected]>Cc Fabrice Gasnier <[email protected]>--- Documentation/ABI/testing/sysfs-bus-iio | 3 +++ Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-)Documentation/ABI/testing/sysfs-bus-iio +0
-0@@ -107,6 +107,9 @@ Description: relevant directories. If it affects all of the above then it is to be found in the base device directory.
Quoted 9 lines
Documentation/ABI/testing/sysfs-bus-iio Description: · line 112
Quoted 3 lines
Documentation/ABI/testing/sysfs-bus-iio +3
-0+ The stm32-timer-trigger has the additional characteristic that + a sampling_frequency of 0 is defined to stop sampling. +I would actually say something like:
A
ampling_frequencyof 0 means to stop sampling, if supported by the driver.
We actively want to stop people doing this without coming to the list and explaining exactly why they need to. The discussion around that one exception was long and involved. So we want them to have to modify this doc to list their part thus raising awareness of them doing this. So far it's in one driver our of many (and to use this feature it needs custom userspace as it is setting up a complex chain of devices, but for other more conventional use, not allowing 0 is fine).
The source of this disagreement is the documentation serves two purposes - for userspace code authors and for kernel developers. Userspace can just not set the value to 0 if it is generic code.
We could add additional ABI element to make userspace aware, but so far only this one device which will run with customer userspace uses this. Hence we rely on documentation.
Jonathan
Quoted 27 lines
Either way:
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0
-0What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_proximity_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: [PATCH 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
Em Mon, 27 Jun 2022 15:09:55 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 51 lines
Quoted 29 lines · On Sun, 26 Jun 2022 23:37:45 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 26 lines
From: Jonathan Cameron <[email protected]>
We can't duplicate the description of
sampling_frequency. This device has some unusual requirements which we solved by giving asampling_frequencyof 0 special meaning. As such add a note about this unusual usage to the main documentation.Whilst I don't particularly like this resolution, it is the best I could come up with given earlier discussion on this topic.
Signed-off-by Jonathan Cameron <[email protected]>Cc Fabrice Gasnier <[email protected]>--- Documentation/ABI/testing/sysfs-bus-iio | 3 +++ Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-)Documentation/ABI/testing/sysfs-bus-iio +0
-0@@ -107,6 +107,9 @@ Description: relevant directories. If it affects all of the above then it is to be found in the base device directory.Quoted 9 lines
Documentation/ABI/testing/sysfs-bus-iio Description: · line 112
Quoted 3 lines
Documentation/ABI/testing/sysfs-bus-iio +3
-0+ The stm32-timer-trigger has the additional characteristic that + a sampling_frequency of 0 is defined to stop sampling. +I would actually say something like:
A
ampling_frequencyof 0 means to stop sampling, if supported by the driver.We actively want to stop people doing this without coming to the list and explaining exactly why they need to. The discussion around that one exception was long and involved. So we want them to have to modify this doc to list their part thus raising awareness of them doing this. So far it's in one driver our of many (and to use this feature it needs custom userspace as it is setting up a complex chain of devices, but for other more conventional use, not allowing 0 is fine).
Quoted 7 lines
The source of this disagreement is the documentation serves two purposes - for userspace code authors and for kernel developers. Userspace can just not set the value to 0 if it is generic code.
We could add additional ABI element to make userspace aware, but so far only this one device which will run with customer userspace uses this. Hence we rely on documentation.
OK!
This actually proves the point that duplicated symbols at ABI cause troubles, as different implementations could end abusing on what it would be expected, like in this case ;-)
Anyway, feel free to add my reviewed-by to this patch.
Regards,
Mauro
Quoted 31 lines
Jonathan
Quoted 27 lines
Either way:
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0
-0What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_proximity_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]
Jonathan Cameron
maintainerRe: [PATCH 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.
Quoted 63 lines · On Tue, 28 Jun 2022 06:51:19 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Mon, 27 Jun 2022 15:09:55 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 51 lines
Quoted 29 lines · On Sun, 26 Jun 2022 23:37:45 +0100 Mauro Carvalho Chehab <[email protected]>…
Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <[email protected]> escreveu:Quoted 26 lines
From: Jonathan Cameron <[email protected]>
We can't duplicate the description of
sampling_frequency. This device has some unusual requirements which we solved by giving asampling_frequencyof 0 special meaning. As such add a note about this unusual usage to the main documentation.Whilst I don't particularly like this resolution, it is the best I could come up with given earlier discussion on this topic.
Signed-off-by Jonathan Cameron <[email protected]>Cc Fabrice Gasnier <[email protected]>--- Documentation/ABI/testing/sysfs-bus-iio | 3 +++ Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 -------- 2 files changed, 3 insertions(+), 8 deletions(-)Documentation/ABI/testing/sysfs-bus-iio +0
-0@@ -107,6 +107,9 @@ Description: relevant directories. If it affects all of the above then it is to be found in the base device directory.Quoted 9 lines
Documentation/ABI/testing/sysfs-bus-iio Description: · line 112
Quoted 3 lines
Documentation/ABI/testing/sysfs-bus-iio +3
-0+ The stm32-timer-trigger has the additional characteristic that + a sampling_frequency of 0 is defined to stop sampling. +I would actually say something like:
A
ampling_frequencyof 0 means to stop sampling, if supported by the driver.We actively want to stop people doing this without coming to the list and explaining exactly why they need to. The discussion around that one exception was long and involved. So we want them to have to modify this doc to list their part thus raising awareness of them doing this. So far it's in one driver our of many (and to use this feature it needs custom userspace as it is setting up a complex chain of devices, but for other more conventional use, not allowing 0 is fine).
Quoted 7 lines
The source of this disagreement is the documentation serves two purposes - for userspace code authors and for kernel developers. Userspace can just not set the value to 0 if it is generic code.
We could add additional ABI element to make userspace aware, but so far only this one device which will run with customer userspace uses this. Hence we rely on documentation.
Quoted 7 lines
OK!
This actually proves the point that duplicated symbols at ABI cause troubles, as different implementations could end abusing on what it would be expected, like in this case ;-)
Anyway, feel free to add my reviewed-by to this patch.
Picked up 2 and 3 of this series. 4 was fixed by someone else.
Thanks,
Jonathan
Quoted 35 lines
Regards,
MauroQuoted 31 lines
Jonathan
Quoted 27 lines
Either way:
Reviewed-by Mauro Carvalho Chehab <[email protected]>Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0
-0What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_intensity_sampling_frequency_available What: /sys/bus/iio/devices/iio:deviceX/in_proximity_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]
Jonathan Cameron
maintainerPATCH 4/4 iio: ABI: sx9324: Squash some formatting to keep scripting happy.
In reply to Jonathan CameronFrom: Jonathan Cameron <[email protected]>
The indenting added in here to give bullet points is nice to read but unfortunately our docs building scripts trip up on it.
make htmldocs gives ../iio/Documentation/ABI/testing/sysfs-bus-iio-sx9324:2: ERROR: Unexpected indentation.
So drop the pretty indenting to avoid that error message.
--- Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-bus-iio-sx9324 +1 -1
@@ -8,7 +8,7 @@ Description: + not connected (HZ), + grounded (GD), + connected to an antenna where it can act as a base - (DS - data shield), or measured input (MI). + (DS - data shield), or measured input (MI). The sensor rotates measurement across 4 phases (PH0, PH1, PH2, PH3), where the inputs are configured
Signature · 1 line
2.36.1
Re: [PATCH 4/4] iio: ABI: sx9324: Squash some formatting to keep scripting happy.
Em Sun, 26 Jun 2022 17:55:11 +0100
Jonathan Cameron <[email protected]> escreveu:
Quoted 21 lines
From: Jonathan Cameron <[email protected]>
The indenting added in here to give bullet points is nice to read but unfortunately our docs building scripts trip up on it.
make htmldocs gives ../iio/Documentation/ABI/testing/sysfs-bus-iio-sx9324:2: ERROR: Unexpected indentation.
So drop the pretty indenting to avoid that error message.
Signed-off-by Jonathan Cameron <[email protected]>Cc Gwendal Grignou <[email protected]>--- Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/ABI/testing/sysfs-bus-iio-sx9324 +0
-0
Documentation/ABI/testing/sysfs-bus-iio-sx9324 Description: · line 11
Quoted 5 lines
Documentation/ABI/testing/sysfs-bus-iio-sx9324 +1
-1@@ -8,7 +8,7 @@ Description: + not connected (HZ), + grounded (GD), + connected to an antenna where it can act as a base - (DS - data shield), or measured input (MI). + (DS - data shield), or measured input (MI).
Actually, the fix would be to simply add a blank line before the list, e. g.:
Documentation/ABI/testing/sysfs-bus-iio-sx9324 +1 -0
@@ -5,6 +5,7 @@ Contact: Gwendal Grignou <[email protected]> Description: SX9324 has 3 inputs, CS0, CS1 and CS2. Hardware layout defines if the input is + + not connected (HZ), + grounded (GD), + connected to an antenna where it can act as a base
Regards,
Mauro