Relevant source files

The following files were used as context for generating this wiki page: - [doc/hardware/porting/soc_porting.rst](https://github.com/seyoungjeong/zephyr/blob/main/doc/hardware/porting/soc_porting.rst) - [doc/contribute/style/devicetree.rst](https://github.com/seyoungjeong/zephyr/blob/main/doc/contribute/style/devicetree.rst) - [doc/contribute/style/index.rst](https://github.com/seyoungjeong/zephyr/blob/main/doc/contribute/style/index.rst) - [doc/releases/release-notes-1.7.rst](https://github.com/seyoungjeong/zephyr/blob/main/doc/releases/release-notes-1.7.rst) - [doc/index.html](https://github.com/seyoungjeong/zephyr/blob/main/doc/index.html) - [doc/contribute/documentation/generation.rst](https://github.com/seyoungjeong/zephyr/blob/main/doc/contribute/documentation/generation.rst)

# Device Tree (DTS) Configuration 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///` 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 `_.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: ```mermaid graph TD ARCH[Arch dtsi] --> SOC_BASE[SoC dtsi] SOC_BASE --> CLUSTER[CPU Cluster dtsi] CLUSTER --> BOARD[Board dts] VND_BIND[Vendor Bindings] -.-> SOC_BASE ``` 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. ```mermaid flowchart TD DTS[DTS/DTSI Files] --> PARSER[DTS Parser/Generator] BINDINGS[YAML Bindings] --> PARSER PARSER --> HEADERS[Generated C Headers] HEADERS --> COMPILER[C Compiler] KCONFIG[Kconfig Symbols] --> COMPILER ``` 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.py` script 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. ```devicetree #include /.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. Sources: [doc/releases/release-notes-1.7.rst:25-28]()