iio: accel: adxl345: Add event scaling and doc fixes

PATCH Superseded Taha Ed-Dafili 5 participants 14 messages Feb 8 – Feb 15

Subsystems (3)

Documentation IIO Analog Devices IIO drivers

lore

Share & tools

lore

Taha Ed-Dafili

author

2026-02-08 15:05 UTC #0 lore raw

v3 cover iio: accel: adxl345: Add event scaling and doc fixes

This series addresses ADXL345 driver non-compliance with the IIO ABI for event thresholds.

Currently, the driver exposes raw values for thresholds (e.g., tap, activity) without providing the necessary scale factor to convert them to SI units (m/s^2), as mandated by the ABI.

This series implements IIO_EV_INFO_SCALE in the IIO core and applies it to the ADXL345 driver, ensuring that userspace can correctly interpret threshold values. It also cleans up existing documentation errors and typos.

Changes in v3:
- Patch 1: Reverted "axis" -> "axes" change in documentation as it is used as an adjective (Randy Dunlap).
- Patch 2: Reworded commit message to "Implement support for..." instead of "missing from..." (David Lechner).
- Patch 4: Simplified documentation table by removing repetitive scale values from every row. Added explicit table entries for the new in_accel_gesture_scale and in_accel_mag_scale attributes instead (Jonathan Cameron).
- Patch 4: Fixed "inscale" typo in commit message.

Changes in v2:
- Added core infrastructure for IIO_EV_INFO_SCALE.
- Implemented event scaling (0.612915 m/s^2) for ADXL345.
- Fixed technical math/decimal errors in existing documentation.
- Cleaned up grammar and pluralization issues in .rst file.

Taha Ed-Dafili (4):
docs: iio: adxl345: fix typos and grammar
iio: core: Add IIO_EV_INFO_SCALE to event info
iio: accel: adxl345: Implement event scaling for ABI compliance
docs: iio: adxl345: update math and examples for scaling

 Documentation/iio/adxl345.rst    | 65 +++++++++++++++++++-------------
 drivers/iio/accel/adxl345_core.c | 28 +++++++++++---
 drivers/iio/industrialio-event.c |  1 +
 include/linux/iio/types.h        |  1 +
 4 files changed, 63 insertions(+), 32 deletions(-)

Signature · 1 line

2.47.3

Taha Ed-Dafili

author

2026-02-08 15:05 UTC #1 lore raw

PATCH v3 1/4 docs: iio: adxl345: fix typos and grammar

Correct several grammatical errors, typos, and pluralization issues throughout the ADXL345 documentation. Key changes include:
- Changing 'generic' to 'general-purpose'
- Correcting 'axis' to 'axes' in multiple tables and descriptions
- Improving phrasing in the device attributes section
- Fixing 'latent' to 'latency' in usage examples

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 Documentation/iio/adxl345.rst | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

Documentation/iio/adxl345.rst +12 ~~-12~~

index bb19d64f67c3..3ca6a78feb5b 100644
@@ -12,16 +12,16 @@ This driver supports Analog Device's ADXL345/375 on SPI/I2C bus.
 * `ADXL345 <https://www.analog.com/ADXL345>`_
 * `ADXL375 <https://www.analog.com/ADXL375>`_
 
-The ADXL345 is a generic purpose low power, 3-axis accelerometer with selectable
+The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable
 measurement ranges. The ADXL345 supports the ±2 g, ±4 g, ±8 g, and ±16 g ranges.
 
 2. Device Attributes
 ====================
 
-Each IIO device, has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
+Each IIO device has a device folder under ``/sys/bus/iio/devices/iio:deviceX``,
 where X is the IIO index of the device. Under these folders reside a set of
 device files, depending on the characteristics and features of the hardware
-device in questions. These files are consistently generalized and documented in
+device in question. These files are consistently generalized and documented in
 the IIO ABI documentation.
 
 The following table shows the ADXL345 related device files, found in the

@@ -42,7 +42,7 @@ specific device folder path ``/sys/bus/iio/devices/iio:deviceX``.
 +-------------------------------------------+----------------------------------------------------------+
 | in_accel_x_raw                            | Raw X-axis accelerometer channel value.                  |
 +-------------------------------------------+----------------------------------------------------------+
-| in_accel_y_calibbias                      | y-axis acceleration offset correction                    |
+| in_accel_y_calibbias                      | Y-axis acceleration offset correction                    |
 +-------------------------------------------+----------------------------------------------------------+
 | in_accel_y_raw                            | Raw Y-axis accelerometer channel value.                  |
 +-------------------------------------------+----------------------------------------------------------+

@@ -68,7 +68,7 @@ present, simply assume its value is 0.
 +-------------------------------------+---------------------------+
 | Channel type                        | Measurement unit          |
 +-------------------------------------+---------------------------+
-| Acceleration on X, Y, and Z axis    | Meters per second squared |
+| Acceleration on X, Y, and Z axes    | Meters per second squared |
 +-------------------------------------+---------------------------+
 
 Sensor Events

@@ -78,8 +78,8 @@ Specific IIO events are triggered by their corresponding interrupts. The sensor
 driver supports either none or a single active interrupt (INT) line, selectable
 from the two available options: INT1 or INT2. The active INT line should be
 specified in the device tree. If no INT line is configured, the sensor defaults
-to FIFO bypass mode, where event detection is disabled and only X, Y, and Z axis
-measurements are available.
+to FIFO bypass mode, where event detection is disabled and only individual
+X, Y, and Z axis measurements are available.
 
 The table below lists the ADXL345-related device files located in the
 device-specific path: ``/sys/bus/iio/devices/iio:deviceX/events``.

@@ -90,11 +90,11 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | Event handle                                | Description                                 |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_gesture_doubletap_en               | Enable double tap detection on all axis     |
+| in_accel_gesture_doubletap_en               | Enable double tap detection on all axes     |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_gesture_doubletap_reset_timeout    | Double tap window in [us]                   |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_gesture_doubletap_tap2_min_delay   | Double tap latent in [us]                   |
+| in_accel_gesture_doubletap_tap2_min_delay   | Double tap latency in [us]                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_gesture_singletap_timeout          | Single tap duration in [us]                 |
 +---------------------------------------------+---------------------------------------------+

@@ -118,9 +118,9 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_x_gesture_singletap_en             | Enable single tap detection on X axis       |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_x&y&z_mag_falling_en               | Enable inactivity detection on all axis     |
+| in_accel_x&y&z_mag_falling_en               | Enable inactivity detection on all axes     |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_x&y&z_mag_adaptive_falling_en      | Enable AC coupled inactivity on all axis    |
+| in_accel_x&y&z_mag_adaptive_falling_en      | Enable AC coupled inactivity on all axes    |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_y_gesture_singletap_en             | Enable single tap detection on Y axis       |
 +---------------------------------------------+---------------------------------------------+

@@ -330,7 +330,7 @@ Configure one or several events:
         ## doubletap, window [us]
         root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_reset_timeout
 
-        ## doubletap, latent [us]
+        ## doubletap, latency [us]
         root:/sys/bus/iio/devices/iio:device0> echo 0.025 > ./events/in_accel_gesture_doubletap_tap2_min_delay
 
         ## AC coupled activity, enable

Signature · 1 line

2.47.3

Taha Ed-Dafili

author

2026-02-08 15:05 UTC #2 lore raw

PATCH v3 2/4 iio: core: Add IIO_EV_INFO_SCALE to event info

In reply to Taha Ed-Dafili

Implement support for IIO_EV_INFO_SCALE in the internal enum iio_event_info to allow proper ABI compliance.

This allows drivers (like the ADXL345) to expose event scale attributes using the standard IIO ABI rather than manual device attributes.

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 drivers/iio/industrialio-event.c | 1 +
 include/linux/iio/types.h        | 1 +
 2 files changed, 2 insertions(+)

drivers/iio/industrialio-event.c +1 -0

index 06295cfc2da8..5096baf233f0 100644
@@ -256,6 +256,7 @@ static const char * const iio_ev_info_text[] = {
 	[IIO_EV_INFO_TAP2_MIN_DELAY] = "tap2_min_delay",
 	[IIO_EV_INFO_RUNNING_PERIOD] = "runningperiod",
 	[IIO_EV_INFO_RUNNING_COUNT] = "runningcount",
+	[IIO_EV_INFO_SCALE] = "scale",
 };
 
 static enum iio_event_direction iio_ev_attr_dir(struct iio_dev_attr *attr)

include/linux/iio/types.h +1 -0

index 34eebad12d2c..4e3099defc1d 100644
@@ -21,6 +21,7 @@ enum iio_event_info {
 	IIO_EV_INFO_TAP2_MIN_DELAY,
 	IIO_EV_INFO_RUNNING_PERIOD,
 	IIO_EV_INFO_RUNNING_COUNT,
+	IIO_EV_INFO_SCALE,
 };
 
 #define IIO_VAL_INT 1

Signature · 1 line

2.47.3

Taha Ed-Dafili

author

2026-02-08 15:05 UTC #3 lore raw

PATCH v3 3/4 iio: accel: adxl345: Implement event scaling for ABI compliance

In reply to Taha Ed-Dafili

The ADXL345 uses a fixed threshold resolution of 62.5 mg/LSB for event-related registers. Previously, the driver reported raw values without a scale factor.

Implement IIO_EV_INFO_SCALE for all event types to provide the conversion factor (0.612915 m/s^2) as required by the IIO ABI.

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 drivers/iio/accel/adxl345_core.c | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

drivers/iio/accel/adxl345_core.c +22 -6

index 78e3f799ecc1..dfe3169ffc5f 100644
@@ -212,7 +212,8 @@ static const struct iio_event_spec adxl345_events[] = {
 		.type = IIO_EV_TYPE_MAG,
 		.dir = IIO_EV_DIR_RISING,
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_ENABLE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),
 	},
 	{

@@ -221,6 +222,7 @@ static const struct iio_event_spec adxl345_events[] = {
 		.dir = IIO_EV_DIR_RISING,
 		.mask_shared_by_type =
 			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),
 	},
 	{

@@ -228,15 +230,19 @@ static const struct iio_event_spec adxl345_events[] = {
 		.type = IIO_EV_TYPE_GESTURE,
 		.dir = IIO_EV_DIR_SINGLETAP,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
-		.mask_shared_by_type = BIT(IIO_EV_INFO_VALUE) |
+		.mask_shared_by_type =
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_TIMEOUT),
 	},
 	{
 		/* double tap */
 		.type = IIO_EV_TYPE_GESTURE,
 		.dir = IIO_EV_DIR_DOUBLETAP,
-		.mask_shared_by_type = BIT(IIO_EV_INFO_ENABLE) |
-			BIT(IIO_EV_INFO_RESET_TIMEOUT) |
+		.mask_shared_by_type =
+			BIT(IIO_EV_INFO_ENABLE)		|
+			BIT(IIO_EV_INFO_RESET_TIMEOUT)	|
+			BIT(IIO_EV_INFO_SCALE)		|
 			BIT(IIO_EV_INFO_TAP2_MIN_DELAY),
 	},
 };

@@ -274,7 +280,8 @@ static const struct iio_event_spec adxl345_fake_chan_events[] = {
 		.dir = IIO_EV_DIR_FALLING,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_VALUE) |
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_PERIOD),
 	},
 	{

@@ -283,7 +290,8 @@ static const struct iio_event_spec adxl345_fake_chan_events[] = {
 		.dir = IIO_EV_DIR_FALLING,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_VALUE) |
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_PERIOD),
 	},
 };

@@ -1367,6 +1375,14 @@ static int adxl345_read_event_value(struct iio_dev *indio_dev,
 				return ret;
 			*val = sign_extend32(tap_threshold, 7);
 			return IIO_VAL_INT;
+		case IIO_EV_INFO_SCALE:
+			/*
+			 * The event threshold LSB is fixed at 62.5 mg/LSB
+			 * 0.0625 * 9.80665 = 0.612915625 m/s^2
+			 */
+			*val = 0;
+			*val2 = 612915;
+			return IIO_VAL_INT_PLUS_MICRO;
 		case IIO_EV_INFO_TIMEOUT:
 			*val = st->tap_duration_us;
 			*val2 = MICRO;

Signature · 1 line

2.47.3

David Lechner

reviewer

2026-02-14 17:02 UTC #4 lore raw

Re: [PATCH v3 3/4] iio: accel: adxl345: Implement event scaling for ABI compliance

Quoted 18 lines · Taha Ed-Dafili

The ADXL345 uses a fixed threshold resolution of 62.5 mg/LSB for event-related registers. Previously, the driver reported raw values without a scale factor.
Implement IIO_EV_INFO_SCALE for all event types to provide the conversion factor (0.612915 m/s^2) as required by the IIO ABI.
Suggested-by Jonathan Cameron <[email protected]>
Signed-off-by Taha Ed-Dafili <[email protected]>
---
 drivers/iio/accel/adxl345_core.c | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)
drivers/iio/accel/adxl345_core.c +0 -0
index 78e3f799ecc1..dfe3169ffc5f 100644

drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 217

Quoted 7 lines

drivers/iio/accel/adxl345_core.c +2 -1

@@ -212,7 +212,8 @@ static const struct iio_event_spec adxl345_events[] = {
 		.type = IIO_EV_TYPE_MAG,
 		.dir = IIO_EV_DIR_RISING,
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_ENABLE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),

Would be nice to be consistent and put scale after value as the ones at the end.

Quoted 11 lines

drivers/iio/accel/adxl345_core.c +1 -0

 	},
 	{

@@ -221,6 +222,7 @@ static const struct iio_event_spec adxl345_events[] = {
 		.dir = IIO_EV_DIR_RISING,
 		.mask_shared_by_type =
 			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),
 	},
 	{

drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 235

Quoted 7 lines

drivers/iio/accel/adxl345_core.c +3 -1

@@ -228,15 +230,19 @@ static const struct iio_event_spec adxl345_events[] = {
 		.type = IIO_EV_TYPE_GESTURE,
 		.dir = IIO_EV_DIR_SINGLETAP,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
-		.mask_shared_by_type = BIT(IIO_EV_INFO_VALUE) |
+		.mask_shared_by_type =
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|

What is the units for gesture that we are scaling to?

drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 245

Quoted 12 lines

drivers/iio/accel/adxl345_core.c +4 -2

 			BIT(IIO_EV_INFO_TIMEOUT),
 	},
 	{
 		/* double tap */
 		.type = IIO_EV_TYPE_GESTURE,
 		.dir = IIO_EV_DIR_DOUBLETAP,
-		.mask_shared_by_type = BIT(IIO_EV_INFO_ENABLE) |
-			BIT(IIO_EV_INFO_RESET_TIMEOUT) |
+		.mask_shared_by_type =
+			BIT(IIO_EV_INFO_ENABLE)		|
+			BIT(IIO_EV_INFO_RESET_TIMEOUT)	|
+			BIT(IIO_EV_INFO_SCALE)		|

There is no value here, so scale doesn't make sense (plus it is gesture as above.

Quoted 38 lines

drivers/iio/accel/adxl345_core.c +12 -2

 			BIT(IIO_EV_INFO_TAP2_MIN_DELAY),
 	},
 };

@@ -274,7 +280,8 @@ static const struct iio_event_spec adxl345_fake_chan_events[] = {
 		.dir = IIO_EV_DIR_FALLING,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_VALUE) |
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_PERIOD),
 	},
 	{

@@ -283,7 +290,8 @@ static const struct iio_event_spec adxl345_fake_chan_events[] = {
 		.dir = IIO_EV_DIR_FALLING,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
 		.mask_shared_by_type =
-			BIT(IIO_EV_INFO_VALUE) |
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_PERIOD),
 	},
 };

@@ -1367,6 +1375,14 @@ static int adxl345_read_event_value(struct iio_dev *indio_dev,
 				return ret;
 			*val = sign_extend32(tap_threshold, 7);
 			return IIO_VAL_INT;
+		case IIO_EV_INFO_SCALE:
+			/*
+			 * The event threshold LSB is fixed at 62.5 mg/LSB
+			 * 0.0625 * 9.80665 = 0.612915625 m/s^2
+			 */
+			*val = 0;
+			*val2 = 612915;
+			return IIO_VAL_INT_PLUS_MICRO;
 		case IIO_EV_INFO_TIMEOUT:
 			*val = st->tap_duration_us;
 			*val2 = MICRO;

David Lechner

reviewer

2026-02-14 17:09 UTC #5 lore raw

Re: [PATCH v3 3/4] iio: accel: adxl345: Implement event scaling for ABI compliance

Quoted 14 lines · David Lechner

Quoted 13 lines · Taha Ed-Dafili
The ADXL345 uses a fixed threshold resolution of 62.5 mg/LSB for event-related registers. Previously, the driver reported raw values without a scale factor.
Implement IIO_EV_INFO_SCALE for all event types to provide the conversion factor (0.612915 m/s^2) as required by the IIO ABI.
Suggested-by Jonathan Cameron <[email protected]>
Signed-off-by Taha Ed-Dafili <[email protected]>
---
 drivers/iio/accel/adxl345_core.c | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

...

Quoted 10 lines

drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 235
Quoted 8 lines
drivers/iio/accel/adxl345_core.c +3 -1
@@ -228,15 +230,19 @@ static const struct iio_event_spec adxl345_events[] = {
 		.type = IIO_EV_TYPE_GESTURE,
 		.dir = IIO_EV_DIR_SINGLETAP,
 		.mask_separate = BIT(IIO_EV_INFO_ENABLE),
-		.mask_shared_by_type = BIT(IIO_EV_INFO_VALUE) |
+		.mask_shared_by_type =
+			BIT(IIO_EV_INFO_VALUE)	|
+			BIT(IIO_EV_INFO_SCALE)	|
What is the units for gesture that we are scaling to?

After looking at the docs, I understand this now, so no need to reply.

Quoted 3 lines

Quoted 3 lines
drivers/iio/accel/adxl345_core.c +0 -0
 			BIT(IIO_EV_INFO_TIMEOUT),
 	},

Andy Shevchenko

2026-02-14 18:22 UTC #6 lore raw

Re: [PATCH v3 3/4] iio: accel: adxl345: Implement event scaling for ABI compliance

In reply to David Lechner

Quoted 7 lines · David Lechner

Quoted 6 lines · Taha Ed-Dafili
The ADXL345 uses a fixed threshold resolution of 62.5 mg/LSB for event-related registers. Previously, the driver reported raw values without a scale factor.
Implement IIO_EV_INFO_SCALE for all event types to provide the conversion factor (0.612915 m/s^2) as required by the IIO ABI.

...

Quoted 2 lines

drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 215
Quoted 2 lines
drivers/iio/accel/adxl345_core.c +1 -1
-			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_ENABLE)	|

What's the difference here?

Quoted 5 lines

Review
Quoted 2 lines
(quoted diff) +1 -0
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),
Would be nice to be consistent and put scale after value as the ones at the end.

Would it be better other way around to avoid unneeded churn with touching the last line?

Signature · 2 lines

With Best Regards,
Andy Shevchenko

Randy Dunlap

reviewer

2026-02-14 21:49 UTC #7 lore raw

Re: [PATCH v3 3/4] iio: accel: adxl345: Implement event scaling for ABI compliance

Quoted 9 lines · Andy Shevchenko

Quoted 7 lines · David Lechner
Quoted 6 lines · Taha Ed-Dafili
The ADXL345 uses a fixed threshold resolution of 62.5 mg/LSB for event-related registers. Previously, the driver reported raw values without a scale factor.
Implement IIO_EV_INFO_SCALE for all event types to provide the conversion factor (0.612915 m/s^2) as required by the IIO ABI.

Quoted 6 lines

...
Quoted 2 lines
drivers/iio/accel/adxl345_core.c static const struct iio_event_spec adxl345_events[] = { · line 215
Quoted 2 lines
drivers/iio/accel/adxl345_core.c +1 -1
-			BIT(IIO_EV_INFO_ENABLE) |
+			BIT(IIO_EV_INFO_ENABLE)	|
What's the difference here?

Space replaced by Tab just before the ending '|' character. An undesirable change.

Quoted 10 lines

Quoted 6 lines
Review
Quoted 3 lines
(quoted diff) +1 -0
+			BIT(IIO_EV_INFO_SCALE)	|
 			BIT(IIO_EV_INFO_VALUE),
Would be nice to be consistent and put scale after value as the ones at the end.
Would it be better other way around to avoid unneeded churn with touching the last line?

Signature · 1 line

~Randy

Taha Ed-Dafili

author

2026-02-08 15:05 UTC #8 lore raw

PATCH v3 4/4 docs: iio: adxl345: update math and examples for scaling

In reply to Taha Ed-Dafili

Update the documentation to reflect the addition of event scaling and correct existing technical errors in scale values.

key changes:
- Fix the 62.5 g/LSB typo to 62.5 mg/LSB and add SI unit conversion.
- Correct decimal precision of in_accel_scale and in_accel_scale_available to match actual SI unit (m/s^2) values reported by the driver.
- Add sysfs example showing how to read and interpret the newly implemented event scale factor.

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 Documentation/iio/adxl345.rst | 41 +++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 14 deletions(-)

Documentation/iio/adxl345.rst +27 ~~-14~~

index 3ca6a78feb5b..321565699817 100644
@@ -13,7 +13,12 @@ This driver supports Analog Device's ADXL345/375 on SPI/I2C bus.
 * `ADXL375 <https://www.analog.com/ADXL375>`_
 
 The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable
-measurement ranges. The ADXL345 supports the ±2 g, ±4 g, ±8 g, and ±16 g ranges.
+measurement ranges. The ADXL345 supports the following ranges:
+
+- ±2g  (approx. ±19.61 m/s^2)
+- ±4g  (approx. ±39.23 m/s^2)
+- ±8g  (approx. ±78.45 m/s^2)
+- ±16g (approx. ±156.91 m/s^2)
 
 2. Device Attributes
 ====================

@@ -98,23 +103,23 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_gesture_singletap_timeout          | Single tap duration in [us]                 |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_gesture_singletap_value            | Single tap threshold value in 62.5/LSB      |
+| in_accel_gesture_singletap_value            | Single tap threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_falling_period                 | Inactivity time in seconds                  |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_falling_value                  | Inactivity threshold value in 62.5/LSB      |
+| in_accel_mag_falling_value                  | Inactivity threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_rising_en             | Enable AC coupled activity on X axis        |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_falling_period        | AC coupled inactivity time in seconds       |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold in 62.5/LSB |
+| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold             |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold in 62.5/LSB   |
+| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold               |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_rising_en                      | Enable activity detection on X axis         |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_rising_value                   | Activity threshold value in 62.5/LSB        |
+| in_accel_mag_rising_value                   | Activity threshold value                    |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_x_gesture_singletap_en             | Enable single tap detection on X axis       |
 +---------------------------------------------+---------------------------------------------+

@@ -126,6 +131,10 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_z_gesture_singletap_en             | Enable single tap detection on Z axis       |
 +---------------------------------------------+---------------------------------------------+
+| in_accel_gesture_scale                      | Tap threshold scale (0.612915 m/s^2).       |
++---------------------------------------------+---------------------------------------------+
+| in_accel_mag_scale                          | Activity threshold scale (0.612915 m/s^2).  |
++---------------------------------------------+---------------------------------------------+
 
 Please refer to the sensor's datasheet for a detailed description of this
 functionality.

@@ -140,8 +149,8 @@ When changing the **g range** configuration, the driver attempts to estimate
 appropriate activity and inactivity thresholds by scaling the default values
 based on the ratio of the previous range to the new one. The resulting threshold
 will never be zero and will always fall between 1 and 255, corresponding to up
-to 62.5 g/LSB as specified in the datasheet. However, you can override these
-estimated thresholds by setting explicit values.
+to 62.5 mg/LSB (0.612915 m/s^2/LSB) as specified in the datasheet. However,
+you can override these estimated thresholds by setting explicit values.
 
 When **activity** and **inactivity** events are enabled, the driver
 automatically manages hysteresis behavior by setting the **link** and

@@ -270,13 +279,13 @@ Scale range configuration:
 .. code-block:: bash
 
         root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale
-        0.478899
+        0.004789
         root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale_available
-        0.478899 0.957798 1.915595 3.831190
+        0.004789 0.009578 0.019156 0.038312
 
-        root:/sys/bus/iio/devices/iio:device0> echo 1.915595 > ./in_accel_scale
+        root:/sys/bus/iio/devices/iio:device0> echo 0.019156 > ./in_accel_scale
         root:/sys/bus/iio/devices/iio:device0> cat ./in_accel_scale
-        1.915595
+        0.019156
 
 Set output data rate (ODR):

@@ -312,10 +321,14 @@ Configure one or several events:
 
         root:/sys/bus/iio/devices/iio:device0> echo 24 > ./buffer0/length
 
-        ## AC coupled activity, threshold [62.5/LSB]
+        ## Check the event scale factor (0.0625 * 9.80665)
+        root:/sys/bus/iio/devices/iio:device0> cat ./events/in_accel_gesture_scale
+        0.612915
+
+        ## AC coupled activity, threshold [0.612915 m/s^2/LSB]
         root:/sys/bus/iio/devices/iio:device0> echo 6 > ./events/in_accel_mag_adaptive_rising_value
 
-        ## AC coupled inactivity, threshold, [62.5/LSB]
+        ## AC coupled inactivity, threshold, [0.612915 m/s^2/LSB]
         root:/sys/bus/iio/devices/iio:device0> echo 4 > ./events/in_accel_mag_adaptive_falling_value
 
         ## AC coupled inactivity, time [s]

Signature · 1 line

2.47.3

David Lechner

reviewer

2026-02-14 17:11 UTC #9 lore raw

Re: [PATCH v3 4/4] docs: iio: adxl345: update math and examples for scaling

Quoted 65 lines · Taha Ed-Dafili

Update the documentation to reflect the addition of event scaling and correct existing technical errors in scale values.

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 Documentation/iio/adxl345.rst | 41 +++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 14 deletions(-)

Documentation/iio/adxl345.rst +11 -6

index 3ca6a78feb5b..321565699817 100644
@@ -13,7 +13,12 @@ This driver supports Analog Device's ADXL345/375 on SPI/I2C bus.
 * `ADXL375 <https://www.analog.com/ADXL375>`_
 
 The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable
-measurement ranges. The ADXL345 supports the ±2 g, ±4 g, ±8 g, and ±16 g ranges.
+measurement ranges. The ADXL345 supports the following ranges:
+
+- ±2g  (approx. ±19.61 m/s^2)
+- ±4g  (approx. ±39.23 m/s^2)
+- ±8g  (approx. ±78.45 m/s^2)
+- ±16g (approx. ±156.91 m/s^2)
 
 2. Device Attributes
 ====================

@@ -98,23 +103,23 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_gesture_singletap_timeout          | Single tap duration in [us]                 |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_gesture_singletap_value            | Single tap threshold value in 62.5/LSB      |
+| in_accel_gesture_singletap_value            | Single tap threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_falling_period                 | Inactivity time in seconds                  |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_falling_value                  | Inactivity threshold value in 62.5/LSB      |
+| in_accel_mag_falling_value                  | Inactivity threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_rising_en             | Enable AC coupled activity on X axis        |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_falling_period        | AC coupled inactivity time in seconds       |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold in 62.5/LSB |
+| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold             |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold in 62.5/LSB   |
+| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold               |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_rising_en                      | Enable activity detection on X axis         |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_rising_value                   | Activity threshold value in 62.5/LSB        |
+| in_accel_mag_rising_value                   | Activity threshold value                    |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_x_gesture_singletap_en             | Enable single tap detection on X axis       |
 +---------------------------------------------+---------------------------------------------+

Documentation/iio/adxl345.rst listed. · line 137

Quoted 7 lines

Documentation/iio/adxl345.rst +4 -0

@@ -126,6 +131,10 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_z_gesture_singletap_en             | Enable single tap detection on Z axis       |
 +---------------------------------------------+---------------------------------------------+
+| in_accel_gesture_scale                      | Tap threshold scale (0.612915 m/s^2).       |
++---------------------------------------------+---------------------------------------------+
+| in_accel_mag_scale                          | Activity threshold scale (0.612915 m/s^2).  |
++---------------------------------------------+---------------------------------------------+

It looks like the others are in alphabetical order (or , so would be nice to insert the new ones in the appropriate order.

(in_accel_mag_falling is also out of order, so that could be part of the precursor cleanup patch)

Also, missing in_accel_mag_adaptive_scale (it was added in the driver changes.)

Jonathan Cameron

maintainer

2026-02-15 19:29 UTC #10 lore raw

Re: [PATCH v3 4/4] docs: iio: adxl345: update math and examples for scaling

Quoted 65 lines · On Sat, 14 Feb 2026 11:11:41 -0600 David Lechner <[email protected]> wrote:

Quoted 64 lines · Taha Ed-Dafili

Update the documentation to reflect the addition of event scaling and correct existing technical errors in scale values.

Signed-off-by Taha Ed-Dafili <[email protected]>

---
 Documentation/iio/adxl345.rst | 41 +++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 14 deletions(-)

Documentation/iio/adxl345.rst +11 -6

index 3ca6a78feb5b..321565699817 100644
@@ -13,7 +13,12 @@ This driver supports Analog Device's ADXL345/375 on SPI/I2C bus.
 * `ADXL375 <https://www.analog.com/ADXL375>`_
 
 The ADXL345 is a general-purpose, low-power, 3-axis accelerometer with selectable
-measurement ranges. The ADXL345 supports the ±2 g, ±4 g, ±8 g, and ±16 g ranges.
+measurement ranges. The ADXL345 supports the following ranges:
+
+- ±2g  (approx. ±19.61 m/s^2)
+- ±4g  (approx. ±39.23 m/s^2)
+- ±8g  (approx. ±78.45 m/s^2)
+- ±16g (approx. ±156.91 m/s^2)
 
 2. Device Attributes
 ====================

@@ -98,23 +103,23 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_gesture_singletap_timeout          | Single tap duration in [us]                 |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_gesture_singletap_value            | Single tap threshold value in 62.5/LSB      |
+| in_accel_gesture_singletap_value            | Single tap threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_falling_period                 | Inactivity time in seconds                  |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_falling_value                  | Inactivity threshold value in 62.5/LSB      |
+| in_accel_mag_falling_value                  | Inactivity threshold value                  |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_rising_en             | Enable AC coupled activity on X axis        |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_adaptive_falling_period        | AC coupled inactivity time in seconds       |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold in 62.5/LSB |
+| in_accel_mag_adaptive_falling_value         | AC coupled inactivity threshold             |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold in 62.5/LSB   |
+| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold               |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_mag_rising_en                      | Enable activity detection on X axis         |
 +---------------------------------------------+---------------------------------------------+
-| in_accel_mag_rising_value                   | Activity threshold value in 62.5/LSB        |
+| in_accel_mag_rising_value                   | Activity threshold value                    |
 +---------------------------------------------+---------------------------------------------+
 | in_accel_x_gesture_singletap_en             | Enable single tap detection on X axis       |
 +---------------------------------------------+---------------------------------------------+

Quoted 8 lines

Documentation/iio/adxl345.rst listed. · line 137

Quoted 8 lines

Documentation/iio/adxl345.rst +4 -0

@@ -126,6 +131,10 @@ listed.
 +---------------------------------------------+---------------------------------------------+
 | in_accel_z_gesture_singletap_en             | Enable single tap detection on Z axis       |
 +---------------------------------------------+---------------------------------------------+
+| in_accel_gesture_scale                      | Tap threshold scale (0.612915 m/s^2).       |
++---------------------------------------------+---------------------------------------------+
+| in_accel_mag_scale                          | Activity threshold scale (0.612915 m/s^2).  |
++---------------------------------------------+---------------------------------------------+

Does it? See below,

Quoted 9 lines

It looks like the others are in alphabetical order (or , so would be nice to insert the new ones in the appropriate order.
(in_accel_mag_falling is also out of order, so that could be part of the precursor cleanup patch)
Also, missing in_accel_mag_adaptive_scale (it was added in the driver changes.)

That missing is particularly interesting as I think Claude code + Chris's prompts found an issue (took a while as I ran out of tokens yesterday!)

Issue: IIO_EV_INFO_SCALE is added to mask_shared_by_type for MAG and
MAG_ADAPTIVE event types (both rising and falling), but adxl345_read_mag_value() doesn't handle IIO_EV_INFO_SCALE — it falls through to default: return -EINVAL. The sysfs attributes in_accel_mag_scale and in_accel_mag_adaptive_scale will be created by the IIO core but reading them returns -EINVAL. The scale case is only handled for IIO_EV_TYPE_GESTURE events.

Which i think is right:
The code is only added in patch 3 for the TYPE_GESTURE, but the relevant bit is set to create the interface you call out as missing... + indeed in_accel_mag_scale.

Taha assuming this bug report is correct, please up your testing game. This stuff is much easier for an author to find by actually looking at what new files are created and checking they respond as expected than it is for reviewers to figure out from patches.

Jonathan

Quoted 1 line

Jonathan Cameron

maintainer

2026-02-14 17:21 UTC #11 lore raw

In reply to Taha Ed-Dafili

Quoted 11 lines · On Sun, 8 Feb 2026 10:05:01 -0500 Taha Ed-Dafili <[email protected]> wrote:

This series addresses ADXL345 driver non-compliance with the IIO ABI for event thresholds.
Currently, the driver exposes raw values for thresholds (e.g., tap, activity) without providing the necessary scale factor to convert them to SI units (m/s^2), as mandated by the ABI.
This series implements IIO_EV_INFO_SCALE in the IIO core and applies it to the ADXL345 driver, ensuring that userspace can correctly interpret threshold values. It also cleans up existing documentation errors and typos.

Nice series thanks!

Applied to the testing branch of iio.git which I'll rebase once rc1 is available.

Jonathan

Quoted 30 lines

Changes in v3:
- Patch 1: Reverted "axis" -> "axes" change in documentation as it is used as an adjective (Randy Dunlap).
- Patch 2: Reworded commit message to "Implement support for..." instead of "missing from..." (David Lechner).
- Patch 4: Simplified documentation table by removing repetitive scale values from every row. Added explicit table entries for the new in_accel_gesture_scale and in_accel_mag_scale attributes instead (Jonathan Cameron).
- Patch 4: Fixed "inscale" typo in commit message.
Changes in v2:
- Added core infrastructure for IIO_EV_INFO_SCALE.
- Implemented event scaling (0.612915 m/s^2) for ADXL345.
- Fixed technical math/decimal errors in existing documentation.
- Cleaned up grammar and pluralization issues in .rst file.
Taha Ed-Dafili (4):
docs: iio: adxl345: fix typos and grammar
iio: core: Add IIO_EV_INFO_SCALE to event info
iio: accel: adxl345: Implement event scaling for ABI compliance
docs: iio: adxl345: update math and examples for scaling
 Documentation/iio/adxl345.rst    | 65 +++++++++++++++++++-------------
 drivers/iio/accel/adxl345_core.c | 28 +++++++++++---
 drivers/iio/industrialio-event.c |  1 +
 include/linux/iio/types.h        |  1 +
 4 files changed, 63 insertions(+), 32 deletions(-)

Jonathan Cameron

maintainer

2026-02-15 15:57 UTC #12 lore raw

Quoted 10 lines · On Sat, 14 Feb 2026 17:21:45 +0000 Jonathan Cameron <[email protected]> wrote:

Quoted 7 lines · On Sun, 8 Feb 2026 10:05:01 -0500 Taha Ed-Dafili <[email protected]> wrote:
This series addresses ADXL345 driver non-compliance with the IIO ABI for event thresholds.
Currently, the driver exposes raw values for thresholds (e.g., tap, activity) without providing the necessary scale factor to convert them to SI units (m/s^2), as mandated by the ABI.

Quoted 8 lines

Quoted 4 lines
This series implements IIO_EV_INFO_SCALE in the IIO core and applies it to the ADXL345 driver, ensuring that userspace can correctly interpret threshold values. It also cleans up existing documentation errors and typos.
Nice series thanks!
Applied to the testing branch of iio.git which I'll rebase once rc1 is available.

Ah. Raced with other feedback. Dropped again for now.

Jonathan

Quoted 35 lines

Jonathan
Quoted 30 lines
Changes in v3:
- Patch 1: Reverted "axis" -> "axes" change in documentation as it is used as an adjective (Randy Dunlap).
- Patch 2: Reworded commit message to "Implement support for..." instead of "missing from..." (David Lechner).
- Patch 4: Simplified documentation table by removing repetitive scale values from every row. Added explicit table entries for the new in_accel_gesture_scale and in_accel_mag_scale attributes instead (Jonathan Cameron).
- Patch 4: Fixed "inscale" typo in commit message.
Changes in v2:
- Added core infrastructure for IIO_EV_INFO_SCALE.
- Implemented event scaling (0.612915 m/s^2) for ADXL345.
- Fixed technical math/decimal errors in existing documentation.
- Cleaned up grammar and pluralization issues in .rst file.
Taha Ed-Dafili (4):
docs: iio: adxl345: fix typos and grammar
iio: core: Add IIO_EV_INFO_SCALE to event info
iio: accel: adxl345: Implement event scaling for ABI compliance
docs: iio: adxl345: update math and examples for scaling
 Documentation/iio/adxl345.rst    | 65 +++++++++++++++++++-------------
 drivers/iio/accel/adxl345_core.c | 28 +++++++++++---
 drivers/iio/industrialio-event.c |  1 +
 include/linux/iio/types.h        |  1 +
 4 files changed, 63 insertions(+), 32 deletions(-)

Taha Ed-Dafili

author

2026-02-15 17:11 UTC #13 lore raw

Quoted 1 line · Jonathan Cameron

Ah. Raced with other feedback. Dropped again for now.

Understood. I will prepare a v4 addressing the feedback from David, Andy, and Randy regarding attribute ordering, whitespace consistency, and the missing documentation entry.

Thank you all for your time and guidance.

Best regards,
Taha