# Devicetree Guide by ZephyrProject [From docs.zephyrproject.com v.3.0.99](https://docs.zephyrproject.org/latest/guides/dts/intro.html) ## Introduction to devicetree A *devicetree* is a hierarchical data structor used to describe hardware, used by Zephyr to describe the supported boards and initial configurations. **Input files:** *devicetree sources* contain the devicetree, and *devicetree bindings* describe its contents. The input files are used to generate a C header which is used by the `devicetree.h` API. [Image describing the process](https://docs.zephyrproject.org/latest/_images/zephyr_dt_build_flow.png) The API is based on C macros, where all macro names begin with `DT_`. Zephyr is in the process of converting some information from Kconfig to decivetree. ### Syntax and structure A devicetree follow a similiar structure to UNIX file systems. They consist of nodes, where each tree must contain a root node `/` and optional subnodes. An example might be `/a-node/a-sub-node`. Nodes might also have properties, which are bytes of data. ### Unit address examples Unit addresses are the addresses following the `@`-symbol in a node name. They give the node's address in the address space of its parent node. ### Important properties `compatible`: The nme of the hardware device the node represents. Recommended format is `"vendor,device"`. `label`: The device's name according to Zephyr's [Device Driver Model](https://docs.zephyrproject.org/latest/reference/drivers/index.html#device-model-api). `reg`: The information used to address the device. The property is a sequence of `(address, length)` pairs, or "register blocks". `status`: A string describing whether the node is enabled. In Zephyr, accepted values are `"okay"` and `"disabled"`. `interrupts`: An array of one or more *interrupt specifiers*. ### Writing property values See doc. ### Aliases and chosen nodes The `/aliases` and `/chosen` nodes do not refer to an actual hardware device, but rather specify other nodes in the devicetree. Aliases can be used to allow overriding partincular hardware devices used by an application in a generic way. Chosen nodes' properties are used to configure system- or subsystem-wide values. ### Input and output files `.overlay` files override `.dts` files. Devicetree bindings (with `.yaml` extension) contain rules for devicetree's contents. During building, an intermediate dts file called `zephyr.dts.pre` is outputted from the C preprocessor. This file, together with the devicetree bindings produce the output files `zephyr.dts` and C headers. The outputted dts is useful for debugging. Can be decompiled with `dtc`. #### Input files There are four types of devicetree input files: - sources (`.dts`) - includes (`.dtsi`) - overkays (`.overlay`) - bindings (`.yaml`) Every supported board should have a `BOARD.dts` file describing its hardware. The file's include files (`.dtsi`-files) describe the CPU or SoC that Zephyr runs on. For Zephyr there is a file `dts/common/skeleton.dtsi` which is a minimal include file for defining a complete devicetree. It is extended by the architecture-specific subdirectories' `.dtsi`-files. the C preprocessor is run on all devicetree files to expand macro references. `BOARD.dts` can be extended or modified using *overlays*, which are regular DTS files but with the extension `.overlay` for clearity. Along with Configuration System (Kconfig) it is possible to reconfigure the kernel and device drivers without modifying source code. #### Scripts and tools Useful scripts and libraries are located in `scripts/dts/`: - `dtlib.py`: A low-level DTS parsing library. - `edtlib.py`: A library layered on top of dtlib that uses bindings to interpret properties and give a higher-level view of the devicetree. - `gen_defines.py`: A script that uses edtlib to generate C preprocessor macros from the devicetree and bindings. #### Output files These are created in your application's build directory. `<build>/zephyr/zephyr.dts.pre` is the preprocessed DTS source. `<build>/zephyr/include/generated/devicetree_unfixed.h` is the generated macros and additional comments describing the devicetree. `<build>/zephyr/include/generated/devicetree_fixups.h` is the concatenated contents of any `dts_fixup.h` files. `<build>/zephyr/zephyr.dts` is the final merged devicetree. --- ## Devicetree bindings