Advanced Device Tree (Part 4): Practical Linux Debugging

1. Device Tree in the sys Filesystem

1.1 /sys/firmware/devicetree/base

The Linux kernel exports device tree information to the/sys/firmware/devicetree/base directory, providing a user-space access interface.

Directory Structure:

/sys/firmware/devicetree/base/
├── compatible
├── model
├── #address-cells
├── #size-cells
├── cpus/
│   ├── cpu@0/
│   └── cpu@1/
├── memory@80000000/
├── soc/
│   ├── i2c@10002000/
│   ├── uart@10009000/
│   └── gpio@10015000/
└── clocks/

1.2 Viewing Device Tree Information

View Root Node Properties

# View compatible
cat /sys/firmware/devicetree/base/compatible

# View model
cat /sys/firmware/devicetree/base/model

# View all properties
ls -la /sys/firmware/devicetree/base/

View Specific Node

# View I2C node
ls -la /sys/firmware/devicetree/base/soc/i2c@10002000/

# View node properties
cat /sys/firmware/devicetree/base/soc/i2c@10002000/compatible
cat /sys/firmware/devicetree/base/soc/i2c@10002000/reg

Traverse Device Tree

# Recursively list all nodes
find /sys/firmware/devicetree/base -type d

# Find all compatible properties
find /sys/firmware/devicetree/base -name compatible -exec cat {} \;

# Find devices with specific compatible
find /sys/firmware/devicetree/base -name compatible | \
    xargs grep -l "arm,pl011" | \
    xargs dirname

1.3 Reading Property Values

String Properties:

# Directly read text property
cat /sys/firmware/devicetree/base/soc/i2c@10002000/compatible

Binary Properties:

# Use hexdump to view binary properties (e.g., reg, interrupts)
hexdump -C /sys/firmware/devicetree/base/soc/i2c@10002000/reg

2. /proc/device-tree

2.1 proc Interface

/proc/device-tree is another access interface for the device tree (symbolic link to/sys/firmware/devicetree/base).

# Check symbolic link
ls -l /proc/device-tree

# View device tree
ls /proc/device-tree/

# Read properties
cat /proc/device-tree/compatible
cat /proc/device-tree/model

2.2 Useful Commands

View Node Information:

# View compatible
cat /proc/device-tree/soc/i2c@10002000/compatible

# View reg property (binary)
hexdump -C /proc/device-tree/soc/i2c@10002000/reg

# View status
cat /proc/device-tree/soc/i2c@10002000/status

3. fdtdump Tool

3.1 Introduction to fdtdump

fdtdump is a device tree binary file dump tool used to view the detailed contents of DTB files.

Features:

Display DTB file header information
Dump device tree structure
Display property values
Debug device tree format issues

3.2 Basic Usage

# Dump DTB file
fdtdump board.dtb

# Display file header information
fdtdump -h board.dtb

# Only display structure (no data)
fdtdump -s board.dtb

# Display memory reserved mapping
fdtdump -m board.dtb

3.3 Output Example

Basic Dump:

/dts-v1/;
// magic:               0xd00dfeed
// totalsize:           0x1234 (4660)
// off_dt_struct:       0x38
// off_dt_strings:      0x567
// off_mem_rsvmap:      0x28
// version:             17
// last_comp_version:   16
// boot_cpuid_phys:      0x0
// size_dt_strings:     0x200
// size_dt_struct:      0x52f

/ {
    model = "Demo Board";
    compatible = "demo,board";
    #address-cells = <0x1>;
    #size-cells = <0x1>;
    
    soc {
        compatible = "simple-bus";
        #address-cells = <0x1>;
        #size-cells = <0x1>;
        
        i2c@10002000 {
            compatible = "arm,versatile-i2c";
            reg = <0x10002000 0x1000>;
            interrupts = <0x0 0x1e 0x4>;
        };
    };
};

3.4 Advanced Usage

# Dump specific node
fdtdump board.dtb | grep -A 20 "i2c@10002000"

# Find specific property
fdtdump board.dtb | grep "compatible"

# Save dump result
fdtdump board.dtb > board_dump.txt

# Compare two DTB files
fdtdump board_v1.dtb > dump1.txt
fdtdump board_v2.dtb > dump2.txt
diff dump1.txt dump2.txt

4. Comprehensive Debugging Methods

4.1 Device Tree Viewing

List All Nodes:

find /sys/firmware/devicetree/base -type d | sed "s|/sys/firmware/devicetree/base||" | sort

Display Node Information:

# View all properties of the node
ls -la /sys/firmware/devicetree/base/soc/i2c@10002000/

# View compatible
cat /sys/firmware/devicetree/base/soc/i2c@10002000/compatible

# View reg (binary property)
hexdump -C /sys/firmware/devicetree/base/soc/i2c@10002000/reg

Find Devices:

# Find devices with specific compatible
find /sys/firmware/devicetree/base -name compatible | \
    xargs grep -l "arm,pl011" | \
    xargs dirname

4.2 Device Status Check

Check Device Status:

# Find all status properties
find /sys/firmware/devicetree/base -name status

# View device status
cat /sys/firmware/devicetree/base/soc/i2c@10002000/status

Check Device Driver Binding:

# View platform devices
ls /sys/bus/platform/devices/

# View device drivers
ls /sys/bus/platform/drivers/

4.3 Device Tree Comparison

Export Runtime Device Tree:

# Export the runtime device tree as DTS
dtc -I fs -O dts /sys/firmware/devicetree/base -o runtime.dts

Compare Device Trees:

# Compare with original DTB
dtc -I dtb -O dts board.dtb -o original.dts
diff original.dts runtime.dts

5. Debugging Tips

5.1 Finding Device Issues

Check if devices in the device tree match drivers:

# View device tree nodes
for node in /sys/firmware/devicetree/base/soc/*/; do
    node_name=$(basename "$node")
    if [ -f "$node/compatible" ]; then
        compatible=$(cat "$node/compatible" | tr '\0'', ')
        echo "Device: $node_name, compatible: $compatible"
        
        # Check if corresponding platform device exists
        if [ -d "/sys/bus/platform/devices/$node_name" ]; then
            echo "  ✓ Found platform device"
        else
            echo "  ✗ Platform device not found (driver may not be loaded)"
        fi
    fi
done

5.2 View Kernel Logs

# View device tree related logs
dmesg | grep -i "device-tree\|dtb"

# View device initialization logs
dmesg | grep -i "i2c\|uart\|gpio"

5.3 Check Overlay Applications

# Check loaded overlays
if [ -d "/sys/kernel/config/device-tree/overlays" ]; then
    echo "Loaded Overlays:"
    for overlay in /sys/kernel/config/device-tree/overlays/*/; do
        name=$(basename "$overlay")
        if [ -f "$overlay/status" ]; then
            status=$(cat "$overlay/status")
            echo "  $name: $status"
        fi
    done
fi

5.4 Verify Device Tree Integrity

Basic Structure Check:

# Check if device tree directory exists
[ -d /sys/firmware/devicetree/base ] && echo "Device tree directory exists"

# Check root node compatible
[ -f /sys/firmware/devicetree/base/compatible ] && \
    echo "Root node compatible exists"

Key Node Check:

# Check key nodes
key_nodes=("cpus" "memory" "soc" "clocks")
for node in "${key_nodes[@]}"; do
    [ -d "/sys/firmware/devicetree/base/$node" ] && \
        echo "✓ $node node exists" || \
        echo "✗ $node node missing"
done

6. Summary

In this section, we learned about debugging methods for the device tree in the Linux system:

Key Points:

/sys/firmware/devicetree/base provides the device tree access interface
/proc/device-tree is the proc interface (symbolic link)
fdtdump is used to dump DTB file contents
Comprehensive use of various tools for debugging

Debugging Tools:

sys Filesystem – View device tree at runtime
proc Interface – Compatibility interface
fdtdump – DTB file analysis
dtc – Device tree compilation and conversion

Debugging Process:

Use sys filesystem to view runtime device tree
Use fdtdump to analyze DTB file
Compare original DTB and runtime device tree
Check device status and driver matching
Verify overlay application status
View kernel logs to locate issues

Series Summary: Through this series of articles, we have comprehensively learned the basic knowledge of device trees, compilation commands, syntax specifications, common device descriptions, as well as advanced memory formats, schema checks, overlay mechanisms, and debugging methods. Mastering these concepts will greatly enhance development efficiency and system maintainability in embedded Linux development.