Introduction to devicetree

A devicetree is a data structure that describes supported hardware. Its content is defined into source files called devicetree source files (.dts). A dedicated compiler named devicetree compiler (DTC) compile such files and output devicetree blobs files(.dtb) which are the binary version of the devicetree.

../../../_images/devicetree_compiling.png — Device tree compiler

GAP SDK usage

The GAP SDK integrates devicetree files to describe the supported hardware. Associated with Kconfig, the devicetree provides data required by applications.

Devicetree source files respect the devicetree specifications to produce their binary version. GAP_SDK aims to parse devicetree blob file and generate a C coded representation that fill the needs of the software concerning hardware data.

To do this, GAP_SDK implement a parser based on the python flat device tree library (pyfdt) that provide an API to read devicetree blob files and extract their data.

../../../_images/devicetree_parsing_process.png — Devicetree parsing process

Devicetree files organization

GAP SDK implement devicetree in a way that one file represent a known board or a known chip.

Devicetree source files are designed to be combined in the same way as hardware is. Like a hat or an addon plugged into a main board, a devicetree source file can be merged into a main one to create a global devicetree. The main devicetree source file (or the base) of a hardware setup is dedicated to the chip itself. Boards onwhich the chip is mounted and/or connected to are described into devicetree source file called overlays. Overlays are merged with the main devicetree file thanks to the flat device tree overlay utility (fdtoverlay).

In GAP_SDK context, selecting a hardware configuration that uses a GAP9Mod V1.0b plugged into a GAP9evk V1.3 will require gap9 chip’s .dts file and both boards dts files.

Build process

The devicetree feature is managed by CMake. Cmake purpose is to find required devicetree source file depending the selected hardware in menuconfig interface, compile them and merge them to get the global devicetree. Then, depending on enabled drivers though menuconfig interface, the devicetree content is parsed and filtered to generate a C-coded version of it located in the application’s build directory. Generated C files are then included by applications.

../../../_images/devicetree_cmake_process.png — Devicetree creation process from Cmake example

The content of devicetree’s C version will always be updated according to the application being compiled. Only required hardware will be outputed.