Hi David, On Wed, 3 Sept 2025 at 22:58, David Gibson <david@xxxxxxxxxxxxxxxxxxxxx> 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 <ilias.apalodimas@xxxxxxxxxx> > > Acked-by: Conor Dooley <conor.dooley@xxxxxxxxxxxxx> > > Signed-off-by: Raymond Mao <raymond.mao@xxxxxxxxxx> > > --- > > 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
