[PATCH 0/2] docs: abi: iio: RFC: Request to add event when offsets calculated by sensorhub change

[PATCH 0/2] docs: abi: iio: RFC: Request to add event when offsets calculated by sensorhub change

[Gwendal Grignou]

Some sensor hubs calculate offsets for some sensors, like hard or
soft iron for magnetometer, or drift for gyroscope (in addition to
factory calibration).
However, the user space application is not aware when the sensorhub
produces a new set of values. Instead of polling at regular interval,
iio driver could send an event when a new offset vector is available.

Gwendal Grignou (2):
  Documentation: ABI: iio: Use What: consistently
  Documentation: ABI: iio: Add event when offset changes

 Documentation/ABI/testing/sysfs-bus-iio | 81 +++++++++++++++++--------
 1 file changed, 57 insertions(+), 24 deletions(-)

-- 
2.28.0.402.g5ffc5be6b7-goog

[PATCH 1/2] docs: abi: iio: Use What: consistently

[Gwendal Grignou]

Change "[w|W]hat[:| ]" to What: for consistency.

Signed-off-by: Gwendal Grignou <gwendal@chromium.org>
---
 Documentation/ABI/testing/sysfs-bus-iio | 48 ++++++++++++-------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index c3767d4d01a6f..47df16c87862d 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -401,21 +401,21 @@ Description:
 		Hardware applied calibration offset (assumed to fix production
 		inaccuracies).
 
-What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_q_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltage_i_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltage_q_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
-What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
-what		/sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
-what		/sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_q_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_i_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_q_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
+What:		/sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale
 What:		/sys/bus/iio/devices/iio:deviceX/in_illuminance_calibscale
@@ -483,7 +483,7 @@ Description:
 		If a discrete set of scale values is available, they
 		are listed in this attribute.
 
-What		/sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
+What:		/sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain
 What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain
@@ -750,9 +750,9 @@ What:		/sys/.../events/in_voltageY_raw_thresh_falling_value
 What:		/sys/.../events/in_tempY_raw_thresh_rising_value
 What:		/sys/.../events/in_tempY_raw_thresh_falling_value
 What:		/sys/.../events/in_illuminance0_thresh_falling_value
-what:		/sys/.../events/in_illuminance0_thresh_rising_value
-what:		/sys/.../events/in_proximity0_thresh_falling_value
-what:		/sys/.../events/in_proximity0_thresh_rising_value
+What:		/sys/.../events/in_illuminance0_thresh_rising_value
+What:		/sys/.../events/in_proximity0_thresh_falling_value
+What:		/sys/.../events/in_proximity0_thresh_rising_value
 KernelVersion:	2.6.37
 Contact:	linux-iio@vger.kernel.org
 Description:
@@ -830,11 +830,11 @@ What:		/sys/.../events/in_tempY_thresh_rising_hysteresis
 What:		/sys/.../events/in_tempY_thresh_falling_hysteresis
 What:		/sys/.../events/in_tempY_thresh_either_hysteresis
 What:		/sys/.../events/in_illuminance0_thresh_falling_hysteresis
-what:		/sys/.../events/in_illuminance0_thresh_rising_hysteresis
-what:		/sys/.../events/in_illuminance0_thresh_either_hysteresis
-what:		/sys/.../events/in_proximity0_thresh_falling_hysteresis
-what:		/sys/.../events/in_proximity0_thresh_rising_hysteresis
-what:		/sys/.../events/in_proximity0_thresh_either_hysteresis
+What:		/sys/.../events/in_illuminance0_thresh_rising_hysteresis
+What:		/sys/.../events/in_illuminance0_thresh_either_hysteresis
+What:		/sys/.../events/in_proximity0_thresh_falling_hysteresis
+What:		/sys/.../events/in_proximity0_thresh_rising_hysteresis
+What:		/sys/.../events/in_proximity0_thresh_either_hysteresis
 KernelVersion:	3.13
 Contact:	linux-iio@vger.kernel.org
 Description:
-- 
2.28.0.402.g5ffc5be6b7-goog

[PATCH 2/2] docs: abi: iio: Add event when offset changes

[Gwendal Grignou]

Some sensors/sensorhubs can calculate drift or hard iron offsets to
apply to raw data to get the true measure data.
These offsets are applied by the user space application.
When these offsets change, events are raised to tell the application
to update the cached offset values.

Signed-off-by: Gwendal Grignou <gwendal@chromium.org>
---
 Documentation/ABI/testing/sysfs-bus-iio | 33 +++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index 47df16c87862d..40da602e7a555 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -1716,3 +1716,36 @@ Description:
 		Mass concentration reading of particulate matter in ug / m3.
 		pmX consists of particles with aerodynamic diameter less or
 		equal to X micrometers.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_offset
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_offset
+What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_offset
+KernelVersion:	x.y
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Gyroscope drift calculated by the sensor. In addition to factory
+		calibration, sensor or sensorhub can
+		detect gyroscope drift and report it to userspace.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_magn_x_offset
+What:		/sys/bus/iio/devices/iio:deviceX/in_magn_y_offset
+What:		/sys/bus/iio/devices/iio:deviceX/in_magn_z_offset
+KernelVersion:	x.y
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Hard Iron bias calculated by the sensor or sensorhub. To be applied by
+		user space application to the raw data to obtain the geomagnetic field.
+
+What:		/sys/.../iio:deviceX/events/in_accel_offset_change_en
+What:		/sys/.../iio:deviceX/events/in_magn_offset_change_en
+What:		/sys/.../iio:deviceX/events/in_magn_scale_change_en
+What:		/sys/.../iio:deviceX/events/in_anglvel_offset_change_en
+KernelVersion:	x.y
+Contact:	linux-iio@vger.kernel.org
+Description:
+		Some sensors internally calculate offset to apply to remove bias (for
+		instance, hard/soft-iron bias for magnetometer, online calibration bias for
+		gyroscope or accelerometer).
+		When the sensor computes a new set of offset values, it generates an
+		event for the userspace application to refresh the offsets to apply to raw
+		data.
-- 
2.28.0.402.g5ffc5be6b7-goog

Re: [PATCH 1/2] docs: abi: iio: Use What: consistently

[Jonathan Cameron]

On Fri, 28 Aug 2020 16:31:55 -0700
Gwendal Grignou <gwendal@chromium.org> wrote:

> Change "[w|W]hat[:| ]" to What: for consistency.
> 
> Signed-off-by: Gwendal Grignou <gwendal@chromium.org>
Hi Gwendal,

This patch stands fine on its own so I'll apply this whilst we are discussing
patch 2.

Applied with a bit of fuzz to the togreg branch of iio.git and pushed out
as testing to be completely ignored by the autobuilders.

Thanks,

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 48 ++++++++++++-------------
>  1 file changed, 24 insertions(+), 24 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index c3767d4d01a6f..47df16c87862d 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -401,21 +401,21 @@ Description:
>  		Hardware applied calibration offset (assumed to fix production
>  		inaccuracies).
>  
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltageY_q_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltage_i_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltage_q_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
> -What		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
> -what		/sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
> -what		/sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_i_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltageY_q_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_i_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_q_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale
> +What:		/sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale
>  What:		/sys/bus/iio/devices/iio:deviceX/in_illuminance_calibscale
> @@ -483,7 +483,7 @@ Description:
>  		If a discrete set of scale values is available, they
>  		are listed in this attribute.
>  
> -What		/sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
> +What:		/sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain
>  What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain
>  What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain
>  What:		/sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain
> @@ -750,9 +750,9 @@ What:		/sys/.../events/in_voltageY_raw_thresh_falling_value
>  What:		/sys/.../events/in_tempY_raw_thresh_rising_value
>  What:		/sys/.../events/in_tempY_raw_thresh_falling_value
>  What:		/sys/.../events/in_illuminance0_thresh_falling_value
> -what:		/sys/.../events/in_illuminance0_thresh_rising_value
> -what:		/sys/.../events/in_proximity0_thresh_falling_value
> -what:		/sys/.../events/in_proximity0_thresh_rising_value
> +What:		/sys/.../events/in_illuminance0_thresh_rising_value
> +What:		/sys/.../events/in_proximity0_thresh_falling_value
> +What:		/sys/.../events/in_proximity0_thresh_rising_value
>  KernelVersion:	2.6.37
>  Contact:	linux-iio@vger.kernel.org
>  Description:
> @@ -830,11 +830,11 @@ What:		/sys/.../events/in_tempY_thresh_rising_hysteresis
>  What:		/sys/.../events/in_tempY_thresh_falling_hysteresis
>  What:		/sys/.../events/in_tempY_thresh_either_hysteresis
>  What:		/sys/.../events/in_illuminance0_thresh_falling_hysteresis
> -what:		/sys/.../events/in_illuminance0_thresh_rising_hysteresis
> -what:		/sys/.../events/in_illuminance0_thresh_either_hysteresis
> -what:		/sys/.../events/in_proximity0_thresh_falling_hysteresis
> -what:		/sys/.../events/in_proximity0_thresh_rising_hysteresis
> -what:		/sys/.../events/in_proximity0_thresh_either_hysteresis
> +What:		/sys/.../events/in_illuminance0_thresh_rising_hysteresis
> +What:		/sys/.../events/in_illuminance0_thresh_either_hysteresis
> +What:		/sys/.../events/in_proximity0_thresh_falling_hysteresis
> +What:		/sys/.../events/in_proximity0_thresh_rising_hysteresis
> +What:		/sys/.../events/in_proximity0_thresh_either_hysteresis
>  KernelVersion:	3.13
>  Contact:	linux-iio@vger.kernel.org
>  Description:

Re: [PATCH 2/2] docs: abi: iio: Add event when offset changes

[Jonathan Cameron]

On Fri, 28 Aug 2020 16:31:56 -0700
Gwendal Grignou <gwendal@chromium.org> wrote:

> Some sensors/sensorhubs can calculate drift or hard iron offsets to
> apply to raw data to get the true measure data.
> These offsets are applied by the user space application.
> When these offsets change, events are raised to tell the application
> to update the cached offset values.
> 
> Signed-off-by: Gwendal Grignou <gwendal@chromium.org>
Hi Gwendal

This strikes me as rather prone to races.  I guess if the updates
tend to be fairly minor we will just have slightly less accurate data
until the update gets picked up by userspace.

We have had some discussions about how to handle meta data updates
in the past.  One option was to provide a metadata index channel
that could be used to indicate there was an update to something
sat in a separate fifo.

> ---
>  Documentation/ABI/testing/sysfs-bus-iio | 33 +++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> index 47df16c87862d..40da602e7a555 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio
> +++ b/Documentation/ABI/testing/sysfs-bus-iio
> @@ -1716,3 +1716,36 @@ Description:
>  		Mass concentration reading of particulate matter in ug / m3.
>  		pmX consists of particles with aerodynamic diameter less or
>  		equal to X micrometers.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_x_offset
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_y_offset
> +What:		/sys/bus/iio/devices/iio:deviceX/in_anglvel_z_offset
> +KernelVersion:	x.y
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Gyroscope drift calculated by the sensor. In addition to factory
> +		calibration, sensor or sensorhub can
> +		detect gyroscope drift and report it to userspace.

This looks like standard ABI that should probably already be documented,
unrelated to the controversial part of this patch. I would split it out into
it's own patch a I can pick that up much faster.


> +
> +What:		/sys/bus/iio/devices/iio:deviceX/in_magn_x_offset
> +What:		/sys/bus/iio/devices/iio:deviceX/in_magn_y_offset
> +What:		/sys/bus/iio/devices/iio:deviceX/in_magn_z_offset
> +KernelVersion:	x.y
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Hard Iron bias calculated by the sensor or sensorhub. To be applied by
> +		user space application to the raw data to obtain the geomagnetic field.

Same as above.

> +
> +What:		/sys/.../iio:deviceX/events/in_accel_offset_change_en
> +What:		/sys/.../iio:deviceX/events/in_magn_offset_change_en
> +What:		/sys/.../iio:deviceX/events/in_magn_scale_change_en
> +What:		/sys/.../iio:deviceX/events/in_anglvel_offset_change_en
> +KernelVersion:	x.y
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Some sensors internally calculate offset to apply to remove bias (for
> +		instance, hard/soft-iron bias for magnetometer, online calibration bias for
> +		gyroscope or accelerometer).
> +		When the sensor computes a new set of offset values, it generates an
> +		event for the userspace application to refresh the offsets to apply to raw
> +		data.

I'm not totally sold on this idea, though would like inputs from other people before
ruling it out.

One minor change I'd make would be to have a single event to indicate that something
userspace might care about in the way of metadata for this channel has changed.
I guess something like

in_accel_metachange_en etc with a single new event code.  For events, it's the event
code mapping that normally matters more than sysfs binding as that is much more
tightly restricted.

Jonathan

Re: [PATCH 2/2] docs: abi: iio: Add event when offset changes

[Gwendal Grignou]

On Sun, Aug 30, 2020 at 6:11 AM Jonathan Cameron <jic23@kernel.org> wrote:
>
> On Fri, 28 Aug 2020 16:31:56 -0700
> Gwendal Grignou <gwendal@chromium.org> wrote:
>
> > Some sensors/sensorhubs can calculate drift or hard iron offsets to
> > apply to raw data to get the true measure data.
> > These offsets are applied by the user space application.
> > When these offsets change, events are raised to tell the application
> > to update the cached offset values.
> >
> > Signed-off-by: Gwendal Grignou <gwendal@chromium.org>
> Hi Gwendal
>
> This strikes me as rather prone to races.  I guess if the updates
> tend to be fairly minor we will just have slightly less accurate data
> until the update gets picked up by userspace.
In case of hard iron for instance, the sensorhub needs several samples
to find out the current offset are now invalid. So it is likely the
measurement of the geomagnetic field was incorrect for a while.
For accelerometer online calibration, we don't expect vast changes
when new offsets are available.
>
> We have had some discussions about how to handle meta data updates
> in the past.  One option was to provide a metadata index channel
> that could be used to indicate there was an update to something
> sat in a separate fifo.
An extra sounds like a waste of space, as it will mostly be 0 most of
the time, and edge to 1 once in a while. An event looks more
appropriate.
>
> > ---
> >  Documentation/ABI/testing/sysfs-bus-iio | 33 +++++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> >
> > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > index 47df16c87862d..40da602e7a555 100644
> > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > @@ -1716,3 +1716,36 @@ Description:
> >               Mass concentration reading of particulate matter in ug / m3.
> >               pmX consists of particles with aerodynamic diameter less or
> >               equal to X micrometers.
> > +
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_offset
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_offset
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_offset
> > +KernelVersion:       x.y
> > +Contact:     linux-iio@vger.kernel.org
> > +Description:
> > +             Gyroscope drift calculated by the sensor. In addition to factory
> > +             calibration, sensor or sensorhub can
> > +             detect gyroscope drift and report it to userspace.
>
> This looks like standard ABI that should probably already be documented,
> unrelated to the controversial part of this patch. I would split it out into
> it's own patch a I can pick that up much faster.
Done in v2.
>
>
> > +
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_x_offset
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_y_offset
> > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_z_offset
> > +KernelVersion:       x.y
> > +Contact:     linux-iio@vger.kernel.org
> > +Description:
> > +             Hard Iron bias calculated by the sensor or sensorhub. To be applied by
> > +             user space application to the raw data to obtain the geomagnetic field.
>
> Same as above.
Done in v2.
>
> > +
> > +What:                /sys/.../iio:deviceX/events/in_accel_offset_change_en
> > +What:                /sys/.../iio:deviceX/events/in_magn_offset_change_en
> > +What:                /sys/.../iio:deviceX/events/in_magn_scale_change_en
> > +What:                /sys/.../iio:deviceX/events/in_anglvel_offset_change_en
> > +KernelVersion:       x.y
> > +Contact:     linux-iio@vger.kernel.org
> > +Description:
> > +             Some sensors internally calculate offset to apply to remove bias (for
> > +             instance, hard/soft-iron bias for magnetometer, online calibration bias for
> > +             gyroscope or accelerometer).
> > +             When the sensor computes a new set of offset values, it generates an
> > +             event for the userspace application to refresh the offsets to apply to raw
> > +             data.
>
> I'm not totally sold on this idea, though would like inputs from other people before
> ruling it out.
>
> One minor change I'd make would be to have a single event to indicate that something
> userspace might care about in the way of metadata for this channel has changed.
> I guess something like
Make sense, scale and offset should be checked together if they both exists.
Using vents/in_<type>_metadata_en in v2.
>
> in_accel_metachange_en etc with a single new event code.  For events, it's the event
> code mapping that normally matters more than sysfs binding as that is much more
> tightly restricted.
>
> Jonathan
>

Re: [PATCH 2/2] docs: abi: iio: Add event when offset changes

[Jonathan Cameron]

On Mon, 31 Aug 2020 20:00:43 -0700
Gwendal Grignou <gwendal@chromium.org> wrote:

> On Sun, Aug 30, 2020 at 6:11 AM Jonathan Cameron <jic23@kernel.org> wrote:
> >
> > On Fri, 28 Aug 2020 16:31:56 -0700
> > Gwendal Grignou <gwendal@chromium.org> wrote:
> >  
> > > Some sensors/sensorhubs can calculate drift or hard iron offsets to
> > > apply to raw data to get the true measure data.
> > > These offsets are applied by the user space application.
> > > When these offsets change, events are raised to tell the application
> > > to update the cached offset values.
> > >
> > > Signed-off-by: Gwendal Grignou <gwendal@chromium.org>  
> > Hi Gwendal
> >
> > This strikes me as rather prone to races.  I guess if the updates
> > tend to be fairly minor we will just have slightly less accurate data
> > until the update gets picked up by userspace.  
> In case of hard iron for instance, the sensorhub needs several samples
> to find out the current offset are now invalid. So it is likely the
> measurement of the geomagnetic field was incorrect for a while.
> For accelerometer online calibration, we don't expect vast changes
> when new offsets are available.
> >
> > We have had some discussions about how to handle meta data updates
> > in the past.  One option was to provide a metadata index channel
> > that could be used to indicate there was an update to something
> > sat in a separate fifo.  
> An extra sounds like a waste of space, as it will mostly be 0 most of
> the time, and edge to 1 once in a while. An event looks more
> appropriate.

Agreed for this case.
It would be a much more general interface with a lot of other
usecases. It is overkill here.  There isn't a huge burden in adding
support for your case in the meantime, even if we eventually end up
finding a better way of doing metadata in general.

> >  
> > > ---
> > >  Documentation/ABI/testing/sysfs-bus-iio | 33 +++++++++++++++++++++++++
> > >  1 file changed, 33 insertions(+)
> > >
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
> > > index 47df16c87862d..40da602e7a555 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio
> > > @@ -1716,3 +1716,36 @@ Description:
> > >               Mass concentration reading of particulate matter in ug / m3.
> > >               pmX consists of particles with aerodynamic diameter less or
> > >               equal to X micrometers.
> > > +
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_offset
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_offset
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_offset
> > > +KernelVersion:       x.y
> > > +Contact:     linux-iio@vger.kernel.org
> > > +Description:
> > > +             Gyroscope drift calculated by the sensor. In addition to factory
> > > +             calibration, sensor or sensorhub can
> > > +             detect gyroscope drift and report it to userspace.  
> >
> > This looks like standard ABI that should probably already be documented,
> > unrelated to the controversial part of this patch. I would split it out into
> > it's own patch a I can pick that up much faster.  
> Done in v2.
> >
> >  
> > > +
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_x_offset
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_y_offset
> > > +What:                /sys/bus/iio/devices/iio:deviceX/in_magn_z_offset
> > > +KernelVersion:       x.y
> > > +Contact:     linux-iio@vger.kernel.org
> > > +Description:
> > > +             Hard Iron bias calculated by the sensor or sensorhub. To be applied by
> > > +             user space application to the raw data to obtain the geomagnetic field.  
> >
> > Same as above.  
> Done in v2.
> >  
> > > +
> > > +What:                /sys/.../iio:deviceX/events/in_accel_offset_change_en
> > > +What:                /sys/.../iio:deviceX/events/in_magn_offset_change_en
> > > +What:                /sys/.../iio:deviceX/events/in_magn_scale_change_en
> > > +What:                /sys/.../iio:deviceX/events/in_anglvel_offset_change_en
> > > +KernelVersion:       x.y
> > > +Contact:     linux-iio@vger.kernel.org
> > > +Description:
> > > +             Some sensors internally calculate offset to apply to remove bias (for
> > > +             instance, hard/soft-iron bias for magnetometer, online calibration bias for
> > > +             gyroscope or accelerometer).
> > > +             When the sensor computes a new set of offset values, it generates an
> > > +             event for the userspace application to refresh the offsets to apply to raw
> > > +             data.  
> >
> > I'm not totally sold on this idea, though would like inputs from other people before
> > ruling it out.
> >
> > One minor change I'd make would be to have a single event to indicate that something
> > userspace might care about in the way of metadata for this channel has changed.
> > I guess something like  
> Make sense, scale and offset should be checked together if they both exists.
> Using vents/in_<type>_metadata_en in v2.
> >
> > in_accel_metachange_en etc with a single new event code.  For events, it's the event
> > code mapping that normally matters more than sysfs binding as that is much more
> > tightly restricted.
> >
> > Jonathan
> >