The device tree is a data structure that describes the hardware components available on a system. The Linux kernel queries the device tree to find out which drivers to load during boot.

Device tree file types

Device tree files are located at arch/arm64/boot/dts/digi/ and can have two extensions:

  • .dtsi files are device tree source include files. They describe hardware that is common to several platforms that include these files in their .dts files.

  • .dts files are device tree source files. They describe one specific platform.

System-on-module device tree

The ConnectCore 8X is a system-on-module (SOM) solution that integrates:

  • NXP i.MX8QXP system-on-chip featuring many interfaces such as UART, CAN, SPI, and I2C

  • LPDDR4 memory

  • eMMC memory

  • PMIC chip

  • Crypto-authentication chip

  • Optional Wi-Fi + Bluetooth chip

  • Micro Controller Assist (MCA) chip

The ConnectCore 8X system-on-module needs to be soldered to a carrier board. For this reason, there is not a single .dts file for it. Instead, its hardware features are collected into .dtsi files that can be included by a final platform .dts.

Even though the ConnectCore 8X system-on-module is offered in different variants, only one .dtsi file has been defined to describe the hardware inside: ccimx8x.dtsi.

Your final platform .dts file must include this SOM include file.

Variants of the SOM are handled through the use of device tree overlays, which are explained later in this same page.

Carrier board device tree

The ConnectCore 8X SBC Pro is a carrier board assembling the ConnectCore 8X system-on-module. The carrier board assembles additional hardware like a video port, Ethernet PHY, audio chip, PCIe minicard, microSD card holder, user LEDs, and so on.

As a final platform, the carrier board has a .dts file that includes the ConnectCore 8X system-on-module .dtsi file: ccimx8x-sbc-pro.dts.

Device tree overlays

Complex embedded SoMs and carrier boards would require of multiple device tree blobs to account for the many different SoM/board variants and feature combinations.

Device tree overlays are special device tree blob fragments that allow you to override specific parts of a device tree on-the-fly in the boot loader, before booting the operating system. This allows you to combine a base device tree with optional elements, that you decide at boot time, without the need to recompile a device tree for just a tiny change.

Overlays can only perform constructive changes such as adding or modifying nodes or properties. They cannot be used to perform destructive changes such as deleting nodes or properties.

File naming conventions

Digi device tree overlay filenames follow these conventions:

  • Source files use the regular .dts extension.

  • Compiled device tree overlay blobs use the .dtbo extension.

  • Filenames follow the syntax: ov<som|board>_<functionality>[_<hardware>].dts, where

    • _ov_ identifies the file as a device tree overlay.

    • <som|board> indicates whether the overlay affects the SoM or the carrier board.

    • <functionality> indicates the specific interface enabled/affected by the overlay.

    • <hardware> optionally describes the specific hardware targeted by the overlay.

Digi device tree overlays mechanism

The Digi ConnectCore 8X carrier board has a base device tree blob with the default hardware configuration. Digi also provides a number of pre-compiled device tree overlays that enable different hardware and peripherals.

The custom Digi U-Boot dboot command does the following:

  1. Loads the base device tree (defined in variable fdt_file).

  2. Parses the contents of variable overlays (a comma-separated list of device tree overlay filenames).

  3. Sequentially loads and applies each overlay over the base device tree.

If an overlay fails to load, the boot process is aborted.

To apply an overlay to the base device tree, set the overlays variable to your device tree overlay filename. For example:

=> setenv overlays my-overlay.dtbo

You can instruct dboot to apply several device tree overlay files by separating them with commas:

=> setenv overlays my-overlay1.dtbo,my-overlay2.dtbo,my-overlay3.dtbo

Overlays on Digi Embedded Yocto boot script

Digi Embedded Yocto builds a U-Boot boot script (boot.scr) that runs automatically. The bootscript:

  1. Reads the hardware capabilities of the SOM variant, such as Wi-Fi or Bluetooth, and prepends any related device tree overlay to the overlays variable.

  2. Reads the SOM version and carrier board version and, if applicable, prepends any related device tree overlay to the overlays variable.

  3. Calls the dboot command to boot the system.

This mechanism resolves the overlays that need to be applied for the hardware detected on your ConnectCore 8X variant. From there, you may set the overlays variable to any custom (or pre-compiled) overlay you want to additionally apply for your purposes.

Pre-compiled device tree overlays

Digi Embedded Yocto provides a number of pre-compiled device tree overlays that resolve combinations of ConnectCore 8X SOM variants and hardware versions, as well as others that help test interfaces that are disabled on the default device tree due to multiplexing with other interfaces.

SOM overlays

File Description

_ov_som_bt_ccimx8x.dtbo (dts)

Enable the Bluetooth interface

_ov_som_mca-keypad_ccimx8x.dtbo (dts)

Enable the MCA keypad

_ov_som_quad_ccimx8x.dtbo (dts)

Quad-core variants of the ConnectCore 8X SOM

_ov_som_wifi_ccimx8x.dtbo (dts)

Enable the Wi-Fi interface

As described in Overlays on Digi Embedded Yocto boot script, the SOM overlays are automatically added to the list in U-Boot overlays variable by the default boot script, based on the detected SOM variant.

Carrier board overlays

File Description

_ov_board_flexcan1_ccimx8x-sbc-pro.dtbo (dts)

Enable FlexCAN1 (and change LPUART0 to use 2 wires in return)

_ov_board_gpio-watchdog_ccimx8x-sbc-pro.dtbo (dts)

Demo overlay for ConnectCore 8X SBC Pro MCA GPIO-refreshed watchdog

_ov_board_hsd101pfw2-lvds_ccimx8x-sbc-pro.dtbo (dts)

Enable Fusion 10 LVDS display support

_ov_board_lpuart3_ccimx8x-sbc-pro.dtbo (dts)

Enable LPUART3 (and disable FlexCAN3 in return)

_ov_board_lt8912-hdmi-dsi0_ccimx8x-sbc-pro.dtbo (dts)

Enable LT8912 MIPI-to-HDMI adapter board on DSI0 (and disable LVDS0 and touch screen in return)

_ov_board_lvds1_ccimx8x-sbc-pro.dtbo (dts)

Enable LVDS1

_ov_board_parallel-camera_ccimx8x-sbc-pro.dtbo (dts)

Enable parallel camera (and disable MIPI camera in return)

_ov_board_pcie-card_ccimx8x-sbc-pro.dtbo (dts)

Enable PCIe (only usable on non-Wi-Fi variants)

_ov_board_pcie-modem_ccimx8x-sbc-pro.dtbo (dts)

Enable support for PCIe modems.

_ov_board_user-leds_ccimx8x-sbc-pro.dtbo (dts)

Demo overlay for ConnectCore 8X SBC Pro user LEDs

_ov_board_v1-v3_ccimx8x-sbc-pro.dtbo (dts)

Change Goodix IRQ GPIO polarity for ConnectCore 8X SBC Pro versions 1 through 3

The default boot script automatically adds the _ov_board_v1-v3_ccimx8x-sbc-pro file to the U-Boot overlays variable list if required. See Overlays on Digi Embedded Yocto boot script for more information.