linux-kernel - [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>] [day] [month] [year] [list]

Message-Id: <20250911151436.2467758-1-raymond.mao@linaro.org>
Date: Thu, 11 Sep 2025 08:14:36 -0700
From: Raymond Mao <raymond.mao@...aro.org>
To: linux-doc@...r.kernel.org,
	devicetree-spec@...r.kernel.org,
	devicetree@...r.kernel.org
Cc: ilias.apalodimas@...aro.org,
	Raymond Mao <raymond.mao@...aro.org>,
	Rob Herring <robh@...nel.org>,
	Krzysztof Kozlowski <krzk+dt@...nel.org>,
	Conor Dooley <conor+dt@...nel.org>,
	linux-kernel@...r.kernel.org
Subject: [PATCH v3] docs: devicetree: overlay-notes: recommend top-level compatible in DTSO

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.
+
+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.
+
+
 Overlay in-kernel API
 --------------------------------
 
-- 
2.25.1