Re: [PATCH v10 2/8] Documentation: iio: add Open Sensor Fusion driver overview

[Jonathan Cameron <jic23@kernel.org>]

On Sat, 19 Sep 2026 03:24:40 +0900
Jinseob Kim <kimjinseob88@gmail.com> wrote:

> Document the supported OSF receiver profile, runtime sensor discovery,
> IIO channel units, scale validation and session lifetime.
> 
> Link the project-maintained fixed wire specification instead of
> duplicating its layouts and compatibility policy. Explain host IIO
> timestamps and the explicit rebind needed after a changed inventory.
> 
> Assisted-by: LLM
> Signed-off-by: Jinseob Kim <kimjinseob88@gmail.com>

Hi Jinseob,

Just a couple of minor things inline.

Thanks,

Jonathan

> ---
>  Documentation/iio/index.rst              |  1 +
>  Documentation/iio/open-sensor-fusion.rst | 77 ++++++++++++++++++++++++
>  MAINTAINERS                              |  1 +
>  3 files changed, 79 insertions(+)
>  create mode 100644 Documentation/iio/open-sensor-fusion.rst
> 
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> index b02b879b053a..c2b7963348fd 100644
> --- a/Documentation/iio/index.rst
> +++ b/Documentation/iio/index.rst
> @@ -40,4 +40,5 @@ Industrial I/O Kernel Drivers
>     adxl345
>     bno055
>     ep93xx_adc
> +   open-sensor-fusion
>     opt4060
> diff --git a/Documentation/iio/open-sensor-fusion.rst b/Documentation/iio/open-sensor-fusion.rst
> new file mode 100644
> index 000000000000..03ab36aca5f8
> --- /dev/null
> +++ b/Documentation/iio/open-sensor-fusion.rst
> @@ -0,0 +1,77 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +Open Sensor Fusion
> +==================
> +
> +Open Sensor Fusion is a sensor aggregation hub interface. The Linux IIO driver
> +receives device-to-host frames over UART and discovers sensor channels from
> +capability reports. Device Tree describes the hub using the
> +``opensensorfusion,osf`` compatible; individual sensors are discovered at
> +runtime. See the binding in
> +``Documentation/devicetree/bindings/iio/opensensorfusion,osf.yaml``.
> +
> +The OSF Device-to-Host 0.0 specification is maintained by the Open Sensor Fusion
> +project. The canonical specification_ defines the wire layout, compatibility
> +rules, reserved fields and physical units. This document describes the Linux
> +receiver profile and its mapping to IIO.
> +
> +.. _specification: https://github.com/opensensorfusion/opensensorfusion-protocol/blob/ca9cdea1ae550c2b4d6f29f87877adae99470744/spec/osf-d2h-0.0.md
> +
> +Supported receive profile
> +-------------------------
> +
> +The driver supports the fixed OSF0 frame layout with protocol major version 0.
> +Compatible minor versions use the same known message layouts. The decoder
> +requires exact lengths for known messages, validates CRC and bounds before
> +interpreting payloads, and tolerates reserved padding. Unsupported majors and

If you spin again "Unsupported major versions and.."

> +unknown message types are ignored. Unsupported capability entries are skipped
> +individually. A CRC-valid application rejection consumes the complete frame;
> +an invalid frame candidate is resynchronized without trusting its payload length.
> +
> +The receive path handles sensor samples, complete capability reports and
> +device status. Its limits are 4096 bytes per frame and 16 supported sensor
> +descriptors. These are implementation limits, not protocol-wide maxima.
> +
> +IIO mapping
> +-----------
> +
> +The supported sensor classes map to:
> +
> +* accelerometer: ``IIO_ACCEL`` X/Y/Z, in m/s^2;
> +* gyroscope: ``IIO_ANGL_VEL`` X/Y/Z, in rad/s;
> +* magnetometer: ``IIO_MAGN`` X/Y/Z, in gauss;
> +* temperature: ``IIO_TEMP``, in millidegrees Celsius.
> +
> +Each registered channel exposes signed ``RAW`` data and descriptor-derived
> +``SCALE``. Multiplying RAW by SCALE gives a value in the channel's IIO unit.
> +Buffered samples use signed 32-bit values with native CPU endianness. Active
> +channels are packed into the scan, with initialized padding before an optional
> +64-bit timestamp.
> +
> +Discovery and session lifetime
> +------------------------------
> +
> +The driver validates all supported descriptors before registering IIO devices.
> +An empty or entirely unsupported initial report leaves discovery open for a
> +later supported report. 

So if the device can send multiple discovery reports, this implies if we
recognise something in the first one we will stop looking at later ones?
That seems odd given if we don't recognise anything we keep looking.
If I'm reading too much into this text, then please tweak it to make
it clear why this doesn't matter.

> Supported descriptors must advertise a nonzero scale.
> +A sample's channel count, format and scale must match its registered descriptor
> +before it can update the latest RAW cache or be published to a buffer. A
> +rejected sample preserves previously accepted data.
> +
> +Repeated reports are compared by sensor type and index, independently of entry
> +order. Reserved padding, advisory flags and unsupported additions do not change
> +the supported inventory. A supported key appearing or disappearing, or a
> +change in its channel count, format or scale, faults the bound session.
> +
> +After a session fault, new cache updates and buffer publication stop, and
> +direct RAW reads fail. Existing IIO devices remain until driver teardown.
> +An equivalent report does not clear the fault; explicit unbind/rebind starts
> +fresh discovery. No fault-specific userspace ABI is exposed.
> +
> +Timestamps
> +----------
> +
> +Buffered samples use the selected IIO host clock when they are pushed into
> +the buffer. The device timestamp is not correlated with that clock and is not
> +used as the IIO buffer timestamp. Device timestamp or sequence discontinuities
> +alone do not start a new host session.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9463b8111d52..26b9b2862724 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20515,6 +20515,7 @@ OPEN SENSOR FUSION
>  M:	Jinseob Kim <kimjinseob88@gmail.com>
>  S:	Maintained
>  F:	Documentation/devicetree/bindings/iio/opensensorfusion,osf.yaml
> +F:	Documentation/iio/open-sensor-fusion.rst
>  K:	opensensorfusion
>  
>  OPENCOMPUTE PTP CLOCK DRIVER