Skip to main content

First Steps with Device Tree Overlays

Introduction​

In this article, we will guide you through the first steps of working with Device Tree Overlays. You will learn how to chose a ready-to-use Device Tree Overlay or write/customize one to your specific need.

Prerequisites​

Get Started with Device Tree Overlays​

Device tree overlays are binary files that contain modifications to the device tree structure. Instead of modifying the original device tree source (DTS) file directly, overlays allow you to apply changes dynamically without recompiling or rebooting the system. An overlay file (*.dtbo) is generated by compiling a device tree overlay source (DTO) file. The DTO file describes the modifications to be applied, including device additions, deletions, property changes, and even complete device tree substitutions. These modifications can be applied to specific sections of the device tree or the entire tree itself.

Toradex offer a series of articles to aiming to provide a wide understanding of device trees and device tree overlays on its computer on modules:

  1. Device Tree Overview
  2. Device Tree Overlays Overview

You can refer to the kernel.org archives to find oficial documentation about the topic: Device Tree Overlay Notes - kernel.org

Use a Provided Device Tree Overlay​

You can chose a readily-available Device Tree Overlay if it covers the hardware configuration you need.

They are already deployed to Torizon OS and Reference Images, you would need just to enable/disable the desired ones. If the Device Tree Overlay is provided compiled, you can jump straight into the deploy part of the process. If not, check how to compile it before.

However, in some cases, you will have to write your Device Tree Overlay or modify a base Device Tree Overlay. If this is the case, identify and understand the customizations needed and follow the next sections. The provided Device Tree Overlays are also available as .dts (source file) so you can use one as starting point when writing your own DTOs. You can check how to get the sources in the Toradex Resources section.

Identify and Understand Customizations​

Before writing your overlays, it's crucial to identify the specific customization requirements for your system. Determine the dynamic modifications you wish to make to the hardware configuration. This could involve enabling or disabling devices, adjusting pin assignments, configuring peripherals, or modifying device properties on-the-fly. By clearly understanding your customization needs, you can effectively leverage device tree overlays to achieve the desired hardware configuration changes without rebuilding or rebooting the system.

Device Tree Binding Documentation​

To understand the structure and syntax of the DTS file, it is crucial to refer to the device tree binding documentation specific to your hardware platform. The device tree binding documentation provides detailed information on the available device tree nodes, properties, and their valid values.

Toradex Resources​

If you want to obtain the source code of the Device Tree Overlays provided by Toradex for the products available in the webshop, see the Build U-Boot and Linux Kernel from Source Code article.

Toradex offer a series of articles to aiming to provide a wide understanding of pinmuxing and pin assignments on its computer on modules:

  1. Customizing Nodes and Properties
  2. Pinmuxing Guide Overview.
  3. Pinmuxing with i.MX 6/6ULL Based Modules.
  4. Pinmuxing with i.MX 7 Based Modules.
  5. Pinmuxing with i.MX 8/8X Based Modules.
  6. Pinmuxing with i.MX 8M Mini/Plus Based Modules.

Write a Device Tree Overlay​

To create a device tree overlay, you will need the original device tree source (DTS) file and the device tree overlay source (DTO) file. The DTS file represents the base device tree, while the DTO file describes the modifications to be applied.

  1. Clone the Toradex Device Tree Overlays repository (branch toradex_5.15-2.1.x-imx for BSP 6) and find an overlay for you to base yourself. The most recommended way to create a new overlay is to start looking at similar overlays and then adapt to your project's needs.

    $ git clone -b <branch> git://git.toradex.com/device-tree-overlays.git
    $ cd overlays

  2. Create your custom .dts on your work directory.

    $ touch custom-overlay.dts

  3. Copy and paste this template for an overlay to change the default pin muxing, or base yourself on the already existing ones from the device-trees/overlays/ repository. The content of the custom-overlay.dts should be simillar to the following template.

    View template overlay
    /dts-v1/;
    /plugin/; //Indicates a Device Tree Overlay

    // Header file with pin definitions
    #include <soc-pinfunc.h>

    / {
        compatible = "toradex,apalis-imx8"; // Set hardware compatibility
    };
        
    &iomuxc {
        pinctrl-names = "default";
        pinctrl-0 = <&pinctrl-originally-in-device-tree>, <&pinctrl_my_pins>;  // Pin group available in userspace i.e. as GPIO

        name-of-som {
            pinctrl_my_pins: my_muxgrp {
                fsl,pins = <
                    PIN_NAME_PIN_MUX   PAD_CTRL // PINS
                >;
            };
        };
    };

    &node {
        pinctrl-names = "default";
        pinctrl-0 = <&pinctrl_my_pins>;  // Pin group used in genericPeripheral
        status = "okay";
    };

Build a Device Tree Overlay​

Manual Build​

To build the Device Tree Overlay manually, see the Build Device Tree Overlays from Source Code article.

Build with Torizon OS​

For evaluation, early development or troubleshooting, it can be convenient to use the dto command of TorizonCore Builder.

For later development stages and when preparing the production image, you can leverage the build command, which provides an easy Device Tree Customization process.

Under the device-tree customization section of the build.yaml file, you should add an overlays section, including the .dts files of the DTOs you want to add, as follows:

customization:
  device-tree:
    include-dirs:
      - device-trees/include/
    overlays:
      add:
        - device-trees/overlays/<your-custom-device-tree-overlay.dts

This will enable the build command to compile and deploy the DTOs to your customized image.

Deploy a Device Tree Overlay​

Testing and Development: Manual Deployment​

To deploy a custom overlay on a Toradex SoM:

  1. Copy the .dtbo file to the overlays/ directory in the boot partition.

  2. Add the file name (<custom-overlay>.dtbo) to the overlays.txt file. This file contains a space separated list of overlays. For example:

    $ cat /boot/overlays.txt 
    fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_ov5640_overlay.dtbo custom-overlay.dtbo

  3. After changing the overlays.txt, run the command sync and reboot the board. Do not power-cycle because the edits done may not sync to the file system.

    $ sync 
    $ reboot

Production: Yocto Project​

If you decide to deploy the overlays, two steps are required and explained below:

  • Add your overlays, making sure they are compiled and deployed to the image.
  • Have the overlays listed in overlays.txt, making sure they are enabled.
caution

Raw NAND modules don't support device tree overlays

  1. Add Your Overlays to the Yocto Project: There are currently two recipes that handle device tree overlays:

    You can, for instance, write your own bbappends to add your device tree overlays repository.

  2. Enable Your Overlays in the Yocto Project: The class meta-toradex-bsp-common/classes/image_type_tezi.bbclass is responsible for adding overlays that will be applied during boot time. It uses the variable TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT that is set by default in our machine configuration files, either machine.conf or machine.inc. You can find them using grep inside the layers directory:

    $ cd ~/oe-core/layers
    $ grep -nre "TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT"

    Then you need to either append to or override the variable. One possibility is to use a <machine>-extra.conf file. You can find an example on Custom meta layers, recipes and images in Yocto Project (hello-world examples).

Device Tree Overlays on Torizon​

The build and deployment on Torizon OS can be done in a single step, as explained in the Deploy section. For more Torizon-related information, refer to Device Tree Overlays on Torizon.

Next Steps​

The next step is create and edit your device tree overlay in a case oriented way.

For this, follow the steps at How to Write Device Tree Overlays.



Send Feedback!