source-maintenance-reader

name	source-maintenance-reader
description	理解、解释、排查、修改和移植已有 MCU/嵌入式源码。适用于接手老固件项目、回答启动流程、调用链、中断、条件编译、板卡变体、寄存器配置问题，或需要新增功能、修改参数、跨芯片移植功能时。

源码理解与维护

老项目先理解，再修改。不要一上来重构。

工作流

1. 识别项目类型和构建系统
   判断 Keil、IAR、Make、CMake、厂商 IDE、RTOS、裸机或嵌入式 Linux。找到工程文件、启动文件、链接脚本、配置、生成代码和板卡变体。

2. 梳理启动和运行路径
   看 Reset Handler、系统时钟、HAL/厂商初始化、板级初始化、调度器或主循环、中断向量表、已启用中断、tick 和任务分发。

3. 梳理模块职责
   识别 driver、bsp、component、app、workflow、协议、存储、UI。发现跨层问题可以记录，但不要无关重构。

4. 追踪目标行为
   找入口函数、回调、ISR、flag、缓冲区、状态变量、宏和条件编译。注意板卡/芯片变体会改变行为。

5. 最小修改
   保持现有风格和命名。能加日志、测试或保护就加。窄问题不要做大架构调整。

6. 验证
   能编译就编译；需要板端验证时说明步骤；更新调试记录或决策记录。

回答源码问题的格式

回答“这段代码怎么工作”时，包含：

• 简短结论。
• 涉及文件和函数。
• 调用链或状态转移。
• 关键宏和配置。
• 哪些是源码事实，哪些是推断。
• 风险和未知项。

老项目风险

• 一个代码库可能通过宏兼容多个板子和芯片。
• 厂商生成文件可能被 IDE 覆盖。
• 直接寄存器操作可能依赖未写明的顺序或延时。
• 全局 flag 和 ISR 交互可能隐藏竞态。
• 奇怪的 delay 可能是硬件稳定时间，不一定是随手乱写。

排错规则

• 先读原始报错、日志和现象，再提修复。
• 崩溃/卡死重点看栈、ISR、看门狗、时钟、内存越界和阻塞调用。
• 通信问题重点看波特率/时钟、引脚复用、上下拉、缓冲处理、超时和协议帧。
• 显示/UI 问题要区分代码逻辑正确和产品/布局判断错误。

移植规则

• 先分离可移植逻辑和芯片相关 driver/BSP。
• 为目标板重新生成硬件接口表。
• 重新验证时序、内存、栈、Flash/RAM、外设可用性。
• 不要假设不同 MCU 家族的引脚复用、DMA 通道、中断向量和时钟树相同。