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:

• Toradex's Device Tree Customization article
• Device Trees, overlays, and parameters
• Tutorial for BBB, but is a good example of overlays

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

• A computer on module with Torizon already installed.
• Read TorizonCore Builder Tool.

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:

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.

Touch controllers

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

RTC

DSI to HDMI Adapter

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

# uname -r

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.

## dtconf status
Device is colibri imx7(0039)
Currently active overlays:
display_7_parallel_cap_touch.dts.dtbo
colibri-imx7-aster-atmel-mxt-overlay.dts.dtbo
Available base device trees:
        imx7d-colibri-eval-v3.dtb
        imx7d-colibri-emmc-eval-v3.dtb
        imx7s-colibri-eval-v3.dtb
Available overlays for running kernel:
        colibri-imx7-aster-atmel-mxt-overlay.dts:
                Atmel touchscreen for the 7inch capacitive display orderable at Toradex. Use this devicetree on the Aster board.
        colibri-imx7-eval-atmel-mxt-overlay.dts:
                Atmel touchscreen for the 7inch capacitive display orderable at Toradex. Use this devicetree on the Evaluation or Iris board.
        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.

## dtconf build display-lt161010-overlay.dts

## dtconf validate  display-lt161010-overlay.dtbo

## dtconf validate display-lt161010-overlay.dts -c imx7d-colibri-emmc-eval-v3.dtb

## dtconf enable display-lt161010-overlay.dtbo
or
## dtconf -e display-lt161010-overlay.dtbo

## dtconf enable display-lt161010-overlay.dts -c imx7d-colibri-emmc-eval-v3.dtb

## dtconf activate display-lt161010-overlay.dts
or
## dtconf -a display-lt161010-overlay.dts 

## dtconf activate display-lt161010-overlay.dts -c imx7d-colibri-emmc-eval-v3.dtb

## dtconf disable display-lt161010-overlay.dts.dtbo

## dtconf disable --all
or
## dtconf -d --all

## dtconf print display-lt161010-overlay.dtbo

## dtconf build modified_overlay.dts

## dtconf validate modified_overlay.dtbo

## dtconf enable modified_overlay.dtbo

ums 0 mmc 0