Device Tree description

The Device Tree (DT for short) is a data structure used in the Linux kernel for describing hardware. It contains a structured description of the peripherals available to the system, and their mapping to the hardware platform.

The DT is described in .dts files, which are later compiled using the dtc tool (Device Tree Compiler) into .dtb files (Device Tree Blob) which can be interpreted by the bootloader.

By modifying the default DT, additional peripherals can be made available to the kernel, unneeded peripherals can be removed, or existing peripherals can be remapped.

Modifying the Device Tree

We will now review the process needed to apply a modification to the DT and export it to our DevelBoard BSP local repository.

It is recommended to follow the first 4 steps in the kernel guide in order to have a working environment as a starting point.

Modifying the source

In the Linux kernel, the .dts files are available in the arch/XXX/boot/dts folder, where XXX is the architecture identifier (in our case, arm).

Modifying the DT is a simple matter of changing the .dts file relative to the board that we want to use. For DevelBoard, this file is at91-sama5d4_xplained.dts.

Creating the patch

After changing the kernel, we need to create a patch to put in our DevelBoard BSP repository, so that the changes can be seen by buildroot while compiling the mainstream kernel (by applying our patch).

Note: remember that before modifying the kernel, it is necessary to align it with the status of the BSP, by first applying all the patches provided in the BSP repository.

Once you have modified everything you need, you must first commit the changes:

$ git commit -m"Modified DTS" at91-sama5d4_xplained.dts

At this point, you need to generate the patch relative to the same tag used by the DevelBoard BSP (in our kernel example, linux4sam_4.7). This is done by using the git format-patch command:

$ cd <linux4sam_dir>
$ git format-patch -N linux4sam_4.7

The result should be something like:

$ git format-patch -N linux4sam_4.7
0001-Added-DevelBoard-config.patch
0002-add-macb1-ethernet.patch
0003-enable-usart2.patch
0004-mux-mmc0-pins.patch
0005-disable-unused-peripherals.patch
0006-pinctrl-at91-add-support-for-output-config.patch
0007-config-heartbeat-led.patch
0008-support-wl18xx-wifi-on-at91-sama5d4-board.patch
0009-configure-internal-eeprom-at24mac402.patch
0010-add-spi1-and-spi2-device-tree-nodes.patch
0011-add-i2c1-device-tree-node.patch
0012-Modified-DTS.patch

This is a list of all the patches applied since the linux4sam_4.7 tag. In particular, the first and the last patches are specific to our repository, while the other ones are those provided by the BSP.

Applying the patch

To import the changes in the BSP repository, simply copy the patch to the buildroot/board/develer/develboard/linux-linux4sam_4.7-patches folder, using the correct numbering format and order:

$ cp 0012-Modified-DTS.patch <bsp_dir>/buildroot/board/develer/develboard/linux-linux4sam_4.7-patches/linux-linux4sam_4.7-0011-Modified-DTS.patch

Note the fact that the numbering is different in the destination folder, since in our kernel we previously added a commit for the configuration file. In the patches folder, the numbering should be consistent with the patch ordering.

In this example, the above folder, after the inclusion of the new patch, will look like this:

linux-linux4sam_4.7-0001-add-macb1-ethernet.patch
linux-linux4sam_4.7-0002-enable-usart2.patch
linux-linux4sam_4.7-0003-mux-mmc0-pins.patch
linux-linux4sam_4.7-0004-disable-unused-peripherals.patch
linux-linux4sam_4.7-0005-pinctrl-at91-add-support-for-output-config.patch
linux-linux4sam_4.7-0006-config-heartbeat-led.patch
linux-linux4sam_4.7-0007-support-wl18xx-wifi-on-at91-sama5d4-board.patch
linux-linux4sam_4.7-0008-configure-internal-eeprom-at24mac402.patch
linux-linux4sam_4.7-0009-add-spi1-and-spi2-device-tree-nodes.patch
linux-linux4sam_4.7-0010-add-i2c1-device-tree-node.patch
linux-linux4sam_4.7-0011-Modified-DTS.patch

Recompiling the kernel

To recompile the kernel, you need to force a rebuild by removing the .stamp* files located in buildroot/output/build/linux-linux4sam_4.7, as described here:

# From the BSP repository
$ rm -rf buildroot/output/build/linux-linux4sam_4.7/.stamp*
$ make

Wait for the process to finish.