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

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

You are not able to set a display-overlay for our STM modules, refer to STM display setting.

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

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 [...]"