Zephyr Configuration System

Device Tree

Using device tree to describe hardware configurations across different platforms is a great design in my opinion, especially for microcontrollers where there are lots of vendors with their unique features for similar peripherals. However, just like Zephyr’s disadvantages, the documentation and examples are few, especially for vendor specific configurations. Here are some tips for using device tree in Zephyr:

Device tree includes

Decive tree supports including other device tree files just like how C does, but without a language service provider (LSP) like IntelliSense for C/C++ or Pylance for Python, it is hard to find where the included files are. The following are some common places where Zephyr may put these files:

Device tree header files (.dtsi) for a specific architecture in zephyr/dts
C header files (.h) for constants and macros in zephyr/include/zephyr/dt-bindings
Board support package (BSP) files in zephyr/boards
Vendor specific device tree files (especially for ping control) in modules/hal/<vendor>/dts

Device tree macros

Since device tree in Zephyr is processed into C macros for the compiler to further process, it supports including C hearder files as well as using macros defined in it.

For example, you may see clock-frequency = <DT_FREQ_K(48)>, in clock configs where DT_FREQ_K is a macro defined as DT_FREQ_M(x) ((x) * 1000) in zephyr/dts/common/freq.h.

STM32 device tree

For STM32, it is a good idea to use STM32CubeMX as a reference when configuring the device tree as most of the time is just copying the configurations from STM32CubeMX to the device tree.

Kconfig

Kconfig Macros

Kconfig also supports macros, which is mainly used in Zephyr for accessing the device tree. It is useful for example to enable a feature only when a specific property is defined in the device tree. The supported macros can be referenced from Custom Kconfig Preprocessor Functions.

Porting New Boards to Zephyr

A board that is not supported by Zephyr can be added to it by following the official Board Porting Guid

In Zephyr v3.7.0, a new hardware model is introduced for defining the configuration of boards. Though a new qualification system for determining the SoC, CPU cluster, and variant of a target is introduced. It however does not support using different SoCs across different versions of the same board (or at least I don’t think it is designed to do so). For example, the Kconfig.<board> file for selecting the SoC is not versioned [1], and the <board>.dts file that selects the SoC of the board file only allows <board>_<revision>.overlay files to be merged into the base device tree file, but no way to replace the it [2]. Hence, though the versioning system is still useful for the same set of SoCs, it is required to create a new board when a different SoC is used.

A wierd thing is that the YAML file extensions for board metadata file board.yml and twister metadata file <board>.yaml are different [3]. The board may not be indentified if the extensions are not correct.