Torizon 5.0.0

Introduction

Linux Device Tree is a data structure describing a system's hardware.

Sometimes, it is necessary to modify the Device Tree. Some use cases that require Device Tree modifications include (but not limited to):

• Add a Display to the board and configure its pin and timing settings.
• Bring-up a new peripheral connected to the SoM, for example, an external CAN transceiver connected through the SPI interface.
• Changing the SoC's pin functions, i.e., Pin Multiplexing, e.g., set the GPIO function for some specific pin not assigned to this function by default.

Device Tree is built with the Kernel when building the distribution. However, Device Tree Overlays provide a way to modify the overall device tree without the need for re-compiling 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 hardware components in the system.

Due to its flexible nature, overlays provide an advantageous way of describing peripheral hardware added or removed from the system. It is also useful for tweaking the existing hardware parameters before committing it to a complete device tree. You can find rich information about overlays available on the web.

In a very brief description, the process of designing for a Device Tree Overlay comprises three macro steps:

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

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.

This article will show the tools available for designing Device Tree Overlays for Toradex CoMs on TorizonCore. 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 Toradex Computer-on-Module (CoM) with Torizon already installed.
• A host machine with TorizonCore Builder installed

Prototypes only: Quickly Enabling Displays, Touch Controllers, Adapters, and other Add-on Products Provided by Toradex

Attention: The instructions provided in this session intended for prototype and proof-of-concept only. For production, skip directly to the next section of this article for information about TorizonCore Builder usage.

On TorizonCore image there are pre-built Device Tree Overlays for Add-on Products available in Toradex's webshop. You can see a complete list of the available overlays at the end of this article.

First, see a list of available pre-built overlays (*.dtbo files):

# ls /sysroot/boot/ostree/torizon-*/dtb/overlays

To enable these overlays, you need to modify the file /sysroot/boot/ostree/torizon-*/dtb/overlays.txt in your SoM, adding the desired overlays. You can create it, if not existing.

This file will contain the string fdt_overlays= followed by a space-separated list of overlays.

For example, to enable the DSI to HDMI converter and the CSI Camera Module OV5640 on the Verdin iMX8M Mini module, use the following commands:

# cd /sysroot/boot/ostree/torizon-*/dtb/
# sudo sh -c "echo 'fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_ov5640_overlay.dtbo' > overlays.txt"
# sync

In this example, this will be the content of the overlays.txt file:

 /sysroot/boot/ostree/torizon-*/dtb/overlays.txt
fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_ov5640_overlay.dtbo

To enable the DSI to HDMI converter only, use the following command:

# sudo sh -c "echo 'fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo' > overlays.txt"
# sync

After changing the overlays.txt file, reboot the board.

If you want to obtain the source code of the Device Tree Overlays provided by Toradex for the products available on the webshop, see the TorizonCore Builder Tool section of this article.

Note: The changes applied following these steps will not persist after an OTA update. Also, this will not generate an image to deploy multiple boards. Therefore, this procedure is not scalable and is not recommended for production. For information about how to proceed with development for production, continue reading the next sections of this article.

Attention: If you add a device tree overlay that will break the kernel boot you can set the U-Boot environment variable skip_fdt_overlays to 1. In U-Boot do: setenv skip_fdt_overlays 1

Development and Production: Using TorizonCore Builder

TorizonCore Builder Tool assists users in creating and managing updates for deployed Torizon images. It runs in a container on the host system. Among all other functionalities, TorizonCore Builder Tool can compile device tree overlay(s), apply it to the devicetree, and merge it to a TorizonCore image (on a Toradex Easy Installer compatible format). The tool can also deploy the changes over ssh directly to the Torizon image running on a target machine.

See the TorizonCore Builder Tool article for detailed information about the software and its sub-commands and options.

Note: Install TorizonCore Builder before you start following the instructions below.

Writing a Device Tree Overlay

The most recommended way to create a new overlay is to start looking at similar overlays and then adapt to your project's needs. The next chapters of this article will show how you can obtain Device Tree Overlays source files for peripherals sold by Toradex.

However, if you need to build overlays for different hardware, the Linux Kernel source provides binding documentation for specific peripherals.

To access this information, visit The Linux Kernel Archives website and browse the Linux Kernel source for your board's specific version. You will find the particular bindings information in the Linux kernel source at the Documentation/devicetree/bindings directory.

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

Cloning the Toradex Device Tree and Overlays Repository

Toradex provides source files of Device Trees and 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 TorizonCore Builder Tool article. The repository contains device tree source files, device tree overlays, and .dtsi and .h files.

Note: The examples below uses docker volume. You can easily adapt the examples to use without docker volume. See the TorizonCore Builder Tool article for more information.

With TorizonCore Builder in a host machine, to clone the repository using the tool, execute the following:

$ torizoncore-builder dt checkout
Cloning into 'device-trees'...
remote: Enumerating objects: 1067, done.
remote: Counting objects: 100% (1067/1067), done.
remote: Compressing objects: 100% (727/727), done.
remote: Total 1067 (delta 441), reused 947 (delta 321), pack-reused 0
Receiving objects: 100% (1067/1067), 800.96 KiB | 367.00 KiB/s, done.
Resolving deltas: 100% (441/441), done.

The device-trees Toradex repository has the following directory organization:

• dts-arm32 - source files of device trees for Toradex modules of 32-bit architectures.
• dts-arm64 - source files of device trees for Toradex modules of 64-bit architectures.
• overlays - source files of device tree overlays for Toradex modules.

The source files for both device trees and device tree overlays have the .dts extension.

The following sections provide examples of building device trees from source and applying overlays using TorizonCore Builder.

Compiling and Applying Device Trees

To identify the current device tree of the image, use dt status:

 $ torizoncore-builder dt status
Current device tree is: imx6q-apalis-eval.dtb

In the above command, note that the device tree has the .dtb extension, meaning that it's a compiled device tree.

Note: Some images of Toradex modules don't set the device tree upfront, delaying the selection of a device tree for boot time. In these cases, dt status won't be able to show the current device tree of the image.

To compile a given device tree source file and then set it to be used in the image, use dt apply:

$ torizoncore-builder dt apply device-trees/dts-arm32/imx6q-apalis-ixora-v1.1.dts
/tmp/tmpxkgnzwvq: Device Tree Blob version 17, size=77701, boot CPU=0, string block size=6225, DT structure block size=71420
'imx6q-apalis-ixora-v1.1.dts' compiles successfully.
Device tree imx6q-apalis-ixora-v1.1.dtb successfully applied.

Note: When applying a device tree with dt apply, all overlays that were eventually applied are reset.

Compiling and Applying Device Tree Overlays

To list the overlays under device-trees/overlays that are compatible with the current device tree, use dto list:

$ torizoncore-builder dto list
Overlays compatible with device tree imx6q-apalis-ixora-v1.1.dtb:
- device-trees/overlays/apalis-imx6_atmel-mxt_overlay.dts
- device-trees/overlays/apalis-imx6_hdmi_overlay.dts
- device-trees/overlays/apalis-imx6_lcd_overlay.dts
- device-trees/overlays/apalis-imx6_lvds_overlay.dts
- device-trees/overlays/apalis-imx6_stmpe-ts_overlay.dts
- device-trees/overlays/apalis-imx6_vga_overlay.dts
- device-trees/overlays/display-edt5.7_overlay.dts
- device-trees/overlays/display-edt7_overlay.dts
- device-trees/overlays/display-fullhd_overlay.dts
- device-trees/overlays/display-lt161010_overlay.dts
- device-trees/overlays/display-lt170410_overlay.dts

To compile a given device tree overlay source file and then set it to be applied to the device tree during boot, use dto apply:

$ torizoncore-builder dto apply device-trees/overlays/apalis-imx6_hdmi_overlay.dts
/tmp/tmpgfs3rch0: Device Tree Blob version 17, size=1124, boot CPU=0, string block size=100, DT structure block size=968
'apalis-imx6_hdmi_overlay.dts' compiles successfully.
/tmp/tmp2p3gc2s0: Device Tree Blob version 17, size=77669, boot CPU=0, string block size=6225, DT structure block size=71388
'apalis-imx6_hdmi_overlay.dtbo' can successfully modify the device tree 'imx6q-apalis-ixora-v1.1.dtb'.
Overlay apalis-imx6_hdmi_overlay.dtbo successfully applied.

In the above example:

1. The device tree overlay source apalis-imx6_hdmi_overlay.dts was successfully compiled to apalis-imx6_hdmi_overlay.dtbo.
2. For testing, the compiled overlay apalis-imx6_hdmi_overlay.dtbo modified successfully a temporary copy of the current device tree imx6q-apalis-ixora-v1.1.dtb. This is just a sanity verification that the overlay won't fail when applied during booting the module. This step can be bypassed with option --force to dto apply.
3. On sucessful execution of the previous steps, the compiled overlay was added to the list of overlays that are applied to the current device tree of the module during boot.

Overlays can be applied incrementally; if you want to enable more overlays, use dto apply again.

To identify the device tree overlays that are currently applied to the device tree in the image, use dto status:

$ torizoncore-builder dto status
Enabled overlays over device tree imx6q-apalis-ixora-v1.1.dtb:
- apalis-imx6_hdmi_overlay.dtbo

In the above example, note that the overlays have the .dtbo extension, meaning they are compiled files.

To remove an applied overlay, use dto remove and pass the overlay blob name as given by dt status:

$ torizoncore-builder dto remove apalis-imx6_hdmi_overlay.dtbo

Capturing the Changes

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; when using torizoncore-builder versions 3.0.0 or later, execute:

$ torizoncore-builder union dt_changes

Or, if using versions of the tool before 3.0.0:

$ torizoncore-builder union --union-branch dt_changes

Deploying Changes

Now the tool has committed the change to the unpacked Toradex Easy Installer image of Torizon. You can use the commit for deployment either on the unpacked base image (on Toradex Easy Installer format) or directly on the target board over ssh.

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

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

$ torizoncore-builder deploy <name or checksum of branch from Union command> --output-directory <output path for TorizonCore Toradex Easy Installer image>

For example:

$ torizoncore-builder deploy dt_changes --output-directory output

To deploy directly on a target machine:

$ torizoncore-builder deploy <name or checksum of branch from Union command> --remote-host <host name or ip of target machine> --remote-username <user name of target machine> --remote-password <password of target machine> [--reboot]

For example:

Note: 192.168.1.111 is the board's IP of the target machine.

$ torizoncore-builder deploy dt_changes --remote-host 192.168.1.111 --remote-username torizon --remote-password 1234 --reboot

Pushing Changes to Torizon OTA

Often, after you use the deploy command to validate changes during development, you will want to push your changes to Signing and Pushing TorizonCore Images to Torizon OTA. Learn how to do it on Device Tree Customization Examples.

Checking the changes

After rebooting, in your target machine's terminal, check if the new version is now active:

# 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

Rollback Mechanism

In case you find yourself with a non-working kernel (usually stuck at the "Loading kernel..." message) when applying a device tree overlay with TorizonCore Builder, after a few boot tries (3 by default), the system will roll back to the previous version of the operating system. For more information on the rollback mechanism, see Rollback and boot count support of aktualizr.

Applying a device tree overlay with just one command

If you want to quickly test a device tree overlay, you can apply the overlay on a running device with a single TorizonCore Builder command. Behind the scenes, TorizonCore Builder will execute all the steps necessary to deploy an image to your device.

Attention: For production workflows, the recommended approach is to follow the production section of this article. The production workflow will provide more control over the image customization. This command is intended for quick tests on device tree overlays.

For example, if you want to enable a display using the display-lt161010_overlay.dts overlay, you will only need to run the following command:

$ torizoncore-builder dto deploy --remote-host <Hostname/IP address of target board> --remote-username <User on target board> --remote-password <Password of user on target board> --force --reboot device-trees/overlays/display-lt161010_overlay.dts

Downloading image from: https://artifacts.toradex.com/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/verdin-imx8mm/torizon/torizon-core-docker/oedeploy/torizon-core-docker-verdin-imx8mm-Tezi_5.1.0+build.1.tar

The download may take some time. Please wait...
Download Complete!

Unpacking Toradex Easy Installer image.
Copying Toradex Easy Installer image.
Unpacking TorizonCore Toradex Easy Installer image.
Importing OSTree revision 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82 from local repository...
0 metadata, 0 content objects imported; 0 bytes content written                                                                                                                                            
Unpacked OSTree from Toradex Easy Installer image:
  Commit checksum: 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82
  TorizonCore Version: 5.1.0+build.1
'device-trees' directory already exists
'display-lt161010_overlay.dts' compiles successfully.
warning: --force was used, bypassing checking overlays against the device tree.
Overlay display-lt161010_overlay.dtbo successfully applied.
Commit 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b has been generated for changes and ready to be deployed.
Pulling OSTree with ref dto_deploy (checksum 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b) 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.
Device reboot initiated...

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.

List of Device Tree Overlays available 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 TorizonCore Builder Tool article.

Displays

Attention: the migration to device tree overlays is currently a work-in-progress. There are some overlays listed in the table below that are missing. For more information, please consult the BSP Layers and Reference Images for Yocto Project Issue Tracker.

• Capacitive Touch Display 7" Parallel
• Capacitive Touch Display 10.1" LVDS
• Resistive Touch Display 7" Parallel
• HDMI
• VGA
• EDT 7.0" (EOL)

Pre-enabled Device Tree Overlays

Toradex turns on a pre-set of Device Tree Overlays to support the default display interfaces and panels.

• Apalis
• Colibri
• Verdin

RTC

DSI to HDMI Adapter

# 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