Devicetree Overlays

Overview

From Yocto release 4.0 (kirkstone) onwards, the process of automatically changing the fdt_file variable according to the baseboard setting is being abandoned in favour of FDT overlays.

The overlays are applied to the base DTB file to enable specific HW features.

U-Boot will load the base DTB specified via the fdt_file environment variable and apply any FDT overlays defined in the overlays_${baseboard} variable. I.e. if the variable baseboard is set to “mipi-mb” U-Boot will load the FDT overlays defined in the variable overlays_mipi-mb.

If the variable baseboard is unset U-Boot will check the variable overlays (without any suffix) for a list of overlays to be loaded.

Note

Devicetree overlays are not implemented for every module, yet. In this case, having a single devicetree for each hardware applies.

List of Supported Baseboards

Renesas RZ/G2L

Module Baseboards  
  Shortcut Board Name
txrz-g2l0 mb7 Mainboard 7
txrz-g2l1 mb7 Mainboard 7
txrz-g2l2 lvds-mb TX-MIPI-LVDS Mainboard
qsrz-g2l0

qsbase1

qsbase2

qsbase4

qsgyln1

QSBASE1

QSBASE2

QSBASE4

QSGLYN1

qsrz-g2l1

qsbase1

qsbase2

qsbase4

QSBASE1

QSBASE2

QSBASE4

STM32

Module Baseboards  
  Shortcut Board Name
txmp-1570 mb7 Mainboard 7
txmp-1571 mb7 Mainboard 7
qsmp-1570

qsbase1

qsbase2

qsbase4

qsglyn1

QSBASE1

QSBASE2

QSBASE4

QSGLYN1

qsmp-1530

qsbase1

qsbase2

qsbase4

QSBASE1

QSBASE2

QSBASE4

qsmp-1530

qsbase1

qsbase2

qsbase4

QSBASE1

QSBASE2

QSBASE4

NXP

Module Baseboards  
  Shortcut Board Name
tx8m-1610 mipi-mb TX-MIPI-LVDS Mainboard
tx8m-1620

mb7

lvds-mb

Mainboard 7

TX-MIPI-LVDS Mainboard

tx8m-nd00 mipi-mb TX-MIPI-LVDS Mainboard
tx8p

mb7

lvds-mb

Mainboard 7

TX-MIPI-LVDS Mainboard

qs8m

qsbase2

qsbase4

QSBASE2

QSBASE4

qsxm

qsbase3

qsbase4

QSBASE3

QSBASE4

qsxp

qsbase3

qsbase4

QSBASE3

QSBASE4

Overlay Filenames

The file names of the FDT overlays are constructed according to the following scheme:

({SOC_FAMILY}|${SOC_PREFIX})-<overlay name>.dtb

The names listed in the variable overlay_${baseboard} will be suffixed with ‘.dtb’ and prefixed with either ${SOC_FAMILY} (e.g. imx8mm) ${SOC_PREFIX} (imx8m) whichever file exists.

I.e. U-Boot first tries to locate a file with the ${SOC_FAMILY} prefix. If that fails, it will prepend the more generic ${SOC_PREFIX} to the base fdt filename.

Predefined Overlays

U-Boot has a predefined set of overlays compiled into the default environment for each applicable baseboard suitable for the module in use.

Renesas RZ/G2L

Module Baseboard Overlays
qsrz-g2l[0,1] qsbase1

karo-led

karo-sdcard

qsrz-lcd-panel

qsrz-ft5x06

qsrz-ksz9131

qsrz-g2l[0,1] qsglyn1

karo-led

karo-sdcard

qsrz-lcd-panel

qsrz-ili2130

qsrz-ksz9131

qsrz-g2l[0,1] qsbase4

karo-led

qsrz-ksz9131

txrz-g2l[0,1] mb7

karo-led

karo-sdcard-cd

txrz-rtc

txrz-lcd-panel

txrz-ft5x06

txrz-sound

txrz-g2l2 lvds-mb

karo-led

karo-sdcard

txrz-rtc

txrz-lvds-panel

txrz-sound

STM32

Module Baseboard Overlays
qsmp-1570 qsbase1

qsmp-qsbase1

karo-gpu

qsmp-lcd-panel

qsmp-ft5x06

qsmp-ksz9031

qsmp-1570 qsglyn1

qsmp-qsglyn1

karo-gpu

qsmp-lcd-panel

qsmp-ft5x06

qsmp-ksz9031

qsmp-1570 qsbase2

qsmp-qsbase2

qsmp-ksz9031

qsmp-1570 qsbase4

qsmp-qsbase4

qsmp-ksz9131

qsmp-1530 qsbase1

qsmp-qsbase1

qsmp-lcd-panel

qsmp-ft5x06

qsmp-ksz9031

qsmp-1530 qsbase4

qsmp-qsbase4

qsmp-ksz9131

txmp-1570 mb7

karo-gpu

txmp-lcd-panel

txmp-ft5x06

txmp-sound

karo-rtc

txmp-1571 mb7

txmp-sdcard

karo-gpu

txmp-lcd-panel

txmp-ft5x06

txmp-sound

karo-rtc

NXP

Module Baseboard Overlays
qs8m-mq00 qsbase2

qs8m-ksz9031

qs8m-raspi-display [1]

qs8m-cam [2]

qs8m-tc358867 [3]

qs8m-mq00 qsbase4

qs8m-ksz9131

qs8m-raspi-display [1]

qs8m-tc358867 [3]

qs8m-nd00 qsbase2

qs8m-ksz9031

qs8m-raspi-display [1]

qs8m-tc358867 [3]

qs8m-nd00 qsbase4

qs8m-ksz9131

qs8m-raspi-display [1]

qs8m-tc358867 [3]

qsxm-mm60 qsbase3

qs8m-ksz9031

qsxm-pcie

qs8m-raspi-display [1]

qs8m-tc358867 [3]

qsxm-laird [4]

qsxm-mm60 qsbase4

qs8m-ksz9131

qs8m-raspi-display [1]

qs8m-tc358867 [3]

qsxp-ml81 qsbase3

qsxp-ksz9031

qsxp-pcie [5]

qsxp-raspi-display [1]

qsxp-tc358867 [3]

qsxp-laird [4]

qsxp-ml81 qsbase4

qsxp-ksz9131

qsxp-raspi-display [1]

qsxp-tc358867 [3]

tx8m-1610 mipi-mb

karo-gpu

karo-dsi83 [6]

karo-rtc

tx8m-leds

tx8m-sound

tx8m-wifi [4]

tx8m-1620 lvds-mb

karo-gpu

tx8m-1620-lvds-panel [5]

karo-rtc

tx8m-leds

tx8m-lvds-mb

tx8m-sound

tx8m-wifi [4]

tx8m-1620 mb7

karo-gpu

tx8m-1620-lvds-panel [5]

karo-mb7

karo-rtc

tx8m-ft5x06

tx8m-leds

tx8m-sound

tx8m-1622 mipi-mb

karo-gpu

karo-dsi83

karo-rtc

tx8m-leds

tx8m-sound

tx8m-wifi [4]

tx8m-nd00 mipi-mb

karo-dsi83

karo-rtc

tx8m-leds

tx8m-sound

tx8p-ml81 lvds -mb

karo-gpu

karo-lvds-panel [5]

karo-rtc

tx8p-lvds-mb

tx8p-sound

tx8p-ml81 mb7

karo-gpu

karo-lvds-panel

karo-mb7

karo-rtc

tx8p-ft5x06

tx8p-sound

tx8p-ml82 lvds-mb

karo-gpu

karo-lvds-panel

karo-rtc

tx8p-lvds-mb

tx8p-sound

tx8p-ml82 mb7

karo-gpu

karo-lvds-panel

karo-mb7

karo-rtc

tx8p-ft5x06

tx8p-sound

[1](1, 2, 3, 4, 5, 6, 7, 8) can be disabled via DISTRO_FEATURES:remove = "raspi-display"
[2]can be disabled via DISTRO_FEATURES:remove = "csi-camera"
[3](1, 2, 3, 4, 5, 6, 7, 8) can be disabled via DISTRO_FEATURES:remove = "tc358867"
[4](1, 2, 3, 4, 5) must be enabled via DISTRO_FEATURES:append = "wifi"
[5](1, 2, 3, 4) requires a display panel specific overlay (see FDT overlays for various LCD/LVDS Displays)
[6]can be disabled via DISTRO_FEATURES:remove = "dsi83"

All FDT overlays listed above contain a property named after the overlay in the node “/chosen/overlays”, which can be used to track all overlays that have been applied:

root@tx8m-1620:~# ls -1 /proc/device-tree/chosen/overlays
karo-gpu
karo-panel-tm101jvhg32
karo-rtc
karo-sound
name
tx8m-1620-lvds-panel
tx8m-leds
tx8m-lvds-mb
tx8m-sound
tx8m-wifi

Note

name in the listing above is a standard property added to each DT node containing its own name.

If a certain non-standard feature (like CAN bus, Wifi) needs to be enabled, the corresponding name of the overlay concerned should be added to the appropriate overlays_* variable.

E.g. to enable PCIe for a QSXP module on a QSBASE3 baseboard:

setenv overlays_qsbase3 ${overlays_qsbase3} qsxp-pcie
saveenv
reset

Hint

You may also use the command editenv to enter line editing mode for changing the variable.

Automatic FDT overlay loading

Upon boot U-Boot loads the default DTB file referenced in the variable fdt_file and subsequently applies any overlay listed in the variable overlays_${baseboard}. If the variable baseboard is undefined, U-Boot will use the variable overlays as list of overlays to be loaded. This process can be inhibited by pressing and holding CTRL + C during the initial boot phase (See safeboot).

FDT overlays debugging

To get a list of FDT overlays that are actually being loaded, you can set the variable debug_overlays to a logical TRUE value (‘1’,’t’,’y’).

Manually applying FDT overlays

To apply a certain FDT overlay manually, you can load it to RAM (to an address != ${fdtaddr} [e.g. ${loadaddr}]) and run the command fdt apply.
E.g.:

load mmc ${mmcdev}:${mmcpart} ${loadaddr} imx8mp-qsxp-pcie.dtb
fdt apply ${fileaddr}

Note

The variable fileaddr will have been set up appropriately by the most recent load (or tftpboot) command.

If the overlay cannot be applied due to an error, the FDT header of the original DTB and the overlay will be cleared.

HW Features

Function Description
dsi83 TI SN65DSI83 DSI LVDS converter
ft5x06 EDT FT5x06 Touchpanel Controller
imx219 Raspi Camera MIPI CSI-2 image sensor
ksz9031 Microchip KSZ9031 GigaBit Ethernet Transceiver
ksz9131 Microchip KSZ9131 GigaBit Ethernet Transceiver
laird Laird PCIe WiFi Module
lvds-panel  
mcp2515 CAN controller with SPI interface
pcie enables the PCIe subsystem of the SOC
raspi-display Raspberry Pi Touch Display
rtc  
sound  
tc358867  
wifi  
Baseboards
Module/Function mb7 mipi-mb lvds-mb qsbase2 qsbase3 qsbase4
Module  
TX8M-1610   x        
TX8M-1620 x   x      
TX8M-1622 x   x      
TX8M-ND00   x        
TX8P-ML81 x   x      
TX8P-ML82 x   x      
QS8M-MQ00       x    
QS8M-ND00       x    
QSXM-MM60         x x
QSXP-ML81         x x
Function  
backlight x x x      
dsi83   x   x x x
ft5x06 x          
imx219       x    
ksz9031       x x  
ksz9131           x
laird         x  
lvds-panel     x      
mcp2515   x x      
pcie   x x      
raspi-display       x x x
rtc x x x      
sound x x x      
stk5led x x x      
tc358867       x x  
wifi   x x      
panel-etm0700 x          
panel-etv570 x          
panel-tm101jvhg32   x x      

FDT overlays for various LCD/LVDS Displays

FDT overlay files are included in the standard yocto images for the displays most frequently used with the TX or QS modules:

Overlay name Display name Display type
karo-panel-tm101jvhg32 TM101JVGH32 LVDS
karo-panel-et0570 ETMV570G0EDHU LCD
karo-panel-etm0430 ETM0430G0EDH6 LCD
karo-panel-etm0350 ETM0350G9EDHA LCD
karo-panel-etm0700 ETM0700G0EDH6 LCD
Module Baseboard Overlays
qs8m-mq00 qsbase2 qs8m-ksz9031 qs8m-raspi-display qs8m-cam qs8m-tc358867
qs8m-mq00 qsbase4 qs8m-ksz9131 qs8m-raspi-display qs8m-tc358867
qs8m-nd00 qsbase2 qs8m-ksz9031 qs8m-raspi-display qs8m-tc358867
qs8m-nd00 qsbase4 qs8m-ksz9131 qs8m-raspi-display qs8m-tc358867
qsxm-mm60 qsbase3 qs8m-ksz9031 qsxm-pcie qs8m-raspi-display qs8m-tc358867 qsxm-laird
qsxm-mm60 qsbase4 qs8m-ksz9131 qs8m-raspi-display qs8m-tc358867
qsxp-ml81 qsbase3 qsxp-ksz9031 qsxp-pcie qsxp-raspi-display qsxp-tc358867 qsxp-laird
qsxp-ml81 qsbase4 qsxp-ksz9131 qsxp-raspi-display qsxp-tc358867
tx8m-1610 mipi-mb karo-gpu karo-dsi83 karo-rtc tx8m-leds tx8m-sound tx8m-wifi
tx8m-1620 lvds-mb karo-gpu tx8m-1620-lvds-panel karo-rtc tx8m-leds tx8m-lvds-mb tx8m-sound tx8m-wifi
tx8m-1620 mb7 karo-gpu tx8m-1620-lvds-panel karo-mb7 karo-rtc tx8m-ft5x06 tx8m-leds tx8m-sound
tx8m-1622 mipi-mb karo-gpu karo-dsi83 karo-rtc tx8m-leds tx8m-sound tx8m-wifi
tx8m-nd00 mipi-mb karo-dsi83 karo-rtc tx8m-leds tx8m-sound
tx8p-ml81 lvds-mb karo-gpu karo-lvds-panel karo-rtc tx8p-lvds-mb tx8p-sound
tx8p-ml81 mb7 karo-gpu karo-lvds-panel karo-mb7 karo-rtc tx8p-ft5x06 tx8p-sound
tx8p-ml82 lvds-mb karo-gpu karo-lvds-panel karo-rtc tx8p-lvds-mb tx8p-sound
tx8p-ml82 mb7 karo-gpu karo-lvds-panel karo-mb7 karo-rtc tx8p-ft5x06 tx8p-sound

Building FDT Overlays with Yocto

The build process is governed by the following Yocto variables:

DTB_OVERLAY_INCLUDES list of include (.dtsi) files used within the DTB overlay files to reduce code duplication for common features.
DTB_OVERLAYS_generic list of HW feature specific DTB fragments that are common to all SOC_FAMILY members and will be prefixed with ${SOC_PREFIX} (“imx8m” in this case) and suffixed with “.dtb” to get the actual file name.
DTB_OVERLAYS list of HW feature specific DTB fragments that depend on the SOC_FAMILY (imx8mm,imx8mn,imx8mp) will be prefixed with “${SOC_FAMILY}-” and suffixed with “.dtb” to get the actual file name.
KARO_BASEBOARDS list of baseboards that may be used with the ${MACHINE} that is being built.
KARO_DTB_OVERLAYS[baseboard] list of overlays, that need to be applied to the base DTB to support the HW features of the specified baseboard.

Writing Custom Overlays

General syntax of an FDT overlay file

Contrary to most documentation concerning FDT overlays found on the internet, FDT overlay files can be written just like normal .dts files without the need for special nodes (‘fragment@#’, ‘__overlay__’). These were necessary for older versions of the Device Tree Compiler that did not support creating those node automatically.

https://elinux.org/Device_Tree_Reference#Overlay_Source_Format

The major difference between a ‘normal’ .dts file and an overlay is the additional keyword ‘/plugin/’ at the top of an overlay file:

// SPDX-License-Identifier: (GPL-2.0 OR MIT)
/*
 * Copyright 2022 Lothar Waßmann <LW@KARO-electronics.de>
 *
 */

/dts-v1/;

/plugin/;

#include ...

/* reference to the root node: */
&{/} {
     ...
};

Also, it is not possible to use the ‘&’-notation outside ‘<>’ to refer to a DT path like:

/ {
        aliases {
                i2c0 = &i2c1;
        };
};

Instead, the actual target path has to be spelled out in an FDT overlay file:

&{/aliases} {
       i2c0 = &{/soc@0/bus@30800000/i2c@30a20000};
};

FDT Overlay Example

If you want to support an additional I2C device on the i2c2 interface you would create an overlay file (e.g. imx8m‑custom‑pca9554.dts) like shown below:

// SPDX-License-Identifier: (GPL-2.0 OR MIT)
/*
 * Copyright (C) 2022 ...
 *
 */

/dts-v1/;

/plugin/;

&{/chosen} {
        overlays {
              custom-pca9554;
        };
};

&i2c2 {
        gpioex: gpio-expander@20 {
                compatible = "nxp,pca9554";
                reg = <0x20>;
                gpio-controller;
                #gpio-cells = <2>;
        };
};

Note

When using overlays, every node in the FDT will have a phandle assigned to it, which may have unexpected side effects when some driver checks for the existence of a ‘phandle’-property in its FDT node. E.g. the LCD backlight driver will not automatically enable the backlight upon probing, when a ‘phandle’ property exists, but expects the LCD panel driver to have a reference on that phandle and take care of enabling the backlight.