更换 Wi-Fi 模组：Linux 驱动与设备树验证

更换 Linux 产品上的 Wi-Fi 模组，会同时改变硬件、驱动、固件和运行策略。即使模组能够放进原有封装，也可能需要不同的上电顺序、固件文件、总线配置或用户空间能力。成功扫描到网络只是第一个检查点。

本文介绍使用 SDIO、USB 或 PCIe Wi-Fi 设备的嵌入式 Linux 产品如何进行工程验证，并不假定所有模组采用相同 Linux 无线栈或设备树模型。建议测试属于验收计划，不是实测吞吐量、法规认证或可直接替换的承诺。

1. 修改软件之前，先制作替换对照表

按完整订货型号和硬件版本比较旧模组与候选模组。记录主机接口、电源轨、I/O 电压、复位与使能信号、参考时钟、中断或唤醒信号、天线连接和共存接口。逐个核对引脚功能。外形和连接器兼容，并不能证明电气兼容。

列出产品角色：客户端、接入点、并发接口、休眠唤醒、漫游，以及需要时的蓝牙共存。能够作为客户端关联的驱动，不一定支持要求的 AP 模式或接口组合。在评估驱动可用性之前，先确定目标内核和 BSP 分支。

取得模组供应商的集成文档及固件再分发条款。记录板级专用校准或非易失配置文件，以及它们如何对应装配板。不要仅因为芯片名称相同，就复用另一产品的校准数据。

2. 建立驱动与固件基线

确认目标驱动位于所选内核源码树、由 BSP 提供，还是在树外维护。记录确切提交版本、配置、支持的设备 ID 和依赖。针对其他内核构建的树外模块，可能因 API、配置或模块版本差异而失败；复制二进制文件不是移植策略。

区分主机驱动与在无线芯片内部执行的固件。Linux 固件加载 API 提供按名称请求固件的机制，但正确文件和板级配置仍由驱动及设备决定。参见内核 固件请求文档。应记录请求文件名和最初探测错误，而不是反复给无关固件文件改名，直到某条警告消失。

建立发布清单，包含内核、模块、DTB、无线固件、板级数据和用户空间网络配置。确认根文件系统中安装的文件与清单一致。能够工作的开发文件系统，可能掩盖干净生产镜像中缺少固件的问题。

3. 只修改真正适用的硬件描述

对于 SDIO 模组，检查主机控制器、总线宽度、电源引用、引脚配置、上电时序、可移除介质假设，以及带外中断或唤醒接线。使用实际内核树中的绑定。一个厂商驱动接受的属性，并不会自动对另一驱动生效。

USB 和 PCIe 设备通常通过总线枚举，但板级电源、复位或主机控制器资源仍可能需要描述。不要为了强制加载 USB 驱动，就任意添加 Wi-Fi 节点。首先判断总线能否发现设备，以及其标识是否与目标驱动匹配。

使用所选源码树的工具编译并校验修改后的设备树。Linux 绑定模式指南说明了 dtbs_check 等检查。模式检查通过，只能说明与现有绑定在结构上保持一致，不能验证复位极性、电压或 PCB 连接。

保留经审查的差异，列出每个修改节点与对应原理图网络或供应商要求。如果新模组需要改板，应明确记录依赖，而不是把它描述成纯软件替换。

4. 按总线、探测、无线、网络顺序定位

先检查总线枚举。设备不存在时，应先调查供电、复位、时钟和主机控制器配置，再调试认证。如果设备枚举成功却未绑定驱动，应检查设备 ID、配置和模块是否可用。如果驱动绑定但固件加载失败，应检查请求文件名、软件包内容及板级数据选择。

无线接口出现后，验证能力及当前链路。对于提供标准 nl80211 接口的驱动，以下只读命令很有帮助；请把接口名替换为实际名称。部分厂商驱动需要使用自己的受支持工具。

uname -r
ip link show
iw dev
iw phy
# Example interface name only:
iw dev wlan0 link
iw reg get

Linux Wireless 的 iw 文档介绍了能力和链路检查。列出某项能力，并不证明实际装配天线系统或应用满足性能要求。

随后分别检查关联、地址配置、路由、DNS 和应用连接。无线链路成功时，DHCP 仍可能失败。能 ping 通本地对端，不代表要求的 TLS 应用端点可达，也不代表证书校验所需时间正确。

5. 验证产品真正使用的角色

采用部署需求中的实际接入点型号和安全模式，在合法且受支持的条件下测试每个必需频段和信道宽度。AP 模式应检查客户端关联、重连行为和支持的接口组合。漫游测试应记录应用中断及数据包行为，而不只是看到接入点地址发生变化。

在明确的距离、天线朝向、射频环境、流量方向和对端配置下，同时测量吞吐量、延迟、丢包、CPU 负载与功耗。记录测试工具及版本。将可重复的有线参考路径与无线链路分开，避免把服务器慢误判为射频限制。

如果蓝牙共享模组或天线，应纳入要求的同时使用场景。仅运行 Wi-Fi 测试不能证明共存行为。没有条件说明和实际证据，不应公布吞吐量或距离数值。

6. 纳入恢复及异常测试

• 接入点消失：验证重试有界、应用超时行为，以及 AP 恢复后的重连。
• 凭据无效：显示可操作的状态，避免无限高频重连，也不要在日志中暴露秘密。
• 地址服务缺失：区分无线关联与 DHCP 不可用，并测试产品文档规定的回退行为。
• 固件缺失：在可弃用镜像上确认启动诊断能指出缺失依赖。
• 休眠与唤醒：测试每个要求的唤醒源，确认接口和应用均恢复。
• 冷启动和热重启：两者都要测试；持续供电的模组可能掩盖不完整的冷启动顺序。

在获准的测试网络中执行故障测试，并保留有线或物理恢复通道。没有恢复计划时，不要在唯一远程管理链路上卸载驱动或更换固件。

7. 将法规配置作为独立需求

部署国家、允许信道、天线设计和供应商限制都会影响成品。Linux 法规配置有助于约束运行，但不等于产品认证。不要为了通过测试而强制使用不支持的信道或功率。Linux Wireless 法规文档说明法规信息的处理方式，而产品具体义务应由模组供应商及适当的合规专业人员确定。

支持替换决策的验收证据

交付替换对照表、原理图和设备树差异、驱动与固件清单、启动日志、按角色组织的测试、故障结果和已知限制。如果比较新旧模组，应使用同一夹具和工作负载，并披露无法避免的差异。

欧蓓特的 RK3528 Linux 网络网关项目方案列出了 AP6275S 无线硬件方向，并区分客户端/AP 与蓝牙软件路径。因此它是有用的范围示例，不是替代模组兼容的证明。替换评估可参阅 固件与 BSP 诊断服务，并提供新旧模组完整订货型号、原理图、内核/BSP 版本和必需无线角色。