RFC: Multi-platform overlays - a proposal

[pelwell]

The introduction of the Pi 4, built around the BCM2711 SoC, has caused a split in our code base; for the first time, some overlays won't work on all (can't even be applied) - on all Pis. Some of these failures come under the general heading of "don't do that", e.g. trying to use uart5 on a 3B+, but for others it is clear that something different needs to happen on each platform - a change of implementation, fewer parameters, etc.

There is therefore a need for a method of tailoring an overlay to multiple platforms with differing hardware. Supporting them all in a single .dtbo file would require heavy use of hidden ("dormant") fragments and a switch to an on-demand symbol resolution mechanism so that a missing symbol that isn't needed doesn't cause a failure. A simpler solution is to add a facility to map an overlay name to one of several implementation files depending on the current platform.

For the purposes of this discussion, <overlay> is the name of an overlay, where <overlay>.dtbo is the name of the default implementation file. The first plan was to use an overlay-specific proxy file as a matchmaker for several implementing .dtbo files - <overlay>.ovl, say. It would contain a list of mappings from platform names to overlay file names - a textual format would probably suffice. The absence of a platform from a .ovl means the overlay isn't supported on that platform. The absence of a <overlay>.ovl file would indicate that all platforms should use the common default implementation. The advantage of this scheme is that each overlay remains self contained, but it does require an extra file test/load for each overlay, something which is particularly slow when network booting.

Instead, I favour the addition of a single map file that gets loaded once at start of day. It can be written in .dts format with a node per overlay:

/ {
    vc4-kms-v3d {
        bcm2711 = "vc4-kms-v3d-pi4";
        bcm2835;
    };
};

Notes:

1. The platform names are compatible strings (minus the vendor prefix for brevity).
2. A platform name with no value (an empty property) indicates that the default overlay file (vc4-kms-v3d.dtbo in this case) should be used.
3. As with the previous plan, this only exceptions need to be listed - the absence of a node for an overlay means that the default file should be used.

Once the map has been compiled, use is straightforward - locate the node for an overlay and, if found, retrieve the property with the current platform name.

Although simple, this mechanism allows some nice extensions in the event that the platform property doesn't exist:

/ {
    vc4-kms-v3d {
        bcm2711 = "vc4-kms-v3d-pi4";
        bcm2835;
    };

    pi3-disable-bt {
        renamed = "disable-bt";
    };

    lirc-rpi {
        deprecated = "See gpio-ir";
    };
};

4. The renamed property indicates the new name of the overlay (which should be largely compatible with the original), but also logs a warning about the rename.
5. The deprecated property contains a brief explanatory error message which will be logged after the common "Overlay is deprecated."

As with previous RFCs, I welcome constructive feedback, but plan to press ahead with implementation in the meantime.

Finally, a plug for the updated Device Tree documentation (which this RFC is about to render out-of-date again).

[lurch]

Usual disclaimer: I know very little about DeviceTree 😉 (so please take my comments with a large pinch of salt)

A platform name with no value (an empty property) indicates that the default overlay file ... should be used.

the absence of a node for an overlay means that the default file should be used.

Does that mean that these two are actually equivalent?

• empty property:

/ {
    vc4-kms-v3d {
        bcm2711 = "vc4-kms-v3d-pi4";
        bcm2835;
    };
};

• absence of a node:

/ {
    vc4-kms-v3d {
        bcm2711 = "vc4-kms-v3d-pi4";
    };
};

Or have I misunderstood? Does / should there be a way to indicate that "this overlay can't be used on this platform"? (e.g. your uart5 on a 3B+ example)

Are bcm2711 and bcm2835 currently the only supported platform properties?
I guess there's no way of indicating that "disable-bt" shouldn't be used on Pis that don't have built-in Bluetooth?

It can be written in .dts format

Presumably with a naming scheme that ensures it won't conflict with any current / future .dts files?

[pelwell]

Does that mean that these two are actually equivalent?
No - the equivalent would be:

/ {
    vc4-kms-v3d {
        bcm2711 = "vc4-kms-v3d-pi4";
        bcm2835 = "vc4-kms-v3d";
    };
};

If the overlay can't be used on a platform, that platform shouldn't be listed. To say that the uart5 overlay can only be used on a bcm2711 platform:

/ {
    uart5 {
        bcm2711;
    };
};

Presumably with a naming scheme that ensures it won't conflict with any current / future .dts files?

Overlays are stored in *.dtbo files, while this will be a .dtb. Besides, Whatever name I choose will just become an illegal name for an overlay.

[pelwell]

Are bcm2711 and bcm2835 currently the only supported platform properties?
They are likely to be for the forseeable future.
I guess there's no way of indicating that "disable-bt" shouldn't be used on Pis that don't have built-in Bluetooth?

The intention is to allow the correct overlay to be located, not to give detailed feedback about a user's choices. Deprecation is a special case because something which used to work no longer does, and that deserves an explanation.

[lurch]

If the overlay can't be used on a platform, that platform shouldn't be listed.

Okay, cool - that wasn't obvious from your initial description. (but again, that may just be due to my lack of DT knowledge!)

To say that the uart5 overlay can only be used on a bcm2711 platform:

Presumably your example should have been:

/ {
    uart5 {
        bcm2711;
    };
};

? 😉

Would the user then get an error logged if they did try to use the uart5 overlay on a Pi 3B+? (just out of curiosity, where are these DT-logs visible?) Or would it just silently not-do-anything?

Sorry, I realise I'm probably asking questions now which are only relevant to the documentation-phase, and not the current implementation-phase 😕

[pelwell]

Presumably your example should have been:

Yes.

Would the user then get an error logged if they did try to use the uart5 overlay on a Pi 3B+?

Yes.

(just out of curiosity, where are these DT-logs visible?)

$ sudo vcdbg log msg

[pelwell]

that wasn't obvious from your initial description.

It was kinda covered by the first part where it said "The absence of a platform from a .ovl means the overlay isn't supported on that platform." The second half describes a different format, but the basic idea is the same.

[pelwell]

See #3527 for what this looks like in use.

[pelwell]

#3527 has been merged and firmware support is pending a review, so I'm closing this.