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

Hi David,

On Wed, 3 Sept 2025 at 22:58, David Gibson <[email protected]> wrote:
>
> On Tue, Sep 02, 2025 at 10:43:50AM -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.
> >
> > This provides a way to identify which overlays should be applied once the
> > DT is selected for the case when a device have a common firmware binary
> > which only differs on the DT and overlays.
> >
> > This patch updates the document with a note and example for this
> > practice.
> > For more information on this firmware requirement, please see [1].
> >
> > [1] https://github.com/FirmwareHandoff/firmware_handoff/pull/74
>
> I think this idea is probably useful enough to be a good idea anyway.
> However, note that it leans in to an existing ugliness of the overlay format:
>
> Overlay dtbs kind of mix "in band" information - the actual new
> content for the tree - with "out of band" information - how to apply
> the overlay itself.  Whether a given property is data or metadata is
> determined by it's place in the tree in a moderately complex and not
> super obvious way.
>
> About the clearest divide that exists is that generally the root and
> first-level subnodes are information only for overlay application,
> everything under that is data to be applied to the tree.  This all
> tends to have names that would be unlikely (though not strictly
> impossible) in a fully applied tree.
>
> Putting 'compatible' at the root of the overlay is putting something
> that looks very much like a regular device tree property in a place
> and with a function that's purely about applying / validating the
> overlay itself.
>

Since all information at the root of an overlay is considered as
metadata (out-of-band),
If you think 'compatible' is confused, I can change it to
'overlay-compatible' - which should be 'unlikely' to exist in a full
tree.

Regards,
Raymond

> > Suggested-by: Ilias Apalodimas <[email protected]>
> > Acked-by: Conor Dooley <[email protected]>
> > Signed-off-by: Raymond Mao <[email protected]>
> > ---
> > Changes in v2:
> > - Updated commit message.
> >
> >  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.
> > +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";
>
> This is not valid dts syntax.  Properties must be within a node.
>
> > +
> > +     ...
> > +    ---- 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
> >
> >
>
> --
> David Gibson (he or they)       | I'll have my music baroque, and my code
> david AT gibson.dropbear.id.au  | minimalist, thank you, not the other way
>                                 | around.
> http://www.ozlabs.org/~dgibson