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

["Ilias Apalodimas" <ilias.apalodimas@linaro.org>]

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@linaro.org> if you send
another version.

Thanks
/Ilias
>
> 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.
> +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
>  --------------------------------
>