Linux Device Tree support

The modern linux kernel uses a system called 'devicetree' to describe hardware in a consistent fashion to avoid needing custom 'board support' files for boards.

Typically the bootloader will pass a 'flattened device tree' (a compiled binary representation of a device-tree) to the kernel so that the kernel can configure all the components on the board.

The Gateworks Ventana product family based off the Freescale i.MX6 CPU, uses devicetree (with the exception of the early Yocto 1.3 and Android jellybean BSP's which were based on a 3.0.35 non-device-tree kernel)

Device Tree Terminology

• dts - Board level definitions
• dtsi - SoC level definitions
• dtb - Binary blob of device tree loaded by bootloader

Example Device Tree File

You can find the device tree files in arch/arm/boot/dts

For an example, see here: ​https://github.com/Gateworks/linux-imx6/blob/gateworks_3.10.53_1.1.0_ga/arch/arm/boot/dts/imx6qdl-gw54xx.dtsi

Accessing Device Tree from the Bootloader

The Ventana u-boot has fdt support enabled and uses this through default bootscripts to load an fdt (based on the board model) from the filesystem of the boot media. The bootloader then modifies the devicetree to disable components that are possible on the board, but perhaps not loaded on the bill-of-materials (for example, a Gateworks Special build).

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

Examples:

• display the fdt of a Ventana board (loaded from NAND flash ubifs):

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

• disable PCI via device-tree:

  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 the Ventana bootloader has a fixfdt script that can make integrating fixups like this into the boot process easy. See here for details.

Accessing Device Tree from Linux

If the kernel is configured with CONFIG_PROC_DEVICETREE (which the Ventana OpenWrt BSP does configure) and procfs is enabled, 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.

Examples:

• show board model:

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

• show board serialnumber

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

• 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)
  

• Print the whole device tree:

  find /proc/device-tree/
  

Specifying the Device Tree Used

The bootloader is responsible for loading the device-tree blob (DTB) and executing the kernel The Gateworks ventana bootloader in a way that it knows where the DTB is loaded.

Therefore, its the bootloader that decides which DTB to load and from where.

See ventana/bootloader for details on how the DTB filename is chosen and loaded.

Adding New Devices to the Device Tree

For customers interested in adding a new device to an existing controller, see the SPI wiki page for an example of the process.

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

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

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