1. 问题背景

本文记录一次 OpenHarmony 5.1 小型系统在 Hi3516CV610 平台集成 WS73 Wi-Fi/蓝牙模组的完整定位过程。目标不是只让三个内核模块完成编译，而是让最终烧录镜像能够在冷启动和热重启后稳定完成以下链路：

• SDIO 控制器初始化；
• WS73 设备枚举；
• 平台、Wi-Fi、蓝牙模块加载；
• 主固件和校准固件下载；
• 创建 wlan0、p2p0 等运行时接口。

这类问题的难点在于：DTS 源码正确、KO 编译成功，都不代表最终 FIT 镜像里的设备树正确，也不代表板端实际使用了预期的引脚复用和固件。

2. 先分清三个编号

调试 SDIO 时，最容易混淆的是物理控制器编号、Linux 运行时编号和供应商驱动内部编号。

在本项目中：

• 物理控制器是 SDIO1@0x10040000；
• Linux 枚举后可能显示为 mmc0；
• Nebula 驱动内部使用 devid = <2>；
• WS73 平台层调用 sdhci_nebula_sdio_rescan(2)。

因此，日志中的 sdio2 并不表示板上存在“物理 SDIO2”。判断硬件链路时，应优先结合寄存器地址、设备树节点和 /sys/class/mmc_host 的实际指向，而不是只看日志序号。

3. 设备树必须同时满足控制器、卡检测和冲突外设三类条件

对焊接式 WS73 模组，推荐在产品级 DTS 中明确声明不可拔插，并关闭会争用同一组引脚的外设。示意配置如下：

&sdio0 {
    status = "disabled";
};

&sdio1 {
    devid = <2>;
    status = "okay";
    non-removable;
};

&st7789 {
    status = "disabled";
};

其中 non-removable 很关键。若缺少该属性，MMC 核心可能仍按可拔插卡处理；当控制器的卡检测位为 0 时，扫描会在发送命令前提前结束，表现为“重扫已触发，但始终找不到卡”。

此外，还要检查 SoC 公共 DTSI 中驱动所依赖的 iocfg_regmap、syscon、clock、reset 和 pinctrl 等资源。曾遇到的首个错误链是：

get iocfg regmap failed. -19
sdio 2 not init
fail to detect sdio card
plat_init_etc fail

此时问题发生在控制器 probe 阶段，继续替换固件或修改上层 Wi-Fi 服务都没有意义。

4. GPIO 名称不能替代引脚复用事实

WS73 SDK 通常提供 power_gpio_idx 和 wkup_gpio_idx，但这些编号不能仅凭名称或参考配置直接套用。

本项目曾把 GPIO60/61 当作 POWER/WAKE 使用，结果模块能够枚举，却在下载固件的第一条 CMD53 写操作处稳定超时：

writesb ret=-110
firmware download fail

寄存器对照后发现，GPIO60/61 实际复用为物理 SDIO1 的 D0/D1。平台模块申请 GPIO 后改变了 pinmux，CMD52 等前置命令可能仍正常，但数据阶段必然失败。

最终配置为：

power_gpio_idx=-1
wkup_gpio_idx=-1

这里的 -1 表示本板不使用额外的 POWER/WAKE GPIO，并不表示模组没有供电。该配置必须同步到 SDK 默认配置、活动 .config、生成的 ws73_cfg.ini、vendor 安装源和最终 rootfs，不能只改某一个中间文件。

5. 固件目录名与运行国家码要分开验证

同一硬件下，某套固件可能完成下载却一直等待 BSP READY，另一套固件则可以正常启动。固件选择应以模组启动结果为依据，主固件、Wi-Fi 校准、蓝牙校准和 WOW 固件必须来自同一目录，不能混搭。

运行监管域则由 ws73_cfg.ini 等配置决定。也就是说，固件目录名不应被简单等同为运行国家码；两者需要分别验证。

6. 不只检查 DTS，要检查最终 FIT

构建目录中存在正确的 hi3516cv610-demb-flash.dtb，不代表 uImage 一定打包了它。建议在每次发布前从最终 FIT 反向提取设备树：

dumpimage -T flat_dt -p 0 -o final.dtb uImage
dtc -I dtb -O dts -o final.dts final.dtb

然后检查以下条件：

rg -n 'SDIO1@0x10040000|devid|non-removable|status' final.dts

如果构建系统中同时存在基础 DTB 和 flash 产品 DTB，还应把产品选择逻辑放进 kernel.mk，并让构建在 FIT 中的 DTB 与目标 DTB 不一致时直接失败。

7. 模块和板端验收

三个模块至少要检查架构、vermagic 和未解析符号：

file plat_soc.ko wifi_soc.ko ble_soc.ko
modinfo plat_soc.ko | rg vermagic
modinfo wifi_soc.ko | rg vermagic
modinfo ble_soc.ko | rg vermagic

板端则按以下顺序验收：

1. /sys/class/mmc_host 是否指向物理 SDIO1@0x10040000；
2. SDIO 设备是否枚举；
3. plat_soc、wifi_soc、ble_soc 是否处于 live 状态；
4. 日志是否出现固件下载成功、BSP READY、wlan READY；
5. wlan0、p2p0 是否出现；
6. 冷启动和至少两次热重启是否都能重复成功。

8. 总结

WS73 集成不能只看 KO 是否生成。可靠的闭环应同时覆盖：设备树资源、物理引脚复用、固接设备属性、驱动内部编号、固件组合、最终 FIT、模块 ABI 和板端冷/热启动。

遇到 -19 时先查控制器资源；已经枚举却在首个 CMD53 写入处报 -110 时，优先检查 pinmux 和冲突外设。把问题定位在正确层级，往往比反复更换驱动或固件更有效。