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

[Mauro Carvalho Chehab <mchehab@kernel.org>]

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.