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 I²C 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.