Re: [PATCH] docs: devicetree: overlay-notes: recommend top-level compatible in DTSO

[Raymond Mao <raymond.mao@linaro.org>]

Hi Rob,

On Wed, 9 Jul 2025 at 20:58, Rob Herring <robh@kernel.org> wrote:
>
> +devicetree-spec (because linux-doc doesn't really care)
>
> On Tue, Jun 24, 2025 at 11:13:20AM -0700, Raymond Mao wrote:
> > When managing multiple base device trees and overlays in a structured
> > way (e.g. bundled in firmware or tools), it is helpful to identify the
> > intended target base DT for each overlay, which can be done via a
> > top-level compatible string in the overlay.
>
> I think this should be more general and more specific at the same time.
>
> You might not want to match on a top-level board/soc compatible, but
> rather the compatible for a specific node. For example, you may have an
> overlay for a cape, hat, etc. that applies to a connector node and that
> connector node could be on any number of boards or even multiple
> connectors on 1 board. That's all under development, but so far in those
> cases we expect some sort of connector driver to apply the overlays. But
> I think you could have the same issue of identifying which overlay files
> are relevant. I don't think folks working on add-on boards have thought
> that far ahead.
>

The use case from the angle of a specific driver might be a completely
different scenario.
The motivation of this patch is to support handing over DTOs as
transfer entries across different boot stages via transfer list.
Unlike for a specific driver, a DTO within a transfer entry is usually
board-leveled and contains nodes for more than one driver.
The transfer list library in each boot stage does not have knowledge
on a single specific driver and which target base should be applied is
the only interest.
That is the common DTO use case in Firmware Handoff and why we need
the top-level compatible to be introduced.
For details, please see my PR for the Firmware Handoff spec update to
support DTO as transfer entries at:
https://github.com/FirmwareHandoff/firmware_handoff/pull/74

> And since we don't know the target-path up front, it is just left blank
> so far. It would be better if we expressed *something*. Perhaps
> 'target-compatible'? Something like that would work in your case I
> think.
>
> You'd have to be somewhat crazy, but you can bundle a bunch of
> mutually-exclusive or unrelated overlays within a single overlay file. I
> don't know that we want to prevent doing that. Someone might come up
> with some not crazy reason to do that...
>
> >
> > This patch updates the document with a note and example for this
> > practice.
> >
> > Signed-off-by: Raymond Mao <raymond.mao@linaro.org>
> > ---
> >  Documentation/devicetree/overlay-notes.rst | 28 ++++++++++++++++++++++
> >  1 file changed, 28 insertions(+)
> >
> > diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst
> > index 35e79242af9a..30b142d1b2ee 100644
> > --- a/Documentation/devicetree/overlay-notes.rst
> > +++ b/Documentation/devicetree/overlay-notes.rst
> > @@ -103,6 +103,34 @@ The above bar.dtso example modified to use target path syntax is::
> >      ---- bar.dtso --------------------------------------------------------------
> >
> >
> > +Overlay identification
> > +----------------------
> > +
> > +When managing overlays dynamically or bundling multiple base device trees
> > +and overlays in a single system (e.g., in firmware, initramfs, or user-space
> > +tools), it becomes important to associate each overlay with its intended
> > +target base DT.
> > +
> > +To support this, overlays should include the top-level compatible string
> > +from its base DT.
>
> The base has multiple compatible strings, so which one? Has to match on
> any one or all of them?

Match only with base's top-level compatible, see above for the
explanation of the use case.

Regards,
Raymond

>
> > +This enables higher-level software or firmware to identify which base DT
> > +an overlay is compatible with and apply it accordingly.
> > +
> > +Example usage::
> > +
> > +    ---- bar.dtso - overlay with top-level compatible string -------------------
> > +     /dts-v1/;
> > +     /plugin/;
> > +     compatible = "corp,foo";
> > +
> > +     ...
> > +    ---- bar.dtso --------------------------------------------------------------
> > +
> > +This top-level compatible string is not required by the kernel overlay
> > +mechanism itself, but it is strongly recommended for managing overlays in
> > +scalable systems.
> > +
> > +
> >  Overlay in-kernel API
> >  --------------------------------
> >
> > --
> > 2.25.1
> >