[PATCH 0/4] IIO: Some documentation error and warning fixes.

[PATCH 0/4] IIO: Some documentation error and warning fixes.

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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/20220626085524.42ee92c0@sal.lan/

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

-- 
2.36.1

[PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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.

Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Navin Sankar Velliangiri <navin@linumiz.com>
Cc: Paresh Chaudhary <paresh.chaudhary@rockwellcollins.com>
---
 .../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(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
deleted file mode 100644
index e5ef6d8e5da1..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
+++ /dev/null
@@ -1,31 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/fault_oc
-KernelVersion:	5.1
-Contact:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
-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).
-		===  =======================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
index 4b072da92218..349089e4f2d6 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
+++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
@@ -1,15 +1,3 @@
-What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
-KernelVersion:	5.11
-Contact:	linux-iio@vger.kernel.org
-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:	linux-iio@vger.kernel.org
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
new file mode 100644
index 000000000000..01259df297ca
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
@@ -0,0 +1,18 @@
+What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
+KernelVersion:	5.1
+Contact:	linux-iio@vger.kernel.org
+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:	linux-iio@vger.kernel.org
+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.
-- 
2.36.1

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

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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

Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Navin Sankar Velliangiri <navin@linumiz.com>
---
 .../ABI/testing/sysfs-bus-iio-temperature-max31865        | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
deleted file mode 100644
index 349089e4f2d6..000000000000
--- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
+++ /dev/null
@@ -1,8 +0,0 @@
-What:		/sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency
-KernelVersion:	5.11
-Contact:	linux-iio@vger.kernel.org
-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.
-- 
2.36.1

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

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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.

Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
---
 Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
 Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 3e00d7f7ee22..e81ba6f5e1c8 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -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
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
index c4a4497c249a..05074c4a65e2 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -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:	benjamin.gaignard@st.com
-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:	benjamin.gaignard@st.com
-- 
2.36.1

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

[Jonathan Cameron]

From: Jonathan Cameron <Jonathan.Cameron@huawei.com>

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 <Jonathan.Cameron@huawei.com>
Cc: Gwendal Grignou <gwendal@chromium.org>
---
 Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sx9324 b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
index 632e3321f5a3..9c1e8884a738 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-sx9324
+++ b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
@@ -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
-- 
2.36.1

Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.

[Mauro Carvalho Chehab]

Em Sun, 26 Jun 2022 17:55:08 +0100
Jonathan Cameron <jic23@kernel.org> escreveu:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> 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.


>  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.
> 
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> Cc: Navin Sankar Velliangiri <navin@linumiz.com>
> Cc: Paresh Chaudhary <paresh.chaudhary@rockwellcollins.com>

Except for the above correction, the patch looks OK to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>

> ---
>  .../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(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> deleted file mode 100644
> index e5ef6d8e5da1..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> +++ /dev/null
> @@ -1,31 +0,0 @@
> -What:		/sys/bus/iio/devices/iio:deviceX/fault_oc
> -KernelVersion:	5.1
> -Contact:	linux-iio@vger.kernel.org
> -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:	linux-iio@vger.kernel.org
> -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).
> -		===  =======================================================
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> index 4b072da92218..349089e4f2d6 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> @@ -1,15 +1,3 @@
> -What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> -KernelVersion:	5.11
> -Contact:	linux-iio@vger.kernel.org
> -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:	linux-iio@vger.kernel.org
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> new file mode 100644
> index 000000000000..01259df297ca
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> @@ -0,0 +1,18 @@
> +What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> +KernelVersion:	5.1
> +Contact:	linux-iio@vger.kernel.org
> +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:	linux-iio@vger.kernel.org
> +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 2/4] iio: ABI: max31865: Drop in_filter_notch_centre_frequency as in main docs.

[Mauro Carvalho Chehab]

Em Sun, 26 Jun 2022 17:55:09 +0100
Jonathan Cameron <jic23@kernel.org> escreveu:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> As this is the last element in the file, also delete the file.
> 
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>

> Cc: Navin Sankar Velliangiri <navin@linumiz.com>
> ---
>  .../ABI/testing/sysfs-bus-iio-temperature-max31865        | 8 --------
>  1 file changed, 8 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> deleted file mode 100644
> index 349089e4f2d6..000000000000
> --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> +++ /dev/null
> @@ -1,8 +0,0 @@
> -What:		/sys/bus/iio/devices/iio:deviceX/in_filter_notch_center_frequency
> -KernelVersion:	5.11
> -Contact:	linux-iio@vger.kernel.org
> -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.

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

[Mauro Carvalho Chehab]

Em Sun, 26 Jun 2022 17:55:10 +0100
Jonathan Cameron <jic23@kernel.org> escreveu:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> 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.
> 
> Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
>  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
>  2 files changed, 3 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 3e00d7f7ee22..e81ba6f5e1c8 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -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:

Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>


>  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
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> index c4a4497c249a..05074c4a65e2 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> @@ -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:	benjamin.gaignard@st.com
> -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:	benjamin.gaignard@st.com

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

[Mauro Carvalho Chehab]

Em Sun, 26 Jun 2022 17:55:11 +0100
Jonathan Cameron <jic23@kernel.org> escreveu:

> From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> 
> 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 <Jonathan.Cameron@huawei.com>
> Cc: Gwendal Grignou <gwendal@chromium.org>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio-sx9324 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sx9324 b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
> index 632e3321f5a3..9c1e8884a738 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-sx9324
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
> @@ -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.:

diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sx9324 b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
index 632e3321f5a3..a8342770e7cb 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-sx9324
+++ b/Documentation/ABI/testing/sysfs-bus-iio-sx9324
@@ -5,6 +5,7 @@ Contact:	Gwendal Grignou <gwendal@chromium.org>
 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

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

[Jonathan Cameron]

On Sun, 26 Jun 2022 23:37:45 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> wrote:

> Em Sun, 26 Jun 2022 17:55:10 +0100
> Jonathan Cameron <jic23@kernel.org> escreveu:
> 
> > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > 
> > 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.
> > 
> > Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
> > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
> >  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> >  2 files changed, 3 insertions(+), 8 deletions(-)
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index 3e00d7f7ee22..e81ba6f5e1c8 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -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.
> 

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

> Either way:
> 
> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> 
> 
> >  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
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > index c4a4497c249a..05074c4a65e2 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > @@ -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:	benjamin.gaignard@st.com
> > -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:	benjamin.gaignard@st.com  

Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.

[Jonathan Cameron]

On Sun, 26 Jun 2022 23:33:31 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> wrote:

> Em Sun, 26 Jun 2022 17:55:08 +0100
> Jonathan Cameron <jic23@kernel.org> escreveu:
> 
> > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > 
> > 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.

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.



> 
> 
> >  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.
> > 
> > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > Cc: Navin Sankar Velliangiri <navin@linumiz.com>
> > Cc: Paresh Chaudhary <paresh.chaudhary@rockwellcollins.com>  
> 
> Except for the above correction, the patch looks OK to me.
> 
> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> 
> > ---
> >  .../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(-)
> > 
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > deleted file mode 100644
> > index e5ef6d8e5da1..000000000000
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > +++ /dev/null
> > @@ -1,31 +0,0 @@
> > -What:		/sys/bus/iio/devices/iio:deviceX/fault_oc
> > -KernelVersion:	5.1
> > -Contact:	linux-iio@vger.kernel.org
> > -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:	linux-iio@vger.kernel.org
> > -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).
> > -		===  =======================================================
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > index 4b072da92218..349089e4f2d6 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > @@ -1,15 +1,3 @@
> > -What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > -KernelVersion:	5.11
> > -Contact:	linux-iio@vger.kernel.org
> > -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:	linux-iio@vger.kernel.org
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > new file mode 100644
> > index 000000000000..01259df297ca
> > --- /dev/null
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > @@ -0,0 +1,18 @@
> > +What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > +KernelVersion:	5.1
> > +Contact:	linux-iio@vger.kernel.org
> > +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:	linux-iio@vger.kernel.org
> > +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 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.

[Mauro Carvalho Chehab]

Em Mon, 27 Jun 2022 15:09:55 +0100
Jonathan Cameron <Jonathan.Cameron@Huawei.com> escreveu:

> On Sun, 26 Jun 2022 23:37:45 +0100
> Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> 
> > Em Sun, 26 Jun 2022 17:55:10 +0100
> > Jonathan Cameron <jic23@kernel.org> escreveu:
> >   
> > > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > 
> > > 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.
> > > 
> > > Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
> > > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
> > > ---
> > >  Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
> > >  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> > >  2 files changed, 3 insertions(+), 8 deletions(-)
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > > index 3e00d7f7ee22..e81ba6f5e1c8 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > > @@ -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.
> >   
> 
> 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.


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

> 
> Jonathan
> 
> > Either way:
> > 
> > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > 
> >   
> > >  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
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > index c4a4497c249a..05074c4a65e2 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > @@ -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:	benjamin.gaignard@st.com
> > > -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:	benjamin.gaignard@st.com    
> 

Re: [PATCH 1/4] iio: ABI: temperature: Unify documentation for thermocouple fault detection.

[Mauro Carvalho Chehab]

Em Mon, 27 Jun 2022 15:18:12 +0100
Jonathan Cameron <Jonathan.Cameron@Huawei.com> escreveu:

> On Sun, 26 Jun 2022 23:33:31 +0100
> Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> 
> > Em Sun, 26 Jun 2022 17:55:08 +0100
> > Jonathan Cameron <jic23@kernel.org> escreveu:
> >   
> > > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > 
> > > 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.  
> 
> 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.

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

> 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

> > >  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.
> > > 
> > > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > Cc: Navin Sankar Velliangiri <navin@linumiz.com>
> > > Cc: Paresh Chaudhary <paresh.chaudhary@rockwellcollins.com>    
> > 
> > Except for the above correction, the patch looks OK to me.
> > 
> > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> >   
> > > ---
> > >  .../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(-)
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > > deleted file mode 100644
> > > index e5ef6d8e5da1..000000000000
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > > +++ /dev/null
> > > @@ -1,31 +0,0 @@
> > > -What:		/sys/bus/iio/devices/iio:deviceX/fault_oc
> > > -KernelVersion:	5.1
> > > -Contact:	linux-iio@vger.kernel.org
> > > -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:	linux-iio@vger.kernel.org
> > > -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).
> > > -		===  =======================================================
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > index 4b072da92218..349089e4f2d6 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > @@ -1,15 +1,3 @@
> > > -What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > > -KernelVersion:	5.11
> > > -Contact:	linux-iio@vger.kernel.org
> > > -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:	linux-iio@vger.kernel.org
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > > new file mode 100644
> > > index 000000000000..01259df297ca
> > > --- /dev/null
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > > @@ -0,0 +1,18 @@
> > > +What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > > +KernelVersion:	5.1
> > > +Contact:	linux-iio@vger.kernel.org
> > > +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:	linux-iio@vger.kernel.org
> > > +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.

[Jonathan Cameron]

On Tue, 28 Jun 2022 07:44:09 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> wrote:

> Em Mon, 27 Jun 2022 15:18:12 +0100
> Jonathan Cameron <Jonathan.Cameron@Huawei.com> escreveu:
> 
> > On Sun, 26 Jun 2022 23:33:31 +0100
> > Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> >   
> > > Em Sun, 26 Jun 2022 17:55:08 +0100
> > > Jonathan Cameron <jic23@kernel.org> escreveu:
> > >     
> > > > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > 
> > > > 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.    
> > 
> > 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.
> 
> > 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. 
> 
> > 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.
Applied - hopefully I'll sneak out a pull request later this week.
Apologies for delay. I blame Covid.

J

> 
> Regards,
> Mauro
> 
> > > >  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.
> > > > 
> > > > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > Cc: Navin Sankar Velliangiri <navin@linumiz.com>
> > > > Cc: Paresh Chaudhary <paresh.chaudhary@rockwellcollins.com>      
> > > 
> > > Except for the above correction, the patch looks OK to me.
> > > 
> > > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > >     
> > > > ---
> > > >  .../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(-)
> > > > 
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > > > deleted file mode 100644
> > > > index e5ef6d8e5da1..000000000000
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
> > > > +++ /dev/null
> > > > @@ -1,31 +0,0 @@
> > > > -What:		/sys/bus/iio/devices/iio:deviceX/fault_oc
> > > > -KernelVersion:	5.1
> > > > -Contact:	linux-iio@vger.kernel.org
> > > > -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:	linux-iio@vger.kernel.org
> > > > -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).
> > > > -		===  =======================================================
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > > index 4b072da92218..349089e4f2d6 100644
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31865
> > > > @@ -1,15 +1,3 @@
> > > > -What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > > > -KernelVersion:	5.11
> > > > -Contact:	linux-iio@vger.kernel.org
> > > > -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:	linux-iio@vger.kernel.org
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-thermocouple b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > > > new file mode 100644
> > > > index 000000000000..01259df297ca
> > > > --- /dev/null
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-thermocouple
> > > > @@ -0,0 +1,18 @@
> > > > +What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
> > > > +KernelVersion:	5.1
> > > > +Contact:	linux-iio@vger.kernel.org
> > > > +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:	linux-iio@vger.kernel.org
> > > > +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 3/4] iio: ABI: stm32-timer-trigger: Fuse unusual ABI into main doc.

[Jonathan Cameron]

On Tue, 28 Jun 2022 06:51:19 +0100
Mauro Carvalho Chehab <mchehab@kernel.org> wrote:

> Em Mon, 27 Jun 2022 15:09:55 +0100
> Jonathan Cameron <Jonathan.Cameron@Huawei.com> escreveu:
> 
> > On Sun, 26 Jun 2022 23:37:45 +0100
> > Mauro Carvalho Chehab <mchehab@kernel.org> wrote:
> >   
> > > Em Sun, 26 Jun 2022 17:55:10 +0100
> > > Jonathan Cameron <jic23@kernel.org> escreveu:
> > >     
> > > > From: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > 
> > > > 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.
> > > > 
> > > > Link: https://lore.kernel.org/linux-iio/20210315101217.00002c50@Huawei.com/
> > > > Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
> > > > Cc: Fabrice Gasnier <fabrice.gasnier@foss.st.com>
> > > > ---
> > > >  Documentation/ABI/testing/sysfs-bus-iio             | 3 +++
> > > >  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 | 8 --------
> > > >  2 files changed, 3 insertions(+), 8 deletions(-)
> > > > 
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > > > index 3e00d7f7ee22..e81ba6f5e1c8 100644
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > > > @@ -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.
> > >     
> > 
> > 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.  
> 
> 
> 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

> 
> Regards,
> Mauro
> 
> > 
> > Jonathan
> >   
> > > Either way:
> > > 
> > > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
> > > 
> > >     
> > > >  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
> > > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > index c4a4497c249a..05074c4a65e2 100644
> > > > --- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> > > > @@ -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:	benjamin.gaignard@st.com
> > > > -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:	benjamin.gaignard@st.com      
> >