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> Acked-by: Conor Dooley <conor.dooley@xxxxxxxxxxxxx> Signed-off-by: Raymond Mao <raymond.mao@xxxxxxxxxx> --- Changes in v2: - Updated commit message. 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 -------------------------------- -- 2.25.1
