Re: [PATCH v5 4/4] iio: ABI: document accel and roc event attributes

[Jonathan Cameron <jic23@kernel.org>]

On Sat, 30 Aug 2025 08:58:57 -0300
Gustavo Silva <gustavograzs@gmail.com> wrote:

> Add accelerometer and rate of change event-related sysfs attributes
> exposed by the bmi270 driver.
> 
> Signed-off-by: Gustavo Silva <gustavograzs@gmail.com>
> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 40 +++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 2fb2cea4b192..75a88f0dc533 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -908,6 +908,7 @@ What:		/sys/.../iio:deviceX/events/in_accel_y_roc_rising_en
>  What:		/sys/.../iio:deviceX/events/in_accel_y_roc_falling_en
>  What:		/sys/.../iio:deviceX/events/in_accel_z_roc_rising_en
>  What:		/sys/.../iio:deviceX/events/in_accel_z_roc_falling_en
> +What:		/sys/.../iio:deviceX/events/in_accel_x&y&z_roc_rising_en
>  What:		/sys/.../iio:deviceX/events/in_anglvel_x_roc_rising_en
>  What:		/sys/.../iio:deviceX/events/in_anglvel_x_roc_falling_en
>  What:		/sys/.../iio:deviceX/events/in_anglvel_y_roc_rising_en
> @@ -1129,6 +1130,7 @@ Description:
>  		will get activated once in_voltage0_raw goes above 1200 and will become
>  		deactivated again once the value falls below 1150.
>  
> +What:		/sys/.../events/in_accel_roc_rising_value
>  What:		/sys/.../events/in_accel_x_raw_roc_rising_value
>  What:		/sys/.../events/in_accel_x_raw_roc_falling_value
>  What:		/sys/.../events/in_accel_y_raw_roc_rising_value
> @@ -1177,6 +1179,7 @@ Description:
>  
>  What:		/sys/.../events/in_accel_x_thresh_rising_period
>  What:		/sys/.../events/in_accel_x_thresh_falling_period
> +What:		/sys/.../events/in_accel_roc_rising_period
>  What:		/sys/.../events/in_accel_x_roc_rising_period
>  What:		/sys/.../events/in_accel_x_roc_falling_period
>  What:		/sys/.../events/in_accel_y_thresh_rising_period
> @@ -1187,6 +1190,7 @@ What:		/sys/.../events/in_accel_z_thresh_rising_period
>  What:		/sys/.../events/in_accel_z_thresh_falling_period
>  What:		/sys/.../events/in_accel_z_roc_rising_period
>  What:		/sys/.../events/in_accel_z_roc_falling_period
> +What:		/sys/.../events/in_accel_mag_adaptive_rising_period
>  What:		/sys/.../events/in_anglvel_x_thresh_rising_period
>  What:		/sys/.../events/in_anglvel_x_thresh_falling_period
>  What:		/sys/.../events/in_anglvel_x_roc_rising_period
> @@ -1344,6 +1348,23 @@ Description:
>  		number or direction is not specified, applies to all channels of
>  		this type.
>  
> +What:		/sys/.../iio:deviceX/events/in_accel_x_mag_adaptive_rising_en
> +What:		/sys/.../iio:deviceX/events/in_accel_y_mag_adaptive_rising_en
> +What:		/sys/.../iio:deviceX/events/in_accel_z_mag_adaptive_rising_en
> +KernelVersion:	2.6.37
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Similar to in_accel_x_thresh[_rising|_falling]_en, but here the
> +		adaptive magnitude of the channel is compared to the threshold.
That seems backwards.  I was thinking of this as

the magnitude of the channel is compared to an adaptive threshold. 

I'm not sure what 'adaptive magnitude of the channel' would mean.

> +
> +What:		/sys/.../events/in_accel_mag_adaptive_rising_value
I'm not sure this one needs it's own block.

For the nearest equivalent which is _adaptive_rising_value (which is only documented
for capacitive channels we just put it in the same block as the non _adaptive_ variant.

> +KernelVersion:	2.6.37
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		The value to which the reference adaptive magnitude of the channel is
> +		compared. If the axis is not specified, it applies to all channels
> +		of this type.
> +
>  What:		/sys/.../iio:deviceX/events/in_accel_mag_referenced_en
>  What:		/sys/.../iio:deviceX/events/in_accel_mag_referenced_rising_en
>  What:		/sys/.../iio:deviceX/events/in_accel_mag_referenced_falling_en
> @@ -2386,3 +2407,22 @@ Description:
>  		Value representing the user's attention to the system expressed
>  		in units as percentage. This usually means if the user is
>  		looking at the screen or not.
> +
> +What:		/sys/.../events/in_accel_value_available
> +KernelVersion:	6.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		List of available acceleration threshold values that can be
> +		configured for event generation. Units after application of
> +		scale and offset are m/s^2. Expressed as:
> +

This is generic. What sort of event does it apply to?  Seems like it should
be in_accel_mag_adaptive_value or something along those lines? Might also need
in_acecl_mag_reference_value or even direction specific variants of each.

Whilst the ABI does allow for a broader 'available' to cover for
all channels for instance so this is sort of valid ABI, to me it just
feels non intuitive for a user.    Maybe just adding tot this document
to say that this applies to all forms of event for in_accel channels on
this device is sufficient.

> +		- a range specified as "[min step max]"
> +
> +What:		/sys/.../events/in_accel_period_available

This one feels more reasonable as the idea of all events sharing a period control
is more likely than the values that are accepted being the same for all.

> +KernelVersion:	6.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		List of available periods for accelerometer event detection in
> +		seconds, expressed as:
> +
> +		- a range specified as "[min step max]"