What are "universal" DTBs?

What are the "universal" DTBs, like cape-universal-00A0.dtbo or univ-emmc-00A0.dtbo?

TIA,

The "universal" DTBs are intended to allow user-mode changes to the
pin configurations at run-time. This is very handy on kernels that do
not support dynamic changes to the device tree (ie: 3.14), but is also
useful for 3.8 and 4.x kernels with cape manager support.

The idea is basically that you enable most of the available hardware
(UARTs, PWM, GPIO, etc) and use the pinmux helper kernel module to
make low-level pin settings available via sysfs. That way, you can
modify the pin functions without having to load a new DT overlay.

This allows some combinations that would be "illegal" or hard to
implement without writing your own custom device tree (which is
non-trivial for most folks). For example, if you need a UART but only
require the Rx line and want to use the Tx line as a GPIO, you'd
typically have to craft your own custom device tree. With the
universal overlay, you can just set the Rx line to the UART mode, and
the Tx line to GPIO, since both functions are already enabled and the
pinmux helper module lets you select the pin mode at run-time.

Thanks, Charles, that's helpful. I may offer a patch to the docs with this explanation, would you be okay with that?

In my case, I'm developing a custom cape, and intending to support only 4.1+, and don't mind writing a DTB. In fact, I may have to, since my cape has an audio CODEC on it and I need to enable McASP.

Is that assessment correct, or should I go the route of using a universal overlay and configuring everything at app run time?

Thanks, Charles, that's helpful. I may offer a patch to the docs
with this explanation, would you be okay with that?

Sure! PRs are always welcome!

In my case, I'm developing a custom cape, and intending to support
only 4.1+, and don't mind writing a DTB. In fact, I may have to,
since my cape has an audio CODEC on it and I need to enable McASP.

Is that assessment correct, or should I go the route of using a
universal overlay and configuring everything at app run time?

If you need to enable the McASP with anything other than the settings
for the HDMI transmitter chip, you'll need to craft your own device
tree overlay. It's up to you whether you want the overlay to support
everything needed by your cape or just the McASP part (and have it
work in conjunction with one of the universal overlays).

There are pros and cons to both approaches, but the more traditional
option is to have a single overlay supporting all the required
features for your cape. This will allow the overlay to properly
loaded by the cape manager at boot time (assuming your cape has a
properly programmed EEPROM).

>
>> What are the "universal" DTBs, like cape-universal-00A0.dtbo or
univ-emmc-00A0.dtbo?
>
> The "universal" DTBs are intended to allow user-mode changes to the
> pin configurations at run-time. This is very handy on kernels that do
> not support dynamic changes to the device tree (ie: 3.14), but is also
> useful for 3.8 and 4.x kernels with cape manager support.
>
> The idea is basically that you enable most of the available hardware
> (UARTs, PWM, GPIO, etc) and use the pinmux helper kernel module to
> make low-level pin settings available via sysfs. That way, you can
> modify the pin functions without having to load a new DT overlay.
>
> This allows some combinations that would be "illegal" or hard to
> implement without writing your own custom device tree (which is
> non-trivial for most folks). For example, if you need a UART but only
> require the Rx line and want to use the Tx line as a GPIO, you'd
> typically have to craft your own custom device tree. With the
> universal overlay, you can just set the Rx line to the UART mode, and
> the Tx line to GPIO, since both functions are already enabled and the
> pinmux helper module lets you select the pin mode at run-time.

Thanks, Charles, that's helpful. I may offer a patch to the docs with this
explanation, would you be okay with that?

Documentation?!? Woohoo!!!!

In my case, I'm developing a custom cape, and intending to support only
4.1+, and don't mind writing a DTB. In fact, I may have to, since my cape
has an audio CODEC on it and I need to enable McASP.

Is that assessment correct, or should I go the route of using a universal
overlay and configuring everything at app run time?

The universal overlay relies on being able to start the driver while the
pin mux is in a different configuration. Not every driver will start this
way. I believe the audio codec driver has an issue with being started up
without the pin mux being configured in the McASP mode. I believe this
means you'll need to create either an overlay (dtbo) or custom boot-time
(dtb) device tree file for the driver you select and pin mode configuration
that matches.