linux-kernel - Re: [v3 13/13] docs: iio: add documentation for BNO055 driver

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]

Message-ID: <20220219170645.565afed8@jic23-huawei>
Date:   Sat, 19 Feb 2022 17:06:45 +0000
From:   Jonathan Cameron <jic23@...nel.org>
To:     Andrea Merello <andrea.merello@...il.com>
Cc:     mchehab+huawei@...nel.org, linux-iio@...r.kernel.org,
        linux-kernel@...r.kernel.org, devicetree@...r.kernel.org,
        lars@...afoo.de, robh+dt@...nel.org, andy.shevchenko@...il.com,
        matt.ranostay@...sulko.com, ardeleanalex@...il.com,
        jacopo@...ndi.org, Andrea Merello <andrea.merello@....it>
Subject: Re: [v3 13/13] docs: iio: add documentation for BNO055 driver

On Thu, 17 Feb 2022 17:27:10 +0100
Andrea Merello <andrea.merello@...il.com> wrote:

Perhaps a comment on why it's worth having documentation for this device
when we rarely bother?  (complex device etc...)

> Signed-off-by: Andrea Merello <andrea.merello@....it>
> ---
>  Documentation/iio/bno055.rst | 53 ++++++++++++++++++++++++++++++++++++

Please add it to an appropriate index such as Docuemntation/iio/index.rst
so that it actually gets linked to in the documentation built.

One comment inline.

>  1 file changed, 53 insertions(+)
>  create mode 100644 Documentation/iio/bno055.rst
> 
> diff --git a/Documentation/iio/bno055.rst b/Documentation/iio/bno055.rst
> new file mode 100644
> index 000000000000..4bb185075325
> --- /dev/null
> +++ b/Documentation/iio/bno055.rst
> @@ -0,0 +1,53 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +==============================
> +BNO055 driver
> +==============================
> +
> +1. Overview
> +===========
> +
> +This driver supports Bosch BNO055 IMUs (on both serial and I2C busses).
> +
> +Accelerometer, magnetometer and gyroscope measures are always provided.
> +When "fusion_enable" sysfs attribute is set to 1, orientation (both Euler
> +angles and quaternion), linear velocity and gravity vector are also
> +provided, but some sensor settings (e.g. low pass filtering and range)
> +became locked (the IMU firmware controls them).
> +
> +IIO attributes for unavailable measurements (e.g. Euler angles when fusion
> +mode is disabled) just read zero.

Hmm. Should probably return -EBUSY as 0 could be a valid value.

> +
> +This driver supports also IIO buffers.
> +
> +2. Calibration
> +==============
> +
> +The IMU continuously performs an autocalibration procedure if (and only if)
> +operating in fusion mode. The magnetometer autocalibration can however be
> +disabled writing 0 in the sysfs in_magn_calibration_fast_enable attribute.
> +
> +The driver provides access to autocalibration flags (i.e. you can known if
> +the IMU has successfully autocalibrated) and to the calibration data blob.
> +
> +The user can save this blob in a firmware file (i.e. in /lib/firmware) that
> +the driver looks for at probe time. If found, then the IMU is initialized
> +with this calibration data. This saves the user from performing the
> +calibration procedure every time (which consist of moving the IMU in
> +various way).
> +
> +The driver looks for calibration data file using two different names: first
> +a file whose name is suffixed with the IMU unique ID (exposed in sysfs as
> +serial_number) is searched for; this is useful when there is more than one
> +IMU instance. If this file is not found, then a "generic" calibration file
> +is searched for (which can be used when only one IMU is present, without
> +struggling with fancy names, that change on each device).
> +
> +Valid calibration file names would be e.g.
> + bno055-caldata-0e7c26a33541515120204a35342b04ff.dat
> + bno055-caldata.dat
> +
> +In non-fusion mode the IIO 'offset' attributes provide access to the
> +offsets from calibration data (if any), so that the user can apply them to
> +the accel, angvel and magn IIO attributes. In fusion mode they are not
> +needed (the IMU firmware internally applies those corrections) and they
> +read as zero.