Hi Raymond, On Tue Jun 24, 2025 at 9:13 PM EEST, 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 patch updates the document with a note and example for this > practice. I think it would make sense to describe the firmware handoff stuff shortly here [0] and explain why we need it. I.e it's possible for devices have a common firmware binary which only differs on the DT and the applied overlays so we need a way to identify which overlays should be applied once the DT is selected. [0] https://github.com/FirmwareHandoff/firmware_handoff Also please add Suggested-by: Ilias Apalodimas <ilias.apalodimas@xxxxxxxxxx> if you send another version. Thanks /Ilias > > Signed-off-by: Raymond Mao <raymond.mao@xxxxxxxxxx> > --- > 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"; > + > + ... > + ---- 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 > -------------------------------- >
