refactor(编号): CubeMX 防丢失三层 L1/L2/L3 → 写进 .ioc / 搬进 USER CODE 区 / 审计兜底（批次 3c）
这族只在两处出现：AGENTS 的「平台约束 / CubeMX 与 Fault」段与 `cubemx-regen` skill 全文。 含义是重生成防丢失的三层优先级，与采集链分层 / UI 菜单层级 / 延迟分段三族都不同。 改法：层号直接换成动作短语，层级顺序用「第一层/第二层/第三层」交代—— L1 写进 .ioc → 写进 .ioc（第一层，权限最高） L2 搬进 USER CODE 区 → 搬进 USER CODE 区（第二层） L3 审计兜底 → 审计兜底（第三层） 另有 `L1/L2/L3 方法论` → 「这三层方法论」、`（L1 检查）` → 「（第一层检查）」、 「L3 清单已清空」→「审计清单已清空」等 8 处措辞跟着落。skill 的 description 也改了， 否则目录里还挂着编号（本次会话的技能目录快照已同步显示新描述）。 验证：doc-links / mojibake / bom-guard / 新编号门禁 / git diff --check 全绿。 本批不涉及 C 代码，@build 不必重跑（上一批 0 错 0 警的构建仍有效）。
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: cubemx-regen
|
||||
description: CubeMX 重生成存活工作流（L1 写进 .ioc → L2 USER CODE 区/宏改名 → L3 审计兜底）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
|
||||
description: CubeMX 重生成存活工作流（写进 .ioc → 搬进 USER CODE 区/宏改名 → 审计兜底三层）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
|
||||
whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改动 Src/Inc 生成区附近代码、或排查"重生成后定制丢失/行为变了但编译不报错"时。
|
||||
---
|
||||
|
||||
@@ -12,12 +12,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
|
||||
|
||||
## 三层优先级（防丢失的唯一正确顺序）
|
||||
|
||||
1. **L1 写进 `.ioc`**（权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
|
||||
1. **写进 `.ioc`**（第一层，权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
|
||||
事件组/堆大小/IWDG 参数/FreeRTOS 钩子开关）必须在 GUI 里设——重生成只会照写。
|
||||
⚠ **别凭印象断言"界面里没有该项"**，先翻标签页或查 `db/mcu/IP/*_Modes.xml`
|
||||
（实测 `configCHECK_FOR_STACK_OVERFLOW=2` 在 FreeRTOS → Config parameters →
|
||||
Hook function related definitions 里，自造宏区被抹两次后才找到）。
|
||||
2. **L2 搬进 `USER CODE` 区**：只信 CubeMX **当前模板真实生成**的区名（优先
|
||||
2. **搬进 `USER CODE` 区**（第二层）：只信 CubeMX **当前模板真实生成**的区名（优先
|
||||
`USER CODE BEGIN 0` 这类从未变过的标准位）。**不要依赖"自造标记区"**——
|
||||
模板换代时自造区连同内容一起消失（实测中断函数模板换代的教训）。
|
||||
生成区内要**去掉一句调用** → 宏改名：`USER CODE BEGIN 0` 里放空实现 +
|
||||
@@ -26,12 +26,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
|
||||
要**替换生成实体定义**（如 4 个 Fault Handler 本体）→ 我们的定义放
|
||||
`USER CODE BEGIN 0`，**必须写在 `#define X X_Gen` 之前**（写在之后会被自己的宏改名），
|
||||
生成区恢复原样，链接器自动移除未引用的 `*_Gen`。
|
||||
3. **L3 审计兜底**：清单 + 哈希基线漂移检测（见下）。
|
||||
3. **审计兜底**（第三层）：清单 + 哈希基线漂移检测（见下）。
|
||||
|
||||
## 重生成前后固定动作
|
||||
|
||||
```powershell
|
||||
# 重生成前：把能在 GUI 表达的都写进 .ioc（L1 检查）
|
||||
# 重生成前：把能在 GUI 表达的都写进 .ioc（第一层检查）
|
||||
# 重生成后【立刻】：
|
||||
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py # 人读报告
|
||||
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --check # 门禁模式（pre-commit 同款）
|
||||
@@ -41,14 +41,14 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
|
||||
|
||||
- 退出码 0=通过 / 1=有 FAIL 项；已挂 pre-commit `cubemx-survival` 钩子
|
||||
（改 `.ioc`/`Src/`/`Inc/`/`.uvprojx` 触发）。
|
||||
- **L3 清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
|
||||
- **审计清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
|
||||
- `uvprojx` 不参与漂移检测（每次构建被 UV4 改写），只保留"源文件仍挂载"断言。
|
||||
|
||||
## 实测陷阱清单
|
||||
|
||||
- CubeMX 对 System Exception（HardFault/MemManage/BusFault/UsageFault）**只生成优先级、
|
||||
从不生成使能代码**；`.ioc` 里 `NVIC.MemoryManagement_IRQn=true` ≠ 已使能（只是向量可见）。
|
||||
`SHCSR` 使能位只能手工写（L2）+ 审计项兜底。
|
||||
`SHCSR` 使能位只能手工写（第二层）+ 审计项兜底。
|
||||
- 启用 FreeRTOS 后模板会生成 `USER CODE BEGIN 4 / 5` 区（默认空桩）——**钩子实现必须
|
||||
整体写进这两个区**，且 helper 函数放更早的区（同名两处定义 = 编译错）。
|
||||
- 生成文件行尾/末尾空行按工具自身风格，**勿用改写型钩子去修剪**（已豁免，勿"顺手格式化"）。
|
||||
@@ -56,6 +56,6 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
|
||||
|
||||
## 其它 CubeMX 项目怎么套
|
||||
|
||||
L1/L2/L3 方法论与"宏改名两招"完全通用；本仓库的清单/基线在
|
||||
这三层方法论与"宏改名两招"完全通用；本仓库的清单/基线在
|
||||
`scripts/check_cubemx_survival.py`（21 项 + `.cubemx_survival_baseline.json`），
|
||||
新项目照它建自己的清单。方法论详见 `docs/子系统设计/看门狗设计说明.md` §10.1/§10.2。
|
||||
|
||||
@@ -104,7 +104,7 @@
|
||||
**CubeMX 与 Fault**
|
||||
|
||||
- `Inc/`/`Src/` 是 CubeMX 生成文件（带 `USER CODE BEGIN/END` 标记）：自定义代码**只写标记区之间**；`Drivers/BSP/` 为纯手工代码
|
||||
- **重生成会覆盖标记区之外的一切**（`.ioc` 的 `KeepUserCode=true` **只**保护 USER CODE 区；实测两次重生成各覆盖 4~5 处定制，其中两处**不报编译错**、只在真出故障时暴露）。防丢失按三层优先级 **L1 写进 `.ioc` → L2 搬进 USER CODE 区 → L3 审计兜底**；**每次重生成后立刻跑 `python scripts/check_cubemx_survival.py`**（已挂 `cubemx-survival` 钩子）。方法论与全部实测坑（自造标记区会被模板换代抹掉、宏改名 `#define f f_Gen` 让位、FreeRTOS 钩子必须写进 `USER CODE BEGIN 4/5` 区…）→ `docs/子系统设计/看门狗设计说明.md` §10
|
||||
- **重生成会覆盖标记区之外的一切**（`.ioc` 的 `KeepUserCode=true` **只**保护 USER CODE 区；实测两次重生成各覆盖 4~5 处定制，其中两处**不报编译错**、只在真出故障时暴露）。防丢失按三层优先级 **写进 `.ioc` → 搬进 USER CODE 区 → 审计兜底**；**每次重生成后立刻跑 `python scripts/check_cubemx_survival.py`**（已挂 `cubemx-survival` 钩子）。方法论与全部实测坑（自造标记区会被模板换代抹掉、宏改名 `#define f f_Gen` 让位、FreeRTOS 钩子必须写进 `USER CODE BEGIN 4/5` 区…）→ `docs/子系统设计/看门狗设计说明.md` §10
|
||||
- **ARMCC `__asm` 只有一种合法形态**：整函数 `__asm void f(void) { ... }`；GCC 内联语法报 `#18`、块内联把寄存器名当 C 标识符报 `#20`、**取不到 C 的数据符号**（`A1516E: Bad symbol`）→ 三条坑与可用写法 `docs/子系统设计/看门狗设计说明.md` §10.4
|
||||
- **4 个 Cortex-M4 Fault 全部采集现场**（手工 `__asm` Handler 取 MSP/PSP → `B` 到 per-fault C 入口 `fault_entry_{hard,mem,bus,usage}` → `hard_fault_report` 打 `[ERR] <TAG> …` 后 `NVIC_SystemReset()`）；**MemManage/BusFault/UsageFault 默认禁用**，不使能就被升级成 HardFault、日志看不出根因 → `fault_handler_enable()` 必须在 `app_main_init()` **第一行**；**`SHCSR` 的使能位无法在 CubeMX 配置**（模板只生成优先级）→ 看门狗设计说明 §10
|
||||
|
||||
|
||||
Reference in New Issue
Block a user