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

[Rob Herring]

On Thu, Sep 11, 2025 at 10:14 AM Raymond Mao <raymond.mao@xxxxxxxxxx> 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
>
> Suggested-by: Ilias Apalodimas <ilias.apalodimas@xxxxxxxxxx>
> Signed-off-by: Raymond Mao <raymond.mao@xxxxxxxxxx>
> ---
> Changes in v2:
> - Updated commit message.
> Changes in v3
> - Rename to 'overlay-compatible' and rephrase the description accordingly.
>
>  Documentation/devicetree/overlay-notes.rst | 32 ++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
>
> diff --git a/Documentation/devicetree/overlay-notes.rst b/Documentation/devicetree/overlay-notes.rst
> index 35e79242af9a..77284afba9a4 100644
> --- a/Documentation/devicetree/overlay-notes.rst
> +++ b/Documentation/devicetree/overlay-notes.rst
> @@ -103,6 +103,38 @@ The above bar.dtso example modified to use target path syntax is::
>      ---- bar.dtso --------------------------------------------------------------
>
>
> +Overlay identification
> +----------------------
> +
> +When managing device tree overlays dynamically - such as bundling multiple base
> +device trees and overlays within firmware, initramfs, or user-space tools - it
> +is important to associate each overlay with its corresponding base device tree.
> +
> +To support this association, each overlay should define a top-level compatible
> +string (referred to as the 'overlay-compatible' string). This string is
> +intended to match the top-level compatible property of the target base device
> +tree.

This property needs to be defined in dtschema at a minimum. Really we
need to check the values are documented. We already have all the
possible compatibles, so we'd need to generate a schema from them. But
that part can wait as we don't actually validate overlays on their
own.

> +
> +By including this identifier, higher-level software or firmware can determine
> +which base device tree an overlay is compatible with, and apply it accordingly.
> +
> +Example usage::
> +
> +    ---- bar.dtso - overlay with top-level compatible string -------------------
> +       /dts-v1/;
> +       /plugin/;
> +       / {
> +               overlay-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.

Please define exactly how the matching works. I assume it is the 1
overlay-compatible string has to match any one of the entries in the
base root compatible property. I don't like to assume though.

How would you handle a case where you have 2 similar SoCs which don't
share a common compatible string and the overlay applies to both of
them?

Rob