Re: [PATCH] docs: devicetree: overlay-notes: recommend top-level compatible in DTSO

[Rob Herring <robh@kernel.org>]

+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@linaro.org>
> ---
>  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
>