Message-ID: <87a5fa3a-4242-4755-913d-b87cf8873039@amd.com>
Date: Wed, 3 Dec 2025 15:41:31 +0100
From: Michal Simek <michal.simek@....com>
To: Rob Herring <robh@...nel.org>, 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

Hi,

On 11/14/25 14:08, Rob Herring wrote:
> 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?

Let me describe what we are doing in this space today.

We are applying overlay in u-boot for SOM + CC (Carrier Card) and you can see 
DTs in the Linux kernel tree.

SOM itself is using

	compatible = "xlnx,zynqmp-sm-k24-rev1", "xlnx,zynqmp-sm-k24-revB",
		     "xlnx,zynqmp-sm-k24-revA", "xlnx,zynqmp-sm-k24",
		     "xlnx,zynqmp";

CC are using

	compatible = "xlnx,zynqmp-sk-kd240-rev1",
		     "xlnx,zynqmp-sk-kd240-revB",
		     "xlnx,zynqmp-sk-kd240-revA",
		     "xlnx,zynqmp-sk-kd240", "xlnx,zynqmp";

The reason is that we have to run SW on SOM to detect SC. We have SOM+CC 
combinations for all revisions and based on autodetection we are choosing 
combination which matches it (multiple full DTs in FIT image).

Feel free to look at
https://source.denx.de/u-boot/u-boot/-/blob/master/arch/arm/dts/zynqmp-binman-som.dts
where combinations are described.

Today FIT image have full DTBs and not overlays. Overlays are just helping us to 
build different combinations in a simpler way.

https://source.denx.de/u-boot/u-boot/-/blob/master/arch/arm/dts/Makefile#L351

We would use a mechanism which can connect CC overlay with SOM.
SOM can run on 4 different CCs
And some CCs can be populated by different SOMs (with the same SOC family).

All of these combinations should be working when run time DT overlay applying 
mechanism is in place.

Above is pretty much describing how to connect overlay with base DT and likely 
it should have more then one compatible string.

It should be also described if base DT will accept DT overlay compatible string 
or remain on existing one.

Another mechanism which we are exploring is to use transfer list where SW 
components start to inject DT overlays to it (for example description from 
OP-TEE) which is then passed to U-Boot which should merge them together.
For it overlay-compatible = "xlnx,zynqmp"; in overlay could be used and will be 
connected to actual silicon.

Based on above description I can't see any issue to cover our existing use cases 
if overlay-compatible can contains multiple compatible strings not just one.

Thanks,
Michal

Powered by blists - more mailing lists