Skip to main content
Version: BSP 7.x.y

Device Tree Overlays (Linux)

Introduction​

caution

Device Tree Overlays were introduced in BSP 5. Therefore, this information does not apply to earlier BSPs.

Device Tree Overlays (DTO) provide a way to modify the overall device tree without 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.

Because of this flexible nature, overlays provide an advantageous way of describing peripheral hardware that can be added or removed from the system. It is also useful for tweaking the parameters of existing hardware before committing it to a complete device tree.

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

  1. Write a Device Tree Overlay (.dts) file.
  2. Compile the .dts file to generate a .dtbo file.
  3. Enable the overlay (using the .dtbo file)

This article will explore these steps for the Toradex BSP Layers and Reference Images for Yocto Project. For information specific to Torizon, see the Device Tree Overlays on Torizon article.

Stages of Development​

The development cycle of a device tree overlay, much like many other software components that you plan to integrate into your custom Yocto Project build might have three phases. You are of course free to do it differently, but here's how this article suggests:

  • Evaluation: enable pre-built overlays that are included in our Reference Images, making it possible to evaluate some hardware peripherals in a few minutes.
  • Development: for faster iteration cycles, build the overlays manually, copy them over to the device and enable them. We do provide a Makefile to ease this process.
  • Production: after you are happy with the overlays you have developed:
    • Either integrate them into your custom Yocto Project build.
    • Or integrate them into your final device tree and then integrate your final device tree into your custom Yocto Project build.

Device Tree Overlays Version Information​

The Device Tree Overlays branch matches perfectly with the Kernel branch, which you can find at Kernel Version Information. In other words, for upstream based modules, the branch is master, and for downstream based modules is toradex_5.15-2.<n>.x-imx.

Evaluation: Pre-built Device Tree Overlays for Peripherals and Add-on Products Provided by Toradex​

To reduce complexity and also to provide you with example implementations, Toradex provides pre-built Device Tree Overlays for SoM peripherals and add-on products (Display and Touch Controllers) available in the webshop. The Reference Images offer these Overlays as binaries (.dtbo files).

On a Toradex SoM you can list these files available on the boot partition. As an example, using the the terminal of a Apalis iMX8:

$ ls /boot/overlays
apalis-imx8_ar0521_overlay.dtbo   apalis-imx8_atmel-mxt_overlay.dtbo apalis-imx8_hdmi_overlay.dtbo
apalis-imx8_lvds_overlay.dtbo     apalis-imx8_ov5640-2_overlay.dtbo  apalis-imx8_ov5640_overlay.dtbo
display-dpi-lt170410_overlay.dtbo display-edt5.7_overlay.dtbo        display-edt7_overlay.dtbo
display-fullhd-imx6_overlay.dtbo  display-fullhd_overlay.dtbo        display-lt161010_overlay.dtbo
display-lt170410_overlay.dtbo     display-vga_overlay.dtbo

To enable these overlays, see the Enable/Disable a Device Tree Overlay section. Some overlays are pre-enabled by default, refer to the Pre-enabled Device Tree Overlays section for this.

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.

Displays​

info

Default resolution with these overlays: 1920x1080

Native Interface:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_hdmi_overlay.dtbo
Apalis iMX8 QuadMax6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX66.0.0apalis-imx6_hdmi_overlay.dtbo
Colibri iMX66.0.0colibri-imx6_hdmi_overlay.dtbo

Using Verdin DSI to HDMI adapter:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_dsi-to-hdmi_overlay.dtbo
Verdin iMX8M Mini6.1.0verdin-imx8mm_dsi-to-hdmi_overlay.dtbo
Verdin AM626.4.0verdin-am62_dsi-to-hdmi_overlay.dtbo

Using Colibri DSI to HDMI adapter:

ModuleStarting from versionOverlay
Colibri iMX8X6.2.0colibri-imx8x_dsihdmi_overlay.dtbo

SPIDEV​

Native Interface:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus6.0.0SPIverdin-imx8mp_spidev_overlay.dtbo
Verdin iMX8M Mini6.0.0SPIverdin-imx8mm_spidev_overlay.dtbo
Verdin AM626.4.0SPIverdin-am62_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 1apalis-imx6_spi1_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 2apalis-imx6_spi2_spidev_overlay.dtbo
Colibri iMX8X6.1.0SPIcolibri-imx8x_spidev_overlay.dtbo
Colibri iMX6ULL eMMC6.1.0SPIcolibri-imx6ull_spidev_overlay.dtbo

CAN​

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Mini6.1.0CAN 1 [20MHz]verdin-imx8mm_20mhz_can1.dtbo
Verdin iMX8M Mini6.0.0CAN 1 [Disable]verdin-imx8mm_disable_can1.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Apalis iMX8 QuadMax6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo

Camera​

OV5640 CSI Camera​

See the OV5640 CSI Camera in the Developer Wesite.

Native Interface:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus6.0.0CSIverdin-imx8mp_ov5640_overlay.dtbo
Verdin iMX8M Mini6.0.0CSIverdin-imx8mm_ov5640_overlay.dtbo
Verdin AM626.4.0CSIverdin-am62_ov5640_overlay.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus [Default jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-default-jumpers_overlay.dtbo
Verdin iMX8M Plus [Alternate jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-alt-jumpers_overlay.dtbo
Apalis iMX8 QuadMax6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo

Verdin Mezzanine jumper settings:

Jumper SettingJP3JP4JP5JP6
Default2-32-32-32-3
Alternate2-32-31-21-2

HMP​

Heterogeneous Multicore Processing Overlays:

ModuleStarting from versionOverlay
Verdin AM626.6.0verdin-am62_hmp_overlays.dtbo
Verdin iMX8M Plus6.3.0verdin-imx8mp_hmp_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_hmp_overlay.dtbo
Colibri iMX8X6.4.0colibri-imx8x_hmp_overlay.dtbo

BTL Audio Output on NAU8822​

Verdin Development Board features an analog audio interface based on the NAU8822 24-bit audio codec IC with integrated DSP with specific functions

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.2.0verdin-imx8mp_nau8822-btl_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_nau8822-btl_overlay.dtbo
Verdin AM626.4.0verdin-am62_nau8822-btl_overlay.dts

Pre-enabled Device Tree Overlays​

By default, the following overlays are enabled to simplify the use of Toradex carrier boards and modules. Note that these overlays may cause conflicts with other peripherals.

ModuleSupported PeripheralsOverlays
Apalis iMX8HDMI
SPIDEV		apalis-imx8_hdmi_overlay.dtbo
apalis-imx8_spi1_spidev_overlay.dtbo
apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX6HDMI
SPIDEV		apalis-imx6_hdmi_overlay.dtbo
apalis-imx6_spi1_spidev_overlay.dtbo
apalis-imx6_spi2_spidev_overlay.dtbo

Enable/Disable a Device Tree Overlay​

To enable or disable applying a pre-built overlay on a Toradex SoM just add/remove it to/from the file overlays.txt located on the boot partition, and reboot the system.

For example, one wants to disable a parallel RGB interface and display on Colibri-iMX8X and enable an HDMI interface (using DSI-to-HDMI adapter). The initial overlays.txt file looks like:

# cat /boot/overlays.txt 
fdt_overlays=colibri-imx8x_parallel-rgb_overlay.dtbo colibri-imx8x_ad7879_overlay.dtbo display-edt7_overlay.dtbo

Steps to disable a parallel RGB and enable an HDMI:

  1. Open the overlays.txt file with any text editor, e.g. vi:
# vi /boot/overlays.txt
  1. Remove overlays, that is needed for Resistive Touch Display 7" Parallel and add one for DSI-to-HDMI adapter. The file should look like:
# cat /boot/overlays.txt 
fdt_overlays=colibri-imx8x_dsihdmi_overlay.dtbo
  1. Synchronize them filesystems:
# sync
  1. Reboot the system:
# reboot
info

In case you find yourself with a non-working kernel after applying the overlays, see the Removing a conflicting DTO section.

info

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.

Development: Writing a Custom DTO​

The most recommended way to create a new overlay is to start looking at our evaluation boards' overlays and then adapt to your project's needs. You can find those overlays in the device-tree-overlays repository.

As with normal device trees, overlays must get explicitly written for the correct kernel version. This depends on the BSP you are using from Toradex and can be checked on Build U-Boot and Linux Kernel from Source Code article.

As an example, here is the device tree overlay for parallel RGB on a Colibri iMX8X (colibri-imx8x_parallel-rgb_overlay.dts):

// Enable the parallel RGB interface on Colibri iMX8X

/dts-v1/;
/plugin/;
/ {
    compatible = "toradex,colibri-imx8x";
};

&adma_pwm {
        status = "okay";
};

&backlight {
        status = "okay";
};

&display_lcdif {
        status = "okay";
};

&panel_dpi {
        status = "okay";
};

This overlay, if loaded, is directly appended to imx8qxp-colibri-eval-v3.dts. This device tree, however, includes the "System on Module Level" device tree imx8qxp-colibri.dtsi which contains most of the device tree nodes.

If the overlay gets loaded, it gets integrated into the already loaded device tree. To add or overwrite properties can be achieved with the ampersand character the same way as described in section Device Tree Structure and Conventions.

Devicetree overlays have to be denoted with /plugin/; in the header.

For further reading on this topic, we refer to the kernel documentation: https://www.kernel.org/doc/html/latest/devicetree/overlay-notes.html?highlight=overlays

Building a DTO​

To build the Device Tree Overlay, see the Build U-Boot and Linux Kernel from Source Code article.

Deploying a Device Tree Overlay​

To deploy a custom overlay on a Toradex SoM with the Linux BSP >= 5.0 installed:

  • copy the .dtbo file to the overlays/ directory in the boot partition;
  • add the overlay binary .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

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.

info

In case you find yourself with a non-working kernel after applying the overlay, see the Removing a conflicting DTO section

Removing a conflicting DTO​

In case you find yourself with a non-working kernel (normally, stuck at the "Loading kernel..." message), you can choose the way to solve this issue:

  1. Disable loading all overlays by setting the special u-boot variable:
> setenv skip_fdt_overlays 1
> boot
  1. 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

After this command, you should see a BOOT partition show up on your PC. Delete the conflicting .dtbo and the corresponding item in the overlays.txt file.

info

Check your carrier board datasheet to what ports and jumper configurations work with USB-OTG. With Toradex carrier boards, it requires using the correct port or a small jumper removal (like Ixora's JP2).

Production: Add Your Overlays to a Custom Yocto Project Build​

It is expected that you have some knowledge of Yocto Project/OpenEmbedded. The minimum prerequisite is being able to Build a Reference Image with Yocto Project.

If you decide to integrate your final changes into full device trees, read the article Custom meta layers, recipes and images in Yocto Project (hello-world examples).

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

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 instead of ours.

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 e.g. grep inside the layers directory:

$ cd <yocto projet setup>
$ grep -nre "TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT" layers/*

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

Example bbappend​

Below is an example of a bbappend that adds a custome my-device-tree_overlay.dtbo to the Yocto-built image.

FILESEXTRAPATHS:prepend := "${THISDIR}/device-tree-overlays:"

CUSTOM_OVERLAYS_SOURCE = " \
    my-device-tree_overlay.dts \
"
CUSTOM_OVERLAYS_BINARY = " \
    my-device-tree_overlay.dtbo \
"

SRC_URI += " \
    file://my-device-tree_overlay.dts \
"

TEZI_EXTERNAL_KERNEL_DEVICETREE += " \
    ${CUSTOM_OVERLAYS_BINARY} \
"

TEZI_EXTERNAL_KERNEL_DEVICETREE_BOOT = " \
    ${CUSTOM_OVERLAYS_BINARY} \
"

do_collect_overlays:prepend() {
    for DTS in ${CUSTOM_OVERLAYS_SOURCE}; do
        cp ${WORKDIR}/${DTS} ${S}
    done
}

For this example, the my-device-tree_overlay.dts source file is expected to be located in the folder device-tree-overlays at the same directory of the bbappend.

This example is available at https://github.com/griloHBG/meta-grilo-experiments/tree/scarthgap-7.x.y/meta-new-device-tree-overlays



Send Feedback!