From 0f0158508adf41fb14801d4212939a2e16875b4b Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Wed, 28 Oct 2026 13:15:05 +0800 Subject: [PATCH] =?UTF-8?q?refactor(=E7=BC=96=E5=8F=B7):=20CubeMX=20?= =?UTF-8?q?=E9=98=B2=E4=B8=A2=E5=A4=B1=E4=B8=89=E5=B1=82=20L1/L2/L3=20?= =?UTF-8?q?=E2=86=92=20=E5=86=99=E8=BF=9B=20.ioc=20/=20=E6=90=AC=E8=BF=9B?= =?UTF-8?q?=20USER=20CODE=20=E5=8C=BA=20/=20=E5=AE=A1=E8=AE=A1=E5=85=9C?= =?UTF-8?q?=E5=BA=95=EF=BC=88=E6=89=B9=E6=AC=A1=203c=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 这族只在两处出现：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 警的构建仍有效）。 --- .dsh/skills/cubemx-regen/SKILL.md | 16 ++++++++-------- AGENTS.md | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.dsh/skills/cubemx-regen/SKILL.md b/.dsh/skills/cubemx-regen/SKILL.md index e13656ed..057a4e69 100644 --- a/.dsh/skills/cubemx-regen/SKILL.md +++ b/.dsh/skills/cubemx-regen/SKILL.md @@ -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。 diff --git a/AGENTS.md b/AGENTS.md index 03e7b733..bcea70e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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] …` 后 `NVIC_SystemReset()`）；**MemManage/BusFault/UsageFault 默认禁用**，不使能就被升级成 HardFault、日志看不出根因 → `fault_handler_enable()` 必须在 `app_main_init()` **第一行**；**`SHCSR` 的使能位无法在 CubeMX 配置**（模板只生成优先级）→ 看门狗设计说明 §10