linux-kernel - Re: [PATCH] docs: iio: adxl345: Fix typos, units, and grammatical errors

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 for Android: free password hash cracker in your pocket
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <20260129173337.7fc2a4ad@jic23-huawei>
Date: Thu, 29 Jan 2026 17:33:37 +0000
From: Jonathan Cameron <jic23@...nel.org>
To: Taha Ed-Dafili <0rayn.dev@...il.com>
Cc: me@...ghamcampbell.com, skhan@...uxfoundation.org,
 linux-kernel-mentees-archive@...ts.linuxfoundation.org,
 dlechner@...libre.com, nuno.sa@...log.com, andy@...nel.org, corbet@....net,
 linux-iio@...r.kernel.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs: iio: adxl345: Fix typos, units, and grammatical
 errors

On Tue, 27 Jan 2026 12:34:51 -0500
Taha Ed-Dafili <0rayn.dev@...il.com> wrote:

> Clean up the ADXL345 documentation to improve technical accuracy
> and readability:
> - Fix "latent" to "latency" in double tap descriptions.
> - Correct the threshold unit from "g/LSB" to "mg/LSB"
>   to match the datasheet.
> - Standardize "axis" to "axes" for plural references.
> - Change "generic purpose" to "general purpose".
> - Fix minor subject-verb agreement and punctuation errors.
> 
> Signed-off-by: Taha Ed-Dafili <0rayn.dev@...il.com>
Hi Taha,

Thanks for looking at this.  Unfortunately you are the victim of making
people read it again and spot other issues :(

Not sure we can easily answer them but I have some concerns having
looked at this doc again. Seems at minimum the scaling presented by the driver
is wrong. Also the listing in this file for in_accel_scale_available is incorrect as well.

> ++---------------------------------------------+------------------------------------------------+
> +| Event handle                                | Description                                    |
> ++---------------------------------------------+------------------------------------------------+
> +| 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 latency in [us]                     |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_gesture_singletap_timeout          | Single tap duration in [us]                    |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_gesture_singletap_value            | Single tap threshold value in 62.5 mg/LSB      |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_mag_falling_period                 | Inactivity time in seconds                     |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_mag_falling_value                  | Inactivity threshold value in 62.5 mg/LSB      |
> ++---------------------------------------------+------------------------------------------------+
> +| 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 mg/LSB |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_mag_adaptive_rising_value          | AC coupled activity threshold in 62.5 mg/LSB   |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_mag_rising_en                      | Enable activity detection on X axis            |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_mag_rising_value                   | Activity threshold value in 62.5 mg/LSB        |

To be compliant with the ABI these should be in whatever is provided by in_accel_scale
which according to elsewhere in this doc is any of 0.478899 0.957798 1.915595 3.831190
which are in m/s^2 / LSB
None of those look like they are 62.5 mg

Given there is no other way of establishing scale, if the thresholds really don't change their
scaling with the sensor scale (which would be unusual) then we'd need to compensate the values
in these attributes so that they are still value * _scale ends up in m/s^2.

Those numbers for in_accel_scale are also wrong.  They should be as per the comment
in the driver
0.004789, 0.009578, 0.019156 and 0.038312

(so please fix that whilst you are here - probably in a separate patch as it's a fix
rather than tidying up.

As to what to do about the units.  Firstly, express them all in m/s^2 / LSB so we can more
easily spot the miss match.  Secondly looks like the driver needs a fix to have the right
scaling for these and that runs the risk of causing problems for anyone using it. 

We do have a fairly rarely used ABI option of adding ../events/in_accel_scale
(see Documentation/ABI/testing/sysfs-bus-iio) which allows us to indicate a different
scale factor from the main channel scaling.  That is probably the best approach here.
That would then reflect the scale in m/s^2 for each LSB which correpsonds to this 62.5 mg/LSB.


> ++---------------------------------------------+------------------------------------------------+
> +| 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 axes        |
> ++---------------------------------------------+------------------------------------------------+
> +| 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          |
> ++---------------------------------------------+------------------------------------------------+
> +| in_accel_z_gesture_singletap_en             | Enable single tap detection on Z axis          |
> ++---------------------------------------------+------------------------------------------------+