Device Tree Overlays (DTO) provide a way to modify the overall device tree without re-compiling the complete device tree.
Overlays are small pieces, or fragments of a complete device tree, and can be added or removed as needed, often enabling/disabling hardware components in the system.
Because of this flexible nature, overlays provide an advantageous way of describing peripheral hardware that can be added or removed from the system. It is also useful for tweaking parameters of existing hardware before committing it to a complete device tree.
In a very brief description, the process of designing a Device Tree Overlay comprises three macro steps:
To reduce complexity and also to provide you with example implementations, Toradex provides pre-built Device Tree Overlays for the add-on products (Display and Touch Controllers) available in the webshop. Notice that only for the BSP 5.0 onwards, our reference images offer these Overlays as binaries (.dtbo files).
On a Toradex SoM with the Linux BSP > 5.0 installed, you can list these files from the boot partition. As an example, using the the terminal of a Apalis iMX8:
$ ls /media/mmcblk0p1/overlays display-edt5.7_overlay.dtbo display-lt161010_overlay.dtbo display-edt7_overlay.dtbo display-lt170410_overlay.dtbo
To enable these overlays, see the Deploying a Device Tree Overlay section.
If you want to obtain the source code of the Device Tree Overlays provided by Toradex for the products available on the webshop, see the Build U-Boot and Linux Kernel from Source Code article.
Please refer to our article Device Tree Customization.
To build the Device Tree Overlay, see the Build U-Boot and Linux Kernel from Source Code article.
To deploy a overlay on a Toradex SoM with the Linux BSP > 5.0 installed, copy the .dtbo file to the
overlays/ directory in the boot partition and edit the
overlays.txt file. This file contains a space separated list of overlays. For example:
$ cat /media/mmcblk0p1/overlays.txt fdt_overlays=overlays/verdin-imx8mm_lt8912_overlay.dtbo overlays/verdin-imx8mm_ov5640_overlay.dtbo
After changing the
overlays, reboot the board. Do not power-cycle because the edits done may not sync to the file system.
Note: In case you find yourself with a non-working kernel after applying the overlay, see the Removing a conflicting DTO section
If you want to obtain the source code of the Device Tree Overlays provided by Toradex for the products available on the webshop, see the [Build U-Boot and Linux Kernel from Source Code] article.
In case you find yourself with a non-working kernel (normally, stuck at the "Loading kernel..." message), you can delete your custom overlays easily directly from your PC. You would need to set up a USB-OTG connection with your PC and run the UMS functionality of U-Boot by simply stopping the autoboot at U-boot and running the following commands:
ums 0 mmc 0
After this command, you should see a BOOT partition show up on your PC. Delete the conflicting .dtbo and the corresponding item in the overlays.txt file.
Note: Check your carrier board datasheet what ports and jumper configurations work with USB-OTG. In Toradex Carrier Boards, it requires using the correct port or a small jumper removal (like Ixora's JP2).