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

Doug Anderson
2025-12-02T22:00:09Z

Hi,

On Mon, Dec 1, 2025 at 4:48 PM Rob Herring <robh@kernel.org> wrote:
>
> > > 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";

I was just trying to come up with an example with 3 levels. Usually a
whole pile of boards are based on a reference design, so the reference
board could be an extra level of overlays. Thinking about this with
the sc7180 Chromebooks, you might have:

SoC: qcom,sc7180 (base DTB)
Reference design: google,trogdor
Actual board: google,lazor-rev1, google,lazor

So final compatible could be:
"google,lazor-rev1", "google-lazor", "google-trogdor", "qcom,sc7180"

In the case of what we ended up with upstream for sc7180 Chromebooks,
we actually _didn't_ include the reference design (google,trogdor) in
the list of compatibles in the final board. I think this was because
the name of the reference design ("trogdor") was also the name of the
reference _board_ and it would have been confusing. ...but I can also
see how one might want the reference board to show up here. I don't
feel super strongly either way.

In any case, I'm OK with not focusing on 3-levels right now and I'm
not actually planning to use it in the short term, I just want to make
sure that anything we do doesn't preclude it...

> > 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'm actually OK with deferring the "pluggable SoC" problem for now.
Even for the Google Pixel team, it's a bit of an edge case. If we have
to solve it by duplicating "dtbo" files for socketed boards (or any
board which could have more than one SoC) that's probably OK for now.
Once other problems are solved, we can perhaps come back to the idea
of merging compatible strings and/or other properties.

In v1 of my Pixel 10 series I wasn't even trying to support multiple
SoC revisions, I was just trying to look forward to the future based
on what I saw downstream. ;-)

If I drop the idea of merging compatible strings and just duplicate
the "SoC" parts of the compatible in each of the overlays, then do we
have something that's landable to get things off the ground? I think
Krzysztof will still NAK my base "dtb" that represents just the SoC
since it's not "complete". I certainly wouldn't want to just steamroll
over his concerns. Krzysztof: Do you have any thoughts? Do you
understand my goal here and agree that it's something worth solving?
If you don't agree it's worth solving, would it help to hear more
people express their interest in a solution? If you agree it's worth
solving, can you provide a suggestion for how we can move forward?

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

Yeah, I'm still not really a fan of that proposal. I think different
loaders are going to need different information to know which overlays
to apply, so we need to define "yaml" files for different loaders and
define the formats for a few different loaders.

From a validation point of view, I'd imagine we'd want to (if
possible) validate all different combinations, but (if it's
well-defined in a binding) we could potentially include rules in the
kernel that understand different loaders and could come up with
different things to validate.

-Doug