Applicable Subjects Embedded Linux Driver Development Engineer, BSP Porting Engineer 
Key Takeaways In embedded Linux development, the Device Tree serves as a bridge between hardware and the kernel. In Leakin Technology’s real-world projects—such as industrial control boards and IoT terminal development—we frequently encounter challenges like adapting to new hardware and troubleshooting driver‑loading failures. This article will guide you, starting from the underlying logic, to master the core methodologies for debugging the Device Tree, thereby boosting development efficiency and confidently tackling code reviews and complex technical problems.

Preface: Why is it important to gain a deep understanding of device tree debugging?

In the early days of Linux development, hardware information was hard-coded into the kernel, resulting in redundant and difficult-to-maintain code. The introduction of the Device Tree has enabled… Decoupling of hardware description from kernel code 。

For Leakin Technology’s R&D team, mastering the device tree goes beyond simply being able to write it. .dts Documents, and more importantly, possessing Fault localization capability When we’re debugging a new core board in the lab or encountering a tricky “device not recognized” bug on-site, our ability to quickly pinpoint the issue using device tree logs can make or break the project’s delivery timeline.

This article will focus on Principles of Data Structures 、 Grammatical norms 、 Compilation Process and also Real-world troubleshooting Four dimensions to help you build a comprehensive knowledge system of device trees.

Chapter 1: Infrastructure and Core Concepts

1.1 What is the Device Tree? 
The Device Tree is, in essence, a data structure that describes hardware resources. It serves as a detailed “hardware specification,” listing hardware names, addresses, interrupt information, and more in a tree‑like hierarchy. During kernel boot, the kernel reads this specification, enabling it to dynamically adapt to different hardware platforms without requiring recompilation of the kernel code.

1.2 Core File Types 
In our daily development work, you will frequently encounter the following file formats:

Table

1.3 Core Advantages of the Device Tree

• Code reusability : When developing different products—such as handheld terminals and gateways—based on the same SoC (e.g., i.MX6ULL), you only need to replace the .dts file; no changes are required to the kernel code.
• Transplantation convenience : To port Linux to new hardware, you only need to write the corresponding device tree; no changes to the kernel source code are required.
• Dynamic Configuration : Supports dynamically adding or removing device nodes while the system is running (though this is rarely used in production environments, it is extremely valuable during the debugging phase).

Chapter 2: Grammatical Norms and Node Parsing

2.1 Node Naming Rules 
A node is the fundamental building block for describing hardware. When authoring a device tree, please adhere strictly to the following naming conventions to ensure code consistency—this is a key focus of our Leakin Technology code reviews:

• Format ： node-name@unit-address
• Example ： uart@10000000 
  • UART : Generic device type name.
  • 10000000 : Register base address (hexadecimal).
• Label : For ease of citation, it is recommended to use label: node-name Format. For example, uart4: serial@021f0000 , which can subsequently be used to &uart4 Direct quotation.

2.2 Detailed Explanation of Key Attributes (Property) 
Attributes are expressed as key-value pairs and determine how the device is recognized by the driver.

compatible (Compatibility Property)

• Function : This is the “matchmaker” that binds devices to drivers. Its value is a list of strings.
• Format ： "Vendor, Module Driver Name" 。
• Logic The kernel matches the strings in the list sequentially until it finds the corresponding driver. of_device_id Table).
• Code example ：

dts

1// Correct approach: Match the exact model first, then match the generic model.

2compatible = "fsl,imx6ull-gpmi-nand", "fsl,imx6ul-gpmi-nand";

reg (Address Resource Attribute)

• Function : Describes the register address range of the device.
• Attention : Its format is governed by the parent node's #address-cells and #size-cells Property influence.

interrupts (Interrupt Attribute)

• Function : Describes the device’s interrupt number and trigger type.
• Example ： interrupts = <10 IRQ_TYPE_EDGE_RISING>; Indicates interrupt number 10, triggered on the rising edge.

status (Device Status)

• Common values ：
  • "okay" : The device is functioning normally.
  • "disabled" : Device disabled (commonly used to temporarily mask a device that is causing pin conflicts).
• 2.3 Root Node and Special Nodes
• Root node ( /) : Contains global information and must include compatible (used to match the board support package) and model (Board model).
• chosen Node : A non-real device, used by U-Boot to pass parameters to the kernel (such as bootargs ).
• aliases Node : Define an alias, such as serial0 = &uart4 , enabling applications to make unified calls.

Chapter 3: Compilation Process and Loading Mechanism

In Leakin Technology’s continuous integration (CI) environment, understanding the compilation process can help you troubleshoot build errors.

3.1 Compilation Toolchain

1# Install the DTC tool

2sudo apt-get install device-tree-compiler

3

4# Compilation: DTS -> DTB

5dtc -I dts -O dtb -o myboard.dtb myboard.dts

6

7# Decompilation: DTB -> DTS (Debugging Tool)

8dtc -I dtb -O dts -o myboard_rev.dts myboard.dtb

We typically use the DTC tool built into the kernel, but you can also install it separately on Ubuntu for offline debugging:

bash

3.2 Kernel Loading Method 
Currently, the mainstream approach is to adopt DTB standalone loading Method (high efficiency; modifying the device tree does not require recompiling the kernel):

1. U-Boot loads the kernel image (zImage/Image) and the device tree binary file (.dtb) into different memory addresses, respectively.
2. When U-Boot boots the kernel, it passes the memory address of the .dtb file to the kernel.
3. The kernel reads and parses the device tree based on this address.

Chapter 4: Hands-On Troubleshooting — The “Essential Course” of Embedded Development

When encountering issues such as a driver failing to load or an abnormal system boot, please follow the troubleshooting steps below:

4.1 Common Fault Symptom 1: The device is not recognized.

• Phenomenon : System startup log message no compatible device found Or the driver cannot be bound.
• Troubleshooting Approach ：
  1. Check the device tree node's compatible Whether the attribute string matches that in the driver code of_device_id Table Strict consistency (Note the vendor name, spelling, and hyphens.)
  2. Verify that the node is included correctly (check the include path in the .dtsi file).

4.2 Common Fault Symptom No. 2: Driver Loading Failure

• Phenomenon : An error occurs during driver loading, such as irq: unable to map IRQ or resource conflict 。
• Troubleshooting Approach ：
  • Interrupt number error : Verify the schematic and confirm. interrupts Is the interrupt number in the property correct (e.g., the offset calculation for the GPIO controller)?
  • Address Conflict : Check reg Whether the memory-mapped range defined by the attribute overlaps with that of other devices.

4.3 Common Fault Symptom 3: System Startup Failure (Kernel Panic)

• Phenomenon : The system freezes, reboots, or fails to mount the root file system.
• Troubleshooting Approach ：
  • Memory node error : This is the most fatal mistake. Please be sure to confirm. memory The node’s base address and size are fully consistent with the hardware design.
  • Error Log Example ： VFS: Unable to mount root fs The kernel initialization may have failed due to an incorrect memory configuration.

Chapter 5: Efficient Debugging Techniques and Toolset

5.1 Kernel Log Analysis ( dmesg )
This is the most straightforward debugging method. Use grep to filter out key information:

bash

1# View device tree-related parsing logs

2dmesg | grep device-tree

3

4# View the matching status of a specific bus (e.g., I2C)

5dmesg | grep i2c

• Key clue : Search for parsing node (Analyzing node) or no match (Match failed) and other keywords.

5.2 Utilization dtc Tool decompilation 
When you suspect that the .dtb file running on the board is inconsistent with the code repository, directly extract the .dtb file from the board and decompile it for verification:

bash

 1# Decompile the dtb file on the board into a dts file to verify the configurations that are actually applied.
2dtc -I dtb -O dts -o extracted.dts board.dtb 

This method can help you quickly identify issues where “the code has clearly been modified, but the behavior remains unchanged.”

5.3 Dynamic Debugging ( sysfs )
During system operation, the driver can be re-bound or unbound without a reboot, making it ideal for debugging probe functions.

bash

1# Enter the driver directory corresponding to the bus, for example, USB.

2cd /sys/bus/usb/drivers/usb

3

4# Unbind Device (assuming the device ID is 1-1)

5echo -n "1-1" > unbind

6

7# Rebind Device

8echo -n "1-1" > bind

This operation allows you to use dmesg to monitor the detailed driver-loading process in real time.

Chapter 6: Practical Case Study — Debugging I2C Sensors on an Industrial Control Board

Background ：
During the development of a certain industrial control board, an I2C temperature sensor was added. At the application layer, data reads fail with the error message “Device not found.”

Troubleshooting Steps ：

1. Log Location : Execute dmesg | grep i2c , an error was detected of_find_device_by_node: no compatible device found . Preliminary assessment indicates a matching issue.
2. Decompilation Verification : On the board, /boot/*.dtb Copy the file, then use dtc Decompiled into .dts。
3. Comparative analysis : In the decompiled source code, it was discovered that the sensor node’s … compatible = "vendor,wrong-sensor" , whereas the driver code defines it as "vendor,right-sensor" 。

1. Solve the problem ：
   • Modify the .dts file and correct it. compatible Attribute.
   • Recompile to generate the .dtb file and replace the board’s firmware.
   • Restarting or dynamically reloading the driver resolves the issue.

Conclusion ：
Device tree debugging is a fundamental skill for embedded Linux developers. We hope that, through this tutorial, you will develop a systematic debugging mindset, enabling you to analyze complex hardware environments with composure and pinpoint issues accurately. Wishing you continued progress on your technical journey at Leakin Technology and the successful overcoming of even greater challenges!

Leakin Technology R&D Management Department | Technology Empowerment Center