Hi Rob, On Wed, 9 Jul 2025 at 20:58, Rob Herring <robh@xxxxxxxxxx> 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@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? 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 > >
