Re: [PATCH v9 2/5] Documentation: iio: add Open Sensor Fusion driver overview

[Randy Dunlap]

Hi,

On 9/9/26 8:05 AM, Jinseob Kim wrote:
> Document the Linux IIO mapping for Open Sensor Fusion devices.
> 
> The overview explains that sensor channels are discovered at runtime
> from mandatory capability reports. It also documents that OSF0 is a
> wire-format detail and that protocol_major and protocol_minor carry
> protocol compatibility information.
> 
> Assisted-by: LLM
> Signed-off-by: Jinseob Kim <kimjinseob88@xxxxxxxxx>
> ---
>  Documentation/iio/index.rst              |  1 +
>  Documentation/iio/open-sensor-fusion.rst | 84 ++++++++++++++++++++++++
>  MAINTAINERS                              |  1 +
>  3 files changed, 86 insertions(+)
>  create mode 100644 Documentation/iio/open-sensor-fusion.rst
> 

What email client did you use to send this patch?
It is wrapping (longer) lines for you, in a way that's not good.
It causes malformed patches.
You can see it below or at
https://lore.kernel.org/linux-doc/CALMSewK17jG3MXTHv4Rj+tFVriw9+tqNuAMcX4KGQGy5NQP_MQ@xxxxxxxxxxxxxx/T/#u


> diff --git a/Documentation/iio/open-sensor-fusion.rst
> b/Documentation/iio/open-sensor-fusion.rst
> new file mode 100644
> index 000000000000..15d41202eb66
> --- /dev/null
> +++ b/Documentation/iio/open-sensor-fusion.rst
> @@ -0,0 +1,84 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +Open Sensor Fusion
> +==================
> +
> +Open Sensor Fusion is a sensor aggregation hub interface. The Linux IIO driver
> +receives OSF protocol frames from an attached device and registers matching IIO
> +devices for the sensor classes supported by the driver. The actual sensor
> +channels are discovered at runtime from mandatory OSF capability reports.
> +
> +This document is a driver-facing overview for the Linux IIO mapping. The full
> +wire protocol, firmware behavior, and hardware model details belong in the Open
> +Sensor Fusion project documentation.
> +
> +Device Model
> +------------
> +
> +An OSF device sends binary frames from the device to the host.
> Devices using the

^^^ Should be one line, not two.

> +``opensensorfusion,osf`` compatible are expected to provide
> +``CAPABILITY_REPORT`` messages so the host can discover which sensor
> streams are

Same.

> +available. Device Tree describes the attached OSF sensor aggregation
> hub; it does

Same.

> +not enumerate the individual sensors discovered at runtime.
> +
> +The currently supported Linux subset exposes:
> +
> +* accelerometer samples as ``IIO_ACCEL`` X/Y/Z channels,
> +* gyroscope samples as ``IIO_ANGL_VEL`` X/Y/Z channels,
> +* magnetometer samples as ``IIO_MAGN`` X/Y/Z channels, and
> +* temperature samples as ``IIO_TEMP``.
> +
> +Protocol Scope
> +---------------
> +
> +The driver supports OSF protocol major version 0 for the IIO receive path.
> +The current wire magic is ``OSF0``; that string is a wire-format detail and is
> +not the Linux driver identity. Device Tree keeps the generic
> +``opensensorfusion,osf`` compatible rather than naming a product such as OSF
> +GREEN or a wire magic value.
> +
> +Protocol versioning is carried by the ``protocol_major`` and ``protocol_minor``
> +fields at fixed offsets in the OSF frame header. The driver currently
> +supports ``protocol_major`` 0. ``protocol_minor`` changes within major version
> +0 are intended to remain backward-compatible within the fixed header layout.
> +Incompatible wire-format changes require a new ``protocol_major``. A future
> +device that cannot expose compatible version discovery through that fixed
> +header layout would need a different Device Tree compatible.
> +
> +The Linux driver handles device-to-host frames for:
> +
> +* ``SENSOR_SAMPLE`` buffered and direct-mode sample data,
> +* ``CAPABILITY_REPORT`` based IIO device registration, and
> +* ``DEVICE_STATUS`` cache updates.
> +
> +Vendor-private message types are ignored. Command transport, calibration
> +control ABI, fusion output ABI, and runtime capability removal are outside the
> +Linux IIO receive path.
> +
> +Timestamps
> +----------
> +
> +OSF frames include a device-side ``timestamp_us`` field. Buffered IIO
> samples use

Same.

> +an IIO timestamp captured on the host when samples are pushed to IIO buffers.
> +The driver does not correlate the device timestamp with the host IIO
> +clock.
> +
> +Compatibility Notes
> +-------------------
> +
> +This overview describes the implemented receive path, not a normative wire
> +specification. A publicly versioned specification covering reserved fields,
> +extensions and physical scale units remains needed for interoperability review.
> +
> +The decoder requires the fixed header size and the exact payload lengths of
> +known messages. It ignores unsupported protocol majors, unknown message types
> +and frames with nonzero header reserved fields. Unsupported capability entries
> +are skipped individually; malformed known payloads are rejected. Appending data
> +to an existing known message is therefore not a compatible extension for this
> +receiver.
> +
> +IIO scale is taken from the initial capability report and is not updated by
> +sample frames. Devices must supply scales in the units required by each IIO
> +channel type, including gauss for magnetometers. Historical OSF draft documents
> +differ on reserved-field handling, trailing extensions and magnetometer units;
> +those drafts do not establish a canonical specification for this driver.

There is some help for various email clients in Documentation/process/email-clients.rst
that may help you (or not).

-- 
~Randy