linux-kernel - Re: [RFC PATCH] iio: Add some kerneldoc for channel types

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Fri, 24 Feb 2023 16:20:45 +0200
From:   Andy Shevchenko <andy.shevchenko@...il.com>
To:     Matti Vaittinen <mazziesaccount@...il.com>
Cc:     Matti Vaittinen <matti.vaittinen@...rohmeurope.com>,
        Jonathan Cameron <Jonathan.Cameron@...wei.com>,
        Andrea Merello <andrea.merello@....it>,
        Jagath Jog J <jagathjog1996@...il.com>,
        linux-kernel@...r.kernel.org
Subject: Re: [RFC PATCH] iio: Add some kerneldoc for channel types

On Fri, Feb 24, 2023 at 3:02 PM Matti Vaittinen
<mazziesaccount@...il.com> 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 kerneldocs of respective enums.

kernel doc

Documentation is always welcome!

...

>  #ifndef _UAPI_IIO_TYPES_H_
>  #define _UAPI_IIO_TYPES_H_
> -

Stray change.
...

> +/**
> + * iio_chan_type - Type of data transferred via IIO channel.
> + *
> + * The 'main' type of data transferred via channel. Please note that most
> + * devices need to specify also a more accurate 'sub category'. See the

devices also need to specify a

> + * 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).
> + *
> + * Use of correct units is required but scale and offset that user must apply
> + * to channel values can be advertised.
> + *
> + * 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

Seems you forgot @:s.

> + *
> + * IIO_ACTIVITY:       Activity state. For example a pedometer signaling
> + *                     jogging, walking or staying still.
> + *                     Doc keyword: in_activity_still_thresh_rising_en
> + *
> + * IIO_ALTVOLTAGE:
> + *
> + * 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:
> + *
> + * IIO_CURRENT:                Current, milliamps
> + *                     Doc keyword: in_currentY_raw
> + *
> + * IIO_CONCENTRATION:  Reading of a substance, percents. Used for example by
> + *                     deviced measuring amount of CO2, O2, ethanol...

devices

> + *                     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
> + *                     TODO: What does "can be processed to siemens per meter"
> + *                     mean? Do we have unit requirement?
> + *
> + * 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
> + *                     TODO: What does "can be processed to radians" mean? Do
> + *                     we have unit requirement?
> + *
> + * 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
> + *                     TODO: What means "can be processed..." Do we have unit
> + *                     requirement?
> + *
> + * 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
> + */

...

> +/**
> + * iio_modifier - accurate class for channel data

> + * IIO_MOD_<X,Y,Z>:    Value represents <X,Y,Z>-axis data.

Missing @:s as well.

> + *                     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 infra red light components

infrared

> + * IIO_MOD_LIGHT_IR:   Value represents infra-red 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.
> + */

-- 
With Best Regards,
Andy Shevchenko