[PATCH 16/17] Documentation: Add documentation for device tree overlays

[Trent Piepho]

On Tue, Jun 22, 2021 at 11:14 PM Ahmad Fatoum <a.fatoum at pengutronix.de> wrote:
>
> Hi,
>
> some bikeshedding incoming.

Well, while we're out here at the shed...

> Convention seems to be that attributes of the same thing are preceded by a `.', e.g.:
>
> global.of.overlay.dir
> global.of.overlay.compatible
> global.of.overlay.filepattern

This looks a lot more Barebox-like to me.

> (I think the `.' between of and overlay is not a bad idea, as we may decide to have e.g.
>  global.of.compatible in future)

Are these only used when bootm is run? Aren't most magivars that work
this way in the namespace "global.bootm"?

> > +``global.of_overlay_compatible``
> > +  This is a space separated list of compatibles. Only overlays matching one of
> > +  these compatibles will be applied. When this list is empty then all overlays
> > +  will be applied. Overlays that don't have a compatible are considered being
> > +  always compatible.
>
> Makes sense.

I've always thought the way Barebox's global.linux.bootargs.*
variables worked was nice.  It avoids different things that add
arguments for different reasons from interacting with each other
trying to write to a single variable.

There's a similar process with overlays.  Some overlays are based on
the board variant.  Then an add-on board might bring in an overlay.
Then another overlay from a second add-on board that is unrelated to
the 1st.  Then an overlay to configure something at boot time, like
add an LED trigger at boot.  It's so much easier to just set or unset
a single variable, than to need to worry about appending or removing
or modifying a string inside a space separated list.

> > +``global.of_overlay_filepattern``
> > +  This is a space separated list of file patterns. An overlay is only applied
> > +  when its filename matches one of the patterns. The patterns can contain
> > +  ``*`` and ``?`` as wildcards. When empty, all files are applied.
>
> Similarly, we could have ``*`` as a default.

If the default value is "*", and it's necessary to use a space
separated list, then a script adding another pattern will use
something like:
global.of_overlay_filepattern="${global.of_overlay_filepattern} new-overlay.dtb"

But that doesn't work if the variable doesn't start as empty.  Using
"global.of.filepatterns.*" as a set of variables would help.