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显式指定； - 正确的引脚选择是串口调试输出的关键保障。