1. What is a Device Tree

The Device Tree (abbreviated DT) is a text-structured language and mechanism used by the Linux kernel to describe hardware device information.

• Essentially: a tree-structured configuration file that describes "what peripherals are connected to this hardware and what are their parameters".
• Format: consists of .dts, .dtsi, .dtb and other files, ultimately passed to the kernel by the bootloader.

2. Historical Background and Significance of Device Tree

Why did Device Tree come about?

• Decoupling: Originally, Linux drivers had to hardcode device information in C code, and changing hardware required code changes, which was very inflexible.
• Dynamic adaptation: Device Tree allows the same kernel driver to serve multiple hardware platforms - just modify the Device Tree file, no need to touch the driver code!
• Hardware information migration: Device Tree moved all device resource descriptions (such as addresses/interrupts/names/pins/parameters) from C code to dts text.

3. Device Tree Structure Diagram

Device Tree = Hardware directory with tree structure

• The root node / represents "the entire device"
• Each branch describes a type of hardware (CPU/memory/peripherals/mounted buses, etc.)
• Each node is a device, and nodes can have child nodes, representing the real "what is connected where" relationships
• Each node can contain multiple "properties" (such as register addresses, names, IRQs, pins, etc.)

4. Device Tree Practical Example

The Device Tree source file for LCSC-TaishanPi-3M-RK3576 is located at: kernel-6.1/arch/arm64/boot/dts/rockchip/tspi-3m-rk3576.dts

/*-----------------------------------------------------------
 * Board Basic Information Configuration
 *----------------------------------------------------------*/
/ {
	model = "LCKFB TaishanPi 3M RK3576 Board";
	compatible = "lckfb,tspi-3m-rk3576", "rockchip,rk3576";

	/*
	*	User LED
	*	Used to indicate system status
	*/
	leds: leds {
		status = "okay";
		compatible = "gpio-leds";

		work_led: work {
			linux,default-trigger = "heartbeat";
			gpios = <&gpio0 RK_PA0 GPIO_ACTIVE_LOW>;
		};
	};
};

5. Bridge Between Hardware and Software

• Device Tree is like a hardware circuit manual, but readable by machines and parseable by the kernel
• All hardware resources on a board are organized as a tree structure
• During kernel boot, the dtb (Device Tree binary) is parsed to automatically "create device objects", which automatically match with various platform/i2c/spi drivers

6. Relationship Between Device Tree and sysfs

• Device Tree is static description: tells the kernel what hardware exists and what properties are (written in dts)
• sysfs is dynamic display: the kernel organizes the combination of Device Tree and drivers as a directory structure (/sys/)
  • For example, content under /sys/firmware/devicetree/ is the parsed Device Tree
  • Devices under /sys/bus/platform/devices often correspond one-to-one with definitions in dts!

7. Practical Benefits of Device Tree

• When trimming/porting hardware, you don't need to make major code changes, just modify dts
• For mass production - one set of driver code, N dts files can adapt to multiple models
• Dynamically generate device nodes, allowing drivers to automatically recognize new peripherals
• Greatly improves collaboration efficiency and flexibility between hardware and driver engineers

8. Diagram

Device Tree structure and driver relationship:

• Device Tree is loaded into the kernel by BootLoader (U-boot), generating device objects. After driver matching, it is reflected in sysfs

9. dts, dtsi and dtb

1. What are these?

dts (Device Tree Source)

• dts file (device tree source) is the "Device Tree source file", a text format representing the topological tree structure, manually edited, with file extension .dts. It is a detailed description of the specific hardware resources of a board/SoM.

dtsi (Device Tree Source Include)

• dtsi file (device tree source include) is the "Device Tree source header/common section", with file extension .dtsi. It is mainly used for reusing common hardware descriptions and can be referenced by multiple .dts files, similar to .h files in C language.

dtb (Device Tree Blob)

• dtb file (device tree blob) is the compiled binary Device Tree file, with file extension .dtb, containing all tree information. The bootloader passes dtb to the kernel for startup.

2. Relationships and Uses

• dtsi: Common SoC/peripheral descriptions for reuse
• dts: Each model/board references one or more dtsi files, then adds the board's own parameters - it is the "final source file"
• dtb: Binary file generated by compiling dts files with the compiler (dtc). BOOT loads it into the kernel during boot

3. Common Questions

Q1: What is the difference between dts and dtsi?

• dts is typically one file per board/model, serving as the top-level "main" file, and will include one or more dtsi files
• dtsi provides "common" sections, eliminating the need to repeat CPU/peripheral/on-chip resources in each dts

Q2: Where does dtb come from? Can I modify it?

• Use the Device Tree compiler dtc: dtc -I dts -O dtb xxx.dts -o xxx.dtb
• You can also use the kernel make system for automatic production
• Can only be read, cannot be manually edited - you must recompile dts to modify it!

Q3: What is the Device Tree modification workflow?

1. Edit dts/dtsi
2. Compile dtb using dtc or make
3. Flash/Update/Transfer to development board, bootloader loads automatically

4. Practical Example

Suppose you have the following file structure:

sensor.dtsi        # Sensor common peripheral description
myboard.dts        # Your own development board top-level Device Tree file
myboard.dtb        # Compiled binary file

Typically at the beginning of the myboard.dts file:

#include "sensor.dtsi"

Finally, make will output myboard.dtb.

INFO

Write dts/dtsi, compile to dtb, the board runs dtb!