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. + +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
