【设备树】SDIO节点属性

文章目录

主机控制器节点属性
SDIO功能设备节点属性
完整示例
Rockchip平台的SDIO节点属性特征
- 核心控制器属性 (SoC级)
- 板级功能属性
- [Rockchip 特有属性](#Rockchip 特有属性)
- 子节点 (SDIO功能设备)
- 实践注意事项

在Linux设备树中，SDIO（安全数字输入输出）相关的属性分布在两个层级： 主机控制器层 和 SDIO功能设备层 。主机控制器节点描述SDIO接口的硬件资源（如寄存器、中断、时钟等），而功能设备节点则作为控制器的子节点，描述具体的SDIO外设（如WiFi/蓝牙模块）及其私有属性。

主机控制器节点属性

主机控制器节点（通常兼容mmc-controller）包含以下通用和特定属性：

属性名	描述	示例值
`compatible`	用于匹配驱动程序的兼容性字符串。	`"realtek,ameba-sdiohost"` 或 `"fsl,imx8qm-usdhc"`
`reg`	寄存器地址范围，描述控制器的寄存器资源。	`<0x400D0000 0x8000>`
`interrupts`	控制器使用的中断号及触发类型。	`<GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>`
`clocks`	指向控制器使用的时钟源。	`<&clk IMX8QXP_SDHC0_IPG_CLK>`
`bus-width`	使用的数据线位数，可选`1`、`4`或`8`。	`<4>` 或 `<8>`
`non-removable`	布尔属性，表示设备是永久连接的（如eMMC或板载WiFi），不可移除。	无需值，存在即有效
`broken-cd`	表示卡检测（Card Detect）引脚无效，需使用轮询方式检测卡。	无需值，存在即有效
`no-1-8-v`	表示控制器不支持1.8V电压。	无需值，存在即有效
`disable-wp`	表示写保护（Write Protect）引脚未连接或无需使用。	无需值，存在即有效
`keep-power-in-suspend`	在系统挂起时保持SDIO卡的电源，常用于支持唤醒功能的设备。	无需值，存在即有效
`max-frequency`	控制器支持的最大时钟频率。	`<50000000>`
`pinctrl-0`	指向引脚控制配置的phandle，用于设置引脚复用和电气特性。	`<&pinctrl_usdhc1>`
`cd-gpios`	卡检测所使用的GPIO，当硬件没有专用CD引脚时使用。	`<&gpio1 3 GPIO_ACTIVE_LOW>`
`wp-gpios`	写保护所使用的GPIO。	`<&gpio1 4 GPIO_ACTIVE_HIGH>`
`status`	设备状态，设为`"okay"`启用，`"disabled"`禁用。	`"okay"`

SDIO功能设备节点属性

对于连接到SDIO总线上的具体功能设备（如蓝牙、WiFi），它们作为主机控制器节点的子节点存在，需要通过reg属性指定其SDIO功能号。

属性名	描述	示例值
`compatible`	用于匹配该SDIO功能设备驱动的字符串。	`"mediatek,mt7921s-bluetooth"`
`reg`	必需。该设备在SDIO协议中的功能号（Function Number）。	`<2>` (表示功能2)
`reset-gpios`	用于复位该功能设备的GPIO引脚。	`<&pio 8 GPIO_ACTIVE_LOW>`
`interrupt-parent`	该功能设备专用中断的父节点。	`<&gpio5>`
`interrupts`	该功能设备专用的额外中断（sideband signal）。	`<0 8>`

完整示例

以下是一个完整的设备树结构示例，展示了主机控制器节点和SDIO蓝牙功能节点的配置：

dts 复制代码

// 主机控制器节点 (eMMC/SD/SDIO 控制器)
&usdhc1 {  // 通过标签引用
    pinctrl-names = "default", "sleep";
    // 引脚复用配置
    pinctrl-0 = <&pinctrl_usdhc1 &pinctrl_wifi_ctrl>; 
    pinctrl-1 = <&pinctrl_usdhc1_sleep &pinctrl_wifi_ctrl_sleep>;
    
    bus-width = <4>;          // 使用4位数据线
    non-removable;            // 设备不可移除（如板载WiFi）
    no-1-8-v;                 // 不支持1.8V
    status = "okay";          // 启用该控制器
    #address-cells = <1>;     // 子节点地址占1个cell
    #size-cells = <0>;        // 子节点无大小信息

    // SDIO功能设备节点 (例如：蓝牙)
    bluetooth@2 {             // @2 表示功能号为2
        compatible = "mediatek,mt7921s-bluetooth";
        reg = <2>;            // SDIO功能号2
        reset-gpios = <&pio 8 GPIO_ACTIVE_LOW>; // 专用复位引脚
    };
};

注意：以上属性是Linux内核MMC子系统中常见的标准属性。实际开发中，具体的属性名和取值应以芯片厂商提供的绑定文档 （通常位于内核源码 Documentation/devicetree/bindings/mmc/ 目录下）为准。

Rockchip平台的SDIO节点属性特征

Rockchip平台的SDIO节点属性，在遵循标准MMC/SDIO设备树绑定的基础上，增加了一些特有的扩展。其核心控制器通常兼容"rockchip,rk3288-dw-mshc"，具体的绑定定义在内核文档 Documentation/devicetree/bindings/mmc/rockchip-dw-mshc.yaml 中。

下面我将Rockchip SDIO相关的属性分为核心控制器属性 和板级功能属性进行说明，并补充一些实践中的注意事项。

核心控制器属性 (SoC级)

这部分属性通常在芯片级设备树文件（如 rkxxxx.dtsi）中定义，描述了控制器本身的硬件资源。

属性名	描述	示例值
`compatible`	兼容性字符串，用于匹配驱动。通常包含SoC特定版本和一个通用版本。	`"rockchip,rk3528-dw-mshc"`, `"rockchip,rk3288-dw-mshc"`
`reg`	控制器寄存器的物理地址和范围。	`<0x0 0xffc10000 0x0 0x4000>`
`interrupts`	控制器使用的中断号。	`<GIC_SPI 137 IRQ_TYPE_LEVEL_HIGH>`
`clocks`	指向控制器使用的时钟句柄。通常包括 `biu`（总线接口单元）和 `ciu`（卡接口单元）等。	`<&cru HCLK_SDIO0>, <&cru CCLK_SRC_SDIO0>`
`clock-names`	时钟的名称，必须与 `clocks` 属性对应。对于Rockchip，可能包含 `"biu"`, `"ciu"`, `"ciu-drive"`, `"ciu-sample"` 。	`"biu"`, `"ciu"`, `"ciu-drive"`, `"ciu-sample"`
`fifo-depth`	控制器的FIFO深度。	`<0x100>`
`resets`	指向控制器使用的复位句柄。	`<&cru SRST_H_SDIO0>`
`reset-names`	复位的名称。	`"reset"`
`pinctrl-0`	引脚控制配置，需在板级文件中结合 `pinctrl` 子节点进行具体引脚功能（如时钟、命令、数据线）的复用设置。	`<&sdio0_bus4>, <&sdio0_clk>, <&sdio0_cmd>`
`pinctrl-names`	引脚控制状态的名称，通常为 `"default"` 。	`"default"`

板级功能属性

这部分属性通常在板级设备树文件（如 rkxxxx-evb.dtsi 或自定义板级 dts）中设置，用于使能控制器并配置具体的功能特性。

属性名	描述	示例值
`status`	设备状态，设为 `"okay"` 启用。	`"okay"`
`max-frequency`	控制器支持的最大时钟频率。	`<150000000>`
`bus-width`	使用的数据线位数，SDIO通常为 `4` 。	`<4>`
`non-removable`	关键属性。表示设备是永久连接的（如板载WiFi模块），不可移除。	(无值)
`cap-sdio-irq`	标识该SDIO外设支持带内中断。如果外设使用专用中断引脚（带外中断），则不应添加此项。	(无值)
`keep-power-in-suspend`	在系统挂起时保持SDIO卡的电源，常用于支持唤醒功能的设备。	(无值)
`mmc-pwrseq`	指向电源序列节点，用于控制SDIO外设（如WiFi模块）的上电/复位时序。	`<&sdio_pwrseq>`
`supports-sdio`	关键属性。明确标识此插槽用于SDIO功能，否则可能无法初始化SDIO外设。	(无值)
`sd-uhs-sdr104`	标识支持UHS-I SDR104模式（通常意味着SDIO 3.0及1.8V信令），需要硬件支持电压切换。	(无值)
`cap-sd-highspeed`	标识支持SD高速模式（SD 2.0， 50MHz， 3.3V信令）。	(无值)
`disable-wp`	表示写保护引脚未连接。	(无值)

Rockchip 特有属性

Rockchip的绑定中定义了一些用于时钟相位调优的特有属性，这对高速模式的稳定性至关重要。

属性名	描述	示例值
`rockchip,default-sample-phase`	在探针阶段、低速模式或 tuning 无法找到合适相位时，为 `"ciu-sample"` 时钟设置的默认相位值，单位为度，范围 0-360 。	`<90>`
`rockchip,desired-num-phases`	执行 tuning 时希望尝试的相位点数量，默认为360（即每个度数尝试一次）。	`<360>`

子节点 (SDIO功能设备)

与通用规范相同，具体的SDIO功能设备（如蓝牙、WiFi）作为控制器节点的子节点，通过 reg 属性指定SDIO功能号。

dts 复制代码

&sdio0 {
    status = "okay";
    // ... 控制器级属性 ...

    // SDIO功能设备节点，例如蓝牙
    bluetooth@2 { // @2 表示功能号为2
        compatible = "brcm,bcm43438-bt"; // 厂商提供的兼容性字符串
        reg = <2>; // SDIO功能号2
        // 其他外设私有属性，如复位引脚、时钟等
        reset-gpios = <&gpio0 RK_PB2 GPIO_ACTIVE_LOW>;
    };
};

实践注意事项

关键属性不能少 ：对于SDIO设备，non-removable 和 supports-sdio 通常是必须添加的，否则内核可能无法正确识别和处理设备。
中断类型确认 ：务必确认你的SDIO外设（如WiFi/BT模块）使用的是 SDIO带内中断 （需配置 cap-sdio-irq）还是通过专用GPIO的带外中断 （OOB，此时不应配置 cap-sdio-irq）。错误配置会导致中断无法正常工作。
电源和复位 ：很多SDIO模块（特别是WiFi）有复杂的上电时序要求。使用 mmc-pwrseq 子节点来描述这些时序是一种规范且可靠的做法。也可以直接通过外设子节点中的 xxx-gpios 属性来控制。
时钟相位调优 ：在高速模式（如SDR104）下，rockchip,default-sample-phase 等属性的正确配置对通信稳定性非常关键。这通常需要根据硬件设计进行调试和确认。
U-Boot特有属性 ：在U-Boot的SPL（Secondary Program Loader）阶段，可能会用到 u-boot,spl-fifo-mode 等属性来强制使用FIFO模式（PIO）以绕过DMA问题。这些是Bootloader特有的，内核设备树中不会使用。