[RESEND PATCH v2 0/3] Improve kernel docs

[RESEND PATCH v2 0/3] Improve kernel docs

[Matti Vaittinen]

[-- Attachment #1: Type: text/plain, Size: 2052 bytes --]

IIO has very nice facilities for efficiently providing data from a
device to user (and probably also vice-versa - but I've not used that
direction). Getting started with IIO may not be so simple though - some
of the concepts like triggers and buffers are quite unique.

This series tries to make it easier for a newcomer to write his/her first
IIO driver by adding some documentation to used enums. Series does not
provide extensive documentation but just documents those few entries I
have become familiar with - but it still aims to be a starting point for
others to add missing bits and pieces.

This series is marked as v2 because the patch 1 was previously sent as a
stan-alone RFC to collect the missing channel units. RFC can be seen
here:
https://lore.kernel.org/all/10a855f9adc1d710150b7f647500c3c6a769f9ca.1677243698.git.mazziesaccount@gmail.com/

Patches 2 and 3 were added as a result of discussion followed by the
RFC.

Revision history:
v2 resend:
    - rebased on v6.3-rc2
RFCv1 => v2:
    - added patches 2 and 3
    - added missing channel type docs provided by Jonathan
    - added @in front of member names and fix typos pointed by Andy
    - dropped TODOs as Jonathan clarified the units

---

Matti Vaittinen (3):
  iio: Add some kerneldoc for channel types
  iio: add documentation for iio_chan_info_enum
  doc: Make sysfs-bus-iio doc more exact

 Documentation/ABI/testing/sysfs-bus-iio |  11 +-
 include/linux/iio/types.h               |  46 +++++++-
 include/uapi/linux/iio/types.h          | 134 ++++++++++++++++++++++++
 3 files changed, 185 insertions(+), 6 deletions(-)


base-commit: eeac8ede17557680855031c6f305ece2378af326
-- 
2.39.2


-- 
Matti Vaittinen, Linux device drivers
ROHM Semiconductors, Finland SWDC
Kiviharjunlenkki 1E
90220 OULU
FINLAND

~~~ "I don't think so," said Rene Descartes. Just then he vanished ~~~
Simon says - in Latin please.
~~~ "non cogito me" dixit Rene Descarte, deinde evanescavit ~~~
Thanks to Simon Glass for the translation =] 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[RESEND PATCH v2 2/3] iio: add documentation for iio_chan_info_enum

[Matti Vaittinen]

[-- Attachment #1: Type: text/plain, Size: 3466 bytes --]

Values in the iio_chan_info_enum are crucial for understanding the
characteristics of an IIO channel and the data delivered via IIO channel.
Give a hand to developers who do their first set of IIO drivers.

Add some documentation to these channel specifiers.

Signed-off-by: Matti Vaittinen <mazziesaccount@gmail.com>
---
Please note that I did only add documentation for entries I am familiar
with. I did still add doc placeholders for all of the enum entries to
ease seeing which entries could still be documented. Hopefully this
encourages people to add missing pieces of documentation.
---
 include/linux/iio/types.h | 46 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/include/linux/iio/types.h b/include/linux/iio/types.h
index 82faa98c719a..c8e3288ca24b 100644
--- a/include/linux/iio/types.h
+++ b/include/linux/iio/types.h
@@ -35,7 +35,51 @@ enum iio_available_type {
 	IIO_AVAIL_LIST,
 	IIO_AVAIL_RANGE,
 };
-
+/**
+ * enum iio_chan_info_enum - Information related to a IIO channel
+ *
+ * Many IIO channels have extra properties. Typically these properties can be
+ * read / written by user using the read_raw or write_raw callbacks in the
+ * struct iio_info.
+ *
+ * @IIO_CHAN_INFO_RAW:		Raw channel data as provided by device. Scale
+ *				and offset are often required to convert these
+ *				values to meaningful units.
+ * @IIO_CHAN_INFO_PROCESSED:	Processed data. Typically driver performs
+ *				computations to convert device data to more
+ *				meaningfull processed values.
+ * @IIO_CHAN_INFO_SCALE:	Scale to be applied to data in order to convert
+ *				it to units mandated by the channel type.
+ * @IIO_CHAN_INFO_OFFSET:	Offset to be applied to data in order to convert
+ *				it to units mandated by the channel type.
+ * @IIO_CHAN_INFO_CALIBSCALE:
+ * @IIO_CHAN_INFO_CALIBBIAS:
+ * @IIO_CHAN_INFO_PEAK:		Peak value (TODO: Since measurement start?)
+ * @IIO_CHAN_INFO_PEAK_SCALE:	Scale to be applied to the peak value in order
+ *				to convert it to units mandated by the channel
+ *				type.
+ * @IIO_CHAN_INFO_QUADRATURE_CORRECTION_RAW:
+ * @IIO_CHAN_INFO_AVERAGE_RAW:	Average of raw values (TODO: Since measurement
+ *				start or just for some undefined time?)
+ * @IIO_CHAN_INFO_SAMP_FREQ:	Sampling frequency for device.
+ * @IIO_CHAN_INFO_FREQUENCY:
+ * @IIO_CHAN_INFO_PHASE:
+ * @IIO_CHAN_INFO_HARDWAREGAIN:	Amplification applied by the hardware.
+ * @IIO_CHAN_INFO_HYSTERESIS:
+ * @IIO_CHAN_INFO_HYSTERESIS_RELATIVE:
+ * @IIO_CHAN_INFO_INT_TIME:	Integration time. Time during which the data is
+ *				accumulated by the device.
+ * @IIO_CHAN_INFO_ENABLE:
+ * @IIO_CHAN_INFO_CALIBHEIGHT:
+ * @IIO_CHAN_INFO_CALIBWEIGHT:
+ * @IIO_CHAN_INFO_DEBOUNCE_COUNT:
+ * @IIO_CHAN_INFO_DEBOUNCE_TIME:
+ * @IIO_CHAN_INFO_CALIBEMISSIVITY:
+ * @IIO_CHAN_INFO_OVERSAMPLING_RATIO:
+ * @IIO_CHAN_INFO_THERMOCOUPLE_TYPE:
+ * @IIO_CHAN_INFO_CALIBAMBIENT:
+ * @IIO_CHAN_INFO_ZEROPOINT:
+ */
 enum iio_chan_info_enum {
 	IIO_CHAN_INFO_RAW = 0,
 	IIO_CHAN_INFO_PROCESSED,
-- 
2.39.2


-- 
Matti Vaittinen, Linux device drivers
ROHM Semiconductors, Finland SWDC
Kiviharjunlenkki 1E
90220 OULU
FINLAND

~~~ "I don't think so," said Rene Descartes. Just then he vanished ~~~
Simon says - in Latin please.
~~~ "non cogito me" dixit Rene Descarte, deinde evanescavit ~~~
Thanks to Simon Glass for the translation =] 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Matti Vaittinen]

[-- Attachment #1: Type: text/plain, Size: 2711 bytes --]

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(-)

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


-- 
Matti Vaittinen, Linux device drivers
ROHM Semiconductors, Finland SWDC
Kiviharjunlenkki 1E
90220 OULU
FINLAND

~~~ "I don't think so," said Rene Descartes. Just then he vanished ~~~
Simon says - in Latin please.
~~~ "non cogito me" dixit Rene Descarte, deinde evanescavit ~~~
Thanks to Simon Glass for the translation =] 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [RESEND PATCH v2 0/3] Improve kernel docs

[Jonathan Cameron]

On Tue, 4 Apr 2023 15:24:15 +0300
Matti Vaittinen <mazziesaccount@gmail.com> wrote:

> IIO has very nice facilities for efficiently providing data from a
> device to user (and probably also vice-versa - but I've not used that
> direction). Getting started with IIO may not be so simple though - some
> of the concepts like triggers and buffers are quite unique.
> 
> This series tries to make it easier for a newcomer to write his/her first
> IIO driver by adding some documentation to used enums. Series does not
> provide extensive documentation but just documents those few entries I
> have become familiar with - but it still aims to be a starting point for
> others to add missing bits and pieces.
> 
> This series is marked as v2 because the patch 1 was previously sent as a
> stan-alone RFC to collect the missing channel units. RFC can be seen
> here:
> https://lore.kernel.org/all/10a855f9adc1d710150b7f647500c3c6a769f9ca.1677243698.git.mazziesaccount@gmail.com/
> 
> Patches 2 and 3 were added as a result of discussion followed by the
> RFC.

Something odd happened on this resend. Patch 1 didn't make it to me
or patchwork.  I'll reply to previous posting instead.

Jonathan

> 
> Revision history:
> v2 resend:
>     - rebased on v6.3-rc2
> RFCv1 => v2:
>     - added patches 2 and 3
>     - added missing channel type docs provided by Jonathan
>     - added @in front of member names and fix typos pointed by Andy
>     - dropped TODOs as Jonathan clarified the units
> 
> ---
> 
> Matti Vaittinen (3):
>   iio: Add some kerneldoc for channel types
>   iio: add documentation for iio_chan_info_enum
>   doc: Make sysfs-bus-iio doc more exact
> 
>  Documentation/ABI/testing/sysfs-bus-iio |  11 +-
>  include/linux/iio/types.h               |  46 +++++++-
>  include/uapi/linux/iio/types.h          | 134 ++++++++++++++++++++++++
>  3 files changed, 185 insertions(+), 6 deletions(-)
> 
> 
> base-commit: eeac8ede17557680855031c6f305ece2378af326

Re: [RESEND PATCH v2 0/3] Improve kernel docs

[Matti Vaittinen]

la 8. huhtik. 2023 klo 12.34 Jonathan Cameron (jic23@kernel.org) kirjoitti:
>
> On Tue, 4 Apr 2023 15:24:15 +0300
> Matti Vaittinen <mazziesaccount@gmail.com> wrote:
>
> > IIO has very nice facilities for efficiently providing data from a
> > device to user (and probably also vice-versa - but I've not used that
> > direction). Getting started with IIO may not be so simple though - some
> > of the concepts like triggers and buffers are quite unique.
> >
> > This series tries to make it easier for a newcomer to write his/her first
> > IIO driver by adding some documentation to used enums. Series does not
> > provide extensive documentation but just documents those few entries I
> > have become familiar with - but it still aims to be a starting point for
> > others to add missing bits and pieces.
> >
> > This series is marked as v2 because the patch 1 was previously sent as a
> > stan-alone RFC to collect the missing channel units. RFC can be seen
> > here:
> > https://lore.kernel.org/all/10a855f9adc1d710150b7f647500c3c6a769f9ca.1677243698.git.mazziesaccount@gmail.com/
> >
> > Patches 2 and 3 were added as a result of discussion followed by the
> > RFC.
>
> Something odd happened on this resend. Patch 1 didn't make it to me
> or patchwork.  I'll reply to previous posting instead.
>

It seems checkpatch.pl + some of the patches were only picking the
huawei.com address. Maybe that is the reason?

This really was a resend with no changes other than rebasing it -
hence reviewing the v2 was absolutely fine. Thanks for the review!
I'll check the suggestions and send v3 later this week.

Yours,
  -- Matti

Re: [RESEND PATCH v2 0/3] Improve kernel docs

[Jonathan Cameron]

On Mon, 10 Apr 2023 13:16:22 +0300
Matti Vaittinen <mazziesaccount@gmail.com> wrote:

> la 8. huhtik. 2023 klo 12.34 Jonathan Cameron (jic23@kernel.org) kirjoitti:
> >
> > On Tue, 4 Apr 2023 15:24:15 +0300
> > Matti Vaittinen <mazziesaccount@gmail.com> wrote:
> >  
> > > IIO has very nice facilities for efficiently providing data from a
> > > device to user (and probably also vice-versa - but I've not used that
> > > direction). Getting started with IIO may not be so simple though - some
> > > of the concepts like triggers and buffers are quite unique.
> > >
> > > This series tries to make it easier for a newcomer to write his/her first
> > > IIO driver by adding some documentation to used enums. Series does not
> > > provide extensive documentation but just documents those few entries I
> > > have become familiar with - but it still aims to be a starting point for
> > > others to add missing bits and pieces.
> > >
> > > This series is marked as v2 because the patch 1 was previously sent as a
> > > stan-alone RFC to collect the missing channel units. RFC can be seen
> > > here:
> > > https://lore.kernel.org/all/10a855f9adc1d710150b7f647500c3c6a769f9ca.1677243698.git.mazziesaccount@gmail.com/
> > >
> > > Patches 2 and 3 were added as a result of discussion followed by the
> > > RFC.  
> >
> > Something odd happened on this resend. Patch 1 didn't make it to me
> > or patchwork.  I'll reply to previous posting instead.
> >  
> 
> It seems checkpatch.pl + some of the patches were only picking the
> huawei.com address. Maybe that is the reason?

Nope. Patchwork gets it straight from the list and b4 gets it it from
lore.kernel.org which is also missing patch 1.

> 
> This really was a resend with no changes other than rebasing it -
> hence reviewing the v2 was absolutely fine. Thanks for the review!
> I'll check the suggestions and send v3 later this week.
Great.

I'm behind with a few other discussions including the looking at your
questions around that color sensor you want support.  So may be
a while before I circle back round to this anyway!

Jonathan

> 
> Yours,
>   -- Matti