Re: Proposal: Officially allow "incomplete" trees as a base

Rob Herring
2025-12-02T00:48:46Z

On Tue, Nov 18, 2025 at 5:48 PM Julius Werner <jwerner@chromium.org> wrote:
>
> > 4. When applying an overlay to a device tree that's "incomplete", the
> > top level overlay will be merged instead of replaced.
> >
> > Example for 2 levels:
> >
> > base (incomplete) compatible: "socvendor,mysoc-rev1", "socvendor,mysoc";
> > overlay compatible: "boardvendor,myboard-rev1", "boardvendor,myboard";
> > merged compatible: "boardvendor,myboard-rev1", "boardvendor,myboard",
> > "socvendor,mysoc-rev1", "socvendor,mysoc";
> >
> > Possible example if we support 3 levels:
> >
> > SoC (incomplete) compatible: "socvendor,mysoc-rev1", "socvendor,mysoc"
> > overlay1 (incomplete) compatible: "referencevendor,referencecodename";

I don't understand this one...

> > overlay2 compatible: "boardvendor,myboard-rev1", "boardvendor,myboard"
> > merged compatible: "boardvendor,myboard-rev1", "boardvendor,myboard",
> > "referencevendor,reference-codename",
> > , "socvendor,mysoc";
>
> Sorry, I only cursorily followed the previous discussion so I may have
> missed the exact need for this part. But I would caution against any
> proposal that changes the basic rules of how an overlay is applied.
> The definition of how overlays work has (I think?) been stable for
> over a decade now, and is implemented in bootloaders that often cannot
> easily be updated. I absolutely support your effort to get more
> upstream standardization for managing base device trees and overlays
> (which I think need to be flexible for arbitrary layers, not just SoC
> and board), but let's not break the overlay code in old bootloaders
> while doing it.

I think merging compatibles is orthogonal to splitting SoC and board
DTs. Doug needs to merge because there is more than 1 SoC version or
base DT to pick. In many cases (SoC revision compatibles are the
exception upstream), there is only 1 SoC DT and N board DTs. So we
should consider both and define them separately. In the simple case,
you'd have something like:

SoC (incomplete) compatible: "socvendor,mysoc"
Board overlay compatible: "boardvendor,myboard-rev1",
"boardvendor,myboard", "socvendor,mysoc"

Then you just apply the overlay and it overwrites the incomplete
compatible. That works with existing overlay applying (overwriting)
for multiple steps as long as each step is a superset (compatible
list) of the prior steps.

In Doug's case, I think you need code to decide which base to pick and
then fixup the final compatible.

SoC (incomplete) compatible: "socvendor,mysoc-rev1", "socvendor,mysoc"
Board overlay compatible: "boardvendor,myboard-rev1",
"boardvendor,myboard", "socvendor,mysoc"

And then after applying, you do the merge to insert the SoC rev compatible:

"boardvendor,myboard-rev1", "boardvendor,myboard",
"socvendor,mysoc-rev1", "socvendor,mysoc"

You need SoC specific code to know what SoC revision you are running
on, so SoC specific post apply code should be fine too. There's not
any existing bootloader problem because you need code to handle this.

Maybe that fixup will end up being generic enough that it's not
platform specific, but that's an optimization of the implementation.

> Is there really a need to merge the compatible strings in your case?

Well, you could just require duplicating an overlay N times for N
bases, but that doesn't scale

> I
> think in the vast majority of platform identification cases, code only
> cares about matching the most precise string (i.e.
> "boardvendor,myboard-rev1"). If we do feel like having the whole chain
> of identification is necessary, it could be achieved by just
> copy&pasting the extra strings into the overlay file. If we have
> cross-validation between base and overlay source files we could also
> have the validation check that the overlays correctly contain all
> compatible strings from their base tree. If we know that the base
> trees aren't standalone anyway, we could also just invent other
> property names that identify them (e.g. `soc-compatible =
> "socvendor,mysoc";`). Anything other than breaking the overlay format
> would be preferable in my opinion.

There's also a use case I'm aware of where the base DT is just for a
SoM and then the bootloader applies an expansion board overlay. So it
is not always "not standalone". And of course, this could be combined
with what Doug wants to do.

Note that for any new property (or an incomplete compatible) like
soc-compatible, you will need to consider how we validate it.

> I also feel like we need a better standardized way to tie base device
> trees to overlays, like your `/loaders` node proposal in an earlier
> email, although maybe that's an orthogonal discussion (but related,
> especially if there's supposed to be cross-validation between base
> trees and overlays). The compatible string is just not a scalable way
> for bootloaders to make this determination, there may be a lot more
> differentiation than just "SoC" and "board", and the scheme almost
> certainly needs to be platform/bootloader-specific because every
> hardware vendor has their own ideas about how to group and reuse parts
> of a platform. This information doesn't necessarily need to be *in*
> the device tree, it could also just be in a separate YAML file in the
> same repo (since bootloaders will almost certainly want to have it
> transformed into their own out-of-band descriptor at build-time
> anyway, so that they can compress the device tree itself and don't
> have to decompress each one for matching), but it needs to be
> somewhere.

There is a proposal here[1]. It's simple, but I do wonder if looking
at the root compatible only is too narrow of a view. An overlay could
target a connector compatible for example.

We kind of have this information in the kernel build already as well.
The requirement for overlays in the kernel tree is overlays get
applied to at least one target at build time. It would be nice for any
solution to this problem to replace those build rules.

Rob

[1] https://lore.kernel.org/all/20250911151436.2467758-1-raymond.mao@linaro.org/