4. 设备树绑定与平台适配

在ARM嵌入式Linux系统中，MMC/SD/eMMC控制器的硬件配置与平台适配完全通过设备树（Device Tree）描述。设备树节点中的属性直接决定了驱动初始化时的时序参数、总线宽度、电源管理策略以及引脚复用功能。本章将深入解析MMC设备树节点的核心属性、pinctrl配置方法，并通过实际案例展示如何正确绑定与适配不同平台。

4.1 MMC设备树节点结构

一个典型的MMC控制器设备树节点包含兼容字符串、寄存器地址、中断号、时钟源、pinctrl引脚控制以及MMC协议相关属性。以下是一个基于SDHCI控制器的标准节点示例：

&sdhci0 {
    status = "okay";
    bus-width = <8>;
    non-removable;
    cap-mmc-highspeed;
    cap-sd-highspeed;
    sd-uhs-sdr104;
    sd-uhs-ddr50;
    max-frequency = <200000000>;
    no-1-8-v;
    keep-power-in-suspend;
    enable-sdio-wakeup;
    pinctrl-names = "default", "sleep";
    pinctrl-0 = <&sdhci0_pins_default>;
    pinctrl-1 = <&sdhci0_pins_sleep>;
    vmmc-supply = <&reg_vmmc>;
    vqmmc-supply = <&reg_vqmmc>;
};

4.2 核心属性详解

MMC设备树属性可分为总线配置类、能力声明类、电源管理类和时序约束类四大类。下表列出了最常用的属性及其含义：

4.3 bus-width属性与性能关系

bus-width属性直接决定数据传输的并行度。MMC协议支持1位、4位和8位总线模式。8位模式的理论吞吐量是4位模式的2倍，是1位模式的8倍。但实际性能还受控制器DMA能力、时钟频率和卡本身限制的影响。

下表对比了不同总线宽度在相同时钟频率下的理论带宽：

4.4 能力声明属性详解

能力声明属性（cap-*系列）用于告知驱动该控制器硬件支持哪些高速模式。驱动在初始化阶段会将这些能力与卡的能力进行协商，选择双方都支持的最高模式。

以下是常见能力属性的层级关系：

基础模式
├── cap-mmc-highspeed  (MMC 26MHz → 52MHz)
├── cap-sd-highspeed   (SD 25MHz → 50MHz)
└── cap-sdio-irq       (SDIO中断支持)

UHS-I模式（仅SD）
├── sd-uhs-sdr12       (12.5MHz, 1.8V)
├── sd-uhs-sdr25       (25MHz, 1.8V)
├── sd-uhs-sdr50       (50MHz, 1.8V)
├── sd-uhs-sdr104      (104MHz, 1.8V)
└── sd-uhs-ddr50       (50MHz, DDR, 1.8V)

eMMC高速模式
├── mmc-ddr-3-3v       (DDR52, 3.3V)
├── mmc-ddr-1-8v       (DDR52, 1.8V)
├── mmc-hs200-1-8v     (HS200, 200MHz, 1.8V)
└── mmc-hs400-1-8v     (HS400, 200MHz, DDR, 1.8V)

4.5 pinctrl配置与引脚复用

pinctrl子系统负责管理SoC引脚的复用功能、上下拉电阻和驱动强度。MMC控制器通常需要配置CLK、CMD、DATA[0:7]、CD（卡检测）、WP（写保护）等引脚。pinctrl配置在设备树中通过pinctrl-names和pinctrl-X属性引用。

以下是一个典型的pinctrl配置示例：

&pinctrl {
    sdhci0_pins_default: sdhci0-default {
        pinmux {
            function = "sdio0";
            pins = "GPIO0_0", "GPIO0_1", "GPIO0_2",
                   "GPIO0_3", "GPIO0_4", "GPIO0_5",
                   "GPIO0_6", "GPIO0_7", "GPIO0_8",
                   "GPIO0_9";
        };
        pinconf {
            pins = "GPIO0_0", "GPIO0_1", "GPIO0_2",
                   "GPIO0_3", "GPIO0_4", "GPIO0_5",
                   "GPIO0_6", "GPIO0_7", "GPIO0_8",
                   "GPIO0_9";
            drive-strength = <8>;   /* 驱动强度 8mA */
            bias-pull-up;            /* 内部上拉 */
            input-schmitt-enable;    /* 施密特触发 */
        };
    };

    sdhci0_pins_sleep: sdhci0-sleep {
        pinmux {
            function = "gpio";
            pins = "GPIO0_0", "GPIO0_1", "GPIO0_2",
                   "GPIO0_3", "GPIO0_4", "GPIO0_5",
                   "GPIO0_6", "GPIO0_7", "GPIO0_8",
                   "GPIO0_9";
        };
        pinconf {
            pins = "GPIO0_0", "GPIO0_1", "GPIO0_2",
                   "GPIO0_3", "GPIO0_4", "GPIO0_5",
                   "GPIO0_6", "GPIO0_7", "GPIO0_8",
                   "GPIO0_9";
            bias-pull-down;          /* 休眠时下拉 */
            input-disable;           /* 禁用输入 */
        };
    };
};

4.6 电源供应与电压切换

MMC设备需要两个电源域：vmmc-supply（核心电源，通常3.3V）和vqmmc-supply（I/O电源，3.3V或1.8V）。电压切换是UHS-I和HS200/HS400模式的关键步骤。

设备树中通过vqmmc-supply引用的调节器必须支持电压切换。驱动在初始化时调用regulator_set_voltage()将I/O电压从3.3V切换到1.8V。如果调节器不支持动态电压调整，驱动会回退到3.3V模式。

&sdhci0 {
    vmmc-supply = <&reg_3v3>;      /* 固定3.3V */
    vqmmc-supply = <&reg_vqmmc>;   /* 可切换1.8V/3.3V */
};

/* 调节器节点示例 */
reg_vqmmc: gpio-regulator {
    compatible = "regulator-gpio";
    regulator-name = "vqmmc";
    regulator-min-microvolt = <1800000>;
    regulator-max-microvolt = <3300000>;
    gpios = <&gpio1 10 GPIO_ACTIVE_HIGH>;
    states = <1800000 0x0>,
             <3300000 0x1>;
};

4.7 设备树绑定与驱动初始化流程

理解设备树属性如何被驱动解析，有助于排查配置问题。以下SVG图展示了MMC驱动从设备树解析到硬件初始化的完整流程：

4.8 平台适配实战案例

以下展示两个不同平台的MMC设备树配置对比，帮助理解平台差异对属性配置的影响：

4.9 常见配置错误与调试方法

设备树配置错误是MMC驱动问题的常见根源。以下列出典型错误及其排查方法：

• 总线宽度不匹配：声明bus-width = <8>但PCB只连接了4条数据线，导致卡识别失败。应检查原理图确认实际连线。
• 电压切换失败：声明sd-uhs-sdr104但vqmmc-supply调节器不支持1.8V输出，驱动日志会打印Voltage switch failed。应添加no-1-8-v属性强制使用3.3V。
• pinctrl冲突：多个外设复用了同一组引脚，导致MMC信号被其他模块干扰。使用cat /sys/kernel/debug/pinctrl/*/pinmux-pins检查引脚分配。
• 时钟频率过高：max-frequency设置超过控制器或卡的能力，导致数据传输错误。从较低频率（如25MHz）开始逐步提升。

/* 调试技巧：在驱动中打印设备树解析结果 */
static int sdhci_probe(struct platform_device *pdev)
{
    struct device_node *np = pdev->dev.of_node;
    u32 bus_width, max_freq;
    
    of_property_read_u32(np, "bus-width", &bus_width);
    of_property_read_u32(np, "max-frequency", &max_freq);
    
    dev_info(&pdev->dev, "bus-width: %d, max-frequency: %d\n",
             bus_width, max_freq);
    
    if (of_property_read_bool(np, "non-removable"))
        dev_info(&pdev->dev, "non-removable device\n");
    
    if (of_property_read_bool(np, "cap-mmc-highspeed"))
        dev_info(&pdev->dev, "MMC highspeed supported\n");
    
    /* 继续初始化... */
}

4.10 性能调优属性组合

针对不同使用场景，推荐以下属性组合：