+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. 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@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. The base has multiple compatible strings, so which one? Has to match on any one or all of them? > +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 >
