Search by Tags

Device Tree Overlays on Torizon

 

Article updated at 17 Sep 2020
Compare with Revision




Subscribe for this article updates

Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.

Torizon 5.0.0

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 on Torizon. If you want to use device tree overlays with our Reference Images for Yocto Project, read the Device Tree Overlays section from Build U-Boot and Linux Kernel from Source Code.

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 TorizonCore Builder Tool.

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:

TorizonCore Builder

TorizonCore Builder tool is created to assist user for creating and managing updates for deployed Torizon image. It runs in container on the host system. Among all other functionality described in TorizonCore Builder Tool, it can be used to compile device tree, device tree overlay(s) and also apply overlay(s) to devicetree, which can be later merged to base unpacked Toradex Easy Installer image of Torizon or directly over ssh to the Torizon image running on the target machine.

TorizonCore Builder tool uses Docker volumes as persistent storage for intermediate outputs of sub-commands as default, so it can be used to perform operations either with Docker volume or without Docker volume.

For convenience, create alias first

Note: alias uses $(pwd) which does expand at “aliasing time”, that means the user cannot change the directory afterwards.

With Docker Volume

$ alias torizoncore-builder='docker run --rm -it -v $(pwd):/workdir -v storage:/storage -v /deploy --net=host -v /var/run/docker.sock:/var/run/docker.sock torizon/torizoncore-builder:1'

Without Docker Volume

$ alias torizoncore-builder='docker run --rm -it -v $(pwd):/workdir --net=host -v /var/run/docker.sock:/var/run/docker.sock torizon/torizoncore-builder:1'

TorizonCore Builder tool provides different logging levels, which can be set by using --log-level option. There are five logging levels i.e. debug, info, warning, error and critical and default is set to info. Formatted logging can be enabled by using --verbose option.

To work with TorizonCore builder, a base Toradex Easy Installer image of Torizon is needed on host machine to work on. TorizonCore builder provides a command to unpack the Toradex Easy Installer image of Torizon inside Docker volume on the host machine.

$ torizoncore-builder unpack --image-directory <Path to TorizonCore Toradex Easy Installer source image>

For example

$ torizoncore-builder unpack --image-directory torizon-core-docker-apalis-imx6-Tezi_5.0.0-devel-20200924030222+build.0/
Copying Toradex Easy Installer image.
Unpacking TorizonCore Toradex Easy Installer image.
Running tar command: cat '/storage/tezi/torizon-core-docker-apalis-imx6.ota.tar.zst' | zstd -dc | tar --xattrs --xattrs-include='*' -xhf - -C /storage/sysroot
Importing OSTree revision 54fd6637c9b992e30b7d81e9adf27c4df0e9617c4d94feaa8fb330ae79d170ee from local repository...
Unpacked OSTree from Toradex Easy Installer image:
  Commit checksum: 54fd6637c9b992e30b7d81e9adf27c4df0e9617c4d94feaa8fb330ae79d170ee
  TorizonCore Version: 5.0.0-devel-20200924030222+build.0

dt command

dt has subcommands, which are used to compile device tree or apply overlay(s).It has the following subcommands

$ torizoncore-builder dt --help
usage: torizoncore-builder dt [-h] {overlay,custom,checkout,list-overlays, list-devicetrees} ...

optional arguments:
  -h, --help            show this help message and exit

Commands::
  {overlay,custom,checkout,list-overlays}
    overlay             Apply an overlay
    custom              Compile device tree
    checkout            Checkout a git branch from remote repository
    list-overlays       List overlays
    list-devicetrees    List devicetrees
dt checkout

dt checkout subcommand clones either user provided remote repository or default Toradex provided remote repository device-trees in absence of user input, which contains device trees, device tree overlays, dtsi and header files needed to compile source files. It uses current working directory as default for storing the cloned remote repository

Arguments
`--repository (optional):` URL of remote repository or path to local repository
      **default:** https://github.com/toradex/device-trees

`--branch`  (optional):` branch to checkout
      **default:** gets the kernel version of deployed image from unpacked Toradex Easy Installer image of Torizon and checkout corresponding branch in default repository only.
Example
With docker volume
$ torizoncore-builder dt checkout
Without docker volume
$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> dt checkout --repository <repository URL> --branch <branch to checkout>
dt custom

dt custom subcommand compile the device tree source file.

Arguments
`--devicetree-source`: It is used to provide devicetree source file to be compiled.

`--devicetree-out (optional)`:  If it is specified,  device tree binary is stored inside user specified directory(should be empty) like `<user dir>/usr/lib/modules/<kver>/devicetree`. Output binary is always named `devicetree`.
    **default:** device tree binary is stored(replacing any old) in Docker volume and is also named `devicetree`

`--include-dir (optional)`:  It should point to directory containing .dtsi and .h files. It can be used multiple times to provide multiple directories.
    **default:** It searches in `device-trees/includes` directory of checked out repository.
Example
With docker volume
$ torizoncore-builder dt custom --devicetree-source <Path to device tree source file> --devicetree-out <Path to save output device tree binary named 'devicetree'> --include-dir <Path to directory containing dtsi and/or .h file(s)>
without docker volume
$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> dt custom --devicetree-source <path to device tree source file> --devicetree-out <Path to save output device tree binary named 'devicetree'> --include-dir <Path to directory containing dtsi and/or .h file(s)> --devicetree-out <Path to store device tree binary in `/usr/lib/modules/` with name 'devicetree' inside provided directory`>
dt list-overlays

dt list-overlays lists all compatible device tree overlay file(s) in user provided directory for user provided device tree source file or device tree binary file.

Arguments
`--devicetree-source:` Path to device tree source file

`--devicetree:` Path to device tree binary file

`--overlays-dir (optional):` Path to directory containing overlays to be filtered out
    **default:** It searches in `device-trees/overlays` directory of checked out repository.
Example
$ torizoncore-builder dt list-overlays --devicetree-source <Path to device tree source file> --overlays-dir <Path to source file(s) of device tree overlay(s)>

Or

$ torizoncore-builder dt list-overlays --devicetree <Path to device tree binary file> --overlays-dir <Path to source file(s) of device tree overlay(s)>
dt list-devicetrees

dt list-devicetrees lists all available device tree binaries inside unpacked Toradex Easy Installer image of Torizon.

Arguments
None
Example
With Docker Volume
$ torizoncore-builder dt list-devicetrees
without Docker Volume
$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> dt list-devicetrees
dt overlay

dt overlay compiles and apply device tree overlay(s) to the device tree binary.

Arguments
`--devicetree (optional):` Name of devicetree binary inside OSTree(unpacked Torizon rootfs) or Path to device tree binary in working directory. If device tree binary is not found in the working directory, it is searched inside OSTree as default. 
      **default:** `devicetree` binary file from OSTree.

`--devicetree-out (optional):`Path to overlaid device tree binary output named `devicetree`
      **default:** If user does not specify it, Docker volume is used to save the output.

`--include-dir (optional):` Path to directory containing `.dtsi` and `.h` files. It can be provided multiple times to provide multiple directories/files.
    **default:** It searches in `device-trees/includes` directory of checked out repository.
Positional Argument
Provide overlay(s) to be applied to device tree binary.
Examples
With docker volume

no device tree binary

$ torizoncore-builder dt overlay --include-dir <Path to directory containing .dtsi and/or .h file(s)> --<provide overlay(s)> 

with device tree binary

$ torizoncore-builder dt overlay --device-tree <Name of device tree binary inside OSTree(unpacked Torizon rootfs) or Path to device tree binary> --include-dir <Path to directory containing .dtsi and/or .h file(s)>  <provide overlay(s)> 
without docker volume

no device tree binary

$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> dt overlay --include-dir <Path to directory containing .dtsi and/or .h file(s)> <provide overlay(s)> --devicetree-out <Path to store overlaid device tree in `/usr/lib/modules/` with name 'devicetree'`inside provided directory>

with device tree binary

$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> dt overlay --device-tree <Name of device tree binary inside OSTree(unpacked Torizon rootfs) or Path to device tree binary> --include-dir <Path to directory containing .dtsi and/or .h file(s)>  <provide overlay(s)>  --devicetree-out <Path to store overlaid devicetree in `/usr/lib/modules/` with name 'devicetree'`>

Command Usage Example of TorizonCore Builder

Compile device tree source file and apply overlays. Firstly, clone Toradex provided remote repository containing device tree source files, device tree overlays and .dtsi and .h files.


$ torizoncore-builder dt checkout dt checkout of origin/toradex_5.4.y completed successfully

Optionally to get list of available device trees binaries in unpacked Toradex Easy Installer image of Torizon


$ torizoncore-builder dt list-devicetrees Available device trees are imx6q-apalis-eval.dtb imx6q-apalis-ixora-v1.1.dtb

Compile device tree source file


$ torizoncore-builder dt custom --devicetree-source device-trees/dts-arm32/imx6q-apalis-eval.dts Device tree device-trees/dts-arm32/imx6q-apalis-eval.dts built successfully

If no overlay is needed to be applied, device tree can be merged to Toradex Easy Installer image of Torizon on executing Union command. Union command checks for default locations for all changes in Volume and get them merged to Toradex Easy Installer image of Torizon.

Get list of device tree overlay(s)

$ torizoncore-builder dt list-overlays --devicetree-source device-trees/dts-arm32/imx6q-apalis-ixora.dts
Available overlays are:
     apalis-imx6_adv7280_overlay.dts
     Analogue Camera Adapter orderable at Toradex.
     apalis-imx6_atmel-mxt_overlay.dts
     Atmel MXT touchscreen for the 7inch and 10inch display orderable at Toradex.
     apalis-imx6_lvds_overlay.dts
     Enable the LVDS interface on the Apalis iMX6Q. Make sure to also select a valid display configuration.
     apalis-imx6_ov5640_overlay.dts
     CSI Camera Module 5MP OV5640 orderable at Toradex.
     apalis-imx6_ov5640_v11a_overlay.dts
     CSI Camera Module 5MP OV5640 orderable at Toradex.
     apalis-imx6_parallel-rgb_overlay.dts
     Enable the parallel RGB interface on the Apalis iMX6Q. Make sure to also select a valid display configuration.
     display-edt5.7_overlay.dts
     EDT5.7 display with a resolution of 640x480 pixel
     display-edt7_overlay.dts
     EDT7 display with a resolution of 800x480 pixel     
     display-lt161010_overlay.dts
     LT161010 display (7inch) with a resolution of 800x480 pixel. This display can be ordered at Toradex.    
     display-lt170410_overlay.dts
     LT170410 display (10inch) with a resolution of 1280x800 pixel. This display can be ordered at Toradex.

Compile and apply device tree overlay(s). It will replace device tree in the Docker volume.

$ torizoncore-builder dt overlay --devicetree imx6q-apalis-eval.dtb device-trees/overlays/apalis-imx6-lvds-overlay.dts 
Device tree imx6q-apalis-eval.dtb is to be overlaid
Overlays ['device-trees/overlays/apalis-imx6-lvds-overlay.dts'] successfully applied

Overlaid device tree will get merged to Toradex Easy Installer image of Torizon on executing Union command. Union command checks for changes in Docker Volume and get them merged to Toradex Easy Installer image of Torizon. Refer to TorizonCore Builder Tool for more details on Union command.

torizoncore-builder union --union-branch <branch name>

For example

torizoncore-builder union --union-branch dt_changes
Commit d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3 has been generated for changes and ready to be deployed.

Now it has committed the change to unpacked Toradex Easy Installer image of Torizon, which can be set for deployment either on base unpacked image or directly on the target board over ssh.

For setting a commit for deployment, TorizonCore Builder provides deploy command. Refer to TorizonCore Builder Tool for more information on deploy command.

To set commit for deployment on base unpacked Toradex Easy Installer image of Torizon

torizoncore-builder deploy <commit id> --output-directory <output path for TorizonCore Toradex Easy Installer image>

For example

torizoncore-builder deploy d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3 --output-directory output
Using unpacked Toradex Easy Installer image as base:
  Commit checksum: 54fd6637c9b992e30b7d81e9adf27c4df0e9617c4d94feaa8fb330ae79d170ee
  TorizonCore Version: 5.0.0-devel-20200924030222+build.0
  Kernel arguments: quiet logo.nologo vt.global_cursor_default=0 plymouth.ignore-serial-consoles splash ostree=/ostree/boot.1/torizon/2858281ace2f33c55d8bf1e9e0dacfa6eb7a601f17c89738cb1b00b6ffe01f02/0

Deploying commit ref: d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3
Pulling OSTree with ref d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3 (checksum d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3)from local archive repository...
Pulling done.
Deploying OSTree with checksum d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3
Deploying done.
Copy rootdirs such as /home from original deployment.
Packing rootfs...
Packing rootfs done.

To deploy directly on target machine

torizoncore-builder deploy <commit id> --remote-host <host name or ip of target machine> --remote-username <user name of target machine> --remote-password <password of target machine>

For example

torizoncore-builder deploy d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3 --remote-host 192.168.1.111 --remote-username torizon --remote-password 1234
Pulling OSTree with ref d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3 (checksum d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3) from local archive repository...
Starting http server to serve OSTree.
Starting OSTree pull on the device...
Deploying new OSTree on the device...
Deploying successfully finished.
Please reboot the device to boot into the new deployment.

It can be verified on Target machine after rebooting,

sudo ostree admin status                                                                                              
Password: 
* torizon d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3.0
    Version: 5.0.0-devel-20200924030222+build.0-tcbuilder.20200925235634
    origin refspec: tcbuilder:d36d7f8b393e9226af780d16c0813eaa087fd35ff1251c86b5dc0d61a9ca29b3
  torizon 67f3b0ed5b69cd1b0aa74c8c7cc2ca7b27cf822ae63d347f4aa39b241bd06741.0 (rollback)
    Version: 5.0.0-devel-202009+build.2
    origin refspec: torizon:5/apalis-imx6/torizon/torizon-core-docker/monthly

Removing a conflicting DTO

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

If the connection is properly done, you should see a BOOT partition show up in your PC. Simply delete the conflicting .dtbo and the conflicting line 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 simply requires using the correct port or a small jumper removal (like Ixora's JP2). Note: You can delete the overlays.txt file if you don't have any DTBO working. TorizonCore will recreate this file when activating a new DTBO.

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 webshop. For information about these overlays, see the Toradex Device Tree Overlays repository on Github and the Setting up Displays with Torizon article.

Displays

Toradex provides Device Tree Overlays for the Displays available in the webshop.

Overlay Device
display-edt5.7-overlay.dts Enable the 5.7 inch display (EOL) for Colibri imx7, Apalis iMX6, and Colibri iMX6
display-edt7-overlay.dts Enable the 7 inch display (EOL) for Colibri imx7, Apalis iMX6, and Colibri iMX6
display-lt161010-overlay.dts Enable the 7 inch parallel display for Colibri iMX7, Apalis iMX6, and Colibri iMX6
apalis-imx8x-display-lt161010-overlay.dts Enable the 7 inch parallel display for Apalis iMX8X
colibri-imx8x-display-lt161010-overlay.dts Enable the 7 inch parallel display for Colibri iMX8X
display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX6
apalis-imx8qm-display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX8
apalis-imx8x-display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX8X
apalis-imx6-lvds-overlay.dts Apalis iMX6Q requires a secondary overlay to enable the LVDS interface
apalis-imx6-parallel-rgb-overlay.dts Apalis iMX6Q requires a secondary overlay to enable the parallel RGB interface
colibri-imx8x-disable-parallel-rgb-overlay.dts Disable the parallel RGB interface on Colibri iMX8X

Touch controllers

Toradex provides Device Tree Overlays for the Touch Controllers for the Displays available in the webshop.

Overlay Device
apalis-imx6-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX6
apalis-imx8qm-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX8
apalis-imx8x-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX8X
colibri-imx6-aster-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Aster + Colibri iMX6
colibri-imx7-aster-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Aster + Colibri iMX7
colibri-imx6-eval-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri EVB + Colibri iMX6
colibri-imx7-eval-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri EVB + Colibri iMX7
colibri-imx8x-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri iMX8X
apalis-imx8x-ad7879-overlay.dts Enable the resistive touch controller (AD7879) on the Apalis iMX8X module
colibri-imx8x-ad7879-overlay.dts Enable the resistive touch controller (AD7879) on the Colibri iMX8X module

RTC

Overlay Device
apalis-imx8qm-st-m41t0-overlay.dts Enable the external m41t0 RTC from ST on Apalis iMX8

DSI to HDMI Adapter

Overlay Device
colibri-imx8x-dsihdmi-overlay.dts Enable the dsi to hdmi adapter for Colibri iMX8X

Enable DSI to HDMI Adapter example

To enable the DSI to HDMI Adapter for Verdin with TorizonCore you need to use TorizonCore builder as shown above. The following commands will then apply the overlay and deploy the new image to the Verdin module:

# Setup direcotry 
mkdir custom-torizoncore
cd custom-torizoncore
 
# Download and unpack Toradex Easy Installer image
wget https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prerelease-frankfurt/dunfell-5.x.y/monthly/3/verdin-imx8mm/torizon/torizon-core-docker/oedeploy/torizon-core-docker-verdin-imx8mm-Tezi_5.0.0-devel-202010%2Bbuild.3.tar
tar -xf torizon-core-docker-verdin-imx8mm-Tezi_5.0.0-devel-202010%2Bbuild.3.tar
 
# Unpack the Torizon image into an archive mode ostree
torizoncore-builder unpack --image-directory ./torizon-core-docker-verdin-imx8mm-Tezi_5.0.0-devel-202010+build.3/
# Checkout the devicetree overlays
torizoncore-builder dt checkout
# Apply the hdmi overlay to the base devicetree
torizoncore-builder dt overlay --devicetree imx8mm-verdin-wifi-dev.dtb ./device-trees/overlays/verdin-imx8mm_lt8912_overlay.dts
# Union the modified devicetree with the base image to an ref called hdmi
torizoncore-builder union --union-branch hdmi
# Deploy the new TorizonCore image to the target
torizoncore-builder deploy --remote-host <remote ip> --remote-username torizon --remote-password <password> --reboot hdmi

Torizon 4.0.0

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 on Torizon. If you want to use device tree overlays with our Reference Images for Yocto Project, read the Device Tree Overlays section from Build U-Boot and Linux Kernel from Source Code.

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. This tool is written by Toradex for a smoother development experience with Torizon.

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 CoM, 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, and if this is not possible, you'll have to specify the one that is currently used with the "-c" additional parameter referencing the device tree.

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.

Removing a conflicting DTO

In case you find yourself with a non-working kernel (normally, stuck at the "Loading kernel..." message), you can delete your custom overlays directly from your PC.
You'll 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

If the connection is properly done, you should see a BOOT partition show up in your PC. Simply delete the conflicting .dtbo and the conflicting line 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 simply requires using the correct port or a small jumper removal (like Ixora's JP2). Note: You can delete the overlays.txt file if you don't have any DTBO working. TorizonCore will recreate this file when activating a new DTBO.

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 webshop. For information about these overlays, see the Toradex Device Tree Overlays repository on Github and the Setting up Displays with Torizon article.

Displays

Toradex provides Device Tree Overlays for the Displays available in the webshop.

Overlay Device
display-edt5.7-overlay.dts Enable the 5.7 inch display (EOL) for Colibri imx7, Apalis iMX6, and Colibri iMX6
display-edt7-overlay.dts Enable the 7 inch display (EOL) for Colibri imx7, Apalis iMX6, and Colibri iMX6
display-lt161010-overlay.dts Enable the 7 inch parallel display for Colibri iMX7, Apalis iMX6, and Colibri iMX6
apalis-imx8x-display-lt161010-overlay.dts Enable the 7 inch parallel display for Apalis iMX8X
colibri-imx8x-display-lt161010-overlay.dts Enable the 7 inch parallel display for Colibri iMX8X
display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX6
apalis-imx8qm-display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX8
apalis-imx8x-display-lt170410-overlay.dts Enable the 10.1 inch lvds display for Apalis iMX8X
apalis-imx6-lvds-overlay.dts Apalis iMX6Q requires a secondary overlay to enable the LVDS interface
apalis-imx6-parallel-rgb-overlay.dts Apalis iMX6Q requires a secondary overlay to enable the parallel RGB interface
colibri-imx8x-disable-parallel-rgb-overlay.dts Disable the parallel RGB interface on Colibri iMX8X

Touch controllers

Toradex provides Device Tree Overlays for the Touch Controllers for the Displays available in the webshop.

Overlay Device
apalis-imx6-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX6
apalis-imx8qm-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX8
apalis-imx8x-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Apalis iMX8X
colibri-imx6-aster-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Aster + Colibri iMX6
colibri-imx7-aster-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Aster + Colibri iMX7
colibri-imx6-eval-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri EVB + Colibri iMX6
colibri-imx7-eval-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri EVB + Colibri iMX7
colibri-imx8x-atmel-mxt-overlay.dts Enable the Atmel MXT touchscreen for the 7" and 10" display and Colibri iMX8X
apalis-imx8x-ad7879-overlay.dts Enable the resistive touch controller (AD7879) on the Apalis iMX8X module
colibri-imx8x-ad7879-overlay.dts Enable the resistive touch controller (AD7879) on the Colibri iMX8X module

RTC

Overlay Device
apalis-imx8qm-st-m41t0-overlay.dts Enable the external m41t0 RTC from ST on Apalis iMX8

DSI to HDMI Adapter

Overlay Device
colibri-imx8x-dsihdmi-overlay.dts Enable the dsi to hdmi adapter for Colibri iMX8X