[RESEND,v2,1/3] iio: Add some kerneldoc for channel types
Commit Message
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 <mazziesaccount@gmail.com>
---
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/0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@gmail.com/
---
include/uapi/linux/iio/types.h | 134 +++++++++++++++++++++++++++++++++
1 file changed, 134 insertions(+)
Comments
Hi Matti,
On 4/4/23 05:24, Matti Vaittinen wrote:
> 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 <mazziesaccount@gmail.com>
> ---
> 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/0e0d45b7-e582-82b2-9bac-1f70f9dad9f7@gmail.com/
> ---
> include/uapi/linux/iio/types.h | 134 +++++++++++++++++++++++++++++++++
> 1 file changed, 134 insertions(+)
>
> diff --git a/include/uapi/linux/iio/types.h b/include/uapi/linux/iio/types.h
> index c79f2f046a0b..78f4cfdc5e45 100644
> --- a/include/uapi/linux/iio/types.h
> +++ b/include/uapi/linux/iio/types.h
> @@ -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.
> + *
...
> + */
> 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
Ditto here.
> + *
> + * @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,
Thanks.
On 4/4/23 19:33, Randy Dunlap wrote:
> Hi Matti,
>
> On 4/4/23 05:24, Matti Vaittinen wrote:
>> +/**
>> + * iio_chan_type - Type of data transferred via IIO channel.
>
> * enum iio_chan_type - ...
>
> as you did in patch 2/3.
>
>> +/**
>> + * iio_modifier - accurate class for channel data
>
> Ditto 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
@@ -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,