.. |br| raw:: html
.. |nbsp| unicode:: U+00A0 .. non-breaking space
:trim:
.. _uboot-fdt-overlays-short:
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**
.. list-table::
:header-rows: 2
* - Module
- Baseboards
-
* -
- Shortcut
- Board Name
* - txrz-g2l0
- mb7
- :ref:`Mainboard 7 `
* - txrz-g2l1
- mb7
- :ref:`Mainboard 7 `
* - txrz-g2l2
- lvds-mb
- :ref:`TX-MIPI-LVDS Mainboard `
* - qsrz-g2l0
- qsbase1
qsbase2
qsbase4
qsglyn1
- :ref:`QSBASE1 `
:ref:`QSBASE2 `
:ref:`QSBASE4 `
QSGLYN1
* - qsrz-g2l1
- qsbase1
qsbase2
qsbase4
- :ref:`QSBASE1 `
:ref:`QSBASE2 `
:ref:`QSBASE4 `
**STM32**
.. list-table::
:header-rows: 2
* - Module
- Baseboards
-
* -
- Shortcut
- Board Name
* - txmp-1570
- mb7
- :ref:`Mainboard 7 `
* - txmp-1571
- mb7
- :ref:`Mainboard 7 `
* - qsmp-1570
- qsbase1
qsbase2
qsbase4
qsglyn1
- :ref:`QSBASE1 `
:ref:`QSBASE2 `
:ref:`QSBASE4 `
QSGLYN1
* - qsmp-1530
- qsbase1
qsbase2
qsbase4
- :ref:`QSBASE1 `
:ref:`QSBASE2 `
:ref:`QSBASE4 `
* - qsmp-1530
- qsbase1
qsbase2
qsbase4
- :ref:`QSBASE1 `
:ref:`QSBASE2 `
:ref:`QSBASE4 `
**NXP**
.. list-table::
:header-rows: 2
* - Module
- Baseboards
-
* -
- Shortcut
- Board Name
* - tx8m-1610
- mipi-mb
- :ref:`TX-MIPI-LVDS Mainboard `
* - tx8m-1620
- mb7
lvds-mb
- :ref:`Mainboard 7 `
:ref:`TX-MIPI-LVDS Mainboard `
* - tx8m-nd00
- mipi-mb
- :ref:`TX-MIPI-LVDS Mainboard `
* - tx8p
- mb7
lvds-mb
- :ref:`Mainboard 7 `
:ref:`TX-MIPI-LVDS Mainboard `
* - qs8m
- qsbase2
qsbase4
- :ref:`QSBASE2 `
:ref:`QSBASE4 `
* - qsxm
- qsbase3
qsbase4
- :ref:`QSBASE3 `
:ref:`QSBASE4 `
* - qsxp
- qsbase3
qsbase4
- :ref:`QSBASE3 `
:ref:`QSBASE4 `
* - qs93
- qsbase93
- :ref:`QSBASE93 `
* - tx93
- mb7
lvds-mb
- :ref:`Mainboard 7 `
:ref:`TX-MIPI-LVDS Mainboard `
Overlay Filenames
~~~~~~~~~~~~~~~~~
The file names of the FDT overlays are constructed according to the
following scheme:
**({SOC_FAMILY}|${SOC_PREFIX})**-``\ **.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**
.. list-table::
:header-rows: 1
:widths: 8 8 15 35
* - 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**
.. list-table::
:header-rows: 1
:widths: 8 8 15 35
* - 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**
.. list-table::
:header-rows: 1
:widths: 8 8 15 35
* - 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
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
CSI Camera Support
:ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge support
* - qs8m-mq00
- qsbase4
- qs8m-ksz9131
qs8m-raspi-display [1]_
qs8m-tc358867 [3]_
- KSZ9131 GBit Ethernet PHY support
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
:ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge support
* - qs8m-nd00
- qsbase2
- qs8m-ksz9031
qs8m-raspi-display [1]_
qs8m-tc358867 [3]_
- KSZ9031 GBit Ethernet PHY support
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
:ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge support
* - qs8m-nd00
- qsbase4
- qs8m-ksz9131
qs8m-raspi-display [1]_
qs8m-tc358867 [3]_
- KSZ9131 GBit Ethernet PHY support
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
:ref:`software-documentation/display-guide/display-guide: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
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
:ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge support
:ref:`software-documentation/wifi/wifi:Laird PCIe WiFi Module` support
* - qsxm-mm60
- qsbase4
- qs8m-ksz9131
qs8m-raspi-display [1]_
qs8m-tc358867 [3]_
- KSZ9131 GBit Ethernet PHY support
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display` support
:ref:`software-documentation/display-guide/display-guide: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
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display` support
:ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge support
:ref:`software-documentation/wifi/wifi:Laird PCIe WiFi Module` support
* - qsxp-ml81
- qsbase4
- qsxp-ksz9131
qsxp-raspi-display [1]_
qsxp-tc358867 [3]_
- KSZ9131 GBit Ethernet PHY support
:ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display` support
:ref:`software-documentation/display-guide/display-guide: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
:ref:`DSI83 ` MIPI->LVDS Bridge support
MCP7940/DS1339 RTC support
module LED support
SGTL5000 sound chip support
:ref:`software-documentation/wifi/wifi: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
:ref:`software-documentation/wifi/wifi: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
:ref:`DSI83 ` MIPI->LVDS Bridge support
MCP7940/DS1339 RTC support
module LED support
SGTL5000 sound chip support
:ref:`software-documentation/wifi/wifi:Laird PCIe WiFi Module`
* - tx8m-nd00
- mipi-mb
- karo-dsi83
karo-rtc
tx8m-leds
tx8m-sound
- :ref:`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] can be disabled via ``DISTRO_FEATURES:remove = "raspi-display"``
.. [2] can be disabled via ``DISTRO_FEATURES:remove = "csi-camera"``
.. [3] can be disabled via ``DISTRO_FEATURES:remove = "tc358867"``
.. [4] must be enabled via ``DISTRO_FEATURES:append = "wifi"``
.. [5] requires a display panel specific overlay (see `FDT overlays for various LCD/LVDS Displays`_)
.. [6] can be disabled via ``DISTRO_FEATURES:remove = "dsi83"``
.. [7] 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:
.. code-block:: text
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:
.. prompt::
:prompts: U-Boot>
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 :kbd:`CTRL` + :kbd:`C`
during the initial boot phase (See :ref:`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 |nbsp| ('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``. |br| E.g.:
.. prompt::
:prompts: U-Boot>
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
-----------
.. list-table::
:header-rows: 1
* - Function
- Description
* - dsi83
- TI SN65DSI83 DSI LVDS converter
* - ft5x06
- EDT FT5x06 Touchpanel Controller
* - imx219
- :ref:`yocto-guide/nxp/build:Raspberry Pi Camera` MIPI CSI-2 image sensor
* - ksz9031
- Microchip KSZ9031 GigaBit Ethernet Transceiver
* - ksz9131
- Microchip KSZ9131 GigaBit Ethernet Transceiver
* - laird
- :ref:`software-documentation/wifi/wifi:Laird PCIe WiFi Module`
* - lvds-panel
-
* - mcp2515
- CAN controller with SPI interface
* - pcie
- enables the PCIe subsystem of the SOC
* - raspi-display
- :ref:`software-documentation/display-guide/display-guide:Raspberry Pi Touch Display`
* - rtc
-
* - sound
-
* - tc358867
- :ref:`software-documentation/display-guide/display-guide:Toshiba TC358867` MIPI->RGB Bridge
* - wifi
-
.. table::
:header-alignment: left center center center center center center center
:column-alignment: left center center center center center center center
:column-dividers: none single single single single single single single none
================= ======== ======== ========== ======= ======= ======= ========
\ 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:
.. list-table::
* - Overlay name
- Display name
- Display type
* - karo-panel-tm101jvhg32
- `TM101JVGH32 `_
- LVDS
* - karo-panel-et0570
- :ref:`ETMV570G0EDHU `
- LCD
* - karo-panel-etm0430
- `ETM0430G0EDH6 `_
- LCD
* - karo-panel-etm0350
- `ETM0350G9EDHA `_
- LCD
* - karo-panel-etm0700
- `ETM0700G0EDH6 `_
- LCD
.. table::
:widths: 8 8 50
========= ========== ========
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:
.. list-table::
:widths: 30 70
* - 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
*
*/
/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
~~~~~~~~~~~~~~~~~~~
.. |hyp| unicode:: U+2011 .. non-breaking hyphen
:trim:
If you want to support an additional I\ :sup:`2`\ C device on the **i2c2**
interface you would create an overlay file
(e.g. imx8m\ |hyp|\ custom\ |hyp|\ 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>;
};
};
.. |slash| unicode:: U+2060 / .. non-breaking slash
:trim:
.. 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] = ""
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 [...]"
.. _Overlay-Syntax: https://elinux.org/Device_Tree_Reference