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:

• Device Trees, overlays, and parameters
• Tutorial for BBB, but is a good example of overlays

This article complies to the Typographic Conventions for Torizon Documentation

Prerequisites

• A computer on module with Torizon already installed.

The Container

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 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.

High-Level description of tools in this container are:

dtconf

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

Other Features

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 Container

On the computer on module, run the container:

# docker pull torizon/arm32v7-debian-dev-tools
# docker run -it --rm --privileged -v /dev:/dev -v /boot:/boot torizon/arm32v7-debian-dev-tools

dtconf Command Line Options

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 command 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 command compiles dts code files into a device-tree or device-tree overlay file.
• The validate command 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 command 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 command 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 command 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 command 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.

Examples

Compile device tree or device tree overlay

Build command can be used to convert a dts into a binary device tree file.

## dtconf build 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.

If you don't specify a full path for the file, the tool will search the file in the git repository, matching the current kernel, to prevent this behavior you can use the --no-git-repo option.

Enable overlays

You can enable an overlay using a binary dtbo file:

## dtconf enable display_7_parallel_cap_touch.dto

Or directly using dts file, in this case, the overlay is first compiled to binary format, then validated and then enabled:

## dtconf activate display_7_parallel_cap_touch.dts 

The tool will try to find the base device tree used to boot the module, if it can't find it you'll have to specify it using the -c option.

Validate device tree overlay against base device tree

This simply ensures that the device tree overlay is compatible with a specified device tree. The base device-tree parameter is optional, by default it will validate the overlay against the active device tree:

## dtconf validate some-overlay.dtbo

Deactivate an overlay

## dtconf disable 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.

Remove all active overlays

## dtconf disable --all

View overall status of device trees and overlays

## dtconf status
Device is apalis imx6(0028)
Mounting /mnt/part
Currently active overlays:
touch_cap_apalis_evb.dts.dtbo
Available base device trees:
    devicetree-imx6q-apalis-ixora-v1.1.dtb
    devicetree-imx6q-apalis-ixora.dtb
    devicetree-imx6q-apalis-eval.dtb
Available overlays for running kernel:
    enable_parallel_display_apalis_imx6.dts
    display_7_parallel_cap_touch.dts
    display_EDT7_parallel_res_touch.dts
    display_10.1_lvds_cap_touch.dts
    touch_cap_colibri_imx7_aster.dts
    touch_cap_colibri_imx7_evb.dts
    display_EDT5.7_parallel_res_touch.dts
    touch_cap_colibri_imx6_aster.dts
    touch_cap_apalis_evb.dts
    touch_cap_colibri_imx6_evb.dts
    enable_lvds_display_apalis_imx6.dts

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.

Creating custom overlays: Enabling GPIOs

In addition to the sample overlays that are available on github, one can also create custom overlays by simply creating a new .dts file and applying it using dtconf according to the instructions above. If you build overlays that are not from the Toradex git repo you'll have to use the --no-git-repo option and provide a complete (full or relative) path for the file.

The following overlay will enable any given pinctrl node (&pinctrl_my_gpios) as GPIOs:

/dts-v1/;
/plugin/;
/ {
	compatible = "toradex";
	fragment@0 {
		target = <&iomuxc>;
		__overlay__ {
			pinctrl-names = "default";
			pinctrl-0 = <
				&pinctrl_my_gpios
			>;
		};
	};
};

Known Issues

• 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.