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:
In a very brief description, the process of designing for a Device Tree Overlay comprises 3 macro steps:
This article will show the tools available for designing Device Tree Overlays for Toradex CoMs.
This article complies to the Typographic Conventions for Torizon Documentation
The most recommended way to create a new overlay is to start looking to similar overlays and then adapt to your project's needs. The Linux Kernel source provide binding documentation for specific peripherals.
To access this information, visit The Linux Kernel Archives website and browse the Linux Kernel source for the specific version of your board. You will find the specific bindings information in the Linux kernel source at: Documentation/devicetree/bindings.
As an example, you will find the binding documentation for the version v4.14.184 on the following link: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Documentation/devicetree/bindings?h=v4.14.184
To find out the Linux Kernel version on your board, type on the board's Linux terminal:
# uname -r
To overcome the task of setting up the environment, modifying and re-compiling a device tree, Toradex provides the tools necessary to build, analyze, and apply both device trees and device tree overlays. Device Tree Overlays tools are provided in the Developer Tools Container for TorizonCore.
The bulk of the tools 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 on 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.
See a high-level description of the tools:
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 are stored using git and the tool will match their version with the currently running kernel. It is possible to download updates directly from the container, but this requires an internet connection.
On the computer on module, run the Developer Tools Container for TorizonCore. Then learn how to use dtconf as presented in the next sections.
These are the command Line options for dtconf:
usage: dtconf < command > [arguments]
Commands:
help
build
status
validate
enable
disable
activate
print
Use help command to have a more detailed list of commands and their arguments.
The status subcommand prints out a list of currently active overlays, of the device trees that are available on the device and of those that are available for the currently running kernel.
The build subcommand compiles dts code files into a device-tree or device-tree overlay file.
The validate subcommand checks that overlay files are compatible with a device tree. Depending on the Torizon image and SOC you may have multiple valid device trees on your boot partition, the tool should be able to detect which one has been used to boot the device, if this is not possible, you should specify the one that is currently used with the "-c" additional parameter.
The enable subcommand copies a binary device tree overlay to the boot partition and adds it to the list of overlays that are activated at boot.
The activate subcommand builds a source dts, validates it and enables it in a single step. It's equivalent to run build, validate and enable commands in sequence.
The disable subcommand can be used to remove one overlay from the list of those that are applied at boot. If --all is specified, all overlays will be removed.
The print subcommand translates a binary device-tree file back into a human-readable format, it can be used to debug issues or document the configuration changes performed by active overlays
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.
You can modify any of the overlays we provide and then validate them.
First, you need to build the overlay:
## dtconf build modified_overlay.dts
You can then validate that this overlay will apply to the active device tree by executing:
## dtconf validate modified_overlay.dtbo
And finally set it to be active by executing:
## dtconf enable modified_overlay.dtbo
You would now be required to reboot for these changes to take effect.
Device tree examples, including overlays, can be found on Device Tree Customization Examples. See a list of remarkable examples available:
| Example | Description |
|---|---|
| GPIO pinmux | Some pins are not configured as GPIO by default. Learn how to configure a pin as GPIO. |
Some examples are available in other articles:
Note: at the moment, there are no device tree overlay examples outside the Device Tree Customization Examples.
Toradex provides Device Tree Overlays for the add-on products available in the web shop. For information about these overlays, see the Toradex Device Tree Overlays repository on Github and the sub-sections ahead.
See how to use on Setting up Displays with Torizon.
| Overlay | Device |
|---|---|
| display_EDT5.7_parallel_res_touch.dts | 5.7 inch display proivded by Toradex https://developer.toradex.com/products/edt-display |
| display_EDT7_parallel_res_touch.dts | 7 inch display proivded by Toradex https://developer.toradex.com/products/edt-display |
| display_10.1_lvds_cap_touch.dts | 10.1 inch lvds display proivded by Toradex |
| display_7_parallel_cap_touch.dts | Display with capacitive touch https://developer.toradex.com/products/capacitive-touch-display-7inch-parallel |
See how to use on Setting up Displays with Torizon.
| Overlay | Device |
|---|---|
| touch_cap_apalis_evb.dts | touch controller for capacitive touch displays |
| touch_cap_colibri_imx6_evb.dts | touch controller for capaccitive touch display compatible with colibri-imx6 and evaluation board |
| touch_cap_colibri_imx6_aster.dts | touch controller for capaccitive touch display compatible with colibri-imx6 and Aster board |
| touch_cap_colibri_imx7_evb.dts | touch controller for capaccitive touch display compatible with colibri-imx7 and evaluation board |
| touch_cap_colibri_imx7_aster.dts | touch controller for capaccitive touch display compatible with colibri-imx7 and Aster board |
