4、标准属性详解：compatible、reg、interrupts、status、clocks、pinctrl-0/pinctrl-names的标准用法

设备树（Device Tree）中的标准属性是描述硬件设备与系统资源之间关系的核心语法。在UART调试驱动的移植适配过程中，正确理解和填写这些属性是驱动能够成功匹配、初始化并正常工作的前提。本章将逐一拆解compatible、reg、interrupts、status、clocks以及pinctrl-0/pinctrl-names这六个最常用的标准属性，结合UART场景给出标准用法。

4.1 compatible —— 驱动匹配的“身份证”

compatible属性是设备树中最重要的属性之一，它用于将设备节点与内核中的驱动程序进行绑定。该属性是一个字符串列表，内核在启动时会遍历设备树中的每个节点，并尝试将节点的compatible值与驱动注册时声明的of_match_table进行匹配。

标准格式：

compatible = "厂商,型号", "通用型号";

UART场景示例：

uart0: serial@10000000 {
    compatible = "fsl,imx6q-uart", "fsl,imx21-uart";
    reg = <0x10000000 0x4000>;
    interrupts = <0 58 4>;
    status = "okay";
};

匹配规则：

  • 内核优先使用第一个字符串（最精确的型号）进行匹配。
  • 如果第一个匹配失败，则依次尝试后续的“通用型号”。
  • UART驱动通常会在of_match_table中列出多个兼容字符串，以支持同一IP核的不同SoC变体。
实践建议：在移植UART驱动时，务必确认SoC的UART IP核版本，优先使用“厂商,型号”的精确写法。如果驱动支持多个版本，可以保留“通用型号”作为后备。
compatible 属性驱动匹配流程 设备树节点 compatible = "A,B" 匹配判断 of_match_table 匹配成功 → 驱动绑定 匹配失败 → 尝试下一个 说明： • 内核按顺序尝试 compatible 列表中的每个字符串。 • 第一个匹配成功即停止，不再尝试后续字符串。 • 建议将最精确的型号放在第一位，通用型号作为后备。

4.2 reg —— 寄存器地址与内存映射

reg属性用于描述设备在系统总线上的地址空间，包括起始地址和长度。对于UART设备，reg通常定义UART控制器的寄存器基地址和映射范围。

标准格式：

reg = <地址1 长度1> [, <地址2 长度2> ...];

UART场景示例：

uart1: serial@10004000 {
    compatible = "arm,pl011", "arm,primecell";
    reg = <0x10004000 0x1000>;
    interrupts = <0 59 4>;
    clocks = <&uart_clk>;
    status = "okay";
};

关键点：

  • 地址：UART控制器的基地址，通常由SoC数据手册给出。
  • 长度：映射的地址空间大小，一般覆盖所有UART寄存器（如PL011为0x1000）。
  • 多段reg：某些UART IP核可能包含多个地址段（如FIFO区域和配置区域分开），此时需要按顺序列出。
UART IP核 典型reg长度 说明
ARM PL011 0x1000 标准PrimeCell UART
ns16550 0x100 PC标准UART兼容
fsl,imx6q-uart 0x4000 i.MX6系列UART
常见错误：reg长度设置过小会导致驱动无法访问全部寄存器，引发功能异常；长度设置过大则浪费虚拟地址空间。务必参考数据手册确认寄存器地址范围。

4.3 interrupts —— 中断资源的声明

interrupts属性用于描述设备使用的中断资源，包括中断控制器、中断号和触发类型。UART设备通常使用中断方式接收和发送数据，因此正确配置中断属性至关重要。

标准格式：

interrupts = <中断控制器标识 中断号 触发类型>;

UART场景示例：

uart2: serial@10008000 {
    compatible = "arm,pl011";
    reg = <0x10008000 0x1000>;
    interrupts = <0 60 4>;
    interrupt-parent = <&gic>;
    status = "okay";
};

触发类型编码：

  • 0：未指定
  • 1：上升沿触发
  • 2：下降沿触发
  • 4：高电平触发
  • 8：低电平触发

UART常用触发类型：大多数UART控制器使用高电平触发（4）或上升沿触发（1），具体取决于IP核设计。

UART中断路由结构 UART 控制器 interrupts = <0 60 4> GIC 中断控制器 interrupt-parent = <&gic> CPU 内核 中断处理 中断属性解析： • 第一个字段（0）：中断控制器标识（SPI类型） • 第二个字段（60）：中断号，对应SoC数据手册 • 第三个字段（4）：触发类型（高电平触发）

4.4 status —— 设备启用状态控制

status属性用于控制设备节点的启用或禁用状态。在UART调试中，经常需要通过修改status属性来临时启用或关闭某个UART端口。

标准取值：

取值 含义 UART场景说明
"okay" 设备启用 UART端口正常工作
"disabled" 设备禁用 UART端口不初始化，节省资源
"reserved" 保留给其他用途 UART端口被其他固件占用
"fail" 设备检测失败 UART硬件不存在或损坏

实践用法：

/* 在SoC级dtsi中默认禁用 */
uart3: serial@1000c000 {
    compatible = "arm,pl011";
    reg = <0x1000c000 0x1000>;
    interrupts = <0 61 4>;
    status = "disabled";  /* 默认禁用 */
};

/* 在板级dts中按需启用 */
&uart3 {
    status = "okay";  /* 板级启用 */
};
调试技巧：在UART调试初期，建议只启用一个调试UART端口，其他端口保持disabled状态，避免中断冲突或资源竞争。确认调试UART正常工作后，再逐个启用其他端口。

4.5 clocks —— 时钟源配置

clocks属性用于指定设备使用的时钟源。UART控制器通常需要至少一个时钟源来驱动波特率发生器，部分UART IP核还需要额外的时钟用于总线接口。

标准格式：

clocks = <&时钟控制器1 时钟ID1> [, <&时钟控制器2 时钟ID2> ...];

UART场景示例：

uart4: serial@10010000 {
    compatible = "arm,pl011";
    reg = <0x10010000 0x1000>;
    interrupts = <0 62 4>;
    clocks = <&clk 38>;  /* 时钟ID 38 对应UART时钟 */
    clock-names = "uartclk";
    status = "okay";
};

时钟属性对比：

属性 作用 UART典型值
clocks 指定时钟源 UART外设时钟
clock-names 为时钟命名 "uartclk", "apb_pclk"
assigned-clocks 分配时钟频率 设置UART时钟频率
assigned-clock-rates 指定时钟频率值 <24000000> (24MHz)
时钟配置陷阱：UART的波特率精度直接依赖于时钟频率。如果时钟频率设置错误，会导致波特率偏差过大，出现乱码或无法通信。建议在调试阶段通过assigned-clock-rates显式指定时钟频率。

4.6 pinctrl-0 / pinctrl-names —— 引脚复用控制

pinctrl-0和pinctrl-names属性用于控制设备引脚的复用功能配置。UART的TX、RX、RTS、CTS等引脚通常需要从GPIO模式切换到UART功能模式。

标准格式：

pinctrl-names = "default", "sleep";
pinctrl-0 = <&uart0_pins>;
pinctrl-1 = <&uart0_sleep_pins>;

UART场景示例：

uart5: serial@10014000 {
    compatible = "arm,pl011";
    reg = <0x10014000 0x1000>;
    interrupts = <0 63 4>;
    clocks = <&clk 38>;
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&uart5_pins_active>;
    pinctrl-1 = <&uart5_pins_sleep>;
    status = "okay";
};

引脚配置节点示例：

&iomuxc {
    uart5_pins_active: uart5-active {
        fsl,pins = <
            MX6QDL_PAD_KEY_ROW0__UART5_TX  0x1b0b1
            MX6QDL_PAD_KEY_COL0__UART5_RX  0x1b0b1
        >;
    };

    uart5_pins_sleep: uart5-sleep {
        fsl,pins = <
            MX6QDL_PAD_KEY_ROW0__GPIO4_IO07 0x10059
            MX6QDL_PAD_KEY_COL0__GPIO4_IO06 0x10059
        >;
    };
};
pinctrl 状态切换机制 pinctrl-0 "default" 状态 UART 设备 运行时切换 pinctrl-1 "sleep" 状态 pinctrl 状态管理： • pinctrl-names 定义状态名称列表，与 pinctrl-0、pinctrl-1 等一一对应。 • 系统在设备初始化时应用 "default" 状态，进入低功耗时切换到 "sleep" 状态。

4.7 属性综合配置示例

以下是一个完整的UART设备树节点示例，综合展示了所有标准属性的标准用法：

/* 完整的UART设备树节点 */
uart6: serial@10018000 {
    compatible = "arm,pl011", "arm,primecell";
    reg = <0x10018000 0x1000>;
    interrupts = <0 64 4>;
    interrupt-parent = <&gic>;
    clocks = <&clk 38>;
    clock-names = "uartclk";
    assigned-clocks = <&clk 38>;
    assigned-clock-rates = <24000000>;
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&uart6_pins_active>;
    pinctrl-1 = <&uart6_pins_sleep>;
    dmas = <&edma 0 12>, <&edma 0 13>;
    dma-names = "tx", "rx";
    status = "okay";
};
属性配置检查清单：
  • ✅ compatible：确认UART IP核型号，填写精确和通用字符串。
  • ✅ reg：核对数据手册中的寄存器基地址和映射长度。
  • ✅ interrupts：确认中断号、触发类型与中断控制器匹配。
  • ✅ clocks：确保时钟源存在且频率正确。
  • ✅ pinctrl：验证引脚复用配置与硬件原理图一致。
  • ✅ status：调试阶段只启用必要的UART端口。

掌握这六个标准属性的标准用法，是进行UART设备树移植适配的基础。在实际项目中，这些属性往往需要根据具体的SoC数据手册和硬件设计进行微调，但核心语法和匹配逻辑是通用的。

← 上一章 📖 返回目录 下一章 →