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

Suggested-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
Acked-by: Conor Dooley <conor.dooley@microchip.com>
Signed-off-by: Raymond Mao <raymond.mao@linaro.org>
---
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";
+
+	...
+    ---- 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

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.

> Suggested-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
> Acked-by: Conor Dooley <conor.dooley@microchip.com>
> Signed-off-by: Raymond Mao <raymond.mao@linaro.org>
> ---
> 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

Hi David,

On Wed, 3 Sept 2025 at 22:58, David Gibson <david@gibson.dropbear.id.au> 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@linaro.org>
> > Acked-by: Conor Dooley <conor.dooley@microchip.com>
> > Signed-off-by: Raymond Mao <raymond.mao@linaro.org>
> > ---
> > 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

On Thu, Sep 04, 2025 at 10:40:31AM -0400, Raymond Mao wrote:
> Hi David,
> 
> On Wed, 3 Sept 2025 at 22:58, David Gibson <david@gibson.dropbear.id.au> 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.

No, as I said, I think the advantages of this proposal still outweigh
the disadvantages.  Just pointing out that this is highlighting some
of the ugliness in the current way overlays are designed, which is
relevant in the context of concurrent discussions about connectors and
the like.

-- 
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

Hi David,

On Mon, 8 Sept 2025 at 00:02, David Gibson <david@gibson.dropbear.id.au> wrote:
>
> On Thu, Sep 04, 2025 at 10:40:31AM -0400, Raymond Mao wrote:
> > Hi David,
> >
> > On Wed, 3 Sept 2025 at 22:58, David Gibson <david@gibson.dropbear.id.au> 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.
>
> No, as I said, I think the advantages of this proposal still outweigh
> the disadvantages.  Just pointing out that this is highlighting some
> of the ugliness in the current way overlays are designed, which is
> relevant in the context of concurrent discussions about connectors and
> the like.
>

Thanks for the clarification. Yes, I agree - the overlay format does
blur the line between metadata and payload.
I appreciate you highlighting the broader context here. I’ll update
this patch with 'overlay-compatible' as a clearer, loader-facing key.
If future connector proposals address this more cleanly, I'd be happy
to revisit the structure then.

Regards,
Raymond

> --
> 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