diff mbox series

[v2,3/3] doc: Make sysfs-bus-iio doc more exact

Message ID 41eafb0caa510cddf650cf5ff940639a184f3005.1677331779.git.mazziesaccount@gmail.com
State New
Headers
Series iio: Improce kernel docs |

Commit Message

Matti Vaittinen Feb. 25, 2023, 1:56 p.m. UTC 
  A few IIC channel descriptions explained used units as:
data is in foo "that can be processed into an" [unit] value. The "can be
processed into" is quite broad statement as it does not really explain
what this processing means. This makes units pretty much useless.

After discussion with Jonathan, it seems the units for these channels
should also be well-defined as for all other channels. The processing
means the standard scale and offset application that is used throughout
the IIO. Let's make it more obvious by stating that the units are [unit]
after scale ane offset are applied.

Signed-off-by: Matti Vaittinen <mazziesaccount@gmail.com>
---
 Documentation/ABI/testing/sysfs-bus-iio | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

Comments

Jonathan Cameron April 8, 2023, 10:32 a.m. UTC | #1 
On Sat, 25 Feb 2023 15:56:16 +0200
Matti Vaittinen <mazziesaccount@gmail.com> wrote:

> A few IIC channel descriptions explained used units as:
IIO?
> data is in foo "that can be processed into an" [unit] value. The "can be
> processed into" is quite broad statement as it does not really explain
> what this processing means. This makes units pretty much useless.
> 
> After discussion with Jonathan, it seems the units for these channels
> should also be well-defined as for all other channels. The processing
> means the standard scale and offset application that is used throughout
> the IIO. Let's make it more obvious by stating that the units are [unit]
> after scale ane offset are applied.
> 
> Signed-off-by: Matti Vaittinen <mazziesaccount@gmail.com>
Excellent. Thanks for doing this. I'll pick this patch up now.

Applied to the togreg branch of iio.git and pushed out as testing
(in this case to be mostly ignored by 0-day ;)

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 6ba34c0d9789..b435c6f065ae 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -1807,8 +1807,8 @@ What:		/sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw
>  KernelVersion:	4.3
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> -		Raw (unscaled no offset etc.) resistance reading that can be processed
> -		into an ohm value.
> +		Raw (unscaled no offset etc.) resistance reading.
> +		Units after application of scale and offset are ohms.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/heater_enable
>  KernelVersion:	4.1.0
> @@ -1894,8 +1894,9 @@ What:		/sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw
>  KernelVersion:	4.8
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> -		Raw (unscaled no offset etc.) electric conductivity reading that
> -		can be processed to siemens per meter.
> +		Raw (unscaled no offset etc.) electric conductivity reading.
> +		Units after application of scale and offset are siemens per
> +		meter.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_countY_raw
>  KernelVersion:	4.10
> @@ -1952,7 +1953,7 @@ KernelVersion:	4.18
>  Contact:	linux-iio@vger.kernel.org
>  Description:
>  		Raw (unscaled) phase difference reading from channel Y
> -		that can be processed to radians.
> +		Units after application of scale and offset are radians.
>  
>  What:		/sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input
>  What:		/sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input
Andy Shevchenko April 9, 2023, 9:47 a.m. UTC | #2 
On Sat, Apr 8, 2023 at 1:18 PM Jonathan Cameron <jic23@kernel.org> wrote:
 On Sat, 25 Feb 2023 15:56:16 +0200
> Matti Vaittinen <mazziesaccount@gmail.com> wrote:

...

> Applied to the togreg branch of iio.git and pushed out as testing
> (in this case to be mostly ignored by 0-day ;)

One fix is needed?

...

> >  Description:
> >               Raw (unscaled) phase difference reading from channel Y
> > -             that can be processed to radians.
> > +             Units after application of scale and offset are radians.

The previous chunks and confusion in reading the above suggest that
period after Y must be added.

> >  What:                /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input
> >  What:                /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input
Jonathan Cameron April 10, 2023, 11:23 a.m. UTC | #3 
On Sun, 9 Apr 2023 12:47:58 +0300
Andy Shevchenko <andy.shevchenko@gmail.com> wrote:

> On Sat, Apr 8, 2023 at 1:18 PM Jonathan Cameron <jic23@kernel.org> wrote:
>  On Sat, 25 Feb 2023 15:56:16 +0200
> > Matti Vaittinen <mazziesaccount@gmail.com> wrote:  
> 
> ...
> 
> > Applied to the togreg branch of iio.git and pushed out as testing
> > (in this case to be mostly ignored by 0-day ;)  
> 
> One fix is needed?
> 
> ...
> 
> > >  Description:
> > >               Raw (unscaled) phase difference reading from channel Y
> > > -             that can be processed to radians.
> > > +             Units after application of scale and offset are radians.  
> 
> The previous chunks and confusion in reading the above suggest that
> period after Y must be added.
Fixed.  Thanks

> 
> > >  What:                /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input
> > >  What:                /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input  
>
diff mbox series

Patch

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 6ba34c0d9789..b435c6f065ae 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -1807,8 +1807,8 @@  What:		/sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw
 KernelVersion:	4.3
 Contact:	linux-iio@vger.kernel.org
 Description:
-		Raw (unscaled no offset etc.) resistance reading that can be processed
-		into an ohm value.
+		Raw (unscaled no offset etc.) resistance reading.
+		Units after application of scale and offset are ohms.
 
 What:		/sys/bus/iio/devices/iio:deviceX/heater_enable
 KernelVersion:	4.1.0
@@ -1894,8 +1894,9 @@  What:		/sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw
 KernelVersion:	4.8
 Contact:	linux-iio@vger.kernel.org
 Description:
-		Raw (unscaled no offset etc.) electric conductivity reading that
-		can be processed to siemens per meter.
+		Raw (unscaled no offset etc.) electric conductivity reading.
+		Units after application of scale and offset are siemens per
+		meter.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_countY_raw
 KernelVersion:	4.10
@@ -1952,7 +1953,7 @@  KernelVersion:	4.18
 Contact:	linux-iio@vger.kernel.org
 Description:
 		Raw (unscaled) phase difference reading from channel Y
-		that can be processed to radians.
+		Units after application of scale and offset are radians.
 
 What:		/sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input
 What:		/sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input