On Sun, 26 Jun 2022 23:33:31 +0100 Mauro Carvalho Chehab <mchehab@xxxxxxxxxx> wrote: > Em Sun, 26 Jun 2022 17:55:08 +0100 > Jonathan Cameron <jic23@xxxxxxxxxx> escreveu: > > > From: Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx> > > > > 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@xxxxxxxxxx> > > Cc: Navin Sankar Velliangiri <navin@xxxxxxxxxxx> > > Cc: Paresh Chaudhary <paresh.chaudhary@xxxxxxxxxxxxxxxxxxx> > > Except for the above correction, the patch looks OK to me. > > Reviewed-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxx> > > > --- > > .../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@xxxxxxxxxxxxxxx > > -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@xxxxxxxxxxxxxxx > > -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@xxxxxxxxxxxxxxx > > -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@xxxxxxxxxxxxxxx > > 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@xxxxxxxxxxxxxxx > > +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@xxxxxxxxxxxxxxx > > +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.
