TCB Feature Request - option to add but not auto-load extra dtb overlays

Technical Support
, ,
1

I have feature request for TCB based in one of our use cases: the possibility to add custom overlays, but not explicitly load them at boot time.

For context, we are using a dynamic kernel DTB (similar to Toradex’s fdtfile handling for carrier boards and wifi presence/absence) to handle subtle incompatible differences between board hardware revisions.

We’ve modified u-boot to append a #conf node to the FIT configuration selection based on the detected hardware DTB version (read from EEPROM on the carrier board). We currently use TorizonCore builder to manage device trees since it’s very convenient to do so there and it’s more accessible than a raw Yocto build for rapid iteration and easy adjustments.

We’ve managed to achieve what we want already but I suspect this is a happy accident and not an intended functionality, so I would like to mention our use case for consideration as an explicit capability.

In essence, we are achieving the goal by doing a two-stage build:

  1. First, we run a TorizonCore builder build which specifies the base DTS, and adds two overlays, e.g. my-hardware.dts and my-hardware-v1.dtso/my-hardware-v2.dtso. This adds the overlays to the FIT image (or boot ostree dtb/overlays folder) , but crucially, also adds them to overlays.txt meaning that uboot will attempt to apply multiple conflicting/incompatible overlays.
  2. We then run a second TCB invocation with overlays-> clear: true to clear the applied overlays.
    this empties overlays.txt but does not remove the entries from the FIT image or filesystem

This leaves the build result in exactly the situation we need - the required hw revision conf nodes are present, but not automatically all applied by the overlays.txt processing.

Relying on the “feature” that clearing overlays clears the text file but does not remove the conf nodes or .dtbo files from disk seems like a behaviour that might change in future versions of TCB - especially given the context comment:

      # >> Whether to ignore all overlays from the base image (or ostree
      # >> archive in the future).

Hence: this request to either pin this as an explicit, known behaviour or adding a property option to allow specifying whether added overlays should be included in overlays.txt (or only added to the selection of dtbos/#conf nodes) would be ideal. Ex:

  device-tree:
    # >> Directories where to look for include files.
    include-dirs:
      - my_dts/include/
    # >> Custom device tree source:
    custom: my_dts/imx8mp-verdin-MyDevice.dts
    # >> Device-tree overlays configuration:
    overlays:
      add:
# Legacy syntax and legacy behaviour:
        - my_dts/overlays/some-overlay-to-always-apply.dtso 
# Example for new syntax and new behaviour:
        file: my_dts/overlays/imx8mp-verdin-MyDevice-Rev1.dtso 
          auto_apply: false
        file: my_dts/overlays/imx8mp-verdin-MyDevice-Rev2.dtso 
          auto_apply: false

What do you think?

TCB currently hard-codes u-boot’s fdtfile value when you specify a custom device tree but my proposed feature could potentially go hand-in-hand with the auto-derived fdtfile based on fdt_board as a seamless officially supported dts hw revision management feature if fw_setenv could be used to fix a particular (custom) board at deployment time in the persistent u-boot environment.

~BW908

2

Hi, I’m the Toradex AI Assistant.

I might make mistakes or occasionally get you wrong. Our support team will step in if needed.

Thank you for this detailed feature request! Your use case for managing hardware revision-specific device tree overlays with dynamic FIT configuration selection is well thought out.

Your current two-stage workaround—adding overlays in the first TCB build, then clearing overlays.txt with clear: true in a second build—is indeed clever. However, as you correctly identified, this behavior (where clearing overlays removes them from overlays.txt but leaves the .dtbo files and FIT configuration nodes intact) may not be guaranteed in future TCB versions.

Current TCB Behavior

Based on the available documentation, TorizonCore Builder’s device tree overlay workflow includes:(1)

  1. Adding overlays: Overlays specified under customization: device-tree: overlays: add: are compiled and added to the FIT image or ostree deployment
  2. Enabling overlays: These overlays are also automatically listed in overlays.txt, causing U-Boot to apply them at boot(1)

The clear: true option you’re using is documented as ignoring overlays from the base image,(1) but its interaction with custom-added overlays in a multi-stage build isn’t explicitly defined as a supported pattern.

Your Feature Request

Your proposed syntax enhancement would be valuable:

overlays:
  add:
    - file: my_dts/overlays/imx8mp-verdin-MyDevice-Rev1.dtso 
      auto_apply: false
    - file: my_dts/overlays/imx8mp-verdin-MyDevice-Rev2.dtso 
      auto_apply: false

This would provide explicit control over which overlays are merely available versus which are automatically applied via overlays.txt.

Recommendation

I recommend posting this feature request directly to the Toradex development team through one of these channels:

  • GitHub: Open an issue in the TorizonCore Builder repository
  • Toradex Community: Create a feature request thread in the TorizonCore Builder category

When submitting, include:

  • Your detailed use case (hardware revision management)
  • The current workaround and its limitations
  • Your proposed YAML syntax enhancement
  • The potential integration with fdtfile and fdt_board for seamless revision management

Your use case represents a legitimate production scenario that would benefit from official support rather than relying on undocumented behavior.

Best regards,
Toradex AI Assistant.

Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

3

Greetings @bw908,

Just to make sure I understand the request here fully.

You essentially want a single customized Torizon OS image that has multiple custom device tree overlays compiled in, but NOT applied. Then, you have some kind of custom logic in your customized OS that decides during runtime what overlays should be applied depending on the underlying carrier hardware detected.

I assume the reason you want this in a single image rather than multiple images with their own distinct set of overlays, is because you don’t know what carrier the module will be installed in during factory programming. Or, is it just to streamline and have a single image with everything no matter the carrier variant?

Did I more or less understand the situation correctly? Anything I’m missing?

TCB currently hard-codes u-boot’s fdtfile value when you specify a custom device tree but my proposed feature could potentially go hand-in-hand with the auto-derived fdtfile based on fdt_board as a seamless officially supported dts hw revision management feature if fw_setenv could be used to fix a particular (custom) board at deployment time in the persistent u-boot environment.

Regarding this bit here, is this a completely separate request now regarding device tree selection itself, instead of just the overlays? Or is this just some extra commentary about your use-case?

Best Regards,
Jeremias

4

Hi Jeremias,
Yes - you have the gist of it - As we are using a custom carrier board there are likely to be revisions of this board over time and not all are going to be “passively compatible” with the same device tree (for example, parts substitutions due to supply chain or EoL as we expect this to be a long-lived product). These boards are 99% identical in all other aspects and we’d like to continue the pattern we found worked for us in one of our previous products, where we maintain a ‘base’ DTS of common pieces and additional overlays to enable the components specific to a particular spin/revision of a board. Since we primarily use offline updates, this lets us streamline a single OS image that supports all hardware variants transparently to the end-user.

The fdtfile comment at the end was closely related and not really an independent feature request - in our application we have customized the bootloader to handle the correct dtb selection - not a problem for us to do and maintain, but I wanted to suggest a way this could be made accessible to someone that does not have the skills or desire to maintain a custom Yocto build - Part EoL/shortages are a common problem these days and a way to manage this almost entirely via TCB would likely be useful to many other customers. Just the ability to ship additional overlays without a supported way to apply them semi-dynamically isn’t going to be much use to someone that isn’t already working with Yocto. Consider it a musing/suggestion to make the feature request more broadly useful and accessible rather than an explicit request - I am sure there are a number of ways this could be approached.

I’d be happy to go into more explicit detail about what we’re doing in private if you like, should that help guide decisions or inform on our use cases. Feel free to shoot me an email :slight_smile:

~BW908

5

For now I think I have the information I need to make the feature request internally. I’ll focus the request on allowing TCB to compile and add a device tree overlay, but not enabling it at runtime (i.e. not writing it in overlays.txt). For compatibility reasons, the default will be to enable the overlay as is the case today. Meaning if this theoretical auto_apply property is missing the default will match the behavior today. Which should be okay for your needs.

Also just to set expectation, this is the first time this kind of request has been made. Meaning, I can’t really give any guarantees on timeline or priority in our team regarding this.

Best Regards,
Jeremias