Improve kernel docs
v2 cover Improve kernel docs
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
Signature · 14 lines
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 =]
PATCH RESEND v2 1/3 iio: Add some kerneldoc for channel types
For occasional contributor like me navigating the IIO channel types and modifiers may be a daunting task. One may have hard time finding out what type of channel should be used for device data and what units the data should be converted.
There is a great documentation for the sysfs interfaces though. What is missing is mapping of the channel types and modifiers to the sysfs documentation (and entries in documentation).
Give a hand to a driver writer by providing some documentation and by pointing to the sysfs document from the kernel doc of respective enums.
---
Changelog RFCv1 => v2:
- add missing channel type docs provided by Jonathan
- add @in front of member names and fix typos pointed by Andy
- drop TODOs as Jonathan clarified the units
Initial discussion about these docs can be found from:
https://lore.kernel.org/all/[email protected]/
--- include/uapi/linux/iio/types.h | 134 +++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+)
include/uapi/linux/iio/types.h +134 -0
@@ -11,6 +11,124 @@#ifndef _UAPI_IIO_TYPES_H_#define _UAPI_IIO_TYPES_H_ +/** +* iio_chan_type - Type of data transferred via IIO channel. +* +* The 'main' type of data transferred via channel. Please note that most +* devices also need to specify a more accurate 'sub category'. See the +* enum iio_modifier for this. (For example, IIO_ACCEL channel often needs to +* specify the direction. IIO_CONCENTRATION specifies the type of substance +* it measures etc). +* +* These reflect the units of the measurement via processed or unit after +* application of scale and offset. See the enum iio_chan_info_enum for +* scale and offset. +* +* Please find the detailed documentation for reported values from the +* Documentation/ABI/testing/sysfs-bus-iio. +* +* @IIO_ACCEL: Acceleration, m/s^2 +* Doc keyword: in_accel_x_raw +* +* @IIO_ACTIVITY: Activity state. For example a pedometer signaling +* jogging, walking or staying still. +* Doc keyword: in_activity_still_thresh_rising_en +* +* @IIO_ALTVOLTAGE: Peak to peak voltage, millivolts +* +* @IIO_ANGL: Angle of rotation, radians. +* Doc keyword: in_angl_raw +* +* @IIO_ANGL_VEL: Angular velocity, rad/s +* Doc keyword: in_anglvel_x_raw +* +* @IIO_CAPACITANCE: Capacitance, nanofarads. +* Doc keyword: in_capacitanceY_raw +* +* @IIO_CCT: Correlated color temperature, Kelvins +* +* @IIO_CURRENT: Current, milliamps +* Doc keyword: in_currentY_raw +* +* @IIO_CONCENTRATION: Reading of a substance, percents. Used for example by +* devices measuring amount of CO2, O2, ethanol... +* Doc keyword: in_concentration_raw +* +* @IIO_COUNT: Deprecated, please use counter subsystem. +* +* @IIO_DISTANCE: Distance in meters. Typically used to report measured +* distance to an object or the distance covered by the +* user +* Doc keyword: in_distance_input +* +* @IIO_ELECTRICALCONDUCTIVITY: electric conductivity, siemens per meter +* Doc keyword: in_electricalconductivity_raw +* +* @IIO_ENERGY: Energy in Joules. Typically reported by a device +* measuring energy burnt by the user. +* Doc keyword: in_energy_input +* +* @IIO_GRAVITY: Gravity, m/s^2 +* Doc keyword: in_gravity_x_raw +* +* @IIO_HUMIDITYRELATIVE: Relative humidity, percents +* Doc keyword: in_humidityrelative_raw +* +* @IIO_INCLI: Inclination, degrees +* Doc keyword: in_incli_x_raw +* +* @IIO_INDEX: Deprecated, please use Counter subsystem +* +* @IIO_INTENSITY: Unitless intensity. +* Doc keyword: in_intensityY_raw +* +* @IIO_LIGHT: Visible light intensity, lux +* Doc keyword: in_illuminance_raw +* +* @IIO_MAGN: Magnetic field, Gauss. +* Doc keyword: in_magn_x_raw +* +* @IIO_MASSCONCENTRATION: Mass concentration, ug / m3 +* Doc keyword: in_massconcentration_pm1_input +* +* @IIO_PH: pH reading, negative base-10 logarithm of hydrodium +* ions in a litre of water +* Doc keyword: in_ph_raw +* +* @IIO_PHASE: Phase difference, radians +* Doc keyword: in_phaseY_raw +* +* @IIO_POSITIONRELATIVE: Relative position. +* Doc keyword: in_positionrelative_x_raw +* +* @IIO_POWER: Power, milliwatts +* Doc keyword: in_powerY_raw +* +* @IIO_PRESSURE: Pressure, kilopascal +* Doc keyword: in_pressureY_raw +* +* @IIO_RESISTANCE: Resistance, ohms +* Doc keyword: in_resistance_raw +* +* @IIO_ROT: Euler angles, deg +* Doc keyword: in_rot_yaw_raw +* +* @IIO_STEPS: Steps taken by the user +* Doc keyword: in_steps_input +* +* @IIO_TEMP: Temperature, milli degrees Celsius +* Doc keyword: in_temp_raw +* +* @IIO_UVINDEX: UV light intensity index +* Doc keyword: in_uvindex_input +* +* @IIO_VELOCITY: Current speed (norm or magnitude of the velocity +* vector), m/s +* Doc keyword: in_velocity_sqrt(x^2+y^2+z^2)_input +* +* @IIO_VOLTAGE: Voltage, millivolts +* Doc keyword: in_voltageY_raw +*/ enum iio_chan_type {IIO_VOLTAGE , IIO_CURRENT,
@@ -49,6 +167,22 @@ enum iio_chan_type { IIO_MASSCONCENTRATION, }; +/** +* iio_modifier - accurate class for channel data +* +* @IIO_MOD_<X,Y,Z>: Value represents <X,Y,Z>-axis data. +* Typically used by channels of type: +* IIO_ACCEL, IIO_TEMP, IIO_GRAVITY, IIO_POSITIONRELATIVE, +* IIO_ANGL_VEL, IIO_INCLI, IIO_MAGN +* @IIO_MOD_LIGHT_BOTH: Value contains visible and infrared light components +* @IIO_MOD_LIGHT_IR: Value represents infrared radiation +* @IIO_MOD_LIGHT_<RED, GREEN, BLUE>: +* Value represents visible <red, green, blue> light +* @IIO_MOD_LIGHT_CLEAR: Value represents all visible light frequencies +* +* Please find the detailed documentation for reported values from the +* Documentation/ABI/testing/sysfs-bus-iio. +*/ enum iio_modifier {IIO_NO_MOD ,IIO_MOD_X ,
Signature · 14 lines
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 =]
PATCH RESEND v2 2/3 iio: add documentation for iio_chan_info_enum
In reply to Matti VaittinenValues 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.
---
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(-)
include/linux/iio/types.h +45 -1
@@ -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,
Signature · 14 lines
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 =]
PATCH RESEND v2 3/3 doc: Make sysfs-bus-iio doc more exact
In reply to Matti VaittinenA 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.
--- Documentation/ABI/testing/sysfs-bus-iio | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-)
Documentation/ABI/testing/sysfs-bus-iio +6 -5
@@ -1807,8 +1807,8 @@ What: /sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw KernelVersion: 4.3 Contact: [email protected] 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: [email protected] 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: [email protected] 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
Signature · 14 lines
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 =]
Re: [RESEND PATCH v2 1/3] iio: Add some kerneldoc for channel types
In reply to Matti VaittinenHi Matti,
Quoted 30 lines · Matti Vaittinen
For occasional contributor like me navigating the IIO channel types and modifiers may be a daunting task. One may have hard time finding out what type of channel should be used for device data and what units the data should be converted.
There is a great documentation for the sysfs interfaces though. What is missing is mapping of the channel types and modifiers to the sysfs documentation (and entries in documentation).
Give a hand to a driver writer by providing some documentation and by pointing to the sysfs document from the kernel doc of respective enums.
Signed-off-by Matti Vaittinen <[email protected]>---
Changelog RFCv1 => v2:
- add missing channel type docs provided by Jonathan
- add @in front of member names and fix typos pointed by Andy
- drop TODOs as Jonathan clarified the unitsInitial discussion about these docs can be found from:
https://lore.kernel.org/all/[email protected]/--- include/uapi/linux/iio/types.h | 134 +++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+)include/uapi/linux/iio/types.h +0
-0
include/uapi/linux/iio/types.h line 15
Quoted 5 lines
include/uapi/linux/iio/types.h +2
-0@@ -11,6 +11,124 @@#ifndef _UAPI_IIO_TYPES_H_#define _UAPI_IIO_TYPES_H_ +/** +* iio_chan_type - Type of data transferred via IIO channel.
* enum iio_chan_type - ...
as you did in patch 2/3.
Quoted 1 line
include/uapi/linux/iio/types.h +1
-0+*
...
include/uapi/linux/iio/types.h enum iio_chan_type { · line 171
Quoted 10 lines
+ */
enumiio_chan_type{include/uapi/linux/iio/types.h +2
-0IIO_VOLTAGE , IIO_CURRENT,@@ -49,6 +167,22 @@ enum iio_chan_type { IIO_MASSCONCENTRATION, }; +/** +* iio_modifier - accurate class for channel data
Ditto here.
Quoted 7 lines
include/uapi/linux/iio/types.h +7
-0+* +* @IIO_MOD_<X,Y,Z>: Value represents <X,Y,Z>-axis data. +* Typically used by channels of type: +* IIO_ACCEL, IIO_TEMP, IIO_GRAVITY, IIO_POSITIONRELATIVE, +* IIO_ANGL_VEL, IIO_INCLI, IIO_MAGN +* @IIO_MOD_LIGHT_BOTH: Value contains visible and infrared light components +* @IIO_MOD_LIGHT_IR: Value represents infrared radiation
include/uapi/linux/iio/types.h enum iio_chan_type { · line 188
Quoted 10 lines
include/uapi/linux/iio/types.h +7
-0+* @IIO_MOD_LIGHT_<RED, GREEN, BLUE>: +* Value represents visible <red, green, blue> light +* @IIO_MOD_LIGHT_CLEAR: Value represents all visible light frequencies +* +* Please find the detailed documentation for reported values from the +* Documentation/ABI/testing/sysfs-bus-iio. +*/ enum iio_modifier {IIO_NO_MOD ,IIO_MOD_X ,
Thanks.
Signature · 1 line
~Randy
Re: [RESEND PATCH v2 1/3] iio: Add some kerneldoc for channel types
Quoted 9 lines · Randy Dunlap
Hi Matti,
Quoted 2 lines · Matti Vaittinen
+/**
+ *iio_chan_type- Type of data transferred via IIO channel.* enum
iio_chan_type- ...
Quoted 7 lines
as you did in patch 2/3.
Quoted 2 lines
+/**
+ *iio_modifier- accurate class for channel dataDitto here.
Well spotted. Thanks Randy. I'll wait for a lil while if there'll be some more comments - but I'll fix this in v3.
Yours,
-- Matti
Signature · 5 lines
Matti Vaittinen Linux kernel developer at ROHM Semiconductors Oulu Finland ~~ When things go utterly wrong vim users can always type :help! ~~
Jonathan Cameron
maintainerQuoted 11 lines · On Tue, 4 Apr 2023 15:24:15 +0300 Matti Vaittinen <[email protected]>…
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.
Quoted 7 lines
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
Quoted 24 lines
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 foriio_chan_info_enum
doc: Make sysfs-bus-iio doc more exactDocumentation/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
la 8. huhtik. 2023 klo 12.34 Jonathan Cameron ([email protected]) kirjoitti:
Quoted 20 lines
Quoted 16 lines · On Tue, 4 Apr 2023 15:24:15 +0300 Matti Vaittinen <[email protected]>…
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/
Quoted 6 lines
Quoted 2 lines
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
Jonathan Cameron
maintainerQuoted 24 lines · On Mon, 10 Apr 2023 13:16:22 +0300 Matti Vaittinen <[email protected]>…
la 8. huhtik. 2023 klo 12.34 Jonathan Cameron ([email protected]) kirjoitti:
Quoted 23 lines
Quoted 18 lines · On Tue, 4 Apr 2023 15:24:15 +0300 Matti Vaittinen <[email protected]>…
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.
Quoted 6 lines
Quoted 3 lines
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.
Quoted 4 lines
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
Quoted 3 lines
Yours,
-- Matti