查证 SHCSR 的 Fault 使能位无法在 CubeMX 配置，补入文档与审计提示

用户问 fault_handler_enable() 能否通过 CubeMX 配置。查 CubeMX 安装目录的
模板源码后确认：不能。三重证据：

1. tpl_main_c.ftl 的 MX_NVIC_Init() 用 [#if vector.systemHandler=="false"]
   才生成 HAL_NVIC_EnableIRQ；而 NVIC-STM32F417_Modes.xml 里
   MemoryManagement/BusFault/UsageFault_IRQn 都标 Y（=systemHandler），
   故 CubeMX 对这三个永不生成使能代码（只生成优先级，且仅当优先级 != 0）。
2. 全部模板中 SHCSR 只出现 1 次（tpl_main_c.ftl:2269），且是 MPU 清理时的
   SCB->SHCSR &= ~SCB_SHCSR_MEMFAULTENA_Msk（禁用），无任何 |= 置位。
3. MPU 路径也堵死：.ioc 的 Mcu.IP 列表无 MPU，且 HAL_MPU_Enable 只置
   MEMFAULTENA 一位，BUSFAULTENA/USGFAULTENA 仍拿不到。

实测印证：Src/stm32f4xx_hal_msp.c 的 HAL_MspInit() 里只有
HAL_NVIC_SetPriority(PendSV_IRQn, 15, 0)，三个 Fault 一行代码都没生成。

结论：只能手工写。但函数体在 USER CODE BEGIN 1 区（L2），重生成不会丢，
另有审计项 fault-handler-enable 兜底 -- 故这不是风险，只是无法享受 L1。

顺带记录一个易踩的误解：.ioc 里 NVIC.MemoryManagement_IRQn=true 的第 1 段
只是"向量在 NVIC 表里可见/已配优先级"，与 SHCSR 使能位无关，
不要以为勾了 NVIC 面板的 Enabled 就等于使能了故障。

改动：

- 看门狗设计说明.md：§10.2 新增"为什么 fault_handler_enable() 写不进 .ioc"
  （三路径对照表 + 实测印证 + 结论）；四个 Fault 采集小节加警示；
  L1 表格补该行；变更记录新增 2026-10-01 条。
- AGENTS.md：新增"SHCSR 的 Fault 使能位无法在 CubeMX 配置"铁律条目。
- scripts/check_cubemx_survival.py：fault-handler-enable 的 hint 补上
  "无法 CubeMX 配置"及其原因，便于日后重生成后看提示就能回忆。

验证：pre-commit 13 钩子全通过；审计 18 通过 / 1 警告 / 0 失败。本次仅改
文档与脚本注释，未动代码，无需重编译。

AGENTS.md

@@ -40,6 +40,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~5 处定制，其中 P1 两处**不报编译错**、只在真出故障时暴露）。防止定制丢失按三层优先级：**L1 写进 `.ioc`**（凡 CubeMX 界面能表达的配置，如任务栈/优先级/队列/事件组/堆大小/IWDG 参数——权限最高，重生成只会照写）→ **L2 搬进 `USER CODE` 区**（**只信 CubeMX 当前模板真实生成的区名**，优先文件头 `USER CODE BEGIN 0` 这类从未变过的标准位）→ **L3 审计兜底**。**每次重生成后立刻跑 `python scripts/check_cubemx_survival.py`**（已挂 pre-commit `cubemx-survival` 钩子；改动 `.ioc`/`Src/`/`Inc/`/`task_watchdog`/`.uvprojx` 触发）——清单 18 项 + 哈希基线漂移检测，直接列出"被覆盖了哪几处"。⚠️ **不要依赖"自造标记区"**：2026-09-29 实测 CubeMX **换了一代中断函数模板**（旧 `HardFault_Handler`/`HardFault_Report` 自造区 → 新函数体内 `HardFault_IRQn 0`/`W1_HardFault_IRQn 0`），旧区**连同内容一起消失**（看起来仍像"遵守了规则"）。**生成区内无标记位可用的改动只能 L3 兜底**（如 `Src/iwdg.c` 的 `HAL_IWDG_Init()` 调用、4 个 Fault Handler 本体——本代模板整函数重写），一律加锚点注释（`IWDG-DEFER-START-ANCHOR` / `HARD-FAULT-ANCHOR` / `MEMFAULT-ANCHOR` / `BUSFAULT-ANCHOR` / `USAGEFAULT-ANCHOR`）供审计检出。方法论详见 `docs/子系统设计/看门狗设计说明.md` §10.1/§10.2
 - **4 个 Cortex-M4 Fault 全部采集现场**（2026-09-29）：`HardFault` / `MemManage` / `BusFault` / `UsageFault` 均为手工 `__asm` Handler（取 MSP/PSP 帧指针）→ `B` 到 per-fault C 入口 `fault_entry_{hard,mem,bus,usage}`（各自带故障名）→ `hard_fault_report(tag, frame)` 打 `[ERR] <TAG> PC/LR/xPSR/R0-R3/CFSR/HFSR[/BFAR][/MMFAR]` 后 `NVIC_SystemReset()`。**后三者默认禁用**（复位后 `SHCSR` 只开 HardFault），不使能就会被**升级成 HardFault**、日志看不出根因 → `fault_handler_enable()`（`Src/stm32f4xx_it.c` 的 `USER CODE BEGIN 1` 区）在 `app_main_init()` **第一行**调用。**刻意不启用** `CCR.UNALIGN_TRP` / `CCR.DIV_0_TRP`（会把普通 bug 升级成死机）。⚠️ **ARMCC `__asm` 取不到 C 的数据符号**（`ADR r1, xxx_tag` 报 `A1516E: Bad symbol`，去 static 也无效）且无法传字符串参数 → 故障名必须由 C 侧 per-fault 入口带上，不要在 `__asm` 里取 C 变量
+- **`SHCSR` 的 Fault 使能位无法在 CubeMX 配置**（2026-10-01 查模板源码证实）：CubeMX 对 System Exception **只生成优先级（且仅当优先级 ≠ 0），从不生成使能代码**——`tpl_main_c.ftl` 的 `MX_NVIC_Init()` 用 `[#if vector.systemHandler=="false"]` 挡住 `HAL_NVIC_EnableIRQ`，而 `NVIC-STM32F417_Modes.xml` 里 `MemoryManagement/BusFault/UsageFault_IRQn` 都标 `Y`（=systemHandler）；**全部模板中 `SHCSR` 只出现 1 次**且是 MPU 清理的 `&= ~MEMFAULTENA`（禁用），无任何 `|=` 置位；MPU 路径也堵死（`.ioc` 无 MPU，且 `HAL_MPU_Enable` 只置 `MEMFAULTENA` 一位）。⚠️ **`.ioc` 的 `NVIC.MemoryManagement_IRQn=true` 不代表已使能**（第 1 段只是"向量在 NVIC 表里可见"）——别误以为勾了 Enabled 就等于开了故障。结论：只能手工写（现放 `USER CODE BEGIN 1` 区，属 L2，重生成不丢）+ 审计项 `fault-handler-enable` 兜底
 - **`MDK-ARM/*.uvprojx` 每次 `@build` 后被 Keil UV4 自动改写，改动一律不入库**（2026-09-29 实测）：UV4 构建时会把工程 XML 归一化成它本机风格的旧式写法（`<Tag />` → `<Tag></Tag>`、XML 声明加 `standalone="no"`），并把 `PackID` 降到**本机装的 DFP 版本**（本机实测 `3.1.1` → `3.0.0`，属**降级**）。这些差异是环境相关的，提交后会把别人的 Pack 版本也一起改掉。**判断方法**：`git diff MDK-ARM/STM32F407-Demo.uvprojx` 里若只见 XML 格式/`PackID` 差异而**无源文件挂载增删** → `git checkout -- MDK-ARM/STM32F407-Demo.uvprojx` 丢弃。只有真的新增/删除源文件（`grep 文件名` 计数变化）才提交
 - **ARMCC 内联汇编语法（2026-09-29 踩坑，共 3 坑）**：① `__asm volatile ("MRS %0, lr" : "=r" (x))` 是 **GCC 语法**，ARMCC 报 `#18: expected a ")"`；② `__asm { MRS x, lr }` 块内联会把寄存器名当 C 标识符报 `#20: identifier "lr" is undefined`；③ `__asm` 块里**取不到 C 的数据符号**，`ADR r1, xxx_tag` 报 `A1516E: Bad symbol 'xxx_tag'`（去掉 `static` 也无效——汇编器只认自己作用域内的符号）。**结论**：整个函数用 `__asm void f(void) { ... }`；要传"字符串/表格"这类 C 侧数据，就让 `__asm` 只取寄存器参数然后 `B` 到一个普通 C 函数，由 C 侧补上。若要覆盖 CubeMX 生成的同名函数，用 `#define f f_Gen`（在生成实体之前）把生成实体改名——链接器会把未被引用的 `f_Gen` 自动移除（`.map` 可见 `Removing ... (N bytes)`），**零代码开销且不删生成区任何一行**
 - FreeRTOS V10.3.1（CMSIS-RTOS V2）；HAL 时基 = TIM7（非 SysTick），tick = 1ms；NVIC 4 位优先级分组，外设中断优先级 ≥ 5