Device Tree Overlays provide a way to modify the overall device tree without having to re-compile 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 components of hardware in the system. It is because of this flexible nature that 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. Overlays are described elsewhere, but here are some links that do a good job explaining them:
This article complies to the Typographic Conventions for Torizon Documentation
To overcome the task of setting-up the environment, modifying and re-compiling a device tree, Toradex provides a container that has tools necessary to build, analyze, and apply both device trees and device tree overlays. This container runs on the TorizonCore Operating System, and is intended to act as a hardware configuration tool.
The bulk of the tools in this container are part of the "dtc" (device tree compiler) project and can therefore be found in the dtc repository on Github, but are also shipped as part of the linux kernel in the scripts/dtc directory.
Overlays in human-readable format (dts files) must be compiled to binary format (dtb for complete device-trees, dtbo for overlays) to be parsed by the kernel.
High-Level description of tools in this container are:
Used to manage device-trees and device-tree overlays running on a system.
This container also comes with device-tree and device-tree overlay source files. These files can be used as a base to create new device-trees or device tree overlays.
Default overlays are located inside /usr/src/dts/overlays.
On the computer on module, run the container:
# docker pull torizon/torizon-core-tools-container # docker run --rm --privileged --tmpfs /run/lock -it -v /dev:/dev -v /boot:/boot torizon/torizon-core-tools-container /bin/bash
Usage: dtconf < command > [arguments] commands: -h, --help -b, --build < dts file(s) > [ dtb/dtbo file ] -s, --status -v, --validate < dtb file(s) > -c [ active dtb name ] -e, --enable <dtb name/all> -d, --disable <dtb name/all> -a, --activate < dts file(s) > -c [ active dtb name] -p, --print <dtb file(s)>
Overlays are applied at boot, so the options that affect active overlays configuration (-a,-e and -d) will require a reboot to apply the required changes.
Build command can be used to convert a dts into a binary device tree file.
## dtconf -b /usr/src/dts/overlays/display_EDT7_parallel_res_touch.dts
NOTE: Both device trees (.dtb) and device tree overlays (.dtbo) are built from the same source file (.dts). In an attempt to determine the output file type, the dtconf script will scan the .dts file for the "fragment@0" string. If this string is found it assumes file is an overlay and names the output with a .dtbo extension, otherwise, it is named with a .dtb.
You can enable an overlay using a binary dtbo file:
## dtconf -e display_7_parallel_cap_touch.dts touch_cap_colibri_imx6_aster.dts.dtbo
Or directly using dts file, in this case the overlay is first compiled to binary format, then validated and then enabled:
## dtconf -a display_7_parallel_cap_touch.dts /usr/src/dts/overlays/touch_cap_colibri_imx6_aster.dts
On some modules where multiple device-trees are provided (ex: colibri-imx7, apalis-imx6) you'll have to provide an additional parameter, to select the target device tree.
## dtconf -a display_7_parallel_cap_touch.dts /usr/src/dts/overlays/touch_cap_colibri_imx6_aster.dts -c devicetree-imx7d-colibri-emmc-eval-v3.dtb
This simply ensures that the device tree overlay is compatable with a specified device tree. The device-tree parameter is optional, by default it will verify the overlay against the active device tree:
## dtconf -v some-overlay.dtbo
## dtconf -d display_7_parallel_cap_touch.dts touch_cap_colibri_imx6_aster.dts.dtbo
Note: You should not specify a full path for the overlay because active overlays are stored in the boot partition.
## dtconf -d all
## dtconf -s Currently active overlays: display_EDT7_parallel_res_touch.dts.dtbo Available device trees: devicetree-imx7s-colibri-eval-v3.dtb devicetree-imx7d-colibri-emmc-eval-v3.dtb devicetree-imx7d-colibri-eval-v3.dtb
You can modfiy any of the overlays we provide and then verify them.
First you need to build the overlay:
## dtconf -b modified_overlay.dts
You can then verify that this overlay will apply to the active device tree by executing:
## dtconf -v modified_overlay.dtbo
And finally set it to be active by executing:
## dtconf -e modified_overlay.dtbo
You would now be required to reboot for these changes to take effect.