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

[Kim Jinseob]

Hi Randy,

> What email client did you use to send this patch?

I used a tool that sends through the Gmail API.

I'll check the received raw messages to investigate the line wrapping.

Thanks,

Jinseob


2026년 9월 10일 (목) 오전 1:02, Randy Dunlap <rdunlap@xxxxxxxxxxxxx>님이 작성:
>
> 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
>