Skip to contentSkip to conversation

IIO: Some documentation error and warning fixes.

PATCH In review Jonathan Cameron 3 participants 15 messages Jun 26, 2022 – Jul 18, 2022

Subsystems (3)
lore
Share & tools
lore

Jonathan Cameron

author maintainer
#0 lore raw

cover 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
author maintainer
#1 lore raw

PATCH 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.

Cc Navin Sankar Velliangiri <[email protected]>
Cc Paresh Chaudhary <[email protected]>
---
 .../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
deleted file mode 100644
index e5ef6d8e5da1..000000000000
@@ -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
index 4b072da92218..349089e4f2d6 100644
@@ -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
new file mode 100644
index 000000000000..01259df297ca
@@ -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
Reviewed-by on v1 1/4
#2 lore raw

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-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.

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
deleted file mode 100644
index e5ef6d8e5da1..000000000000
@@ -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
index 4b072da92218..349089e4f2d6 100644
@@ -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
new file mode 100644
index 000000000000..01259df297ca
@@ -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.
#3 lore raw

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-thermocouple

Quoted 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.

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
deleted file mode 100644
index e5ef6d8e5da1..000000000000
@@ -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
index 4b072da92218..349089e4f2d6 100644
@@ -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
new file mode 100644
index 000000000000..01259df297ca
@@ -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.  
#4 lore raw

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-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.

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
deleted file mode 100644
index e5ef6d8e5da1..000000000000
@@ -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
index 4b072da92218..349089e4f2d6 100644
@@ -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
new file mode 100644
index 000000000000..01259df297ca
@@ -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.    
author maintainer
#5 lore raw

Re: [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 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 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,
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-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.

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
deleted file mode 100644
index e5ef6d8e5da1..000000000000
@@ -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
index 4b072da92218..349089e4f2d6 100644
@@ -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
new file mode 100644
index 000000000000..01259df297ca
@@ -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.      
author maintainer
#6 lore raw

PATCH 2/4 iio: ABI: max31865: Drop in_filter_notch_centre_frequency as in main docs.

In reply to Jonathan Cameron

From: Jonathan Cameron <[email protected]>

As this is the last element in the file, also delete the file.

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
deleted file mode 100644
index 349089e4f2d6..000000000000
@@ -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
Reviewed-by on v1 2/4
#7 lore raw

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.

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
deleted file mode 100644
index 349089e4f2d6..000000000000
@@ -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.
author maintainer
#8 lore raw

PATCH 3/4 iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.

In reply to Jonathan Cameron

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 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
index 3e00d7f7ee22..e81ba6f5e1c8 100644
@@ -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
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]
Signature · 1 line
2.36.1
Reviewed-by on v1 3/4
#9 lore raw

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 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 +0 -0
index 3e00d7f7ee22..e81ba6f5e1c8 100644

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 -0
 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
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]
#10 lore raw

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 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 +0 -0
index 3e00d7f7ee22..e81ba6f5e1c8 100644
@@ -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_frequency of 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:

Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0 -0
 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
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]  
#11 lore raw

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 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 +0 -0
index 3e00d7f7ee22..e81ba6f5e1c8 100644
@@ -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_frequency of 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:

Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0 -0
 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
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]    
author maintainer
#12 lore raw

Re: [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 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 +0 -0
index 3e00d7f7ee22..e81ba6f5e1c8 100644
@@ -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_frequency of 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,
Mauro

Quoted 31 lines

Jonathan

Quoted 27 lines

Either way:

Quoted 22 lines
Documentation/ABI/testing/sysfs-bus-iio +0 -0
 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
index c4a4497c249a..05074c4a65e2 100644
@@ -90,14 +90,6 @@ Description:
 		Reading returns the current master modes.
 		Writing set the master mode
 
-What:		/sys/bus/iio/devices/triggerX/sampling_frequency
-KernelVersion:	4.11
-Contact:	[email protected]
-Description:
-		Reading returns the current sampling frequency.
-		Writing an value different of 0 set and start sampling.
-		Writing 0 stop sampling.
-
 What:		/sys/bus/iio/devices/iio:deviceX/in_count0_preset
 KernelVersion:	4.12
 Contact:	[email protected]      
author maintainer
#13 lore raw

PATCH 4/4 iio: ABI: sx9324: Squash some formatting to keep scripting happy.

In reply to Jonathan Cameron

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.

---
 Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-bus-iio-sx9324 +1 -1
index 632e3321f5a3..9c1e8884a738 100644
@@ -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
#14 lore raw

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.

---
 Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/ABI/testing/sysfs-bus-iio-sx9324 +0 -0
index 632e3321f5a3..9c1e8884a738 100644

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
index 632e3321f5a3..a8342770e7cb 100644
@@ -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