4.1 KiB
4.1 KiB
name, description, whenToUse
| name | description | whenToUse |
|---|---|---|
| cubemx-regen | CubeMX 重生成存活工作流（L1 写进 .ioc → L2 USER CODE 区/宏改名 → L3 审计兜底）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。 | 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改动 Src/Inc 生成区附近代码、或排查"重生成后定制丢失/行为变了但编译不报错"时。 |
cubemx-regen — CubeMX 重生成存活（文档型 skill）
核心事实：.ioc 的 KeepUserCode=true 只保护 USER CODE BEGIN/END 标记之间；
标记之外的一切手工改动重生成即被模板覆盖，且多数不报编译错（崩溃采集被打回
while(1)、加固宏被整块删）——只在真出故障时暴露。
三层优先级（防丢失的唯一正确顺序）
- L1 写进
.ioc（权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/ 事件组/堆大小/IWDG 参数/FreeRTOS 钩子开关）必须在 GUI 里设——重生成只会照写。 ⚠ 别凭印象断言"界面里没有该项"，先翻标签页或查db/mcu/IP/*_Modes.xml（实测configCHECK_FOR_STACK_OVERFLOW=2在 FreeRTOS → Config parameters → Hook function related definitions 里，自造宏区被抹两次后才找到）。 - L2 搬进
USER CODE区：只信 CubeMX 当前模板真实生成的区名（优先USER CODE BEGIN 0这类从未变过的标准位）。不要依赖"自造标记区"—— 模板换代时自造区连同内容一起消失（实测中断函数模板换代的教训）。 生成区内要去掉一句调用 → 宏改名：USER CODE BEGIN 0里放空实现 +#define HAL_IWDG_Init(a_h) iwdg_deferred_start(a_h)，生成句自动变空操作 （.map里Removing ... N bytes验证；生成区零 diff）。 要替换生成实体定义（如 4 个 Fault Handler 本体）→ 我们的定义放USER CODE BEGIN 0，必须写在#define X X_Gen之前（写在之后会被自己的宏改名）， 生成区恢复原样，链接器自动移除未引用的*_Gen。 - L3 审计兜底：清单 + 哈希基线漂移检测（见下）。
重生成前后固定动作
# 重生成前：把能在 GUI 表达的都写进 .ioc（L1 检查）
# 重生成后【立刻】：
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py # 人读报告
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --check # 门禁模式（pre-commit 同款）
# 确认 diff 全部是"想要的改动"后重建基线：
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --write
- 退出码 0=通过 / 1=有 FAIL 项；已挂 pre-commit
cubemx-survival钩子 （改.ioc/Src//Inc//.uvprojx触发）。 - L3 清单已清空 = 重生成应当零 diff；仍有 diff 就是被覆盖了，直接跑脚本定位。
uvprojx不参与漂移检测（每次构建被 UV4 改写），只保留"源文件仍挂载"断言。
实测陷阱清单
- CubeMX 对 System Exception（HardFault/MemManage/BusFault/UsageFault）只生成优先级、
从不生成使能代码；
.ioc里NVIC.MemoryManagement_IRQn=true≠ 已使能（只是向量可见）。SHCSR使能位只能手工写（L2）+ 审计项兜底。 - 启用 FreeRTOS 后模板会生成
USER CODE BEGIN 4 / 5区（默认空桩）——钩子实现必须 整体写进这两个区，且 helper 函数放更早的区（同名两处定义 = 编译错）。 - 生成文件行尾/末尾空行按工具自身风格，勿用改写型钩子去修剪（已豁免，勿"顺手格式化"）。
- 重生成后除审计脚本外，照常走
@build（0 错 0 警）+ 必要时@test闭环。
其它 CubeMX 项目怎么套
L1/L2/L3 方法论与"宏改名两招"完全通用；本仓库的清单/基线在
scripts/check_cubemx_survival.py（21 项 + .cubemx_survival_baseline.json），
新项目照它建自己的清单。方法论详见 docs/子系统设计/看门狗设计说明.md §10.1/§10.2。