Search by Tags

Device Tree Overlays

 

Article updated at 22 Jun 2020
Compare with Revision




Subscribe for this article updates

Introduction

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:

  1. Write a Device Tree Overlay (.dts) file.
  2. Build the dts file
  3. Enable the overlay

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

Prerequisites

Writing a Device Tree Overlay

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

Software Tools for Device Tree Overlays

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:

The dtconf Command

Used to manage device-trees and device-tree overlays running on a system.

Device Tree and Overlays Source-code

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.

Using the dtconf Command to Build, Validate and Enable overlays

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.

status

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.

Expand to see an example

build

The build subcommand compiles dts code files into a device-tree or device-tree overlay file.

Expand to see an example

validate

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.

Expand to see an example

enable

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.

Expand to see an example

activate

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.

Expand to see an example

disable

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.

Expand to see an example

print

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

Expand to see an example

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.

Command Usage Example of the dtconf Tool

Modify parameter in an overlay

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.

Known Issues - dtconf

  • Build warnings appear upon building an overlay file. This is due to the compiler assuming the file is a full device-tree instead of an overlay.

Device Tree Overlays Examples

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.

Device Tree Overlays for Add-on Products Provided by Toradex

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.

Displays

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

Touch controllers

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