1. Composition of Device Tree Files

• Mainly composed of Nodes and Properties
• Curly braces {} represent node content block/subtree
• Each node can have child nodes and multiple properties

2. Basic Syntax

1. Nodes

Format:

node_name: node_label@unit_address {
    ...properties/child_nodes...
};

• Node name (optional label) @ physical address {...}
  • The "@address" part can sometimes be omitted, often used for bus-mounted devices to distinguish uniqueness
  • Label (such as xxx:) is commonly used for phandle references

Example:

i2c1: i2c@1c2b400 {    // label i2c1, node name i2c, mount address 0x1c2b400
    /* child nodes and properties */
};

2. Properties

Device parameters, registers, and compatible identifiers are all written as properties

Syntax:

property_name = property_value;    // Most common
property_name;             // Empty property (flag, indicates "this property exists")

Property Types

• String: wrapped in English double quotes compatible = "vendor,device-name";
• Number/Array: wrapped in angle brackets, hexadecimal 0x, decimal directly as number, multiple numbers separated by spaces reg = <0x01c2b400 0x400>; gpios = <&gpio1 4 GPIO_ACTIVE_HIGH>;
• Flag Property: name only, no value status;

3. Comments

• Single-line comment: // content
• Multi-line comment: /* ... */

3. Common Structures and Writing Styles

1. Root Node

The entry/topmost of Device Tree, usually written directly as / { ... };

Example:

/ {
	model = "LCKFB TaishanPi 3M RK3576 Board";
	compatible = "lckfb,tspi-3m-rk3576", "rockchip,rk3576";
    // ...
};

2. Child Node Nesting

Each node can contain properties and child nodes (wrapped in curly braces)

Example:

/ {
    soc {
        i2c@1c2b400 {
            sensor@20 {
                /* This is a child node */
            };
        };
    };
};

3. Node Name and Label Usage

myled: led@0 {
    compatible = "gpio-leds;
};

• myled: label: used for references elsewhere (such as phandle, see advanced usage)
• led@0: node name and unique address under parent node

4. Property Type Detailed Description

Type	Example	Description
String	compatible = "myvendor,mydevice";	Used for driver matching
Single Number	interrupt-parent = <&gpio2>;	Label reference
Array	reg = <0x100000 0x1000>;	Physical address + length
Flag Property	status;	Only indicates "existence", no specific value
Multi-String	compatible = "v1", "v2", "v3";	Multiple compatible strings

5. Quotes and Angle Brackets

• Use English double quotes when property value is a string, each string must be quoted
• Single or array numbers use angle brackets **< ... >**
• Comma separates strings/numbers, space separates numbers

6. Referencing Other Nodes

Common usage, for example gpio, interrupt-parent:

interrupt-parent = <&gpio2>;

&gpio2 is the label form defined earlier, referencing a phandle.

4. include and Splitting

• Supports #include syntax, referencing .dtsi common sections (similar to C language include)

Example:

#include "soc_common.dtsi"

5. Common Standard Properties Quick Reference

Property	Description	Example
compatible	Key for driver matching	"vendor,chip123"
reg	Peripheral physical address/length	<0x40000000 0x1000>
interrupts	Interrupt number	<45 IRQ_TYPE_LEVEL_HIGH>
status	Whether hardware is currently available	"okay" / "disabled"
gpios	GPIO pin information	<&gpio1 5 GPIO_ACTIVE_LOW>
interrupt-parent	Interrupt controller reference	<&gic>
phandle	Node unique reference pointer	<...>

6. Practical Example Analysis

1. Source Code

/ {
	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>;
		};
	};
};

2. Top-level Properties

model = "LCKFB TaishanPi 3M RK3576 Board";:

• model property: the board's name card, mainly used for readability, displayed in boot logs.
• "LCKFB TaishanPi 3M RK3576 Board" corresponds to your board's actual model.

compatible = "lckfb,tspi-3m-rk3576", "rockchip,rk3576";:

• compatible property: the most critical matching identifier!
  • First entry lckfb,tspi-3m-rk3576 (your custom identifier, recommended for driver official adaptation).
  • Second entry rockchip,rk3576 (SoC model identifier, compatible with mainstream Rockchip chips).
• The kernel/driver automatically matches the corresponding driver based on the compatible string.

3. leds Node

leds: leds {

• Here both label and node name appear
  • leds: is the label, convenient for referencing elsewhere (such as phandle advanced usage)
  • leds is the node name, indicating this block is "LED-related hardware resources"
  • Format: label_name: node_name { ... }
• This block describes all LED lights on the board

status = "okay";

• Property indicating the node is "enabled".
  • Alternatively, disabled means the node is disabled and the kernel ignores it.

compatible = "gpio-leds";

• Indicates that devices in this node belong to the "gpio-leds" driver framework. The kernel uses the gpio-led driver to manage all LEDs listed here.

4. work_led Child Node

work_led: work {

• work_led: is the label, convenient for references and use by other nodes or properties (phandle).
• work is the node name, representing this is an LED named work.

linux,default-trigger = "heartbeat";

• This line defines the LED's default trigger, indicating this light will display the Linux heartbeat (CPU load or kernel activity rhythmic blinking).

gpios = <&gpio0 RK_PA0 GPIO_ACTIVE_LOW>;

• Specifies the physical GPIO pin for the driver to control this LED:
  • <&gpio0 ...>: &gpio0 is a phandle label reference to the GPIO controller defined earlier
  • RK_PA0: the specific GPIO pin number (RK is the common naming convention for Rockchip platforms, PA0 means Group 0 Pin 0)
  • GPIO_ACTIVE_LOW: indicates this LED lights up when driven low (hardware is low-level active)
• This set of writing tells the kernel how to actually control this LED.

5. Structure Description

1. Root node uniformly describes board basic information
2. leds node is defined as a gpio-leds framework device, including all LED lights
3. Each LED is then described as a child node with individual properties, corresponding one-to-one with physical hardware

This way of writing allows the kernel and drivers to automatically discover, recognize, and manage all LED devices, without manually writing GPIO resource tables or flashing low-level addresses, facilitating portability and maintenance.

7. Quick Syntax Reference

Syntax	Meaning
xxx { ... };	New node
xxx = yyy;	New property
xxx: yyy@zz {}	Label + node name@address
#include ""	Reference other dts/dtsi files
// comment	Single-line comment
/* comment */	Multi-line comment