3. of核心API概览：of_find_node_by_path、of_get_property、of_parse_phandle等函数族

设备树解析的核心工作由一组以 of_ 前缀命名的内核API完成，它们定义在 drivers/of/ 目录下，头文件位于 include/linux/of.h。本章聚焦于最常用的三个函数族：节点查找、属性读取和phandle解析。理解这些API的调用链和返回值，是使用printk进行调试的前提。

3.1 节点查找：of_find_node_by_path 与 of_find_node_by_name

节点查找是设备树解析的入口。驱动通常通过设备路径或节点名获取 struct device_node 指针，后续所有属性读取都依赖该指针。

// 典型调试代码片段：查找 /soc/i2c@7e804000 节点
struct device_node *np;
np = of_find_node_by_path("/soc/i2c@7e804000");
if (!np) {
    printk(KERN_ERR "OF_DEBUG: Failed to find node /soc/i2c@7e804000\n");
    return -ENODEV;
}
printk(KERN_INFO "OF_DEBUG: Found node %pOF\n", np);  // %pOF 是内核专用打印格式
// ... 使用 np 读取属性 ...
of_node_put(np);  // 释放引用

3.2 属性读取：of_get_property 与 of_property_read_* 系列

获取节点指针后，下一步是读取属性值。of_get_property 是底层函数，返回原始字节流；而 of_property_read_* 系列封装了类型转换和错误检查，推荐在驱动中使用。

// 属性读取调试示例
struct device_node *np;
u32 clock_freq;
const char *compat_str;
int ret;

np = of_find_node_by_path("/soc/i2c@7e804000");
if (!np) {
    printk(KERN_ERR "OF_DEBUG: node not found\n");
    return -ENODEV;
}

// 读取 u32 属性
ret = of_property_read_u32(np, "clock-frequency", &clock_freq);
if (ret) {
    printk(KERN_WARNING "OF_DEBUG: clock-frequency read failed, ret=%d\n", ret);
} else {
    printk(KERN_INFO "OF_DEBUG: clock-frequency = %u Hz\n", clock_freq);
}

// 读取字符串属性
ret = of_property_read_string(np, "compatible", &compat_str);
if (!ret) {
    printk(KERN_INFO "OF_DEBUG: compatible = %s\n", compat_str);
}

// 使用底层 of_get_property 调试原始数据
int proplen;
const u32 *raw = of_get_property(np, "reg", &proplen);
if (raw) {
    printk(KERN_INFO "OF_DEBUG: reg property length = %d bytes\n", proplen);
    printk(KERN_INFO "OF_DEBUG: reg[0] = 0x%08x\n", be32_to_cpu(raw[0]));
}

of_node_put(np);

3.3 phandle解析：of_parse_phandle 与 of_parse_phandle_with_args

设备树通过 phandle（指针句柄）实现节点间的引用，例如中断控制器、时钟源、GPIO控制器等。解析phandle是驱动编写中最容易出错、也最需要printk调试的环节。

// phandle 解析调试示例：解析 clocks 属性
struct device_node *np, *clk_np;
struct of_phandle_args clk_spec;
int ret, i;

np = of_find_node_by_path("/soc/spi@7e204000");
if (!np) return -ENODEV;

// 解析第0个clock引用，带1个参数（#clock-cells = 1）
ret = of_parse_phandle_with_args(np, "clocks", "#clock-cells", 0, &clk_spec);
if (ret) {
    printk(KERN_ERR "OF_DEBUG: Failed to parse clocks[0], ret=%d\n", ret);
    of_node_put(np);
    return ret;
}

printk(KERN_INFO "OF_DEBUG: clocks[0] phandle node = %pOF\n", clk_spec.np);
printk(KERN_INFO "OF_DEBUG: clocks[0] args count = %d\n", clk_spec.args_count);
for (i = 0; i < clk_spec.args_count; i++) {
    printk(KERN_INFO "OF_DEBUG: clocks[0] args[%d] = %u\n", i, clk_spec.args[i]);
}

// 使用完后必须释放 phandle 节点引用
of_node_put(clk_spec.np);
of_node_put(np);

3.4 常用辅助函数与调试技巧

除了上述核心API，以下辅助函数在调试中同样重要：

• of_match_node(matches, np)：检查节点是否匹配 of_device_id 表，常用于 probe 入口调试。
• of_alias_get_id(np, name)：从 /aliases 节点获取别名序号，如获取 i2c0 中的 0。
• of_count_phandle_with_args(np, name, cells)：统计phandle引用个数，用于循环解析前的边界检查。
• of_node_full_name(np)：返回节点的完整路径名，比直接打印 np->name 更准确。

// 综合调试示例：完整解析一个带 phandle 和属性的节点
static int debug_of_parse(struct device_node *np)
{
    struct of_phandle_args gpio_spec;
    u32 reg_base;
    int ret, i;

    // 1. 打印节点基本信息
    printk(KERN_INFO "OF_DEBUG: Parsing node %pOF\n", np);

    // 2. 读取 reg 属性
    ret = of_property_read_u32(np, "reg", ®_base);
    printk(KERN_INFO "OF_DEBUG: reg read ret=%d, value=0x%x\n", ret, reg_base);

    // 3. 解析 GPIO phandle
    ret = of_parse_phandle_with_fixed_args(np, "gpios", "#gpio-cells", 0, &gpio_spec);
    if (ret) {
        printk(KERN_ERR "OF_DEBUG: gpios parse failed, ret=%d\n", ret);
        return ret;
    }
    printk(KERN_INFO "OF_DEBUG: gpio controller = %pOF\n", gpio_spec.np);
    printk(KERN_INFO "OF_DEBUG: gpio args = ");
    for (i = 0; i < gpio_spec.args_count; i++)
        printk("%u ", gpio_spec.args[i]);
    printk("\n");

    of_node_put(gpio_spec.np);
    return 0;
}

3.5 API 调用链与错误传播

在实际驱动中，of API 通常形成调用链：of_find_node_by_path → of_property_read_u32 → of_parse_phandle。任何一个环节失败都会导致后续操作无法进行。下表总结了常见错误及其调试方向：