加 CubeMX 重生成存活审计:防标记区外定制被静默覆盖

背景:.ioc 的 KeepUserCode 只保护 USER CODE 标记区,标记之外的手工改动
重生成即被覆盖,且多数不报编译错(2026-09-29 实测一次覆盖 4 处,含
HardFault_Handler 崩溃采集被打回空 while(1)、两个 FreeRTOS 加固宏被删)。

新增 scripts/check_cubemx_survival.py:
- 16 项易失清单(IWDG 延后启动 / 崩溃采集 / 栈溢出检测 / 堆失败钩子 /
  断言改造 / 看门狗模块与工程挂载 / 复位原因锁存 / HAL 驱动与使能 /
  .ioc 关键项),断言前剥掉 C 注释防误报
- 哈希基线漂移检测(.cubemx_survival_baseline.json),--write 重建
- 标记区外存量以 WARN 提示(3 个 Fault 处理函数、栈注释)

已挂 pre-commit cubemx-survival 钩子(改动 .ioc / Src / Inc /
task_watchdog / .uvprojx 时触发)。

文档:看门狗设计说明 §10.2 新增"重生成不丢的三层手段"方法论
(L1 写 .ioc > L2 搬进 USER CODE 区(可自造标记区)> L3 审计兜底)
及 .ioc / USER CODE 区可用位置 / 存量清单三张对照表;AGENTS.md 平台约束
新增该规则;pre-commit 使用说明 §2.12 新增钩子详解。

门禁:build 0 错误 0 警告;pre-commit 全通过。
This commit is contained in:
2026-09-29 07:30:00 +08:00
parent 7feeea6c56
commit 7a18d2ce28
6 changed files with 578 additions and 3 deletions
+1
View File
@@ -38,6 +38,7 @@ STM32F407ZGTx @168MHz(HSE 8MHz → PLL M=4/N=168/P=2);**仅 Keil MDK-ARM v
## 平台约束
- `Inc/`/`Src/` 中 CubeMX 生成文件带 `USER CODE BEGIN/END` 标记:自定义代码**只写标记区之间**;`Drivers/BSP/` 为纯手工代码
- **CubeMX 重生成会覆盖标记区之外的一切**(`.ioc` 的 `KeepUserCode=true` **只**保护 `USER CODE` 区;2026-09-29 实测一次重生成覆盖 4 处定制,其中 P1 两处**不报编译错**、只在真出故障时暴露)。防止定制丢失按三层优先级:**L1 写进 `.ioc`**(凡 CubeMX 界面能表达的配置,如任务栈/优先级/队列/事件组/堆大小/IWDG 参数——权限最高,重生成只会照写)→ **L2 搬进 `USER CODE` 区**(可**自造**标记区:CubeMX 会保留任何 `/* USER CODE BEGIN 名 */`…`/* USER CODE END 名 */` 对,即使区名非预定义)→ **L3 审计兜底**。**每次重生成后立刻跑 `python scripts/check_cubemx_survival.py`**(已挂 pre-commit `cubemx-survival` 钩子;改动 `.ioc`/`Src/`/`Inc/`/`task_watchdog`/`.uvprojx` 触发)——清单 16 项 + 哈希基线漂移检测,直接列出"被覆盖了哪几处"。方法论详见 `docs/子系统设计/看门狗设计说明.md` §10.2
- FreeRTOS V10.3.1(CMSIS-RTOS V2);HAL 时基 = TIM7(非 SysTick),tick = 1ms;NVIC 4 位优先级分组,外设中断优先级 ≥ 5
- **内核启动(`osKernelStart`)前禁止任何 FreeRTOS/CMSIS-RTOS API 调用**(2026-09-20 启动失败实证根因,修复 `82411cf`):`osMessageQueueNew`/`osMessageQueuePut`/`osMutexNew`/`osSemaphoreNew` 等在内核启动前调用会杀死启动(09/19~09/20 "每次必死" 的代码层根因 = `syslog_mcu_init` 在内核启动前调用 `osMessageQueueNew`)。内核启动前代码的标准模式:纯寄存器/HAL 轮询操作 + **无锁静态缓冲**(如 `s_preboot[8]` 暂存内核前日志)+ **内核启动后惰性创建真队列**(任务上下文首次使用时,见 `syslog_drain`);凡在内核启动前执行的初始化函数里不得创建任何 CMSIS 对象
- CH395F SPI:每次事务须 `ch395f_spi_begin()/end()` 包裹;分频系数**必须为 8**(PCB 约束,勿"优化")