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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CAL_Jsq+apXxvngU9enNw9yzD1YAAOyamwkTBvqdrc2M955Q38g@mail.gmail.com>
Date: Fri, 14 Nov 2025 07:08:27 -0600
From: Rob Herring <robh@...nel.org>
To: Raymond Mao <raymond.mao@...aro.org>
Cc: linux-doc@...r.kernel.org, devicetree-spec@...r.kernel.org, 
	devicetree@...r.kernel.org, ilias.apalodimas@...aro.org, 
	Krzysztof Kozlowski <krzk+dt@...nel.org>, Conor Dooley <conor+dt@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3] docs: devicetree: overlay-notes: recommend top-level
 compatible in DTSO

On Thu, Sep 11, 2025 at 10:14 AM Raymond Mao <raymond.mao@...aro.org> 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@...aro.org>
> Signed-off-by: Raymond Mao <raymond.mao@...aro.org>
> ---
> 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