.. |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