实习周报（2026-08-29）

本周工作：对主线 WiFi 驱动重构后的板端适配

继 NAPI 和同步原语重构后，主线的 SDIO 和 wifi 驱动在 26 号又有大规模重构（#2201），有多处问题导致板子开机阶段便 panic，因此本周优先处理了 WiFi 初始化流程，目前已修复了开机多处 panic 和其它问题：始化步骤推进方式错误、启动失败原因不可见、写寄存器返回校验与适配层格式不一致、芯片版本号读取位置错误、设备 MAC 未获取、设备故障事件上报被队列积压阻断。

#2225

1. 初始化卡死 60 秒后 panic

问题：初始化流程在早期阶段停滞，直至 60 秒启动超时保护触发后报错退出。驱动初始化的执行方式为"提交一步操作后等待其完成事件"，而初始化早期的大部分操作（总线复位、上电、电压切换、总线宽度与时钟设置、CMD52 寄存器读写）为纯寄存器级总线操作，硬件完成时不产生中断。驱动提交此类操作后进入等待状态，等待的中断不会到来，流程停滞在首个此类操作上。板测表现为启动后 67 秒 panic，串口日志在初始化早期即无进展。

修复：修改初始化推进函数：每提交一个新步骤立即以 ProgressCause::Submitted 推进一次，纯寄存器操作在该次推进中同步完成，随后提交并推进下一步骤，循环至首个需要等待完成中断的命令步骤（CMD5）为止。仅单次调用的首次推进使用调用方提供的中断原因。修复后纯寄存器步骤连续同步推进，命令步骤正常等待中断。

2. 增加启动失败原因日志

问题：网络队列初始化失败时仅 "network queue initialization failed"，没有细节，看不到错误出处。

修复：QueueInit 错误增加 NetError 字段携带真实原因。executor 初始化失败时将原因写入 startup_error，runtime builder 取回后随 panic 输出，发生 panic 可以看到填入的失败原因。

3. 修正写寄存器返回校验，与适配层格式保持一致

问题：启动流程在厂商初始化写寄存器环节触发 MalformedResponse panic（板测 37-40 毫秒），原因是格式不一致：驱动的适配层将全部 Direct 操作（含写）的 completion 统一映射为 Byte（CMD52 R5 响应恒携带数据字节，且写操作以 read_after_write 提交），而核心侧四个写寄存器使用位置（VendorSetup、Reinitialize、ArmChipInterrupt、Shutdown）按 Unit 校验，因此全部写操作被判定为响应损坏。该问题是主线的遗留问题。

修复：新增 expect_write_ack（接受 Byte、丢弃回读值），四个使用位置统一改用；request.rs 固化"请求类型 → 完成格式"对照表；MalformedResponse 显示文案改为通用措辞，不再提及与失配点无关的 mailbox。

4. 修正芯片版本号读取位置

问题：板测报 "unsupported chip revision 32" 后 panic。读回数据中版本号位于高半段（位移常量 CHIP_REV_HIGH_SHIFT 已定义），低半段为无关内容。主线代码取低 6 位，得到噪声值 0x20（32），校验失败。报错文本与真实原因不符，实际设备版本号（U01）位于被忽略的高半段。

修复：按 (raw >> CHIP_REV_HIGH_SHIFT) & CHIP_REV_MASK 高位读取版本号；合法性校验改用 CHIP_REV_U01/U02/U03 常量替代魔法数字。

5. 启动时从固件获取设备 MAC

问题：驱动未从固件获取设备 MAC，内部 MAC 字段恒为零。启动完成事件携带全零地址发布，网卡显示 00-00-00-00-00-00；后续下发固件的接口命令同样携带全零地址。设备核心注释注明 MAC 应"在启动期间学习"，但无对应实现，属重构遗漏。重构前驱动通过读 MAC 请求从固件获取地址后再用于接口命令，该路径在新驱动中缺失。

修复：启动序列在 StackStart 之后、ArmChipInterrupt 之前新增 GetMacAddress 阶段：发送 MM_GET_MAC_ADDR_REQ（0x0073），从确认帧数据部分前 6 字节安装 MAC，数据不足 6 字节按 MalformedResponse 处理；读取一次后缓存复用。两条回归测试分别验证 MAC 安装与阶段推进、截断数据失败。板测验证：网卡显示真实 MAC（38-7a-cc-9b-2c-c8），与重构前驱动读取值一致。

6. 设备故障后调用方需等待 30 秒才收到错误

问题：设备判死后，失败事件经有界进度队列上报；队列积压时事件暂存，上报链中断，控制请求调用方需等待 30 秒超时保护（DEFAULT_CONTROL_TIMEOUT）才收到错误。板测表现为命令发出后 30 秒无返回。根因为背压设计应用于终端事件：进度消息丢失可重发，失败事件丢失后无后续机会。

修复：设备失败事件直接向上返回错误，不再经过进度队列；删除失败事件暂存字段与补报逻辑。板测验证：设备判死后控制请求在 5 秒内返回错误。

下周

优先做主线重构版本 WiFi 的适配工作，目前 WiFi 仍不可用。新版 WiFi 是一个封装好的状态机设计，如果能按预期工作的话应该挺好的。