Device Tree

The modern linux kernel as well as the modern U-Boot bootloader use a system called 'devicetree' to describe hardware in a consistent fashion to avoid needing custom 'board support' files (compiled code) for boards.

For a device-tree controlled U-Boot (newport/venice) the Secondary Program Loader (SPL) is in charge of choosing a dtb (flattened device tree binary) to pass to U-Boot.

For a device-tree controlled Linux kernel the bootloader will load a dtb, modify it where necessary, and pass it to Linux.

Because board specific details such as memory size, MAC addresses and serial numbers are relied to the kernel via device-tree the bootloader will modify the device-tree with these details before passing it to the kernel.

Device Tree Terminology

The following terminology is commonly used:

• dt - device tree
• fdt - Flattened device tree (binary image)
• dtc - device tree compiler (the tool used to compile and de-compile device-tree)

The following file extensions are typically used:

• dts - Board level definitions
• dtsi - SoC level definitions
• dtb - Binary blob of device tree loaded by bootloader
• dtbo - Binary blob of device tree overlay (aka fragment) loaded and applied by bootloader

Example Device Tree File

Device tree files exist in:

• Linux kernel tree:
  • arch/arm/boot/dts for 32bit ARM
  • arch/arm64/boot/dts for 64bit ARM
• U-Boot bootloader:
  • arch/arm/dts for ARM

For Gateworks Kernels:

• Venice: ​arch/arm64/boot/dts/freescale imx8*-venice-*.dts*
• Newport: ​dts-newport gw*.dts* (Note Newport dt source is not in the Mainline Linux kernel)
• Ventana: ​arch/arm/boot/dts imx6*-gw-*.dts*

Accessing devicetree from the Bootloader

The U-Boot bootloader is responsible for Loading a device-tree, making any adjustments necessary, and passing it to the kernel.

If desired you can use the ftd U-boot command to access/modify the devicetree before the kernel is booted.

Examples:

• Ventana: display the fdt on a NAND flash board:

  setenv fsload 'ubifsload'
  ubi part rootfs && ubifsmount ubi0:rootfs
  run loadfdt && fdt addr ${fdt_addr} && fdt boardsetup
  fdt print
  

• Ventana: disable PCI via fixfdt script:

  setenv fsload 'ubifsload'
  ubi part rootfs && ubifsmount ubi0:rootfs
  run loadfdt && fdt addr ${fdt_addr} && fdt boardsetup
  fdt resize
  fdt set /soc/pcie@0x01000000 status disabled
  

Note some bootloader environments such as Ventana and Venice call a fixfdt script that can make integrating fixups like this into the boot process easy. See here for details.

Note also that some bootloader environments such as Venice offer dt overlay support where the bootloader can apply overlays to a dt to alter it before passing it to the kernel. In the case of venice you can set the fdt_overlay env variable to a list of files to load and apply as an overlay to modify the base fdt which is typically used for adding features from an add-on board like a display or camera.

Accessing devicetree from Linux

If the kernel is configured with CONFIG_PROC_DEVICETREE and procfs is enabled (both are enabled on Gateworks default kernels), you can access the devicetree via /proc/device-tree. This can be useful to obtain information about the board that the bootloader configured, such as board model and serial number.

Additionally the /sys/firmware/devicetree/base sysfs file represents the binary devicetree which you can use with the device tree compiler.

Examples:

• show board model:

  echo $(cat /proc/device-tree/board)
  

• show board serialnumber

  echo $(cat /proc/device-tree/serial-number)
  

• show devicetree compatible node (this describes which device-tree was used as there is one per base-board design):

  echo $(cat /proc/device-tree/compatible)
  

• show chosen bootargs (the bootargs passed in by the bootloader, same as /proc/cmdline):

  echo $(cat /proc/device-tree/chosen/bootargs)
  

Device Tree Overlays (aka Fragments)

The device-tree compiler and the U-Boot bootloader support the concept of applying changes to a base device-tree to make it easy to implement add-on boards such as a touchscreen display or camera that require dt bindings.

Some specific requirements:

• requires '/plugin/' specified
• requires '&{/} { compatible };' node that specifies the board this fragment is compatible with
• requires using handles of nodes that are defined in the base devicetree
• requires compiling with the-@ flag

To provide a simple example consider adding a simple SPI NOR flash device on an off-board SPI connector. Such a device has a Linux kernel driver and requires using device-tree bindings:

/dts-v1/;
/plugin/;

&{/} {
        compatible = "gw,imx8mm-gw73xx-0x", "fsl,imx8mm";
};

/* off-board header */
&ecspi2 {
       flash@0 {
               compatible = "spansion,m25p128", "jedec,spi-nor";
               spi-max-frequency = <30000000>;
               reg = <0>;
               #address-cells = <1>;
               #size-cells = <1>;
               m25p,fast-read;

               partition@0 {
                       label = "data";
                       reg = <0x0 0x1000000>;
               };
       };
};

• Note the compatible string specifies the board this is compatible with
• Note the board in question's base dt specifies the ecspi2 handle which we modify here

To compile this fragment:

dtc -@ -I dts -O dtb -o imx8mm-gw73xx-0x-spinor.dtbo imx8mm-gw73xx-0x-spinor.dts

And to use it on a Venice imx8mm-gw73xx-0x make sure the dtbo exits alongside the kernel in the directory the bootscript resides (ie /boot)

setenv fdt_overlays "imx8mm-gw73xx-0x-spinor.dtbo"
saveenv

Notes:

• Support for compiling dtbo files appeared in the Linux kernel somewhere between 5.10 and 5.15
• Gateworks uses dtbo's to provide support for adding a RaspberryPi v2.0 camera module and a RaspberryPi DFROBOT touchscreen display to a gw72xx/gw73xx baseboard for example.

Gateworks Product family notes

Venice

For Venice:

• U-Boot is controlled by device-tree, the DTB used is decided upon by the SPL based on EEPROM contents describing the board model, exists in a FIT image along with the ARM Trusted Firmware (ATF) and U-Boot proper and is specified by a 'DTB' banner before the SPL boots U-Boot proper.
• The Linux device-tree comes from the kernel source tree (arch/arm64/boot/dts/freescale) and is loaded and modified by the bootloader. The loadfdt script is used to load the device-tree blob (dtb) and will attempt to load several board dtb files starting with the most specific names possible including board PCB revisions and ending with a generic file represending the baseboard.
• A list of optional files specified by fdt_overlays will be loaded and applied as overlays and if defined fixfdt will be run as well.

Newport

For Newport:

• U-Boot is controlled by device-tree, the dtb used is loaded by BDK from the embedded FATFS based on the model from the board EEPROM.
• DTS source files are in the ​dts-newport repo and built by the BSP Makefile and populated in the FATFS
• The bootscript uses the U-Boot 'live' device-tree used by U-Boot for Linux as well (by passing the bootm command '$fdtcontroladdr'). This is not required and if needed you could load your own dtb and pass the address instead however note that the DTS files for CN80xx do not exist in the kernel tree.

Ventana

For Ventana:

• The latest Gateworks gateworks_v2017.05 U-Boot is not controlled by device tree and instead board support in U-Boot is handled by code based off the board model from the EEPROM
• DTS source files are in the Linux kernel in the arch/arm/boot/dts directory and placed with the kernel uImage in the same directory as the bootscript in the root filesystem (ie /boot)
• The bootloader loadfdt script is used to load the device-tree blob (dtb) in all standard boot cases for the Gateworks bootloader. This script attempts to load a dtb three times, each time with a more generic filename (from the fdt_file, fdt_file1, and fdt_file2) env variable which if not set (overridden) will get set per the board model defined in the Gateworks EEPROM. For example a GW5400-C would have the following:

  Ventana >  print fdt_file
  fdt_file=imx6q-gw5400-c.dtb
  Ventana >  print fdt_file1
  fdt_file1=imx6q-gw5400.dtb
  Ventana >  print fdt_file2
  fdt_file2=imx6q-gw54xx.dtb
  

Laguna

The Laguna bootloader and Linux kernel do not use device-tree for board configuration.

Adding New Devices to the Device Tree

For customers interested in adding a new device to a board's device-tree (for example something connected to an off-board header) see the following examples:

• SPI

Device Tree Compiler

Compiling the Device Tree

If you need to change the device-tree you can easily compile it on a Linux system using the dtc app from the device-tree-compiler package:

apt-get install device-tree-compiler
dtc -O dtb -o imx6dl-gw51xx.dtb imqx6dl-gw51xx.dts

De-Compiling the Device Tree

You can also de-compile a dtb back to a dts:

dtc -I dtb -O dts imx6dl-gw51xx.dtb > imx6dl-gw51xx.dts

You can also decompile the device tree of a running system:

dtc -I fs -O dts /sys/firmware/devicetree/base > MySBC.dts