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 |
QSGLYN1 |
qsrz-g2l1 | 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 |
QSGLYN1 |
qsmp-1530 | qsbase1 qsbase2 qsbase4 |
|
qsmp-1530 | qsbase1 qsbase2 qsbase4 |
NXP
Module | Baseboards | |
---|---|---|
Shortcut | Board Name | |
tx8m-1610 | mipi-mb | TX-MIPI-LVDS Mainboard |
tx8m-1620 | mb7 lvds-mb |
|
tx8m-nd00 | mipi-mb | TX-MIPI-LVDS Mainboard |
tx8p | mb7 lvds-mb |
|
qs8m | qsbase2 qsbase4 |
|
qsxm | qsbase3 qsbase4 |
|
qsxp | 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.