Device Tree (DTS) Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Device Tree (DTS) Configuration is a critical system within the project used to describe hardware topology and provide hardware-specific configuration to the kernel and drivers. It allows for a clear separation between software logic and hardware details, enabling the same OS code to run on diverse hardware platforms by simply providing a different Devicetree Source (DTS) file.
The configuration system encompasses the definition of SoCs, CPU clusters, and peripherals. It utilizes a hierarchical structure where base hardware descriptions are defined in Devicetree Include (.dtsi) files, which are then included and specialized by board-level .dts files. This infrastructure supports various architectures including ARM, RISC-V, and Xtensa, providing essential data such as flash/SRAM base addresses and peripheral configurations.
Sources: doc/hardware/porting/soc_porting.rst:83-113, doc/releases/release-notes-1.7.rst:22-28
Hardware Description Architecture
The Devicetree architecture is organized into a hierarchy that mirrors the physical hardware. At the base are architecture-specific files, followed by vendor-specific SoC descriptions, and finally board-level configurations.
SoC and CPU Cluster Definition
Each SoC requires a .dtsi file located in the dts/<ARCH>/<VENDOR>/ folder. This file describes the hardware using the Devicetree Source (DTS) format and must be included by any boards utilizing that SoC. For complex SoCs with multiple CPU clusters, the memory space and peripherals available to each cluster are described in separate files following the naming scheme <soc>_<cluster>.dtsi.
Sources: doc/hardware/porting/soc_porting.rst:83-93, doc/hardware/porting/soc_porting.rst:133-138
Devicetree Structure Overview
The following diagram illustrates the relationship between different hardware layers in the Devicetree configuration:
The diagram shows the inheritance and inclusion flow from generic architecture definitions down to specific board configurations.
Sources: doc/hardware/porting/soc_porting.rst:95-131
Configuration Components
Devicetree configuration involves several key elements including nodes, properties, and specific "chosen" settings that link hardware to software requirements.
Key Data Structures and Fields
| Component | Description | Reference File |
|---|---|---|
/chosen | Defines system-wide hardware selections (e.g., console, zephyr,sram). | soc_porting.rst |
/cpus | Contains CPU core definitions and cluster information. | soc_porting.rst |
/soc | Node containing SoC-specific peripherals and bus definitions. | soc_porting.rst |
compatible | String used to match hardware nodes with appropriate drivers. | soc_porting.rst |
reg | Defines the address and size of hardware register blocks. | devicetree.rst |
Sources: doc/hardware/porting/soc_porting.rst:104-131, doc/contribute/style/devicetree.rst:24-34
Node and Property Conventions
The project enforces strict style guidelines for Devicetree files to maintain consistency across the codebase:
- Naming: Use dashes (
-) as word separators for node and property names; use underscores (_) for node labels. - Indentation: Files must be indented with tabs (size is 8 characters).
- Spacing: A single space is required on each side of the equal sign (
=) in property definitions. - Separation: Related groups of properties can be split into "paragraphs" by an empty line to aid readability.
Sources: doc/contribute/style/devicetree.rst:3-19
Build System Integration
The Devicetree configuration is tightly integrated with the CMake build system and the Kconfig configuration tool.
Build Process Flow
During the build process, the DTS files are parsed to generate header files that the C code can use to interact with hardware.
This flowchart shows how hardware descriptions (DTS) and driver metadata (Bindings) are processed into C headers for the final compilation.
Sources: doc/contribute/documentation/generation.rst:22-41, doc/hardware/porting/soc_porting.rst:140-151
Tooling and Validation
Specialized tools are provided to ensure the quality and correctness of Devicetree files:
- dts-linter: A tool used to format and check Devicetree files against project style guidelines. It can be run manually or integrated into CI.
- devicetree-language-server: Provides LSP support for editors to assist in writing correct DTS code.
- Scripts: The
list_hardware.pyscript can be used to retrieve lists of known SoCs defined in the system.
Sources: doc/contribute/style/index.rst:102-132, doc/hardware/porting/soc_porting.rst:32-40
Implementation Details
When porting a new SoC, the Devicetree implementation usually begins with a skeleton structure that includes architecture-level defaults.
#include <arch>/<arch>.dtsi
/ {
chosen {
/* common chosen settings for your SoC */
};
cpus {
#address-cells = <1>;
#size-cells = <0>;
cpu@0 {
device_type = "cpu";
compatible = "vendor,soc-cpu";
};
};
soc {
/* Your SoC definitions and peripherals */
/* such as ram, clock, buses, peripherals. */
};
};
Sources: doc/hardware/porting/soc_porting.rst:104-131
This configuration structure ensures that essential system information like memory maps and CPU properties are available to the kernel at compile time.