Re: [PATCH RFC v2 2/7] Documentation: iio: add Open Sensor Fusion protocol v0 reference

[Jonathan Cameron <jic23@kernel.org>]

On Sun, 24 May 2026 17:53:07 +0900
Jinseob Kim <kimjinseob88@gmail.com> wrote:

> Document the OSF0 frame format and payloads used by the driver.
> 
> Signed-off-by: Jinseob Kim <kimjinseob88@gmail.com>
> ---
>  .../iio/open-sensor-fusion-protocol-v0.rst    | 267 ++++++++++++++++++
>  1 file changed, 267 insertions(+)
>  create mode 100644 Documentation/iio/open-sensor-fusion-protocol-v0.rst
> 
> diff --git a/Documentation/iio/open-sensor-fusion-protocol-v0.rst b/Documentation/iio/open-sensor-fusion-protocol-v0.rst
> new file mode 100644
> index 000000000..4800a3ce6
> --- /dev/null
> +++ b/Documentation/iio/open-sensor-fusion-protocol-v0.rst
> @@ -0,0 +1,267 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +Open Sensor Fusion protocol v0
> +==============================
> +
> +This document describes the OSF0 UART wire format used by the Linux IIO
> +driver. It is not a firmware programming interface.

Can we have some background information. Where does this OSF thing come from?
Is it a general standard or something you are personally developing?
Some links would definitely help.

> +
> +Device model
> +------------
> +
> +An Open Sensor Fusion UART device is a sensor aggregation device. It sends
> +binary frames from the device to the host. The host driver decodes the frames
> +and maps supported sensors to IIO devices.
> +
> +The hardware used for smoke testing is an OSF GREEN prototype with an
> +STM32F405RGT6 MCU, an ICM42688P-class IMU, and an MMC5983MA magnetometer. That
> +hardware is a test target, not part of the binding ABI.
> +
> +Transport
> +---------
> +
> +The transport is UART at 115200 baud, 8 data bits, no parity, and 1 stop bit.
> +The Linux transport is serdev. The v0 upstream driver covers device-to-host
> +frames. Flow control is not used by the tested stream.
> +
> +Byte order
> +----------
> +
> +All multi-byte integer fields are little-endian. Samples use signed 32-bit
> +little-endian integers when ``sample_format`` is ``S32``.

s32 given this is kernel code and i'm not sure what else this is referring to.



> +``SENSOR_SAMPLE`` payload
> +-------------------------
> +
> +The base payload size is 16 bytes.

Not sure that is meaninful given expectation that there will be channels.
I'd describe it as a payload header, or express this as 16 + 4 * channel_count

> +
> +.. list-table::
> +   :header-rows: 1
> +
> +   * - Offset
> +     - Size
> +     - Field
> +     - Description
> +   * - 0
> +     - 2
> +     - sensor_type
> +     - Sensor type ID
> +   * - 2
> +     - 2
> +     - sensor_index
> +     - Instance index
> +   * - 4
> +     - 2
> +     - channel_count
> +     - Number of S32 channels
> +   * - 6
> +     - 2
> +     - sample_format
> +     - Must be ``1`` (``S32``)

Is this spec defined, or just what the driver supports?
I think this doc needs to distinguish between those two cases
more clearly.

> +   * - 8
> +     - 4
> +     - scale_nano
> +     - Scale factor in nano-units
> +   * - 12
> +     - 4
> +     - reserved
> +     - Must be zero for v0
> +   * - 16
> +     - 4 * channel_count
> +     - samples
> +     - Signed 32-bit channel samples
> +
> +``DEVICE_STATUS`` payload
> +-------------------------
> +
> +The payload size is 20 bytes. Fields are ``uptime_s``, ``status_flags``,
> +``error_flags``, ``dropped_frames``, and a reserved field. Each field is
> +32 bits.
> +
> +``CAPABILITY_REPORT`` payload
> +-----------------------------
> +
> +The base payload size is 4 bytes. It contains ``capability_count`` and a
> +reserved field. Each capability entry is 20 bytes:

Probably want a separate table for that header.

> +
> +.. list-table::
> +   :header-rows: 1
> +
> +   * - Offset
> +     - Size
> +     - Field
> +     - Description
> +   * - 0
> +     - 2
> +     - sensor_type
> +     - Sensor type ID
> +   * - 2
> +     - 2
> +     - sensor_index
> +     - Instance index
> +   * - 4
> +     - 2
> +     - channel_count
> +     - Number of channels
> +   * - 6
> +     - 2
> +     - sample_format
> +     - Must be ``1`` (``S32``)
> +   * - 8
> +     - 4
> +     - scale_nano
> +     - Scale factor in nano-units
> +   * - 12
> +     - 4
> +     - flags
> +     - Capability flags
> +   * - 16
> +     - 4
> +     - reserved
> +     - Must be zero for v0
> +
> +Capability flag bit 0 means enabled by default. Bit 1 means calibrated data can
> +be provided by the device. Other bits are invalid for v0.
> +

> +Scaling
> +-------
> +
> +``scale_nano`` is the per-channel scale value in nano-units. The Linux driver
> +maps it to ``IIO_CHAN_INFO_SCALE`` as integer plus nano. The exact physical
> +unit depends on the IIO channel type.
> +
> +Timestamps
> +----------
> +
> +The frame header carries ``timestamp_us``, a device-side timestamp in
> +microseconds. v0 transports this value for ordering and diagnostics. The driver
> +does not use it as a production-grade host-correlated timestamp. Buffered IIO
> +timestamps follow IIO timestamp clock handling.

Is there likely to be a non trivial delay?  If so we should figure out how to use
that timestamp to get something more useful.

> +
> +Non-goals for v0 upstream
> +-------------------------
> +
> +The v0 upstream driver does not include USB transport, fusion output,
> +AHRS/Kalman output, calibration command ABI, custom sysfs control surface,

What is AHRS?  I'd spell it out.

> +production timestamp correlation, or runtime capability removal.
This is where an external link would be helpful. Lets us have some visibility
of what is coming.

Thanks,

Jonathan