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.

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 qsglyn1	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
qs93	qsbase93	QSBASE93
tx93	mb7 lvds-mb	Mainboard 7 TX-MIPI-LVDS Mainboard

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) or ${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	HW Features
qsrz-g2l[0,1]	qsbase1	karo-led karo-sdcard qsrz-lcd-panel qsrz-ft5x06 qsrz-ksz9131	Module LED Support SD Card support LCD panel support [5] EDT FT5x06 Touchpanel support KSZ9131 GBit Ethernet PHY support
qsrz-g2l[0,1]	qsglyn1	karo-led karo-sdcard qsrz-lcd-panel qsrz-ili2130 qsrz-ksz9130	Module LED Support SD Card support LCD panel support [5] I2C Touchpanel support KSZ9131 GBit Ethernet PHY support
qsrz-g2l[0,1]	qsbase4	karo-led qsrz-ksz9131	LCD panel support [5] KSZ9131 GBit Ethernet PHY support
txrz-g2l[0,1]	mb7	karo-led karo-sdcard-cd txrz-rtc txrz-lcd-panel txrz-ft5x06 txrz-sound	Module LED Support SD Card support Real Time Clock support LCD panel support [5] EDT FT5x06 Touchpanel support SGTL5000 sound chip support
txrz-g2l2	lvds-mb	karo-led karo-sdcard txrz-rtc txrz-lvds-panel txrz-sound	Module LED Support SD Card support Real Time Clock support LCD panel support [5] Module sound support

STM32

Module	Baseboard	Overlays	HW Features
qsmp-1570	qsbase1	qsmp-qsbase1 karo-gpu qsmp-lcd-panel qsmp-ft5x06 qsmp-ksz9031	QSBase 1 specific settings GPU support LCD panel support [5] EDT FT5x06 Touchpanel support KSZ9031 GBit Ethernet PHY support
qsmp-1570	qsglyn1	qsmp-qsglyn1 karo-gpu qsmp-lcd-panel qsmp-ft5x06 qsmp-ksz9031	QSGlyn 1 specific settings GPU support LCD panel support [5] EDT FT5x06 Touchpanel support KSZ9031 GBit Ethernet PHY support
qsmp-1570	qsbase2	qsmp-qsbase2 qsmp-ksz9031 karo-gpu	QSBase 2 specific settings KSZ9031 GBit Ethernet PHY support GPU support
qsmp-1570	qsbase4	qsmp-qsbase4 qsmp-ksz9131 karo-gpu	QSBase 4 specific settings KSZ9131 GBit Ethernet PHY support GPU support
qsmp-1530	qsbase1	qsmp-qsbase1 qsmp-lcd-panel qsmp-ft5x06 qsmp-ksz9031	QSBase 1 specific settings LCD panel support [5] EDT FT5x06 Touchpanel support KSZ9031 GBit Ethernet PHY support
qsmp-1530	qsbase4	qsmp-qsbase4 qsmp-ksz9131	QSBase 4 specific settings KSZ9131 GBit Ethernet PHY support
txmp-1570	mb7	karo-gpu txmp-lcd-panel txmp-ft5x06 txmp-sound karo-rtc	GPU support LCD panel support [5] EDT FT5x06 Touchpanel support SGTL5000 sound chip support MCP7940/DS1339 RTC support
txmp-1571	mb7	txmp-sdcard karo-gpu txmp-lcd-panel txmp-ft5x06 txmp-sound karo-rtc	SD Card support GPU support LCD panel support [5] EDT FT5x06 Touchpanel support SGTL5000 sound chip support MCP7940/DS1339 RTC support

NXP

Module	Baseboard	Overlays	HW Features
qs93-5210	qsbase93	karo-copro [7] karo-gpu qs93-eqos-lan8710 qs93-fec-lan8710 qs93-qsbase93	Coprocessor Support GPU support 100 MBit Ethernet PHY 100 MBit Ethernet PHY QSBASE93 specific settings
tx93-5210	lvds-mb	karo-copro [7] karo-gpu karo-lvds-mb karo-lvds-panel karo-panel-tm101jvhg32 karo-rtc	Coprocessor Support GPU Support LCD panel support [5] TM10JVHG32 Panel MCP7940/DS1339 RTC support
tx93-5210	mb7	karo-copro [7] karo-gpu karo-lcd-panel karo-mb7 karo-rtc tx93-ft5x06 tx93-ili2130 tx93-sound	Coprocessor Support GPU Support LCD panel support [5] MB7 specific settings MCP7940/DS1339 RTC support EDT FT5x06 Touchpanel Controller I2C Touchpanel support SGTL5000 sound chip support
qs8m-mq00	qsbase2	qs8m-ksz9031 qs8m-raspi-display [1] qs8m-cam [2] qs8m-tc358867 [3]	KSZ9031 GBit Ethernet PHY support Raspberry Pi Touch Display CSI Camera Support Toshiba TC358867 MIPI->RGB Bridge support
qs8m-mq00	qsbase4	qs8m-ksz9131 qs8m-raspi-display [1] qs8m-tc358867 [3]	KSZ9131 GBit Ethernet PHY support Raspberry Pi Touch Display Toshiba TC358867 MIPI->RGB Bridge support
qs8m-nd00	qsbase2	qs8m-ksz9031 qs8m-raspi-display [1] qs8m-tc358867 [3]	KSZ9031 GBit Ethernet PHY support Raspberry Pi Touch Display Toshiba TC358867 MIPI->RGB Bridge support
qs8m-nd00	qsbase4	qs8m-ksz9131 qs8m-raspi-display [1] qs8m-tc358867 [3]	KSZ9131 GBit Ethernet PHY support Raspberry Pi Touch Display Toshiba TC358867 MIPI->RGB Bridge support
qsxm-mm60	qsbase3	qs8m-ksz9031 qsxm-pcie qs8m-raspi-display [1] qs8m-tc358867 [3] qsxm-laird [4]	KSZ9031 GBit Ethernet PHY support PCIe Slot support Raspberry Pi Touch Display Toshiba TC358867 MIPI->RGB Bridge support Laird PCIe WiFi Module support
qsxm-mm60	qsbase4	qs8m-ksz9131 qs8m-raspi-display [1] qs8m-tc358867 [3]	KSZ9131 GBit Ethernet PHY support Raspberry Pi Touch Display support Toshiba TC358867 MIPI->RGB Bridge support
qsxp-ml81	qsbase3	qsxp-ksz9031 qsxp-pcie [5] qsxp-raspi-display [1] qsxp-tc358867 [3] qsxp-laird [4]	KSZ9031 GBit Ethernet PHY support PCIe Slot support Raspberry Pi Touch Display support Toshiba TC358867 MIPI->RGB Bridge support Laird PCIe WiFi Module support
qsxp-ml81	qsbase4	qsxp-ksz9131 qsxp-raspi-display [1] qsxp-tc358867 [3]	KSZ9131 GBit Ethernet PHY support Raspberry Pi Touch Display support Toshiba TC358867 MIPI->RGB Bridge support
tx8m-1610	mipi-mb	karo-gpu karo-dsi83 [6] karo-rtc tx8m-leds tx8m-sound tx8m-wifi [4]	GPU Support DSI83 MIPI->LVDS Bridge support MCP7940/DS1339 RTC support module LED support SGTL5000 sound chip support Laird PCIe WiFi Module support
tx8m-1620	lvds-mb	karo-gpu tx8m-1620-lvds-panel [5] karo-rtc tx8m-leds tx8m-lvds-mb tx8m-sound tx8m-wifi [4]	GPU Support Karo 1620 lvds panel MCP7940/DS1339 RTC support module LED support LVDS specific settings SGTL5000 sound chip support Laird PCIe WiFi Module
tx8m-1620	mb7	karo-gpu tx8m-1620-lvds-panel [5] karo-mb7 karo-rtc tx8m-ft5x06 tx8m-leds tx8m-sound	GPU Support LVDS Panel Support MB7 specific settings MCP7940/DS1339 RTC support EDT FT5x06 Touchpanel support Module LED Support SGTL5000 sound chip support
tx8m-1622	mipi-mb	karo-gpu karo-dsi83 karo-rtc tx8m-leds tx8m-sound tx8m-wifi [4]	GPU Support DSI83 MIPI->LVDS Bridge support MCP7940/DS1339 RTC support module LED support SGTL5000 sound chip support Laird PCIe WiFi Module
tx8m-nd00	mipi-mb	karo-dsi83 karo-rtc tx8m-leds tx8m-sound	DSI83 MIPI->LVDS Bridge support MCP7940/DS1339 RTC support module LED support SGTL5000 sound chip support
tx8p-ml81	lvds -mb	karo-gpu karo-lvds-panel [5] karo-rtc tx8p-lvds-mb tx8p-sound	GPU support LVDS panel support MCP7940/DS1339 RTC support LVDS specific settings SGTL5000 sound chip support
tx8p-ml81	mb7	karo-gpu karo-lvds-panel [5] karo-mb7 karo-rtc tx8p-ft5x06 tx8p-sound	GPU Support LVDS panel support MB7 specific settings MCP7940/DS1339 RTC support EDT FT5x06 Touchpanel support SGTL5000 sound chip support
tx8p-ml82	lvds-mb	karo-gpu karo-lvds-panel [5] karo-rtc tx8p-lvds-mb tx8p-sound	GPU Support LVDS panel support MCP7940/DS1339 RTC support LVDS specific settings SGTL5000 sound chip support
tx8p-ml82	mb7	karo-gpu karo-lvds-panel [5] karo-mb7 karo-rtc tx8p-ft5x06 tx8p-sound	GPU Support LVDS Panel support MB7 specific settings MCP7940/DS1339 RTC support EDT FT5x06 Touchpanel support SGTL5000 sound chip support

[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,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19)

requires a display panel specific overlay (see FDT overlays for various LCD/LVDS Displays)

[6]

can be disabled via DISTRO_FEATURES:remove = "dsi83"

[7] (1,2,3)

can be disabled via DISTRO_FEATURES:remove = "copro"

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	Raspberry Pi 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	Toshiba TC358867 MIPI->RGB Bridge
wifi

	Baseboards
Module/Function	mb7	mipi-mb	lvds-mb	qsbase2	qsbase3	qsbase4	qsbase93
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
QS93-5210							x
TX93-5210	x		x
Function
backlight	x	x	x
dsi83		x		x	x	x
eqos-lan-8710							x
fec-lan-8710							x
ft5x06	x
imx219				x			x
ili2130							x
ksz9031				x	x		x
ksz9131						x
laird					x
lvds-panel			x				x
mcp2515		x	x
pcie		x	x
panel-etm0700	x
panel-etv570	x
panel-tm101jvhg32		x	x				x
raspi-display				x	x	x
rtc	x	x	x
sound	x	x	x
stk5led	x	x	x
spidev							x
tc358867				x	x
wifi		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
qs93-5210	qsbase93	karo-copro karo-gpu qs93-eqos-lan8710 qs93-fec-lan8710
tx93-5210	mb7	karo-copro karo-gpu karo-lcd-panel karo-mb7 karo-rtc tx93-ft5x06 tx93-ili2130 tx93-sound
tx93-5210	lvds-mb	karo-copro karo-gpu karo-lvds-mb karo-lvds-panel karo-panel-tm101jvhg32 karo-rtc
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

The property added to the /chosen/overlays node should reflect the name of the overlay, so that listing /proc/device-tree/chosen/overlays in the running system will show which overlays have been loaded.

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. When using overlays, each node in the FDT will have a phandle associated to it, which may have unexpected side effects when some drivers check for the existence of a ‘phandle’ property in their FDT node.

For example, the LCD backlight driver assumes, that an LCD panel driver has a reference to the backlight when it finds a ‘phandle’ property in its device node. Therefore it will not turn on the backlight in the driver’s probe() function, expecting the LCD panel driver to do so.

Adding overlays for a custom baseboard

When adding a custom baseboard, the following yocto veriables need to be adjusted appropriately:

KARO_BASEBOARDS:append = "custom-baseboard"
KARO_DTB_OVERLAYS[custom-baseboard] = "<list of applicable overlays>"

The list of overlays can be copied from an existing baseboard (e.g. ‘qsbase3’) like:

KARO_DTB_OVERLAYS[custom-baseboard] = "${@ d.getVarFlag('KARO_DTB_OVERLAYS', 'qsbase3', True)}"

You may further augment the list of overlays for custom-baseboard with:

KARO_DTB_OVERLAYS[custom-baseboard] += "my-overlay [...]"