Linux基础 -- 设备树引脚复用之`/omit-if-no-ref/` 用法解析

RK3588 设备树中 UART 引脚复用定义与 /omit-if-no-ref/ 用法解析

在进行 RK3588 嵌入式平台开发时，串口（UART）调试是 Bring-up 阶段的核心手段。而 RK3588 SoC 支持多个引脚复用配置（pinmux），通过设备树灵活选择，合理配置对于调试成功至关重要。

本文以 UART2 为例，讲解其设备树引脚配置方式、复用模式选择机制、以及 /omit-if-no-ref/ 的作用与使用方法。

---

一、设备树引脚复用定义示例

设备树（通常为 rk3588s-pinctrl.dtsi）中，对 UART2 的多个引脚复用模式进行预定义：

uart2 {
    /omit-if-no-ref/
    uart2m0_xfer: uart2m0-xfer {
        rockchip,pins =
            /* uart2_rx_m0 */
            <0 RK_PB6 10 &pcfg_pull_up>,
            /* uart2_tx_m0 */
            <0 RK_PB5 10 &pcfg_pull_up>;
    };

    /omit-if-no-ref/
    uart2m1_xfer: uart2m1-xfer {
        rockchip,pins =
            /* uart2_rx_m1 */
            <4 RK_PD1 10 &pcfg_pull_up>,
            /* uart2_tx_m1 */
            <4 RK_PD0 10 &pcfg_pull_up>;
    };

    /omit-if-no-ref/
    uart2m2_xfer: uart2m2-xfer {
        rockchip,pins =
            /* uart2_rx_m2 */
            <3 RK_PB2 10 &pcfg_pull_up>,
            /* uart2_tx_m2 */
            <3 RK_PB1 10 &pcfg_pull_up>;
    };

    /omit-if-no-ref/
    uart2_ctsn: uart2-ctsn {
        rockchip,pins =
            /* uart2_ctsn */
            <3 RK_PB4 10 &pcfg_pull_none>;
    };

    /omit-if-no-ref/
    uart2_rtsn: uart2-rtsn {
        rockchip,pins =
            /* uart2_rtsn */
            <3 RK_PB3 10 &pcfg_pull_none>;
    };
};

---

二、关键概念解释

1. 多个复用模式（如 uart2m0、m1、m2）

RK3588 中每个 UART 支持多个 引脚复用配置（不同 GPIO 管脚连接），例如：

名称	GPIO Bank	GPIO Pin	模式编号	对应功能
uart2m0_xfer	GPIO0_B6	PB6	10	uart2_rx_m0
uart2m0_xfer	GPIO0_B5	PB5	10	uart2_tx_m0
uart2m1_xfer	GPIO4_D1	PD1	10	uart2_rx_m1
uart2m1_xfer	GPIO4_D0	PD0	10	uart2_tx_m1
uart2m2_xfer	GPIO3_B2	PB2	10	uart2_rx_m2
uart2m2_xfer	GPIO3_B1	PB1	10	uart2_tx_m2

这些 uart2mX_xfer 节点是为不同硬件连线方案预先定义的 pinmux 配置，供开发者按实际布线选择使用。

---

2. /omit-if-no-ref/ 的含义

设备树编译器（DTC）的指令，含义如下：

如果该节点没有被设备树的其它部分引用，在编译 .dtb 时将自动省略该节点。

它的作用是：

• 提高设备树精简度；
• 避免生成不必要的 pinctrl 配置；
• 防止未使用的 pinmux 造成冲突。

---

三、如何在设备树中选择 UART2 引脚

要启用 UART2 并绑定某一组引脚，需要在设备树主文件中这样写：

&uart2 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&uart2m1_xfer>;  // 选择 uart2 使用 mode1 对应的引脚
};

注意：

• 如果不写 pinctrl-0 或引用了不存在的节点，UART2 将无法工作；
• 仅被引用的 uart2mX_xfer 才会在最终 .dtb 中生成；
• 没被引用的节点因 /omit-if-no-ref/ 会自动剔除。

---

四、常见问题与排查建议

问题	原因	解决方法
UART 无法打印调试信息	未配置 pinctrl-0，或引用错误的 uart2mX_xfer	检查是否引用了实际布线所用引脚定义
编译后的 dtb 文件缺少 uart2mX_xfer 节点	未被引用 + 使用了 /omit-if-no-ref/	添加有效引用（如 pinctrl-0 = <&uart2m1_xfer>）
引脚功能冲突	多个设备使用相同 GPIO	确保 pinctrl 定义中引脚唯一性

---

五、小结

• RK3588 支持多种引脚复用方案；
• uart2mX_xfer 定义了不同 pinmux 模式；
• /omit-if-no-ref/ 是设备树中用来精简未使用节点的常用指令；
• 开发者应根据实际硬件选择一组引脚，并通过 pinctrl-0 显式指定；
• 正确的引脚选择是串口调试输出的关键保障。