10.8. Device Tree

A Device Tree is a data structure that is used to describe properties of non-discoverable hardware instead of hardcoding them in the kernel. The device tree data is generally stored in a .dts or a Device Tree Source (DTS) file. This file is then compiled into a binary format called Device Tree Blob (DTB) with .dtb extension. RTEMS preferably uses a DTB built from the FreeBSD source tree matching the freebsd-org HEAD commit hash in libBSD.

10.8.1. Building the DTB

A single DTB file can be built using the dtc tool in libfdt using the following command:

dtc -@ -I dts -O dtb -o my-devicetree.dtb my-devicetree.dts

For building the DTB from the FreeBSD source, the make_dtb.sh script from freebsd/sys/tools/fdt must be used as most of the DTS files in FreeBSD have included .dtsi files from their source tree. An example is given below as a reference for how to build the device tree from the FreeBSD source.

NOTE: The following example uses FreeBSD master branch from github mirror as an example. It is advised to always use the source from the commit matching the freebsd-org HEAD in libBSD.

 1  #We're using the script from freebsd/sys/tools/make_dtb.sh
 2  #Target device: Beaglebone Black.
 3  #Architecture: Arm.
 4  #DTS source name: am335x-boneblack.dts
 5
 6  #The make_dtb.sh script uses environment variable MACHINE
 7  export MACHINE='arm'
 8
 9  SCRIPT_DIR=$HOME/freebsd/sys/tools/fdt
10
11  #The arguments to the script are
12  # $1 -> Build Tree (This is the path to freebsd/sys/ directory)
13  # $2 -> DTS source file
14  # $3 -> output path of the DTB file
15
16  ${SCRIPT_DIR}/make_dtb.sh ${SCRIPT_DIR}/../../ \
17  ${SCRIPT_DIR}/../../gnu/dts/arm/am335x-boneblack.dts \
18  $(pwd)

10.8.2. Using Device Tree Overlay

Device tree overlay is used either to add properties or devices to the existing device tree. Adding any property to DTS using an overlay will override the current values in the DTB. The Overlays enable us to modify the device tree using a small maintainable plugin without having to edit the whole Base Tree.

There are two ways of applying an overlay on top of the built DTB.

  1. Use fdtoverlay from libfdt

  2. Add the overlay in the root partition of the SD card and apply it using U-Boot

The fdtoverlay command can be used as follows:

fdtoverlay -i my-base-tree.dtb -o output-tree.dtb my-overlay.dtbo

To apply it from U-Boot during system initialization we have to add the device tree overlay file in the root directory of the SD card and use U-Boot commands to apply the overlay.

Below is given the series of U-Boot commands that can be used to apply the overlay, given that the overlay blob (.dtbo) file is already in the card.

fatload mmc 0:1 0x80800000 rtems-app.img
fatload mmc 0:1 0x88000000 my-base-tree.dtb
fdt addr 0x88000000
fatload mmc 0:1 0x88100000 my-overlay.dtbo
fdt resize 0x1000
fdt apply 0x88100000
bootm 0x80800000-0x88000000