Scope and purpose

A devicetree is primarily a hierarchical data structure that describes hardware. The Devicetree specification defines its source and binary representations.

Zephyr uses devicetree to describe:

• the hardware available on its Supported Boards

• that hardware’s initial configuration

As such, devicetree is both a hardware description language and a configuration language for Zephyr. See Devicetree versus Kconfig for some comparisons between devicetree and Zephyr’s other main configuration language, Kconfig.

There are two types of devicetree input files: devicetree sources and devicetree bindings. The sources contain the devicetree itself. The bindings describe its contents, including data types. The build system uses devicetree sources and bindings to produce a generated C header. The generated header’s contents are abstracted by the devicetree.h API, which you can use to get information from your devicetree.

Here is a simplified view of the process:

Devicetree build flow

All Zephyr and application source code files can include and use devicetree.h. This includes device drivers, applications, tests, the kernel, etc.

The API itself is based on C macros. The macro names all start with DT_. In general, if you see a macro that starts with DT_ in a Zephyr source file, it’s probably a devicetree.h macro. The generated C header contains macros that start with DT_ as well; you might see those in compiler error messages. You always can tell a generated- from a non-generated macro: generated macros have some lowercased letters, while the devicetree.h macro names have all capital letters.