dsh-stm32 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -31
- package/README_EN.md +96 -29
- package/docs/development-notes.md +837 -4
- package/docs/reading-guide.md +759 -0
- package/lib/commands/register.js +49 -0
- package/lib/data/chips.js +147 -30
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +237 -42
- package/lib/data/device-facts.js +201 -0
- package/lib/data/stm32f1.js +130 -0
- package/lib/data/svd.js +627 -0
- package/lib/engine/assets.js +924 -0
- package/lib/engine/breakpoints.js +242 -0
- package/lib/engine/build.js +115 -16
- package/lib/engine/cache.js +56 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/debug-session.js +153 -5
- package/lib/engine/debug.js +114 -15
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +174 -30
- package/lib/engine/flash.js +70 -9
- package/lib/engine/generate.js +11 -0
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +33 -7
- package/lib/engine/msys2-install.js +332 -61
- package/lib/engine/probe-error.js +212 -0
- package/lib/engine/probe-session.js +311 -0
- package/lib/engine/project-export.js +129 -0
- package/lib/engine/register-clock.js +132 -0
- package/lib/engine/register-linker.js +129 -0
- package/lib/engine/register-template.js +115 -20
- package/lib/engine/regs.js +2 -0
- package/lib/engine/rtt.js +600 -0
- package/lib/engine/scaffold.js +104 -28
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +10 -0
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/assets.js +341 -0
- package/lib/tools/build.js +12 -0
- package/lib/tools/cache.js +47 -8
- package/lib/tools/debug-session.js +40 -5
- package/lib/tools/debug.js +41 -4
- package/lib/tools/doctor.js +22 -2
- package/lib/tools/flash.js +15 -3
- package/lib/tools/generate.js +3 -0
- package/lib/tools/ioc-apply.js +2 -0
- package/lib/tools/ioc-inspect.js +2 -0
- package/lib/tools/ioc-plan.js +198 -4
- package/lib/tools/project-create.js +50 -1
- package/lib/tools/project-export.js +100 -0
- package/lib/tools/regs.js +453 -61
- package/lib/tools/route-plan.js +3 -0
- package/lib/tools/rtt.js +347 -0
- package/package.json +5 -3
- package/templates/register/CMakeLists.txt +25 -6
- package/templates/register/Core/Inc/rtt.h +103 -0
- package/templates/register/Core/Src/main.c +43 -9
- package/templates/register/Core/Src/rtt.c +297 -0
- package/templates/scaffold/RTT.md +86 -0
- package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
- package/templates/scaffold/openocd.cfg +8 -0
|
@@ -4,7 +4,9 @@
|
|
|
4
4
|
> 面向使用者的说明已移到仓库根目录的 [README.md](../README.md)。
|
|
5
5
|
# dsh-stm32
|
|
6
6
|
|
|
7
|
-
DSH 插件(宿主侧,无 UI):把
|
|
7
|
+
DSH 插件(宿主侧,无 UI):把 STM32F1 全系(F100/101/102/103/105/107;0.1.x 时只有 STM32F103C8T6 一块板)的 **环境探测 → .ioc 事务(含时钟)→ 生成工程 → 编译 → 烧录 → 调试** 变成一组可被模型调用的工具。
|
|
8
|
+
|
|
9
|
+
> **2026-10-30 更新**:F1 全系已支持,HAL 与寄存器两条路线都吃任意 F1 型号,时钟配置已并入 `stm32_ioc_plan`。本文件正文里凡是「只支持 / 只覆盖 C8T6」的句子都是当时的历史记录(按时间记账的要求保留原文),最新口径见 §28。
|
|
8
10
|
|
|
9
11
|
规格书:[`docs/dsh-stm32-plugin-规格.md`](docs/dsh-stm32-plugin-规格.md)(v0.2)。
|
|
10
12
|
|
|
@@ -27,7 +29,7 @@ git clone git@github.com:JingYu-er/dsh-stm32.git # 或 https://github.com
|
|
|
27
29
|
cd dsh-stm32
|
|
28
30
|
npm install --no-audit --no-fund # 只装 typescript
|
|
29
31
|
npm run build # tsc -> lib/
|
|
30
|
-
npm test # 可选:
|
|
32
|
+
npm test # 可选:497 个离线用例(34 个套件)
|
|
31
33
|
```
|
|
32
34
|
|
|
33
35
|
然后把 `lib/` 用 `link:` 挂进 dsh 的 profile 并重启 dsh(见下一节)。宿主要求:
|
|
@@ -40,7 +42,7 @@ npm test # 可选:80 个离线用
|
|
|
40
42
|
| STM32CubeMX | `stm32_generate`、首次建工程 | 生成类工具不可用,其余照常 |
|
|
41
43
|
| STM32Cube 固件包 F1(随 CubeMX 安装) | `stm32_project_create` 抄 Drivers | 建骨架报「找不到固件包」 |
|
|
42
44
|
|
|
43
|
-
默认路径在 [`src/data/search-roots.ts`](src/data/search-roots.ts)(msys64 优先),可用 `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT`
|
|
45
|
+
默认路径在 [`src/data/search-roots.ts`](src/data/search-roots.ts)(msys64 优先),可用 `STM32_BIN_DIRS` / `STM32_CUBEMX_ROOT` 覆盖。型号覆盖 **STM32F1 全系**(F100/101/102/103/105/107,2026-10-30 起;本机验证板仍是 C8T6):启动文件 / 设备宏 / 链接脚本由 [`src/data/stm32f1.ts`](src/data/stm32f1.ts) + [`src/engine/hal-chip.ts`](src/engine/hal-chip.ts) 派生,引脚表内置一份、也可由本机 CubeMX `db/mcu/*.xml` 派生(见 §28)。
|
|
44
46
|
## 开发
|
|
45
47
|
|
|
46
48
|
```powershell
|
|
@@ -1644,11 +1646,842 @@ blocked 时的 `message` 是一句人话,不是字段堆砌:
|
|
|
1644
1646
|
|
|
1645
1647
|
`install-units` 17 → **21 例**,按加入顺序:①「已有完整 MSYS2 + 5 个组件 → 说『什么都不用装』、`download.bytes` 为 0」;②「只缺 1 个包 → 只说 `openocd`、不列已装的 4 个」;③「pacman 问不出来(超时 / 报错)→ 不猜缺哪个,只说真装时会先问」;④「缺 CubeMX → 紧凑卡片补一句 HAL 提示,装了就不补」。既有那例「计划里的 pacman 步骤说的是真会跑的事」跟着改了断言:计划模式允许**一条**只读查询,但绝不能出现 `pacman -S` / `-Sy`。
|
|
1646
1648
|
|
|
1647
|
-
**24 套件
|
|
1649
|
+
**24 套件 318 pass / 0 fail**(CI 316 + 2 skipped)。README / README_EN 的计数同步到 318。
|
|
1648
1650
|
|
|
1649
1651
|
**还没验证的**:重启 DSH 后在面板里点「生成安装计划」,确认卡片首句变成「什么都不用装」。
|
|
1650
1652
|
|
|
1653
|
+
## 20. 发布形态三连修:mpu_armv7 的 marker、npm 吞 .gitignore、盘根 mkdir(2026-10-25)
|
|
1654
|
+
|
|
1655
|
+
用户在另一台机器(阿里云 ECS、无 CubeMX、无 USB)实测暴露的三条「作者本机测不出来」的问题,全部是发布/环境形态才炸:
|
|
1656
|
+
|
|
1657
|
+
**Q1 mpu_armv7.h 被 marker 误杀(100% 复现,与网络无关)。** `cmsis-sources.ts` 给 5 个内核头共用 `[__CMSIS,__CORE_,__MPU_]`,但上游 V5.0.4 的 `mpu_armv7.h` 是 ARM 原版,真实守卫是 `ARM_MPU_ARMV7_H`(没有前导下划线)——一个都不命中,四条下载链路全通也必失败。改为按文件各配真实守卫(`__CORE_CM3_H` / `__CMSIS_COMPILER_H` / `__CMSIS_GCC_H` / `__CMSIS_VERSION` / `ARM_MPU_ARMV7_H`)。**测试侧同一个坑**:`cache-units` 的 `markerFor()` 按文件名猜 "`#ifndef __MPU_ARMV7_H`",恰好撞上旧 markers 的 `__MPU_`,等于一直在测假世界——同步改成真实守卫表,并新增回归用例(真守卫内容必须能落盘)。
|
|
1658
|
+
|
|
1659
|
+
**Q2 npm 打包永远排除 .gitignore(所有 npm 用户 100% 复现)。** `.gitignore` 同时是 npm 的忽略过滤器,永远进不了 tarball;而 `register-template.ts` 把它列为**必需**文件,缺失即整次失败,报错还让用户"重新安装插件"——npm 用户重装是同一个包,死循环。用户决定**不改名、只做容错**:`.gitignore` 移出硬检查与复制循环,缺失时继续建工程 + 一句 warning("工程功能不受影响,git 状态会多出 build/;想干净就自己建一个内容为 build/ 的 .gitignore");scaffold 路线同样处理;"重新安装插件"文案改为指向插件版本号反馈。两条路线各加一例"缺失时 ok:true + warning + 其余文件齐全"的测试(测试里临时把真实模板的 .gitignore 改名、finally 恢复)。
|
|
1660
|
+
|
|
1661
|
+
**Q3 盘根 mkdir EPERM(插件自设的雷)。** `targetDir=C:/msys64` 是插件自己建议的默认装法,而 parent 是盘根 `C:/`,Node 的 `mkdirSync(盘根, {recursive:true})` 在 Windows 抛 EPERM。新增 `isDriveRoot(dir)`(导出,纯函数)与 `ensureParentDir(parent)`:盘根走 `existsSync` 校验、其余才 mkdir。install-units 加 isDriveRoot 单测(含"推荐默认 C:/msys64 的 parent 必须被判为盘根"的反向断言)。
|
|
1662
|
+
|
|
1663
|
+
**Q4 USB/探针形态诊断(doctor 分级)。** 云服务器物理上没有 USB 口,与"没插板/线只供电/驱动异常/被占用"是四种完全不同的回答。新增 `diagnoseUsb(pnputilText)`(纯函数,四分类:no-usb / no-dap / driver-error / ok,另有 unknown 兜底)与 `usbDiagnosis(subprocess)`(跑只读 `pnputil /enum-devices /connected`,失败不阻塞)。**编码教训**:中文系统 pnputil 字段名是 GBK("实例 ID" 读出来是乱码),任何依赖字段名的解析都会失效——最终只认行内 ASCII 本体(`USB\\VID_`、`USB\\ROOT_HUB`)。no-usb 判定进 blockers(它阻塞烧录且无解),no-dap/driver-error 进 notes,ok 也给一句"探针在线"。DoctorReport 与工具 outputSchema 新增 `usb` 字段,渲染加一行。doctor-regs-units +5 例。真机复验:本机(有 USB、无 CMSIS-DAP)正确报 no-dap 而不是 no-usb。
|
|
1664
|
+
|
|
1665
|
+
**测试。** cache-units 16 → 17(真守卫回归)、scaffold-patch-units 22 → 24(.gitignore 缺失两条路线各一例)、install-units 21 → 22(isDriveRoot)、doctor-regs-units 5 → 10(四分类 + 空文本)。**24 套件 318 pass / 0 fail**(CI 316 + 2 skipped)。
|
|
1666
|
+
|
|
1667
|
+
**发布顺序**:npm pack --dry-run 人工核对 → 版本 0.1.2(package.json + lock 两处 + 两 README 各两处)→ npm publish(盯 PUT 201/202)→ 模拟用户验收(删缓存 + 新 profile 装 tarball + register/hal 各建一次 + doctor 看 USB 话术)。
|
|
1668
|
+
|
|
1669
|
+
## 21. 阿里云实测后的五档清单:让"别人的机器"也能从零跑到烧录(2026-10-25)
|
|
1670
|
+
|
|
1671
|
+
**背景。** 用户在一台阿里云 Windows ECS(有 MSYS2、无 CubeMX、无 USB 口)上照 README 从零走了一遍,除了 §20 那三条 100% 复现的 P0,还提了五条:①发布形态没人验过——`npm pack` 出来的包里少了文件、`lib/client.js` 与 `client/client.js` 不同步,都要等用户装上才发现;②云服务器上 `stm32_doctor` 说不清"没有 USB 口"和"没插探针"的区别;③只有 `.elf`,想要 `hex` / `bin`,还希望工程自带 `openocd.cfg`;④烧录失败只有一句话,模型没法按类分支;⑤上游文件只靠 marker 判"像不像",`master` 改一行照样落盘。
|
|
1672
|
+
|
|
1673
|
+
定案时明确了两条边界:**不做**自动装 CubeMX(GUI 向导 + ST 账号,装不了);**不加**运行时依赖(zip 都自己写)。
|
|
1674
|
+
|
|
1675
|
+
### 21.1 钉死上游内容:模板每个文件带 sha256(0a)
|
|
1676
|
+
|
|
1677
|
+
marker 只能证明"拿回来的像这个文件",证明不了"还是那一份"。上游 `master` 上把 `system_stm32f1xx.c` 改一行,marker 照样命中,落盘后要到编译期才炸,而缓存还会把坏文件长期留着。
|
|
1678
|
+
|
|
1679
|
+
- `src/engine/fetch.ts` 的 `FetchTarget` 加可选 `sha256`,`fetchOne` 的校验顺序是:HTTP 状态 → 体积下限 → HTML 嗅探(代理拦截页)→ marker → **sha256**;不匹配就换下一个候选源,全失败时报「sha256 对不上(期望 `abcd…`,实际 `ef01…`)多半是上游 master 挪动了内容」,并把实际值写进 attempts 方便核对。
|
|
1680
|
+
- `src/data/cmsis-sources.ts` 新增四张表 `DEVICE_HEADER_SHA256` / `SYSTEM_C_SHA256` / `STARTUP_SHA256` / `CORE_HEADER_SHA256`,10 个下载目标全部接上。值是 2026-10-25 从本机缓存里的真实文件算出来的,关键五条:`stm32f1xx.h` `05e93fa3ddefb2e83d762b9ca4de36e3bba9cd8e9690400fe9f2c11fc0a3cef5`、`system_stm32f1xx.h` `a54dfbb3480c672f532d472a6e84bcf34df6551771d2e9966c5a3503c676b6ab`、`stm32f103xb.h` `d9c7c613d9fea74220892b4fbc3e80617493acad82a04bafadab2b4a7198399c`、`system_stm32f1xx.c` `8465bf3fe9057adecd8b4561403836d1fa2152d3cb088831623da3f91d86ec0a`、`startup_stm32f103xb.s` `a9a5fc7ed5ff617527dd98b3092830f4d17ed4bf57c99eac2c53bdb514ce138c`。
|
|
1681
|
+
- **取舍**:上游一动,新机器就装不上(旧的还能从缓存复用)。仍然选"失败"而不是"照落"——落错文件的代价是半天编译报错的排查,而对不上的提示里直接给了两个哈希,用户(或我)能在 30 秒内判断是上游改了还是网络中间人。
|
|
1682
|
+
- 测试注入点:`TemplateRequest.hashes` 与 `RegisterProjectRequest.hashes`(`src/engine/register-template.ts` 把它们映射到 targets 的 `sha256`),测试侧用 `contentHashes(override)` 按 `SAMPLE_PAYLOADS` 现算;`cache-units` 新增"哈希对不上必须拒绝并报两个哈希"。
|
|
1683
|
+
|
|
1684
|
+
### 21.2 pack-smoke:发布形态得由 CI 自己验(第 1 批)
|
|
1685
|
+
|
|
1686
|
+
`npm test` 跑的是仓库里的 `lib/`,永远发现不了"tarball 里少了 `templates/scaffold/openocd.cfg`"或"`lib/client.js` 没跟着 `client/client.js` 重新生成"。新增 `scripts/pack-smoke.mjs`:
|
|
1687
|
+
|
|
1688
|
+
1. `npm pack` 到临时目录;
|
|
1689
|
+
2. `tar -xzf` 解开(Windows 上 `execFileSync` 必须带 `shell: true`,否则找不到 `tar`);
|
|
1690
|
+
3. 断言 16 个发布必须文件都在(含 `lib/client.js`、`templates/scaffold/openocd.cfg`——`openocd.cfg` 是 2c 新加的,漏打包会让新工程烧不了而单测全绿);
|
|
1691
|
+
4. 断言 `lib/client.js` 与 `client/client.js` 逐字节一致(否则说明忘了 `npm run build`);
|
|
1692
|
+
5. **用解包出来的 `lib/` 与 `templates/` 真建一次寄存器工程**,断言产物与模板计数。
|
|
1693
|
+
|
|
1694
|
+
`package.json` 加 `test:pack`,`.github/workflows/ci.yml` 在 `npm test` 之后单独一步跑它。不并进 `npm test` 的原因:它要跑 `npm pack`(慢),而且它验的是"发布形态"而不是"逻辑",分开跑能一眼看出是哪种失败。
|
|
1695
|
+
|
|
1696
|
+
### 21.3 探针诊断下沉到烧录(2a)
|
|
1697
|
+
|
|
1698
|
+
云服务器上 `stm32_flash` 失败只会说「找不到 CMSIS-DAP 设备」,和"线只供电"、"驱动没装"、"口被占"混在一起。做法是把 §20 的 `usbDiagnosis` 复用出两层:
|
|
1699
|
+
|
|
1700
|
+
- `src/engine/doctor.ts` 的 `hasDap` 名单扩到 CMSIS-DAP / `VID_0D28` / `VID_0483`(ST-Link)/ `VID_C251` / `VID_1A86`(CH340 桥接板),另配 `usb vid_` 小写形态;
|
|
1701
|
+
- `src/engine/flash.ts` 新增导出 `probeMissingLines(errors)`(从 openocd 日志里认出"找不到设备"那几行)与 `usbNoteFor(kind, detail)`(`unknown` 返回 `null`,不乱说话),`runFlash` 只在"确实没找到设备"时把 USB 形态追加进 `notes`。
|
|
1702
|
+
|
|
1703
|
+
### 21.4 hex/bin 与 openocd.cfg(2b / 2c)
|
|
1704
|
+
|
|
1705
|
+
- `stm32_build` 的 `BuildRequest.artifacts`(`elf` / `hex` / `bin` 的子集)与 `BuildReport.converted`(`{kind, path, size}[]`)。链接成功后用 `resolveToolIn(subprocess, ["arm-none-eabi-objcopy"], config.binDirs, signal)` 跑 `-O ihex` / `-O binary` 到 `.elf` 同目录;**转换失败只写 note,不判编译失败**——编译本身已经成功,`.elf` 仍然可用。不让用户自己 `objcopy` 的理由:门禁已经知道工具链在哪,而且失败时文案能说清"缺 objcopy"还是"路径写不进"。
|
|
1706
|
+
- 新增 `templates/scaffold/openocd.cfg`(`source interface/cmsis-dap.cfg`、`transport select hla_swd`、`source target/stm32f1x.cfg`、`adapter speed 2000`),进 `SHARED_TEMPLATE_FILES`,两条路线都自带。2 MHz 是 F103 + CMSIS-DAP 上实测最稳的档位。
|
|
1707
|
+
- 顺带把 `checkNoDebugGuard` 的降级路径做完整:工程里找不到唯一 `.ioc` 时,改看 `openocd.cfg` 的 `transport` —— `swd` 放行并说明"依据是 openocd.cfg";`jtag` 提示 PA13/PA14 可能被复用;连 `transport` 都没有才继续报"守卫没生效"。计数断言随之 14 → 15(scaffold-patch)、6 → 7(cache-units)。
|
|
1708
|
+
|
|
1709
|
+
### 21.5 errorCode:让模型能按类分支(2d)
|
|
1710
|
+
|
|
1711
|
+
`stm32_flash` 新增 `FlashErrorCode`(`""` / `no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`)与 `errorCodeOfLines(lines)`;成功时为空串,`FlashLogVerdict` 与 `FlashReport` 都带上它,工具 schema 用 enum 收口并在卡片里单独一行渲染。分类按 openocd 日志的**首个**命中判定(顺序敏感:先 `no-probe` 再 `probe-busy`,避免把"被占用"读成"没插")。不把 `message` 直接给模型当分支依据——中文话术会改,错误码是契约。
|
|
1712
|
+
|
|
1713
|
+
### 21.6 `/stm32-setup`(第 3 批轻量版)
|
|
1714
|
+
|
|
1715
|
+
人已经决定要干活时,先体检再出计划比"先问他装不装"更顺手:命令一次跑完 `stm32_env_probe` + 安装计划;**命令里带「装」字**(例如 `/stm32-setup 装上缺的`)才真装,否则只回计划与下一句。真装仍然是 43 MB 下载 + 写注册表,不能靠一句 `/stm32-setup` 触发。命令数 6 → 7。
|
|
1716
|
+
|
|
1717
|
+
### 21.7 `stm32_project_export`:把工程交给别人(P1-4)
|
|
1718
|
+
|
|
1719
|
+
用户的原话是"云上建好的工程怎么拿回本地"。与其让他自己挑文件打包,不如给一个工具:
|
|
1720
|
+
|
|
1721
|
+
- `src/engine/project-export.ts`:`collectSources` 递归收集,`SKIP_DIRS` 固定跳过 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`;`includePrebuilt` 时把 `.elf` 一起带上;`readme` 默认在包里写一份开箱说明(内容用 `__inline__` 前缀表示"这是内联生成,不是文件");`outDir` 缺省落在工程同级的 `<name>-export.zip`。
|
|
1722
|
+
- `src/engine/zip.ts`:**store-only 的最小 zip 写盘器**(CRC32 + DOS 时间 + 本地头 + 中央目录),外加 `listZipEntries(buffer)` 给测试验内容。为什么不加 `archiver` / `jszip`:这个仓库的承诺是零运行时依赖、`lib/` 入库、`npm i` 不用编译任何东西,为此引一棵依赖树不划算;我们的场景也不需要压缩比(源码 + 一个 `.elf`)。
|
|
1723
|
+
- 报告字段:`ok` / `projectDir` / `zipPath` / `zipBytes` / `fileCount` / `prebuilt` / `durationMs` / `message` / `notes`;`message` 直接给"多少个文件、多大、要不要带 elf"。
|
|
1724
|
+
- 测试(`test/export-units.test.mjs` 9 例):空工程仍出合法 zip 且能被 `listZipEntries` 读回;`build/` 与 `.dsh-stm32/` 不进包;`includePrebuilt: true` 时 `.elf` 在包里、`false` 时不在;`readme: false` 不写 README;默认落点与 `outDir`;`zipBytes` 与磁盘文件大小一致;`fileCount` 与实际条目一致;CRC 能被独立实现验过。
|
|
1725
|
+
|
|
1726
|
+
### 21.8 计数与文档
|
|
1727
|
+
|
|
1728
|
+
本批新增 8 例(cache 17 → 19 的两条哈希、flash 8 → 13 的五条、doctor 10 → 11 的一条 CH340;`commands-units` 只改命令名单断言、不增例),加 export 9 例:**25 套件 335 pass / 0 fail**(CI 333 + 2 skipped)。README / README_EN 的用例数、套件数、工具数(19 → 20)、命令数(6 → 7)与新增小节一并同步;`package.json` / `package-lock.json` / 两个 README 的 badge 与"装完确认"行升到 0.1.2。
|
|
1729
|
+
|
|
1730
|
+
### 21.9 宿主级验证(2026-10-28,重启加载 0.1.2 后)
|
|
1731
|
+
|
|
1732
|
+
八项实测,全部通过(不碰板子的部分都跑了;碰板子的两条见 21.10):
|
|
1733
|
+
|
|
1734
|
+
1. **计划只报缺件(§19 的回归)**:`stm32_env_install` 默认计划 → `steps: []`、`download.bytes: 0`、`verify.ok: true`、`notes: []`、`nextStep: ""`,全文只有「工具链完整,不需要装任何东西:5 个组件都能跑,PATH 与配置都已就位(D:/app/msys64/ucrt64/bin)。」
|
|
1735
|
+
2. **`stm32_env_probe`**:四项能力全 `true`;gcc 13.3.0、gdb 16.2、openocd 0.12.0、cmake 3.31.5、ninja 1.12.1、`cubemx-java` OpenJDK 21.0.3;`cubemx` 的版本串是空的(路径在、版本没解析出来,记进 21.10)。
|
|
1736
|
+
3. **`stm32_doctor`**:`ok: true`、`usb.kind: "no-dap"`(文案把「没插探针 / 线只供电 / BOOT0=1」分开说了)、`portBusy: false`、`processes: []`、`blockers: []`。
|
|
1737
|
+
4. **2b hex/bin**:寄存器版工程(template 7 / drivers 10,缓存命中)→ 首次 `cmake --preset Debug` 21.9 s、编译 2.2 s、`elf` 431,012 B、RAM 7.7% / FLASH 1.16%;`converted` = `hex` 2,221 B + `bin` 760 B,落在 `build/Debug/` 里。
|
|
1738
|
+
5. **0a sha256 真下载**:把 `%LOCALAPPDATA%\dsh-stm32\cache` 整个挪开 → `stm32_cache fetch` → 11 个文件 / 1,071,297 B 全部过校验并落盘;新缓存与挪开的旧缓存逐文件比对 `diffCount=0`。
|
|
1739
|
+
6. **sha256 反向验证**:同一个 URL 故意喂 64 个 `0` 的哈希 → `ok: false`,attempts 原文「sha256 对不上(期望 0000000000000000…,实际 05e93fa3ddefb2e8…)。多半是上游 master 挪动了内容」;喂真值 → `ok: true`、10,110 B。说明这道门禁不是空转。
|
|
1740
|
+
7. **export**:同一个寄存器工程 `includePrebuilt: true` → zip 1,522,918 B / 21 条,包内有 `prebuilt/{p1verify.elf,hex,bin}`、`README.md`、`openocd.cfg`、`.gitignore`,**没有** `build/`、没有 `.dsh-stm32/`;notes 写明 build 不进包的原因(CMakeCache 记着本机绝对路径)。
|
|
1741
|
+
8. **2c + hal 路线**:hal 工程 template 15(比旧版多 `openocd.cfg`)、drivers 238、`firmwareRoot` = `D:\app\STM32CubeMX\dsh-firmware\STM32Cube_FW_F1_V1.8.8`;`.vscode/launch.json` 与 `settings.json` 剥注释后都 `JSON.parse` 成功、**占位符 0 个、`D:/JingYu` 0 次**,`armToolchainPath` / `gdbPath` 填的是本机探测到的 `D:/app/msys64/ucrt64/bin`;寄存器版工程没有 `.ioc` 时 `checkNoDebugGuard` 按 `openocd.cfg` 的 `transport=swd` 放行(`blocked=false`)并说明依据,不再静默通过。
|
|
1742
|
+
|
|
1743
|
+
**顺手记下的两个 API 事实**(下次写验证脚本别再踩):`src/engine/zip.ts` 的 `listZipEntries(buffer)` 返回的是**文件名数组**(`string[]`),不是对象数组;在 `demo/` 下写脚本 import 插件的 `lib/` 必须用 `file:///` 绝对 URL,相对路径会 `ERR_MODULE_NOT_FOUND`。
|
|
1744
|
+
|
|
1745
|
+
**验证用的临时工程**(`.verify-p1/` 下的 reg、hal、zip 与三个脚本)与挪开的旧缓存都已进回收站,`demo/` 下 `.verify-*` / `.tmp-*` 为 0。
|
|
1746
|
+
|
|
1747
|
+
### 21.10 还没验证的
|
|
1748
|
+
|
|
1749
|
+
- `npm run test:pack` 只在开发机跑过,CI 上首跑要看 windows-latest 的 `tar` 行为(已按经验带 `shell: true`);
|
|
1750
|
+
- 2d 的 `errorCode` 已在真板上验过 `probe-busy`(见 §21.11);`swd-locked` / `flash-protected` / `no-power` / `target-mismatch` 四种要制造锁片、写保护或拔电源,不能为了测试去毁板子,仍只有单测覆盖;
|
|
1751
|
+
- `/stm32-setup`、`/stm32-build` 等斜杠命令的人工卡片:命令只能用户自己输入,工具层结论已由上面的 1–8 覆盖;
|
|
1752
|
+
- `stm32_env_probe` 里 `cubemx` 的版本串为空是**设计如此**(`probe.ts` 的 cubemx 目标 `versionArgs: []`——启动器 exe 没有可用的 `--version`,版本靠 `cubemx-java` 那项);卡片上 `OK cubemx <路径>` 正常显示,只有直接读 JSON 的 `version` 字段才是空串。验证时一度把它当缺陷,记在这里免得下次又查一遍;
|
|
1753
|
+
- P2(多芯片 F0/F3/F4/G0/L4、HAL 外设源文件落位)与 P3(gdb MI 常驻)未开工。
|
|
1754
|
+
### 21.11 上板验证(2026-10-28,蓝丸 F103C8T6 + CMSIS-DAP)
|
|
1755
|
+
|
|
1756
|
+
用户插上板子后补的第五~九项。**这一步抓出了两个只有真硬件才会暴露的缺陷**,单测当时全是绿的。
|
|
1757
|
+
|
|
1758
|
+
**跑通的部分**
|
|
1759
|
+
|
|
1760
|
+
- `stm32_doctor`:`usb.kind` 从 `no-dap` 变成 `ok`(「能看到 CMSIS-DAP 设备且驱动正常」),`processes: []`、`portBusy: false`。
|
|
1761
|
+
- `stm32_flash` 烧 demo:`ok`、`programmed + verified`、2.5 s、`errorCode` 缺省;openocd 日志 `device id = 0x20036410`、`flash size = 64 KiB`、`clock speed 1000 kHz`(工程自带 `demo/openocd.cfg`)。
|
|
1762
|
+
- 新建寄存器工程(`route=register`,`template 7 / drivers 10`,缓存命中)→ 构建 9.0 s configure + 2.5 s 编译、`regcheck.elf` 431,052 B、RAM 7.70% / FLASH 1.16% → `stm32_flash` 走模板 `openocd.cfg`(`transport swd` + `adapter speed 2000`,日志 `clock speed 2000 kHz`)成功,notes 第一条是「SWD 守卫(openocd.cfg 版):transport 是 swd…」——2c 的两条路径(.ioc 与 openocd.cfg)都在真机上成立。
|
|
1763
|
+
- `stm32_regs_read`:`pc=0x08000210`;`0x4001100C`(GPIOC_ODR)=`0x00000000`、`0x40011004`(GPIOC_CRH)=`0x44244444`、`0x40021018`(RCC_APB2ENR)=`0x00000035`、`0xE000ED04`=`0x00000000`,全 `ok`、`errors: []`。
|
|
1764
|
+
- `stm32_debug_run`(`breakAt: main`):`ok`、`hitBreakpoint`、`main () at Core/Src/main.c:67`、`pc=0x8000f58 sp=0x20004ff8 lr=0x80011ab`、backtrace 一条。
|
|
1765
|
+
|
|
1766
|
+
**缺陷 1:模板 `openocd.cfg` 写了 `hla_swd`(2c 的模板错了)**
|
|
1767
|
+
|
|
1768
|
+
寄存器工程第一次烧录,宿主直接拒收:`tool "stm32_flash" returned invalid output: "value.report.errorCode" is not a declared property`(这才是缺陷 2 暴露的入口)。手动跑 openocd 才看到真因:`Error: Debug adapter doesn't support 'hla_swd' transport`,位置正是模板的 `transport select hla_swd`。`hla_swd` 只有 st-link 系适配器支持,CMSIS-DAP 必须 `transport select swd`。
|
|
1769
|
+
|
|
1770
|
+
修法与回归:模板改 `transport select swd`(注释里写清为什么不能用 `hla_swd`),`test/flash-units.test.mjs` 加一条读模板文件的用例——断言 `/transport\s+select\s+swd\b/u` 命中、**生效行**不含 `hla_swd`(注释允许解释)、把这份配置写进临时目录后 `checkNoDebugGuard` 报 `blocked=false` 且 notes 含「transport 是 swd」。教训:模板类文件也要有「按真实消费者跑一遍」的断言,光断言文件存在不够。
|
|
1771
|
+
|
|
1772
|
+
**缺陷 2:`stm32_flash` 的 report schema 漏声明 `errorCode`(2d 在失败路径上不可用)**
|
|
1773
|
+
|
|
1774
|
+
`src/tools/flash.ts` 的 `reportSchema` 是 `additionalProperties: false`,但没写 `errorCode`。成功路径 `errorCode` 是空串、引擎按 `...(errorCode === "" ? {} : { errorCode })` 省略,所以永远不触发;**只要失败带码,宿主就判「工具返回了非法输出」,报告拿不到**。2d 加字段时只改了 `FlashReport` 类型与卡片渲染,没同步 schema,单测也只测了空目录早退(不带码)。
|
|
1775
|
+
|
|
1776
|
+
修法与回归:schema 补 `errorCode`(enum 收到 8 个码,不进 `required`);`test/schema-guard.mjs` 加「失败报告带 errorCode 时仍符合 output schema」,用假 subprocess 返回 `exitCode 1` + `no-probe` 文本,断言 `report.errorCode === "no-probe"` 且过 schema 检查。教训:**新增可选字段必须同时进 schema**,而且要有一条「字段有值」的用例——只测缺省值等于没测。
|
|
1777
|
+
|
|
1778
|
+
**顺手补的分类:两个 openocd 抢同一个探针**
|
|
1779
|
+
|
|
1780
|
+
为了验 `probe-busy`,用 `Start-Process` 起一个常驻 openocd(`-f interface/cmsis-dap.cfg -c "transport select swd" -f target/stm32f1x.cfg -c init`,日志 `Listening on port 3333`)攥住探针,再调 `stm32_flash`。真实失败**不是**「设备忙」,而是两个进程交替收发:`CMSIS-DAP command mismatch. Sent 0x12 received 0x5`、`CMSIS-DAP command CMD_DISCONNECT failed`、满屏 `CMSIS-DAP transfer count mismatch: expected 5, got 1`、`Failed to write memory`、`clearing lockup after double fault`。原来的 `errorCodeOfLines` 一条都不认 → `unknown`。
|
|
1781
|
+
|
|
1782
|
+
修法:`errorCodeOfLines` 增加 `/cmsis-dap (transfer count mismatch|command mismatch)|cmsis-dap command cmd_\w+ failed|libusb_error_busy/` → `probe-busy`;新增 `HINT_BUSY` 并只在 `errorCode === "probe-busy"` 时进 notes(「先关掉调试会话或另一个 openocd,再烧一次」)。宿主级实测:`ok=false`、`exitCode=1`、`errorCode=probe-busy`、notes 就是 `HINT_BUSY`,工具正常返回;杀掉持锁进程后再烧 demo → `ok`、`programmed + verified`、3.1 s、`errorCode` 缺省。
|
|
1783
|
+
|
|
1784
|
+
另外记一个 PowerShell 坑:`Start-Process -ArgumentList` 不会替你加引号,`-c 'transport select swd'` 会被拆成两个参数,openocd 报 `Unexpected command line argument: select`;要写成 `-c '"transport select swd"'`。
|
|
1785
|
+
|
|
1786
|
+
**计数**:本批新增 3 例(flash 13 → 15 两条、schema-guard 23 → 24 一条)→ **25 套件 338 pass / 0 fail**(CI 336 + 2 skipped);README / README_EN 的用例数与 CI 计数已同步。
|
|
1787
|
+
|
|
1788
|
+
**清理**:`demo/.verify-board/`(一次性寄存器工程)与 `%TEMP%` 下的持锁脚本、openocd 日志、重启脚本都进了回收站,计划任务 `dsh-restart-board` 已注销;`demo/` 下 `.verify-*` / `.tmp-*` 为 0。
|
|
1789
|
+
|
|
1790
|
+
|
|
1791
|
+
|
|
1792
|
+
|
|
1793
|
+
|
|
1794
|
+
|
|
1795
|
+
|
|
1796
|
+
|
|
1797
|
+
## 22. 源码精读指南:把 2 万行拆成七站(2026-10-26)
|
|
1798
|
+
|
|
1799
|
+
新增 `docs/reading-guide.md`(约 695 行 / 4 万字符)。它不是 API 文档,而是「怎么读这份源码」的路线图:11 章、14 张 Mermaid 流程图,从宿主装配一路读到测试假件。
|
|
1800
|
+
|
|
1801
|
+
结构:0 心法(四层:L4 装配 / L3 tools 契约 / L2 engine 逻辑 / L1 data 事实表,加四条设计约定)→ 1 整体框架图 + 目录行数全景 → 2 七站阅读顺序(每站有行数、能回答的问题、建议时长)→ 3 入口层 → 4 tools 骨架与 20 工具表 → 5 engine 十个域逐文件表 → 6 data 六张事实表 → 7 十四条流程各配一张图 → 8 二十条不变量 → 9 测试三层 → 10 改东西动哪里 → 11 已知的坑。
|
|
1802
|
+
|
|
1803
|
+
**写文档时踩到的两件事**
|
|
1804
|
+
|
|
1805
|
+
1. **数字必须从磁盘重算,不能抄早先的清点。** 第一版的行数是从几轮前的一次 `grep` 清点里拿的,已经过时:engine 合计写成 11 994(实为 12 753)、`commands/register.ts` 386(实为 445)、`client/client.js` 674(实为 682)、`msys2-install.ts` 1808(实为 2038)、`types.ts` 164(实为 196)。最后用脚本按「读文件 → 按 `\n` 切 → 去掉末尾空行」重新统计,再把文档里所有 `文件名(数字)`、章节小计、目录合计、阅读站小计逐个对齐,并做了一次反向扫描(把每个「文件名 + 数字」对拿新表校验,剩 0 处不一致)。教训:文档里的数字要么别写,要么每次由产物重算——写死手抄值必然在下一批改动后变成假话。
|
|
1806
|
+
2. **Mermaid 的标签一律用双引号包住。** 节点标签里出现括号、斜杠、方括号(`probeCache.set(key, {at})`、`missing[]`)时,不引号化会直接把图解析坏;状态图的行内标签里也尽量别用括号(本轮把 `turn/end(本轮输出结束)` 改成顿号版本)。
|
|
1807
|
+
|
|
1808
|
+
**顺手发现的一处杂物**
|
|
1809
|
+
|
|
1810
|
+
`templates/scaffold/build/` 里有 4 个文件、29 459 B 的构建残留(`.cmake/api/v1/query/client-vscode/query.json`、`CMakeFiles/CMakeConfigureLog.yaml`、`CMakeFiles/3.31.5/CMakeSystem.cmake`、`CMakeFiles/3.31.5/CompilerIdC/CMakeCCompilerId.c`)。全仓库 grep 不到任何 `scaffold/build` 引用,但 `package.json` 的 `files` 含 `templates`,会把它一起打进发行包。已写进指南 §11 待清,尚未删除(等用户确认)。
|
|
1811
|
+
|
|
1812
|
+
README 与 README_EN 的 docs 索引各加一行指向新文档。
|
|
1813
|
+
|
|
1814
|
+
## 23. 可视化:用 Archify 出两张可交互图(2026-10-28)
|
|
1815
|
+
|
|
1816
|
+
精读指南里原来只有 Mermaid。Mermaid 适合贴在 Markdown 里速览,但排版、配色、缩放和导出都不受控;这一节记的是用 Archify(`@tt-a1i/archify-dsh` 技能)把它升级成两张单文件 HTML 的过程与踩坑。
|
|
1817
|
+
|
|
1818
|
+
**产物**(已复制进仓库,随 `docs` 一起发布)
|
|
1819
|
+
|
|
1820
|
+
- `docs/diagrams/dsh-stm32-architecture.html`(约 787 KB):17 个节点、1 个宿主进程边界、19 条连线、5 张卡片。主轴是「调用入口 → tools 层 → 门禁 → engine 五簇 → 子进程桥 → 外部程序(CubeMX / 工具链 / openocd+gdb / pacman)/ 上游仓库」,磁盘状态放卡片。
|
|
1821
|
+
- `docs/diagrams/dsh-stm32-journey.html`(约 771 KB):6 列 × 4 lane 的 workflow。列是时间(定路线 → 体检 → 建工程 → 生成 → 改码 → 编译 → 上板),lane 是「你与模型 / 契约层 / 门禁与失败分支(exception 配色)/ 外部程序与板子」。
|
|
1822
|
+
- 两张都带「来源 N」角标:点开是 `path` + 行号,对着 `reading-guide.md` 第 5 章能直接跳到文件。
|
|
1823
|
+
|
|
1824
|
+
**生成命令**(本机没有 Chrome,用 Edge 冒充 Chromium 通过 browser-check)
|
|
1825
|
+
|
|
1826
|
+
```powershell
|
|
1827
|
+
$env:ARCHIFY_CHROME="C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"
|
|
1828
|
+
node "<skill>/bin/archify.mjs" finalize architecture `
|
|
1829
|
+
".archify/architecture-dsh-stm32-overview-20261028-152823/candidate.json" `
|
|
1830
|
+
".archify/architecture-dsh-stm32-overview-20261028-152823/dsh-stm32-architecture.html" `
|
|
1831
|
+
--quality showcase --repo-root "D:/JingYu/Desktop/c8t6_vscode_test/demo/dsh-stm32" --json
|
|
1832
|
+
```
|
|
1833
|
+
|
|
1834
|
+
candidate JSON 放在工作区 `.archify/<type>-<slug>-<时间戳>/`,不进仓库;改完重新 finalize,再把 HTML 覆盖到 `docs/diagrams/`。
|
|
1835
|
+
|
|
1836
|
+
**踩到的六个坑**
|
|
1837
|
+
|
|
1838
|
+
1. **没有 Chrome 时 browser-check 直接 skipped**(`viewer/chrome-unavailable`,整体 exit 1)。本机只有 Edge,`ARCHIFY_CHROME` 指过去就能跑——Edge 是 Chromium 内核,CDP 检查全过。
|
|
1839
|
+
2. **证据按 HEAD 的已提交字节校验,不认工作区**。`/nodes/N/sources/path` 必须在该 revision 存在:我第一次把 `install-guides.ts` 写成 `src/engine/…`(实际在 `src/data/…`),报 `repository-evidence/file-missing`。行号同理——0.1.2 尚未提交,凡是这一批新加的行都别写行号,只写 `path` 更稳。
|
|
1840
|
+
3. **showcase 要求零警告**:`composition/viewport-height` 在普通检查里只是 warning,在 showcase deliver 里算失败。判据很具体——1440×900 视口下,画布要么高度 ≤ 785(宽 1218),要么横向铺到 ≥ 1414;我最初 6 条 lane 的 workflow 是 1218×912,被判超高,删掉一条 lane(6→5→4)才合格。
|
|
1841
|
+
4. **`composition/desktop-readability` 卡字号**:画布越宽缩放越小,8px 源文字投到 930px 预算上必须 ≥ 6px。把节点宽度一口气加到 196 后 viewBox 变成 1511,投影只有 4.9px;退回 132–160 的混合宽度(viewBox 1218)才过。宽度和字号是一对矛盾,别只盯布局。
|
|
1842
|
+
5. **workflow 的 lane/col 是硬网格**:`mainPath` 必须按列单调,`entry(col1) → route(col0)` 这种回退会报 `mainPath moves backward`;同一 lane 同一 col 只能放一个节点;`route: "straight"` 在跨 lane 的边上根本不可能满足(`workflow/route-preset-conflict`),同 lane 相邻列的边又容易撞 `ambiguous-corridor`(两条边共用一段通道 ≥ 8px)。最后是靠「把失败分支从图里挪进卡片、把 patch/build 放进同一 lane」收掉的。
|
|
1843
|
+
6. **回执文件有归属校验**:artifact 变了以后旧的 `*.browser-check.json` 会被判 `viewer/evidence-path-conflict`(`ownership-artifact-mismatch`),不许覆盖。每轮改完 finalize 前,把旧回执改名(如 `stale-browser-check-*.json`)而不是删掉。
|
|
1844
|
+
|
|
1845
|
+
**经验**:Archify 的价值在「强制你把话说清楚」——节点要一句话、边要有方向、失败分支要么成节点要么进卡片。两次 finalize 卡住的都不是审美,而是「这条边到底谁指向谁」「这个失败到底属于哪个阶段」。写图的过程等于把 `reading-guide.md` 第 7 章又校对了一遍。
|
|
1846
|
+
|
|
1847
|
+
## 24. 第五批:选错 .elf、调试丢根因、安装包单源(F1–F4,2026-10-29)
|
|
1848
|
+
|
|
1849
|
+
用户点名的四个问题,顺序 F1 → F4(m00536)。F1/F2 修的是「已经在做对的事,但结果说错/做错」,F3 修的是「只在网络不好或国内访问时才暴露」,F4 是文档。
|
|
1850
|
+
|
|
1851
|
+
### 24.1 F1:`findElf` 会把旧固件当产物(P0)
|
|
1852
|
+
|
|
1853
|
+
旧规则是「构建目录同名优先」:`buildDir` 叫 `build/Debug` 时 `buildName = "Debug"`,而产物叫 `demo.elf`,两者**永不相等**,于是退化成 `readdir` 顺序——改过工程名(或换个 `project()` 重新生成)之后,中间产物和上一次的固件都在同一个 `build/` 里,谁排在前面就烧谁。这条路径被 **5 个调用点**共用:`src/engine/build.ts:414`(编译后报产物)、`flash.ts:210`(烧之前找 elf)、`debug.ts:402`、`doctor.ts:213`(体检报 elf 大小)、`project-export.ts:104`(导出 prebuilt),所以坏一次是五处一起坏。
|
|
1854
|
+
|
|
1855
|
+
新实现(`src/engine/build.ts:194-284`):
|
|
1856
|
+
|
|
1857
|
+
- `readCmakeProjectName(buildDir)`:从 `CMakeCache.txt` 里读 `CMAKE_PROJECT_NAME:<TYPE>=<名字>`,读不到返回空串(没有缓存不影响出结果)。
|
|
1858
|
+
- `elfCandidates(buildDir)`:列出全部 `.elf`,带 `size` / `mtimeMs`,按修改时间从新到旧排序;`readdir` 或 `stat` 抛错(刚被删、被独占)就跳过,不炸整条链路。
|
|
1859
|
+
- `pickElf(buildDir)`:**先按 CMakeCache 里的工程名精确匹配 `<name>.elf`**(`byProjectName: true`,最权威);匹配不到才退回"修改时间最新"(`byProjectName: false`)。
|
|
1860
|
+
- `findElf(buildDir)`:对外的老签名不变,仍返回 `ElfInfo`,所以五个调用点一行都不用改。
|
|
1861
|
+
- `elfSelectionNote(buildDir)`:构建目录里有 ≥2 个 `.elf` 时回一句人话("用了 demo.elf(18:42:03,按 CMakeCache 的工程名选);没动的 2 个:…"),只放 `notes`,只有一个 elf 时返回空串——不给报告加噪音。
|
|
1862
|
+
|
|
1863
|
+
**判据为什么不是「最新」而是 CMakeCache**:`mtime` 只能回答"谁最后被写",回答不了"谁属于当前这套构建"。`stm32_generate` 重新生成、`cmake --preset` 换 preset、用户手动 `rename` 都能让旧固件比新固件更新;而 `CMakeCache.txt` 是 CMake 自己写的、和这套构建目录一一对应的事实。**先在事实层找答案,再退回启发式**,这条经验在 `buildDir` 检测、`findProjectConfig` 里都出现过。
|
|
1864
|
+
|
|
1865
|
+
### 24.2 F2:`stm32_debug_run` 失败只说"起不来"(P0)
|
|
1866
|
+
|
|
1867
|
+
旧代码在 `waitForListening` 超时后只做两件事:把日志 `tail(15)` 塞进 `openOcdLogTail`,message 写 "没调试:openocd 起不来"。真机上 adapter init 失败的那几行(`Error: unable to find CMSIS-DAP device`、`CMSIS-DAP command mismatch`)常被后 15 行的 `Info :` 挤出去,模型和用户都拿不到根因,而且**同一套分类逻辑在 `stm32_flash` 里已经有了**(`errorCodeOfLines` / `probeMissingLines` / `usbDiagnosis`),调试路径没接上。
|
|
1868
|
+
|
|
1869
|
+
修法(两条失败路径都覆盖):
|
|
1870
|
+
|
|
1871
|
+
1. **openocd 起不来**(`src/engine/debug.ts:277-299`):`errorCodeOfLines(lines)` 归类 → `debugHintFor(code)` 给一句下一步(`no-probe`→查线/驱动、`probe-busy`→关掉另一个 openocd、`swd-locked`→`monitor reset halt`/改 BOOT、`no-power`→查 3V3/GND);只有 `no-probe` 且 `probeMissingLines` 命中时才多跑一次 `usbDiagnosis`(`usbNoteFor` 出人话,`ok` 时不打扰);`firstProblemLine(lines)` 取第一条 `Error/unable to find/no device found/couldn't bind/cannot open/invalid` 进 `errors`,message 带 `(code)`。
|
|
1872
|
+
2. **gdb 起来了但没收好**(`src/engine/debug.ts:351-362`):`ok === false` 时同样算一次 `errorCode`,只在失败时附上(成功时报告里根本不出现这个字段)。
|
|
1873
|
+
3. **日志尾巴换算法**(`keyLogTail(lines, 40)`,`debug.ts:192-203`):先用 `/error|unable to find|no device found|adapter|cmsis-dap|listening|couldn't bind|jtag|cannot/i` 从尾部往前挑"有信息量"的行,挑不满 40 行再按尾部补齐,最后按原顺序拼回去。旧的 `tail(15)` 只保证"最后",新的保证"最后 + 关键"。
|
|
1874
|
+
4. 契约同步:`src/tools/debug.ts` 的 `reportSchema` 补 `errorCode`(8 个码的 enum,不进 `required`),`formatDebugReport` 在"固件:"后加一行"错误码:";`test/schema-guard.mjs` 加一条"失败报告带 `errorCode` 时仍过 output schema + 卡片打印错误码"的用例(手搓报告对象,不跑 15 s 超时)。
|
|
1875
|
+
|
|
1876
|
+
**教训**:同一类失败在两个工具里各写一遍,就一定会有一边落队(`flash` 有 `errorCode` 时 `debug` 没有)。现在两者共用 `HINT_PROBE` / `HINT_BUSY` / `HINT_DP` / `errorCodeOfLines` / `probeMissingLines` / `usbDiagnosis`,改一处两边都变。
|
|
1877
|
+
|
|
1878
|
+
### 24.3 F3:MSYS2 安装包只有 GitHub 一个来源(P1)
|
|
1879
|
+
|
|
1880
|
+
**a) 候选链**(`resolveInstallerUrls(env)`,替换掉的旧名 `resolveInstallerUrl` 已不存在):`MSYS2_INSTALLER_URL`(单源,给了就只试它)> `MSYS2_MIRROR`(给全 `.exe` 当完整地址,否则当目录拼两个文件名)> 四个国内镜像 × 两个文件名 > GitHub × 两个文件名,共 **10 个候选**,顺序就是"国内优先、GitHub 兜底"。**为什么每个源要试两个名字**:镜像只同步 `msys2-x86_64-latest.sfx.exe`,GitHub releases 只有 `msys2-base-x86_64-latest.sfx.exe`(实测 TUNA 上 `msys2-base-…` 是 404),钉死一个名字等于把一半源排除掉。
|
|
1881
|
+
|
|
1882
|
+
**b) pacman 也走国内镜像**(`preferMirrorServers(text, servers)` + `preferChinaMirrors(msys64)`):MSYS2 自带的 `etc/pacman.d/mirrorlist.{msys,mingw}` 第一顺位是官方源,国内装 173 个包会慢到像卡死。安装成功后把国内镜像插到这两个文件**最前面**(`Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/msys/$arch/` 这类),官方条目不删、只在缺失时插入(幂等),文件不存在就跳过。**已经有 MSYS2 的机器一个字都不改**——那是用户自己的配置。
|
|
1883
|
+
|
|
1884
|
+
**c) 断点续传 + 低速判死**(`src/engine/fetch.ts`,同步用于所有下载):`streamOnce(url, part, startAt, …)` 带 `Range: bytes=N-` 流式写 `.part-<pid>-<seq>`;watchdog 每 `min(1000, max(100, stallMs/4))` ms 检查:超过 `stallMs`(默认 10 s)没有新字节,或窗口内平均速率 < `minBytesPerSec`(默认 1024),就 `slow = true` + `controller.abort()`,然后**从已落盘字节续一次**(`fetchOne` 里 `if (!streamed.ok && streamed.slow && streamed.bytes > 0 && !isCancelled())`)。`206` 才追加、`200` 一律截断重写(服务器无视 Range 时不能把两段拼起来)、`416` 直接判失败。**换源一定从零开始**(不同源的字节不保证是同一份,拼出来的 sha256 必然对不上)。安装包那边同一套逻辑用 curl 实现:`-C -` + `--speed-limit 1024 --speed-time 10`,退出码 28 单独写成"太慢(10 s 内不足 1 KB/s)",退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次。
|
|
1885
|
+
|
|
1886
|
+
**d) 缓存三道粗检**:① 命中缓存先 `cachedInstallerBytes`(MZ 魔数 + ≥ `MIN_INSTALLER_BYTES` = 40 MB 才算数)② 下载后查退出码/体量/MZ 头 ③ 解压后查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删,留证据)并让用户重跑。**为什么不能钉 sha256**:镜像与 GitHub 的文件名不同、字节数也不同(实测 TUNA/NJU/aliyun 43,117,824 B、GitHub 42,907,176 B,同步时点不同),跨源钉同一个哈希必然误杀。
|
|
1887
|
+
|
|
1888
|
+
**e) 顺序不变的部分**:CMSIS 头与 ST 固件包仍走原来的候选(raw.githubusercontent → jsdelivr → ghfast → …)。实测 codeload 4.2 s、jsdelivr 675 ms、raw 859 ms,换顺序省不下时间;真正的大头是 43 MB 安装包和 pacman 包体。
|
|
1889
|
+
|
|
1890
|
+
**测试**:`test/install-units.test.mjs` 27 例(新增候选链 / `preferMirrorServers` 幂等 / `preferChinaMirrors` 只动两个文件 / 1 KB 缓存不算数→10 个候选全试 / 已有 MSYS2 不改配置)、`test/cache-units.test.mjs` 22 例(新增"断在 1500 字节→`Range: bytes=1500-`→206 续传""服务器回 200 时截断重写""慢源试两次后换快源、不拼接")。**A29 那条测试同时被改了**:它用 1 KB 假缓存来"跳过下载、在解压步取消",`MIN_INSTALLER_BYTES` 一上就让缓存失效、取消点前移到下载步,解压步自然变 `skipped`——把假缓存改成 40 MB 的 `Buffer.alloc(40_000_002)` 才恢复原意。
|
|
1891
|
+
|
|
1892
|
+
### 24.4 F4:README 排错段补"连不上 GitHub"
|
|
1893
|
+
|
|
1894
|
+
现象:`dsh plugin add github:JingYu-er/dsh-stm32` 报 `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443`。这不是 pnpm 11 的 `allowBuilds` 拦截、不是签名问题、不是包坏了,而是**取包这一跳根本连不上 GitHub**——换个说法就没人再往 pnpm 身上查。
|
|
1895
|
+
|
|
1896
|
+
给了三条不再碰全局配置的路(README 中/英同一条):① 走 npm registry(`add dsh-stm32`,已发布时最省事)② 进程级代理:只给本次命令设 `GIT_CONFIG_COUNT=1` / `GIT_CONFIG_KEY_0=http.https://github.com.proxy` / `GIT_CONFIG_VALUE_0=…`,不写 `git config --global`(那样会影响用户所有仓库)③ 直接吃 codeload 的 tarball。装最新用 `github:JingYu-er/dsh-stm32#main`,要稳定版用 `dsh-stm32@latest`。
|
|
1897
|
+
|
|
1898
|
+
### 24.5 计数与行数
|
|
1899
|
+
|
|
1900
|
+
`npm run build` exit 0;`npm test` → **24 套件 348 pass / 0 fail**(CI 346 + 2 skipped)。行数按"文件内 `\n` 个数"重算:src 65 个 `.ts` **20,758 行**、tools 19 文件 4,832、engine 36 文件 **13,328**(`fetch.ts` 197→**341**、`msys2-install.ts` 2038→**2313**)、data 6 文件 1,803、client 682;`reading-guide.md` 的合计与两处单文件数字、第 9 章用例数已同步。
|
|
1901
|
+
|
|
1902
|
+
**顺手记一个度量坑**:PowerShell 的 `(Get-Content x.ts).Count` 和 `Measure-Object -Line` 都**不等于**行数(前者受文件尾换行影响,后者忽略空行),`wc -l` 在 Git Bash 里对 CRLF 文件也会差一。本文档与 `reading-guide.md` 统一用 Node 读文件数 `\n`:`(text.match(/\n/g) ?? []).length`——示例:`index.ts` 是 119,`Get-Content` 给 108。
|
|
1903
|
+
|
|
1904
|
+
## 25. T1 / T2 验收:sha256 负向与 .ioc 事务链(2026-10-30)
|
|
1905
|
+
|
|
1906
|
+
发布前该验的三件(T1 sha256 负向、T2 .ioc 四步链、T3 真机)里,T1/T2 完全离线,先做掉;T3 卡在探针没识别(见 25.3)。
|
|
1907
|
+
|
|
1908
|
+
### 25.1 T1:sha256 门禁负向(6 例全过,抓到一个真缺陷)
|
|
1909
|
+
|
|
1910
|
+
用注入的 `fetchImpl` 走真 `fetchOne`(一次网络都不发):正控(哈希对→落盘、字节一致、失败记录为空);负控(哈希错→拒绝、消息里有「期望」与「实际」两个前缀和「重新实测」的提示、**不落盘**);旧文件已存在时失败(旧文件原样不动,A15 语义);多源(第一个源回代理登录页 html、第二个源哈希不符→`attempts` 两条各说各的);`minBytes`(1 字节→「只有 1 字节(< 16)」);模拟上游漂移(内容变了但声明哈希还是旧的→拦下并提示去更新 `cmsis-sources`)。
|
|
1911
|
+
|
|
1912
|
+
**抓到的缺陷**:四道校验(体量 / 网页 / markers / sha256)失败后只 `continue`,**没删 `.part` 半成品**。该路径在 `streamOnce` 内部有自己的清理,但校验发生在整个文件读完之后,`.part` 已经躺在缓存目录里——43 MB 的安装包、几十 MB 的模板,几次失败能攒出几百 MB 垃圾,而且它既不参与续传(换源一律从零)也不会被任何清理逻辑回收。
|
|
1913
|
+
|
|
1914
|
+
修法:`src/engine/fetch.ts` 的校验段加局部 `reject(reason)`(`attempts.push` + `removeQuietly(part)`),四道校验改用它再 `continue`;回归沉到 `test/cache-units.test.mjs` 的「fetchOne:校验失败(sha256 / markers / 体量 / 网页)时必须连 .part 半成品一起删掉(T1)」——四道校验各跑一遍,断言目标文件不存在、目录里没有 `.part-*`(22 → 23 例)。
|
|
1915
|
+
|
|
1916
|
+
### 25.2 T2:`.ioc` 事务链(7 例全过,用仓库自带 `templates/scaffold/demo.ioc`)
|
|
1917
|
+
|
|
1918
|
+
工具层走真注册(假 `ctx`:`tools.register` 收定义、`workingDirectory.ensure` 给临时目录、`subprocess` 一律抛错证明没起进程),工程是 `templates/scaffold/demo.ioc`(4 084 B,sha `a487d32b1d3b8818…`)复制到临时目录:
|
|
1919
|
+
|
|
1920
|
+
- `stm32_ioc_inspect`:`STM32F103C8T6` / `STM32Cube FW_F1 V1.8.7` / `SWD=Serial_Wire` / 8 个引脚 / 3 个外设,**不写盘**(sha 不变)。
|
|
1921
|
+
- `stm32_ioc_plan`(加 `PA0` 输出、label `t2led`):`planId` 10 位、`sourceSha256` 等于当前文件、`candidateSha256` 变了,diff **8 条**(`Mcu.Pin8`、`Mcu.PinsNb` 与 `PA0.GPIO_*` 五项),**不写盘**。
|
|
1922
|
+
- `stm32_ioc_apply`:`shaBefore` = 原文件、`shaAfter` = 候选、备份落在 `.dsh-stm32/backups/<时间戳>-ioc/demo.ioc` 且与原文件逐字节一致;写完后反读 inspect 能看到 `PA1` / `t2btn`。
|
|
1923
|
+
- `stm32_ioc_apply({rollbackFrom})`:`rolledBack=true`,文件**逐字节**回到原 sha。
|
|
1924
|
+
- 两条守卫:plan 之后外部改过 `.ioc` → apply 拒写(消息里带两个 sha 与「请重新 plan」)、文件不动;缺 `planId` / 不存在的 `planId` → 给人话且不写盘。
|
|
1925
|
+
|
|
1926
|
+
脚本留在工作区 `.t1-t2/`(不进仓库、不进包):它们的长期价值已经分别沉到 `test/cache-units.test.mjs`(T1)与既有的 `test/e2e-a8-ioc-rollback.mjs` + `test/ioc-plan-units.test.mjs`(T2),重复收进仓库只会养一批没人跑的脚本。
|
|
1927
|
+
|
|
1928
|
+
### 25.3 T3:真机项先挂起
|
|
1929
|
+
|
|
1930
|
+
`stm32_doctor` 报 `usb.kind = "no-dap"`(「有 USB 控制器但没看到常见探针(CMSIS-DAP / ST-Link / DAPLink / CH340)」),`processes: []`、`portBusy: false`。也就是说板子/探针当前没被识别:现在跑 `stm32_flash` / `stm32_regs_read` / `stm32_debug_run` 只会得到 `no-probe` 分支——那验证的是错误路径(2026-10-28 已验过),不是 T3 要的烧录 / 读寄存器 / 断点。插上后再跑。
|
|
1931
|
+
|
|
1932
|
+
### 25.4 计数
|
|
1933
|
+
|
|
1934
|
+
`npm run build` exit 0;`npm test` → **24 套件 348 pass / 0 fail**(CI 346 + 2 skipped);`npm run test:pack` exit 0(16 个必须文件齐全)。README / README_EN / `reading-guide.md` 第 9 章的用例数已同步到 348 / 346。
|
|
1935
|
+
|
|
1936
|
+
## 26. 修掉老洞:`cmake/stm32cubemx/CMakeLists.txt` 从不跟着 .ioc 更新(2026-10-30)
|
|
1937
|
+
|
|
1938
|
+
### 26.1 洞是什么,怎么证实的
|
|
1939
|
+
|
|
1940
|
+
CubeMX 无头生成(`generate all_code_in_main` + `generate code`)只重写 `Core/` 下的代码,`cmake/stm32cubemx/CMakeLists.txt` 这份源清单它一个字都不碰——那是脚手架拷进来的快照。后果:`.ioc` 里新开了 USART1,CubeMX 会老老实实把 `HAL_UART_MODULE_ENABLED` 写进 `stm32f1xx_hal_conf.h`、把 `MX_USART1_UART_Init()` 写进 `main.c`,但源清单里没有 `stm32f1xx_hal_uart.c`,到链接阶段才炸 `undefined reference to HAL_UART_Init`,而错误信息完全指不到真正的原因。
|
|
1941
|
+
|
|
1942
|
+
证据(2026-10-30 实测):`demo/cmake/stm32cubemx/CMakeLists.txt`(3 466 B,mtime 2026/10/21 17:55:36)与 `templates/scaffold/cmake/stm32cubemx/CMakeLists.txt` 逐字节相同,而 `demo/Core/Src/main.c` 的 mtime 是 2026/10/24 15:17:33——中间跑过生成,源清单没变过。模板里三个写死的点:`set(MX_Defines_Syms ... STM32F103xB)`、`set(MX_Application_Src ...)`、`set(STM32_Drivers_Src ...)`(只有 11 个 HAL 模块)。
|
|
1943
|
+
### 26.2 修法:新增 `src/engine/cmake-sources.ts`(450 行)
|
|
1944
|
+
|
|
1945
|
+
- `deviceDefineFromStartup` / `familyTokensFromStartup`:从 `startup_stm32f103xb.s` 反推设备宏 `STM32F103xB` 与家族目录名 `STM32F1xx`(规则:upper 后把倒数第二个 X 换小写 x),不查表。
|
|
1946
|
+
- `halModulesInUse`:模块清单以 `Core/Inc/stm32f1xx_hal_conf.h` 里 CubeMX 自己写的 `HAL_xxx_MODULE_ENABLED` 为准,再并上 `Core/Src/*.c`、`Core/Inc/*.h` 里显式 `#include "stm32f1xx_hal_xxx.h"` 的(兜住手写代码)。不能扫 hal_conf 里那一圈 `#include`:那里 33 个模块全列了一遍,只是被 `#ifdef` 包住。
|
|
1947
|
+
- `collectCmakeSources`:算出启动文件、设备宏、模块清单、驱动源文件(顺序 = `system_stm32f1xx.c` → `stm32f1xx_hal.c` → 其余按模块名字母序,`_ex.c` 存在才带上)、应用源文件(`Core/Src/*.c` + 启动文件),缺 `.c` 的模块进 notes 而不是硬写。
|
|
1948
|
+
- `refreshCubemxCmakeLists(projectDir, { dryRun })`:只改上面三个 managed 块,其余行原样;清单保留原顺序、摘掉磁盘上已不存在的条目、缺的追加到末尾(对用户工程 diff 最小);内容一致时一个字节都不写。
|
|
1949
|
+
- `describeRefresh`:一句话给 notes(「已是最新 / 已更新(新增 N 条)/ 未处理 —— 原因」)。
|
|
1950
|
+
- 接线:`src/engine/generate.ts` 在两条返回路径上都调它——CubeMX 真跑完落位之后(dryRun 时只算不写),以及缓存命中直接复用产物时。只要经过 `stm32_generate`,源清单就会被对齐。
|
|
1951
|
+
### 26.3 差分构建验证(真工具链,不是单测)
|
|
1952
|
+
|
|
1953
|
+
把 `demo` 复制一份(2 935 文件 / 261 914 598 B,排除 `build`、`.dsh-stm32` 等),在副本上做最小改动:
|
|
1954
|
+
|
|
1955
|
+
1. `Core/Inc/stm32f1xx_hal_conf.h` 打开 `HAL_UART_MODULE_ENABLED`,`main.c` 的 `USER CODE BEGIN 2` 里塞 `UART_HandleTypeDef huart1; huart1.Instance = USART1; (void)HAL_UART_Init(&huart1);`。
|
|
1956
|
+
2. `cmake --preset Debug` + `cmake --build --preset Debug`(不刷新源清单)→ 复现老洞:`Core/Src/main.c:84:(.text.main+0x20): undefined reference to HAL_UART_Init`,`ninja: build stopped`。
|
|
1957
|
+
3. 跑 `refreshCubemxCmakeLists` → `added = ["Drivers/STM32F1xx_HAL_Driver/Src/stm32f1xx_hal_uart.c"]`,`modules` 从 7 个变 8 个。
|
|
1958
|
+
4. 重新 configure + build → `[21/21] Linking C executable demo.elf`,`demo.elf` 存在。
|
|
1959
|
+
|
|
1960
|
+
先失败、后成功,两遍都是真跑了 arm-none-eabi-gcc + ninja;这是「修复确实治好了那个症状」的唯一硬证据。副本与临时脚本用完丢回收站。
|
|
1961
|
+
|
|
1962
|
+
### 26.4 验证过程里又抓到两个真缺陷
|
|
1963
|
+
|
|
1964
|
+
- 注释里的 `#define` 被当成启用:真实 `stm32f1xx_hal_conf.h` 里没用到的模块写的是 `/*#define HAL_ADC_MODULE_ENABLED */`,正则照样命中,于是第一次刷新把整个 HAL 的 30 多个 `.c` 全加进了清单(差分验证第 3 步一开始看到的是 30 条 added)。修法:匹配前先 `stripComments`(块注释 + 行注释),并补一条回归用例(三个注释形态 + 源码里被注释掉的 `#include` 都不算)。
|
|
1965
|
+
- 行尾混排导致整文件重写:`demo` 这份文件的 86 行里 6 行 CRLF、80 行 LF,而 `readTextFile` 的 `eol` 是「含 CRLF 就算 CRLF」→ 内容一个字没改,写出来却是全文件翻成 CRLF;再加上「按行切完末尾多一个空串」没摘,每跑一次多一个空行,幂等直接断掉。修法:`dominantEol` 按多数行尾决定写回值、比较时只比内容不比行尾、切完 `pop()` 掉末尾空串。现在对真实 `demo` 跑 dryRun 报「已是最新」,字节不动。
|
|
1966
|
+
### 26.5 测试与计数
|
|
1967
|
+
|
|
1968
|
+
新套件 `test/cmake-sources-units.test.mjs`(15 例):设备宏/家族反推、启动文件排序、原样工程零写入、换芯片(startup + 设备宏一起换、旧 startup 从清单摘掉)、开 UART 只加真存在的 `hal_uart.c` 且第二次幂等、hal_conf 开着但驱动包缺 `.c` 时只进 notes、hal_conf 里那一圈 `#include` 不算用到、源码手写 `#include` 也算、ADC 连 `_ex` 一起加、删掉的驱动文件从清单摘除、dryRun 不写盘、非 CMake 布局/无启动文件 `ok=false`、注释掉的 `#define` 不算启用、CRLF/LF 混排零写入,以及一条接线回归(伪造 `cubemx/jre/bin/java.exe` + 缓存命中,`runGenerate` 在 `skipped=true` 时也必须把 `hal_uart.c` 写进清单);`test/run-units.mjs` 已登记。
|
|
1969
|
+
|
|
1970
|
+
`npm run build` exit 0;`npm test` → **25 套件 363 pass / 0 fail**(CI 361 + 2 skipped);`npm run test:pack` exit 0(16 个必须文件齐全、解包产物能建寄存器工程)。README / README_EN / `reading-guide.md` 第 9 章已同步到 363 / 361。
|
|
1971
|
+
## 27. F1 全系第一步:src/data/stm32f1.ts(2026-10-30)
|
|
1972
|
+
|
|
1973
|
+
### 27.1 为什么先做这一层
|
|
1974
|
+
|
|
1975
|
+
扩 F1 全系的最小切口不是改工具,而是把「型号 → 启动文件 / 设备宏 / 容量」这条事实单独拎出来。原来这条映射散在 src/data/cmsis-sources.ts:105-123 的 startupChoiceFor(只认 STM32F103 加三个字母)和 src/data/chips.ts 的一张 C8T6 引脚表里。
|
|
1976
|
+
|
|
1977
|
+
### 27.2 数据来源(优先级)
|
|
1978
|
+
|
|
1979
|
+
1. 固件包 Drivers/CMSIS/Device/ST/STM32F1xx/Source/Templates/gcc 里真实存在的启动文件——实测 14 个:f100xb/xe、f101x6/xb/xe/xg、f102x6/xb、f103x6/xb/xe/xg、f105xc、f107xc。设备头在同级 Include/,14 个同名(没有 f106)。
|
|
1980
|
+
2. 本机 CubeMX db/mcu/*.xml(Flash/RAM/引脚数,将来做校验用)。
|
|
1981
|
+
3. 文件内置的容量字母表。
|
|
1982
|
+
### 27.3 两个真坑(都是实测暴露的)
|
|
1983
|
+
|
|
1984
|
+
- 容量字母到容量档不是全局映射:字母 C 在 F103 上是 xE(startup_stm32f103xe.s),在 F105/F107 上却是 xC(startup_stm32f105xc.s)。第一版用全局表直接映射,STM32F107VCT6 被判成「没有 xe 这一档」而返回 null。修法:chooseGroup 先试「该 line 真有 x 加字母」,不行再退回全局表。
|
|
1985
|
+
- F106 不存在:最初凭「F105/F106 共用」的旧笔记加了 code 106,结果对着固件包实测没有 startup_stm32f106xc.s,测试直接红。删掉该 line——宁可少一条,也不要编一个上游没有的文件。
|
|
1986
|
+
|
|
1987
|
+
### 27.4 接口与边界
|
|
1988
|
+
|
|
1989
|
+
resolveF1Chip(input) 支持三种输入:完整型号(STM32F103RCT6)、去掉温度后缀(STM32F103C8)、显式容量档(F103:xb)。返回 { chip, reason }:认不出时 chip=null 且 reason 是人话(「F107 没有 xb 这一容量档(上游真实档位:xc)」这种),绝不返回一个不存在的启动文件名。
|
|
1990
|
+
|
|
1991
|
+
RAM 表按「line:容量字母」而不是按容量档——xE 跨 C/D/E 三个字母,RAM 分别是 48/64/64 KiB;查不到就 ramBytes=null 并进 notes,不猜数字。
|
|
1992
|
+
### 27.5 验证
|
|
1993
|
+
|
|
1994
|
+
test/stm32f1-units.test.mjs 11 例:C8T6 与既有事实一致、RCT6 走 xE、C/D/E 三字母 RAM 不同、F107 只有 xC、不存在的档位明确拒绝、未知 line 与坏格式与空输入与坏封装后缀都给原因、无温度后缀也认、F103:xb 与完整型号同解、6 条 line 的每个档位都能反推回启动文件名、RAM 未收录只给 note,以及「本机有固件包时,14 个组合的启动文件与设备头都真实存在」(CI 上自动 skip)。
|
|
1995
|
+
|
|
1996
|
+
npm run build exit 0;npm test 26 套件 374 pass / 0 fail(CI 372 + 2 skipped)。README / README_EN / reading-guide.md 第 9 章已同步。
|
|
1997
|
+
|
|
1998
|
+
## 28. F1 全系落地:HAL/寄存器两条路 + 时钟并入 .ioc 事务 + 薄表(2026-10-30)
|
|
1999
|
+
|
|
2000
|
+
§27 把「型号 → 启动文件 / 设备宏 / 容量」抽成了一张事实表,这一批把这张表接到三条链路上(HAL 建工程、寄存器建工程、.ioc 时钟事务),再加一层一致性护栏与一份全族薄表。四件事各自独立可回退,改动没有新开工具:时钟走的是既有的 `stm32_ioc_plan`,薄表是新脚本产出的数据文件。
|
|
2001
|
+
|
|
2002
|
+
### 28.1 t1:HAL 路线不再写死 C8T6(新增 src/engine/hal-chip.ts,284 行)
|
|
2003
|
+
|
|
2004
|
+
原来的 scaffold 把三个型号相关的文件写死在代码里:`startup_stm32f103xb.s`(拷哪个启动文件)、`STM32F103XX_FLASH.ld`(链接脚本)、`demo.ioc`(工程名与 MCU 字段)。这三处现在都改成**按芯片渲染**。
|
|
2005
|
+
|
|
2006
|
+
`src/engine/hal-chip.ts` 只有两件事:派生与渲染,全是字符串函数(不起进程、不写盘),所以能在**写盘之前**把整份产物渲染完——渲染失败时一个字节都不落盘,不会留下半截工程。
|
|
2007
|
+
|
|
2008
|
+
- `resolveHalChip(input)`:型号 → 启动文件 / 设备宏 / `.ld` 名 / 包名(复用 §27 的 `resolveF1Chip`,认完整型号、去温度后缀、`F103:xb`)。
|
|
2009
|
+
- `renderStartupAndDefine`:`STM32F103RCT6 → startup_stm32f103xe.s + STM32F103xE`。
|
|
2010
|
+
- `renderLinkerScript`:把模板的 MEMORY 两行(RAM / FLASH)与注释两行换成 `STM32F103RCTx_FLASH.ld`,256 KiB / 48 KiB。
|
|
2011
|
+
- `renderIoc`:demo.ioc 的 `Mcu.CPN`、引脚与时钟键一起按型号重写。
|
|
2012
|
+
- `pointLinkerFlagAt`:工具链文件里写死的 `-T STM32F103XX_FLASH.ld` 改成指向新名。**这一步不做就完蛋**——要么链到旧脚本(容量不对),要么命令行上出现两个 `-T`(链哪个看顺序)。
|
|
2013
|
+
|
|
2014
|
+
链接脚本从这一批起按 `<DeviceId>_FLASH.ld` 命名:
|
|
2015
|
+
|
|
2016
|
+
| 型号 | 启动文件 | 设备宏 | 链接脚本 | Flash / RAM |
|
|
2017
|
+
| --- | --- | --- | --- | --- |
|
|
2018
|
+
| STM32F103C8T6 | startup_stm32f103xb.s | STM32F103xB | STM32F103C8Tx_FLASH.ld | 64 / 20 KiB |
|
|
2019
|
+
| STM32F103RCT6 | startup_stm32f103xe.s | STM32F103xE | STM32F103RCTx_FLASH.ld | 256 / 48 KiB |
|
|
2020
|
+
| STM32F107VCT6 | startup_stm32f107xc.s | STM32F107xC | STM32F107VCTx_FLASH.ld | 256 / 64 KiB |
|
|
2021
|
+
|
|
2022
|
+
旧名 `templates/scaffold/STM32F103XX_FLASH.ld` 保留为 **C8T6 的兼容副本**(`templates/` 的文件数没变,scaffold 的文件数断言仍 15),但 cmake 的 `-T` 一律指向按型号命名的那份。
|
|
2023
|
+
|
|
2024
|
+
实测(真建工程):RCT6 → `startup_stm32f103xe.s` / `STM32F103xE` / `STM32F103RCTx_FLASH.ld`(256 KiB、48 KiB);F107VCT6 → `startup_stm32f107xc.s` / `STM32F107xC` / `STM32F107VCTx_FLASH.ld`(256 KiB、64 KiB);C8T6 不回归(`templateFiles` 仍 15,链接脚本换成 `STM32F103C8Tx_FLASH.ld`)。
|
|
2025
|
+
|
|
2026
|
+
### 28.2 t2:寄存器路线泛化到 14 个容量档
|
|
2027
|
+
|
|
2028
|
+
`src/data/cmsis-sources.ts`(392 行)重写。三处要点:
|
|
2029
|
+
|
|
2030
|
+
1. `startupChoiceFor(mcu)` 不再自己认型号,改成委托 `resolveF1Chip`,并保留旧写法的兼容解析:`F1:B`、`F1:8`、`F103:xb`、`STM32F103C8T6` 四种输入同解。老工程里缓存过的条目 id(`F1:B` 那种)也能读。
|
|
2031
|
+
2. `STARTUP_SHA256` 从 1 条变 14 条,**全部是真实下载后算的**(2026-10-30 UTC)。来源:`https://fastly.jsdelivr.net/gh/STMicroelectronics/cmsis-device-f1@master/Source/Templates/gcc/<startup>.s`,备用 `cdn.jsdelivr.net` / `raw.githubusercontent.com` / `ghproxy.net`。sha256 表里连文件字节数一起记,失败信息能直接告诉你「是上游挪了内容还是网络换了页面」。
|
|
2032
|
+
3. 缓存条目 id 改成 `cmsis:F1:103xb`(族 + 容量档),`chipEntryId` / `parseCmsisEntryRef` / `cmsisEntryAliases` 三件套负责新旧 id 互认。
|
|
1651
2033
|
|
|
2034
|
+
另两个新模块:
|
|
1652
2035
|
|
|
2036
|
+
- `src/engine/register-clock.ts`(261 行):寄存器版的时钟代码生成。每条 line 的最高 SYSCLK 不同——**F100 24 / F101 36 / F102 48 / F103·F105·F107 72 MHz**;HSE 8 MHz 乘到上限(F101 走 HSE/2×9 才凑得出 36 MHz);FLASH latency 按频率给 0/1/2(F100 的设备头里没有 latency 字段,自动跳过);APB1 在 >36 MHz 时 ÷2;HSE 起不来就退到 HSI/2×N 并写警告。生成的 `clock_init()` 插在 main() 第一行,末尾 `SystemCoreClockUpdate()` 让 SysTick 与 delay_ms 跟着对。
|
|
2037
|
+
- `src/engine/register-linker.ts`(152 行):按型号渲 `<DeviceId>_FLASH.ld`(改 MEMORY 的 RAM/FLASH 两行 + 注释两行)。F100/F101/F102 的 RAM 不在 §27 的表里,这里用 CubeMX db 的最小值兜底**并明确警告**——宁可报小,也不要让栈跑出真 RAM。
|
|
2038
|
+
|
|
2039
|
+
于是寄存器路线对 F1 的 14 个容量档全部可用,且**不需要 CubeMX、不需要固件包**,只靠下载缓存(第二次起完全离线)。
|
|
2040
|
+
|
|
2041
|
+
### 28.3 t3:时钟配置并入 stm32_ioc_plan(不新开工具)
|
|
2042
|
+
|
|
2043
|
+
为什么不做成 `stm32_clock_plan`:时钟改动本来就是改 .ioc 键,而 .ioc 只能走「plan → 用户确认 → apply」这一条事务。新开工具等于让用户可以绕过 SHA 校验直接写时钟。
|
|
2044
|
+
|
|
2045
|
+
新增两张:`src/data/clock-f1.ts`(215 行,事实:PLL 源 HSE 8 MHz / HSI÷2 4 MHz / HSI 8 MHz、×2..×16、上限 SYSCLK 72 / APB1 36 / APB2 72 / ADC 14 / USB 48、APB1/APB2/ADC 分频表、14 条外设→总线、UART 波特率档、20 个 RCC IPParameters)与 `src/engine/clock-plan.ts`(801 行,求解)。
|
|
2046
|
+
|
|
2047
|
+
求解顺序:枚举全部可行组合 → 取 `|sysclk − target|` 最小(**同距取更高档**,所以 60 MHz 的目标落在 64 MHz,而不是 56 MHz)→ 与 .ioc 现有键做 diff → 派生键**全量重算** → 给逐外设频率表、UART 波特率整除误差、备选档位。
|
|
2048
|
+
|
|
2049
|
+
`mode` 四态:`snapshot`(只看不写,未请求时钟时的缺省)/ `nearest`(就近)/ `explicit`(钉死倍频)/ `none`。任何早退分支都必须带 `clockPlan`(`IocPlanReport.clockPlan` 是必填字段,不是 `null`),这样报告形状统一、schema 不用多态。
|
|
2050
|
+
|
|
2051
|
+
实测(真实 `test/fixtures/project/demo.ioc`,`clock: { targetHz: 60000000 }`,dry plan 未 apply):
|
|
2052
|
+
|
|
2053
|
+
- planId `b4f83c6165de72f7`,17 个键变化(新增 1、删除 0、修改 16);
|
|
2054
|
+
- 结论:目标 60 MHz **不可达**,已选 64 MHz(差 +4 MHz)。F1 的 PLL 只能整数倍频(×2..×16),HSE 8 MHz 拼不出这一档;HSI÷2 4 MHz ×15 正好 60 MHz,但 HSI 精度 ±1% 会把 UART 一起带漂,所以默认没选它(备选里能看到);
|
|
2055
|
+
- 总线:SYSCLK 64 / HCLK 64 / APB1 32(÷2,定时器 64)/ APB2 64(÷1)/ ADC 10.667 MHz(÷6,.ioc 里写成 10666667)/ USB 不可用;
|
|
2056
|
+
- 逐外设:USART1@64、SPI1@64、TIM1@64、ADC1/2@10.667;USART2/3@32、SPI2@32、I2C1/2@32、TIM2/3/4@64;
|
|
2057
|
+
- 波特率误差(16 倍过采样):USART1@64 MHz 最差 115200 −0.080%,USART2@32 MHz 最差 57600 −0.080%;
|
|
2058
|
+
- 写入 21 个 RCC 键(含 `RCC.IPParameters` 合并),源 .ioc 未被修改(`ok=true` 但 dry)。
|
|
2059
|
+
|
|
2060
|
+
错误路径是硬的:SYSCLK >72 / APB1 >36 / ADC >14 时**一个键都不写**,只报错并给最近可行档位。
|
|
2061
|
+
|
|
2062
|
+
### 28.4 t4:doctor 五项一致性 + 引脚表从本机 db 派生
|
|
2063
|
+
|
|
2064
|
+
`src/engine/doctor.ts`(665 行,+382)加了 `checkChipConsistency` / `collectChipConsistency`,比原计划的四项多拆一项:
|
|
2065
|
+
|
|
2066
|
+
1. 芯片型号 ↔ 启动文件名(例:RCT6 却只有 `startup_stm32f103xb.s` → blocker,并写出该有的名字);
|
|
2067
|
+
2. 启动文件 ↔ cmake 设备宏(`STM32F103xB` 配 xE 启动文件 → blocker,提示重跑 `stm32_generate`);
|
|
2068
|
+
3. `.ld` 的 MEMORY ↔ 芯片实际容量(小于芯片 → note「浪费了 N KiB」;大于 → blocker,RAM 同理);
|
|
2069
|
+
4. `.elf` 的 Flash 占用 ↔ Flash 容量(超了 → blocker,≥90% → note);
|
|
2070
|
+
5. .ioc 用到的引脚是否在封装里(本机 db 有封装表时才算)。
|
|
2071
|
+
|
|
2072
|
+
第四项踩了个真坑:**别用 .elf 文件大小判超 Flash**。工作区里那个正经 C8T6 工程,`.elf` 有 641.5 KiB——全是 `-g3` 的调试信息,按文件大小判会把 64 KiB 的芯片判成超容量。改成读 ELF program header,只累加 `p_paddr` 落在 `0x08000000` 起 1 MiB 的 `PT_LOAD` 的 `p_filesz`,同一工程立刻变成 0 blocker。解析不出 program header 时才退回文件大小,并在 notes 里注明「按文件大小粗算」。
|
|
2073
|
+
|
|
2074
|
+
`src/data/chips.ts`(202 行,+162;内置表 2026-10-31 已删,见 §28.9):保留原 `CHIPS` / `findChip` / `isKnownPin` 的语义(未知型号一律放行,不猜、不误拦),新增 `parseMcuDbXmlPins`(`<Pin Name= Position=>`,`Position<=0` 的虚拟脚丢弃,`PC13-TAMPER-RTC → PC13`,电源脚不算)、`findMcuDbDir`(`<CubeMX>/db/mcu`)、`readMcuDbPins`、`deriveChipPinTable({cpn, mcuName, dbMcuDir})` → `kind: db / builtin / unknown`:db 命中就注明来源 XML 与引脚数,否则明说「未与本机 db 校验」,都没有就说明未知引脚一律放行。
|
|
2075
|
+
|
|
2076
|
+
### 28.5 包体三分法与护栏
|
|
2077
|
+
|
|
2078
|
+
这一批开始往仓库里加东西(薄表、图、脚本),先把「什么东西放哪」定下来,否则包体迟早失控:
|
|
2079
|
+
|
|
2080
|
+
| 类别 | 内容 | 实测 |
|
|
2081
|
+
| --- | --- | --- |
|
|
2082
|
+
| 随 npm 包 | `lib/**`(含 `lib/client.js`)、`client/client.js`、`templates/scaffold/**`、`cordis.patch.yml`、两份 README、LICENSE、`docs/*.md` | tarball 525.7 KB / 99 个文件,解包 1538.3 KB,templates/** 38.5 KB |
|
|
2083
|
+
| 进 git 不进包 | `src/**`、`test/**`、`scripts/**`、`docs/diagrams/**` | diagrams 2 MB 原始 / 891 KB gz;`package.json` 的 files 从 `docs` 收窄成 `docs/*.md` |
|
|
2084
|
+
| 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头、HAL 固件包 | 带 sha256 校验,缓存在本机 |
|
|
2085
|
+
| 现造 | `.ioc` 内容(`renderIoc`)、`.ld` MEMORY(`renderLinkerScript`)、cmake 源清单(`refreshCubemxCmakeLists`) | 不进包,按型号生成 |
|
|
2086
|
+
|
|
2087
|
+
护栏是 `scripts/pack-size.mjs`(80 行,`npm run test:size`,CI 在 `test:pack` 之后跑):tarball ≤1.2 MB、`templates/**` ≤60 KB、包内禁止 png/jpg/jpeg/gif/webp/bmp/pdf/html/zip/7z/exe/dll、必须含 README.md / README_EN.md / LICENSE / cordis.patch.yml / docs/reading-guide.md。它用 `npm pack --dry-run --json` 拿文件清单,不写盘。
|
|
2088
|
+
|
|
2089
|
+
### 28.6 芯片薄表:scripts/gen-chip-table.mjs(371 行)——**2026-10-31 已整体删除,见 §28.9**
|
|
2090
|
+
|
|
2091
|
+
目标是一份「不联网、不依赖 CubeMX 运行时」的芯片事实表,供将来扩族时查容量与封装,也方便人肉核对。
|
|
2092
|
+
|
|
2093
|
+
- 来源:本机 CubeMX 的 `db/mcu/*.xml`(2019 个 xml,其中 `compatibility.xml` / `families.xml` / `rules.xml` 不是 MCU,真正 2016 颗;F1 系 58 个)。
|
|
2094
|
+
- XML 里**没有 CPN 字段**,只有 `RefName` 模式(`STM32F103C(8-B)Tx` 这种带备选字母的写法),文件名 = `Mcu.Name` = `.ioc` 里的 join key,CPN 由 RefName 展开派生。
|
|
2095
|
+
- 输出 `src/data/chip-table.json`:2016 行、157546 字节(gz 后约 10 KB),字段为 CPN / 内核 / 主频 / RAM / Flash / 电压 / 引脚数。文件头写明「脚本生成,不要手改」,并注明插件当前只消费 F1 那一段、其余为将来扩族备查。
|
|
2096
|
+
- `--check` 模式:重新从 db 抽一遍,与已落盘的文件比对,不一致就 exit 1(给 CI 用)。
|
|
2097
|
+
- 安装位置不必手填:`--mcu-dir` > `--cube-mx-root` > `STM32_CUBEMX_ROOT` > `~/.dsh-stm32/config.json` 的 `cubeMxRoot` > 默认位置 > 扫盘发现(本机 CubeMX 装在 `D:/app/STM32CubeMX`,就是靠扫盘找到的——只扫目录、不读注册表,扫不到就让人用 `--cube-mx-root` 指过来)。
|
|
2098
|
+
- 读不到 db(没装 CubeMX / 路径不对)时**明确报错退出,不写半截文件**(先写临时文件再 rename,校验通过才替换)。
|
|
2099
|
+
|
|
2100
|
+
### 28.7 文档口径
|
|
2101
|
+
|
|
2102
|
+
README / README_EN / `docs/reading-guide.md` / `src/skill/stm32-workflow.ts` 里「只支持 STM32F103C8T6」的说法全部改口成 **F1 全系**(F100/101/102/103/105/107),并补了两件最容易漏的事:
|
|
2103
|
+
|
|
2104
|
+
- **链接脚本命名规则**:`<DeviceId>_FLASH.ld`(`STM32F103C8Tx_FLASH.ld` / `STM32F103RCTx_FLASH.ld` / `STM32F107VCTx_FLASH.ld`),旧名 `STM32F103XX_FLASH.ld` 只是 C8T6 的兼容副本;命令行上只能有一个 `-T`。
|
|
2105
|
+
- **时钟就近策略**:目标频率不可达时选最接近的一档并**显式标注差多少**(60 MHz → 「不可达,已选 64 MHz(+4 MHz)」),同距取更高档;派生键全量重算;超限一个键都不写。
|
|
2106
|
+
|
|
2107
|
+
skill 的 R2 现在点名「本型号的启动文件 + 本型号的 `.ld`」,R3 补了时钟走同一条事务,`§四 踩过的坑` 加了两条:裸 `cmake -S . -B build` 不读 `CMakePresets.json` 会丢工具链文件(必须 `cmake --preset default` 或显式 `-DCMAKE_TOOLCHAIN_FILE`);换芯片后别留旧链接脚本名(`-T` 两个 .ld 时链哪个看顺序,症状是「编译过、上板跑飞」)。
|
|
2108
|
+
|
|
2109
|
+
### 28.8 验证
|
|
2110
|
+
|
|
2111
|
+
- `npm run build` → exit 0。
|
|
2112
|
+
- `npm test` → **29 套件 418 pass / 0 fail**(CI 上 416 pass + 2 skipped);本批新登记 `hal-route-units`(12 例)、`clock-units`(14 例)、`doctor-chip-units`(15 例),既有套件未回归。
|
|
2113
|
+
- `node scripts/gen-chip-table.mjs --check` → exit 0(生成物与 db 一致)。
|
|
2114
|
+
- `npm run test:size` → exit 0(tarball 525.7 KB / 上限 1171.9 KB,templates 38.5 KB / 上限 60 KB)。
|
|
2115
|
+
|
|
2116
|
+
注:§27.5 里的「26 套件 374 例」是当时的数,现在是 29 套件 418 例(captain 口径里的 28 个套件少算了 `schema-guard`);§27.3 的坑、§27.4 的接口都还成立,只是 `startupChoiceFor` 现在委托给 `resolveF1Chip` 了。
|
|
2117
|
+
|
|
2118
|
+
### 28.9 2026-10-31:删掉全部内置芯片表,设备事实只从资源包缓存读
|
|
2119
|
+
|
|
2120
|
+
用户原话:「**内置表删了吧**」。这一批把插件里三张手写/生成的事实表全部清掉,改成「资源仓库出事实、插件只读本地缓存」:
|
|
2121
|
+
|
|
2122
|
+
- **删文件**:`src/data/chip-table.json`(2016 颗薄表,157 KB)、`src/data/f1-ram.generated.ts`(RAM 反查表)、`scripts/gen-chip-table.mjs`(371 行)。脚本**直接删**而不是保留:生成 CPN 的逻辑已经搬到资源仓库的 `scripts/build-assets.mjs`,插件侧再留一份生成器就等于留两条事实来源。
|
|
2123
|
+
- **新增读取层** `src/data/device-facts.ts`:唯一事实来源是 `~/.dsh-stm32/assets/<版本>/device/f1/chips.json`(版本取本地已装最新一版;`DSH_STM32_ASSETS` 可换根目录),按 path+size+mtime 内存缓存一次。`loadDeviceFacts()` / `findChipFact(cpn)`(缺失返回 null)/ `requireChipFact(cpn)`(抛 `DeviceFactError`,code = `facts-missing` / `chip-unknown`)/ `deviceFactsSource()`(缓存路径或 `"none"`)。没有缓存时不抛、不猜,把「先跑 stm32_assets refresh,或检查网络」原样交上去。
|
|
2124
|
+
- **`src/data/stm32f1.ts`**:删 `F1_LINES` / `GROUP_BY_LETTER` / `FLASH_BY_LETTER` / `RAM_BY_LINE_LETTER` / `PINS_BY_PACKAGE` 与 `f1-ram.generated` 的 import;`resolveF1Chip` 的签名与 `F1Chip` 结构不变,改为「解析写法 → 查 device facts」;`f1GroupsFor(code)` 从事实聚合。错误分四类,都带 refresh 提示。
|
|
2125
|
+
- **`src/data/cmsis-sources.ts`**:`F1:B` / `F1:8` 这类只给容量字母的老写法,原来的「字母 → 档位」常量表已删,改成从事实里挑一颗同档芯片当代表(优先 F103),没缓存就返回 null。
|
|
2126
|
+
- **`src/data/chips.ts`**:删 `CHIPS` / `KNOWN_CHIPS` / `findChip` / `ChipInfo`。`isKnownPin(pin)` 改成单参、只查**引脚名合法性**(`PA0..PG15`、`VP_*`;`PA0-WKUP` / `PC13-TAMPER-RTC` 先归一化)。没有拿 `pinCount` 去猜封装引脚——那等于又造一张表;引脚存在性只认本机 CubeMX db(`deriveChipPinTable` 的 `kind` 从 `db / builtin / unknown` 收窄成 `db / unknown`,没有 db 就明说「引脚存在性不校验」)。
|
|
2127
|
+
- **首次使用自动 refresh**:`src/engine/assets.ts` 新增 `ensureAssets({profile:'core'})` —— 缓存命中(已装版本里有 `device/f1/chips.json`)直接返回 `status: "cache"`,否则走 `fetchManifest` + `verifyAndInstall` 自动装一次(`status: "refreshed"`),失败 `status: "missing"` 并带 refresh 文案。接进 `stm32_project_create`(**硬失败**,结构化错误)、`stm32_doctor` / `stm32_ioc_plan` / `stm32_cache` 的 fetch(**软提示**,其余检查照跑);`stm32_generate` / `stm32_ioc_inspect` / `stm32_ioc_apply` / `stm32_route_plan` 本来不读芯片事实,**故意不接**(接了只会让不相关的工具因为没网而失败)。
|
|
2128
|
+
- **测试**:新增夹具 `test/fixtures/assets/2026.10.31-1/`(20 颗真实 CPN + `manifest.json` + `install.json`,值从资源包原样抽,测试不联网);`stm32f1-units` 重写成「事实从哪来 / 缺缓存怎么报」,`doctor-chip-units` 的 builtin 用例改成 `kind: unknown` + 空引脚,`assets-units` 的「内置表兜底」断言全部改口径。`test/run-units.mjs` 未动(captain 统一登记)。
|
|
2129
|
+
- **验证**:`npm run build` exit 0;`npm test` → **31 套件 442 pass / 0 fail**;资源包版本 `2026.10.31-1`(`chips.json` 83 颗 = F1 全部 CPN;任务书里的「58 颗」是 CubeMX `db/mcu` 的 XML 分组数,不是 CPN 数)。
|
|
2130
|
+
- **偏差备案**:任务书要求 `stm32_generate` / `stm32_ioc_*` 也 `await ensureAssets`,实际只接了 `stm32_ioc_plan`(软提示);其余不读芯片事实的工具按上面的理由不接,避免把「没网」变成无关工具的硬失败。
|
|
2131
|
+
|
|
2132
|
+
## 29. B 阶段:结构化探针错误 + 会话复用快路径 + 断点预算(2026-10-31)
|
|
2133
|
+
|
|
2134
|
+
这一批只做三件事,都是「工具已经能用、但在真机上还硌手」的地方:**故障说清楚(B2)**、**连读不要每次重起 openocd(B3)**、**断点别等 openocd 起来才说不够(B4)**。三件都在 engine 层新增一个模块,工具层只负责声明 schema 与渲染。
|
|
2135
|
+
|
|
2136
|
+
### 29.1 B2:一套字段取代 errorCode —— 只留 `probeError`
|
|
2137
|
+
|
|
2138
|
+
旧形态是一枚枚举 `errorCode`(`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`),只回答「哪一类」,不回答「为什么」和「下一步做什么」。用户看到 `swd-locked` 还是不知道要按住 BOOT0 还是查复位时序。现在换成结构化对象:
|
|
2139
|
+
|
|
2140
|
+
```ts
|
|
2141
|
+
interface ProbeError {
|
|
2142
|
+
kind: ProbeErrorKind; // 8 类
|
|
2143
|
+
cause: string; // 一句话根因(来自真实日志行)
|
|
2144
|
+
hint: string; // 可执行的下一步,每类都有专属文案
|
|
2145
|
+
evidence: string[]; // 原始日志行,便于复核
|
|
2146
|
+
retryable: boolean; // 照 hint 处理完再调一次同一个工具,有没有意义
|
|
2147
|
+
}
|
|
2148
|
+
```
|
|
2149
|
+
|
|
2150
|
+
**为什么是「直接替换」而不是加兼容别名**(这是本批唯一的取舍点):
|
|
2151
|
+
|
|
2152
|
+
- 两个字段并存,等于两份规则。flash 与 debug 本来就各有一份分类代码(`errorCodeOfLines` + `debugHintFor`),再加一层旧字段只会让漂移更难发现。
|
|
2153
|
+
- 宿主侧 `output.schema` 是硬的(report 上 `additionalProperties: false`)。多留一个字段就要在 schema 里多声明一次、在 `schema-guard` 里多守一次;而 `errorCode` 这种「只有失败时才有」的可选字段已经在 0.1.2 出过一次事故(失败路径被判非法输出)。
|
|
2154
|
+
- 本插件的版本号还在 0.1.x、外部消费者为零(README 里就是这么写的),没有「老字段要留着不破坏兼容」的义务。既然要改,就改干净。
|
|
2155
|
+
|
|
2156
|
+
具体落点:
|
|
2157
|
+
|
|
2158
|
+
- `src/engine/probe-error.ts`(257 行,新):`ProbeErrorKind` 8 类(多了 `timeout`)、运行期枚举 `PROBE_ERROR_KINDS`、`classifyProbeFailure({lines, exitCode, stage, timedOut, spawnError})` —— 判定顺序是 **MATCHERS 首个命中 → timedOut(timeout) → spawnError(unknown 但带 cause) → unknown**,所以 MATCHERS 数组的**顺序是敏感的**(`no-probe` 必须排在 `probe-busy` 前面,否则 `no device found` 会被 `cmsis-dap command cmd_\w+ failed` 抢走)。hint 常量八条只此一份;`firstProblemLine` / `probeMissingLines` / `usbNoteFor` 从 flash.ts 迁来;`formatProbeError` 出「错误:<kind> — <cause>;建议:<hint>」;`PROBE_ERROR_SCHEMA` 五个字段全 required、`additionalProperties: false`。
|
|
2159
|
+
- `retryable` 的判据只有一条:**照 hint 处理完再调一次同一个工具,有没有意义**。因此 `flash-protected`(要解 RDP / 全片擦除)与 `target-mismatch`(芯片型号根本不对)是 `false`,其余六类 `true`。
|
|
2160
|
+
- `src/engine/flash.ts` / `src/engine/debug.ts`:字段从 `errorCode` 换成 `probeError: ProbeError | null`。**解析层不再归类**(`parseFlashLog` 只回答 programmed / verified / errors / noise),分类在 `runFlash` / `runDebugRun` 里各调一次 `classifyProbeFailure`,两条路径同一个函数、同一组 kind。
|
|
2161
|
+
- `src/tools/flash.ts` / `src/tools/debug.ts`:schema 里 `errorCode` 删除、加 `probeError: PROBE_ERROR_SCHEMA`;卡片行改成「错误:<kind> — <cause>;建议:<hint>」;新增 `flashReportForHost` / `debugReportForHost` —— 引擎在成功路径给的是 `null`,而宿主 schema 不接受 `null`,必须在工具层把 null 摘掉,「成功时字段不出现」才真的成立。
|
|
2162
|
+
- 测试:`test/probe-error-units.test.mjs`(23 例)覆盖 8 类 kind、判定顺序、每条 hint、retryable 表;`schema-guard` 里两条 `errorCode` 用例改成 `probeError` 并断言成功路径的 null 被摘掉;`flash-units` 同步到新 API。
|
|
2163
|
+
|
|
2164
|
+
**四类真机故障的专属 hint**(本批要求写死的四条):
|
|
2165
|
+
|
|
2166
|
+
| kind | cause 形态 | hint 指向的动作 |
|
|
2167
|
+
| --- | --- | --- |
|
|
2168
|
+
| `swd-locked` | `Error connecting DP` / `cannot read IDR` / `AP lock` | 按 BOOT0 上电进系统存储器启动、复位时序里先释放 NRST 再连;确认 PA13/PA14 没被固件改成 GPIO |
|
|
2169
|
+
| `flash-protected` | `flash programming` / `write protected` / `read protected` | 先 `openocd -c "stm32f1x unlock 0"` 解 RDP,或全片擦除后再烧;只擦扇区不够 |
|
|
2170
|
+
| `no-power` | `target voltage may be too low` / `no power` | 查 3V3 / GND、BOOT 跳线、是否只接了 SWD 没共地;量一下目标板电压 |
|
|
2171
|
+
| `target-mismatch` | `device id` / `cannot identify` / `unexpected idcode` | 目标芯片与 `target/stm32f1x.cfg` 不符;换对应族的 target cfg,或确认买到的不是国产兼容片 |
|
|
2172
|
+
|
|
2173
|
+
这四条的 hint 与 kind 都进了单测,但**只有单测没有真机**(真故障不好造,见 §11 的坑 4)——这也是为什么 hint 写得像「操作清单」而不是一句安慰话。
|
|
2174
|
+
|
|
2175
|
+
**历史段落的读法**:本文件 §21(2d)与 §24.2(F2 缺陷)里出现的 `errorCode`、`FlashErrorCode`、`errorCodeOfLines`、`debugHintFor` 都是**当时的字段名与函数名**,原样保留(改历史记录等于篡改当时的验收口径)。从 §29 起,字段只有 `probeError`,函数只有 `classifyProbeFailure`;读旧段落时按这个映射翻译即可。
|
|
2176
|
+
|
|
2177
|
+
### 29.2 B3:会话复用快路径 —— 1493 ms → 15 ms
|
|
2178
|
+
|
|
2179
|
+
痛点:烧完看寄存器,「连读十次看计数器有没有在翻」是标准动作,而每次 `stm32_regs_read` 都**新起一个 openocd、读完关掉**,一次约 1.5 s(旧的一次性路径实测 1493 ms/次;另一次在 WCH-Link 上量到 7010 ms)。
|
|
2180
|
+
|
|
2181
|
+
做法不是「把 gdb 跑快一点」,而是**绕开 gdb**:openocd 启动日志里会打 `Listening on port`(gdb server 与 tcl 两个端口):`debug-session.ts` 新增 `parseListeningPorts` 解析出 `{gdb, tcl, telnet}`,并在 `TCL_PORT_SETTLE_MS = 120` 之后拿**完整启动缓冲**再解析一次(端口行还没打出来就解析会拿到 0),结果存进 `session.tclPort`。新模块 `src/engine/probe-session.ts`(365 行)只消费这个端口:在**一条 TCP 连接**上依次发 halt → `reg pc` → `mdw`×N → resume,帧用 `0x1a`(`TCL_FRAME`)分隔,帧齐立刻收尾(`readWordsViaSession`)。tcl 端口没拿到、或 RPC 出错,就回退到会话里的 gdb 读,并把「为什么回退」写进 notes。
|
|
2182
|
+
|
|
2183
|
+
复用的边界(**只有两个工具复用**):
|
|
2184
|
+
|
|
2185
|
+
- `stm32_regs_read`:`ensureSession` → 有会话就借、没有就起一个并保留到 90 s 空闲租约;报告新增 `reusedSession` 与 `durationMs`;借用已有会话时 `configFile` / `adapterSpeed` 不生效(openocd 是会话里那个),notes 会明说并提示「先 stm32_debug_stop」。
|
|
2186
|
+
- `stm32_debug_eval`:本来就连会话端口上的 gdb,不会起第二个 openocd;**没有会话时明确报「没有调试会话」,而不是自己起一个**。
|
|
2187
|
+
- `stm32_debug_run`:保持一次性(快照工具,跑完就还探针)。
|
|
2188
|
+
- `stm32_flash`:不碰会话(烧录要先独占探针)。
|
|
2189
|
+
- 会话的唯一真相仍是 `debug-session.ts` 的 `debugSessions` 单例——`probe-session.ts` 不自己存句柄、不自己算租约;并发靠模块级 starting Promise 去重(同时两次调用只起一个进程);端口被占**直接报 `probe-busy`**,不让 openocd 顺延端口去抢探针(顺延就是「两个 openocd 抢一个 CMSIS-DAP」的经典翻车姿势)。
|
|
2190
|
+
- 释放四条路都通:turn/end(`src/index.ts` 既有 stop)、90 s 空闲(`sweepExpired`)、`stm32_debug_stop`(`debugSessions.stop`)、进程退出(`process.once('exit')` 里 `terminateSync()` 尽力清理)。
|
|
2191
|
+
|
|
2192
|
+
数字(假探针实测:假 subprocess + 本地假 Tcl 服务端,量的是新代码路径本身):旧一次性路径 **1493 ms/次**;新路径起会话 **790 ms**(第一次调用含启动),之后 10 连读单次 **13–18 ms**(`[16,14,15,18,13,15,16,15,16,15]`)、总计 **154 ms**、openocd 进程数 **1**。
|
|
2193
|
+
|
|
2194
|
+
**真机计时这一条没达成**,如实记在这里:当时插的探针是 WCH-Link(`USB\VID_C251&PID_F001`),openocd 0.12 一 init 就报 `Error: CMSIS-DAP command CMD_INFO failed.`,hid / bulk 后端与 `adapter speed 1000` 都试过;用仓库里 B3 之前的旧版工具跑同一次读,报的也是同一句(那次一次性 openocd 耗 7010 ms)。所以这不是本次改动引入的故障,而是探针/固件不兼容。**复测方法**:换回 CMSIS-DAP 探针,跑 `stm32_regs_read` 连读 10 次 `0x4001100C`,看报告里的 `durationMs` 与 `reusedSession`。
|
|
2195
|
+
|
|
2196
|
+
### 29.3 B4:断点预算 6 / 4 —— 在碰探针之前就报
|
|
2197
|
+
|
|
2198
|
+
Cortex-M3(F1)的硬件断点靠 FPB 的 6 个比较器、观察点靠 DWT 的 4 个。以前设第 7 个断点,要等 openocd 起来、gdb 跑完 `break` 才报错,白占一次探针(还会把你正开着的调试会话顶掉)。
|
|
2199
|
+
|
|
2200
|
+
`src/engine/breakpoints.ts`(281 行,新)把这个上限做成预算:`BreakpointBudget{code, data}`、`F1_BREAKPOINT_BUDGET = {code: 6, data: 4}`、`quotaOf(used, limit)` 给 `{used, limit, remaining}`;预算来源优先 `.ioc` 的 `Mcu.CPN` → 资源包 `chips.json` 里可选的 `breakpoints` / `watchpoints`(只写一个另一个按 F1 补齐),没 `.ioc`、chips.json 没这颗、或没写这两个值都回退 F1 6/4,**并在 note 里明说为什么回退**(不让用户以为芯片就是这么设计的)。
|
|
2201
|
+
|
|
2202
|
+
收集端:`breakAt` + `breakpoints` 参数 + `preCommands` 里的 `break` / `tbreak` / `hbreak` / `watch` / `rwatch` / `awatch` 一起算(`collectBreakpointRequests`),同 kind + location 去重。判定端:`planBreakpoints` 给 `detail`(「这次要设 7 个硬件断点 / 0 个观察点,芯片上限是 6/4(多 1 个硬件断点)」)与 `suggestion`(换 `tbreak`、拆成多次、或换芯片)。
|
|
2203
|
+
|
|
2204
|
+
落点:`debug_run` 与 `debug_session` 都在 spawn openocd **之前**算预算,超限直接失败——不碰探针、也不关已有会话;报告统一带 `breakpoints` / `watchpoints` 两个三元组,卡片打「断点预算:6/6(还剩 0);观察点 0/4」;`debug_eval` 里 `commands` 中的 `break` / `watch` 同样过一遍预算。证据:拿真实 C8T6 工程(`demo.ioc` + `build/Debug/demo.elf`,用 forbidden subprocess 保证不碰探针)设 7 个断点,输出「没调试:断点超预算(硬件断点 6/6,观察点 0/4)」+ detail + 建议——**判定发生在碰探针之前**,所以与 §29.2 那个 WCH-Link 故障完全解耦。
|
|
2205
|
+
|
|
2206
|
+
### 29.4 文档口径
|
|
2207
|
+
|
|
2208
|
+
- `README.md` / `README_EN.md`:错误段落全部改成 `probeError`(`kind` / `cause` / `hint` / `evidence` / `retryable`,8 类),**不再出现 `errorCode`**;烧录行、调试行补了「超断点预算不占探针」与「连读复用会话」;资源包大小从「约 100 KB」改为 **core 约 180 KB**,并在安装一节加了一句「首次使用要联网拉一次资源包,装好之后离线可用」——插件不内置芯片表这件事,用户应该在装的时候就知道,而不是建工程时才撞上。
|
|
2209
|
+
- `docs/reading-guide.md`:engine 从 41 个增至 44 个(表里 44 行;目录里实际 45 个 `.ts`,`assets.ts` 一直没单独成行),§5.4 从 5 个 / 2257 行改成 8 个 / 3160 行并补 `probe-error.ts` / `probe-session.ts` / `breakpoints.ts` 三行;§7.5 / §7.6 的流程图与文字改成 `classifyProbeFailure` + `probeError`,并写了 B3 的 Tcl RPC 快路径与 B4 的预算先算、§9.1 / §9.2 改成 34 套件 497 例(CI 495 + 2 skipped)、§10 的「给工具加错误码」那行改成「加 / 改探针错误分类」、§11 补了坑 13(B3 真机计时欠着)。
|
|
2210
|
+
|
|
2211
|
+
### 29.5 验证
|
|
2212
|
+
|
|
2213
|
+
- `npm run build` → exit 0。
|
|
2214
|
+
- `npm test` → **34 套件 497 pass / 0 fail**(CI 上 495 pass + 2 skipped)。本批新登记三个套件:`probe-error-units` 23 例、`probe-session-units` 16 例、`breakpoints-units` 17 例;既有套件无回归(`schema-guard` 25 例、`flash-units` 已迁到新 API)。
|
|
2215
|
+
- 真机:B4 的 7 断点判定在真实 C8T6 工程上实测(不碰探针);B2 的四类故障、B3 的计时**只有单测 / 假件**,原因见 §29.2 与 §11 的坑 4、坑 13。
|
|
2216
|
+
|
|
2217
|
+
### 29.6 偏差备案
|
|
2218
|
+
|
|
2219
|
+
- **B3 真机计时未达成**:探针侧硬件/固件问题(WCH-Link `CMD_INFO failed`),非代码引入;替代证据是假件实测,复测命令写在 §29.2 与 reading-guide 坑 13。
|
|
2220
|
+
- **资源包体积口径**:任务书写「core 约 180 KB」,实际量到 core profile 是 30 个文件 / 242903 字节 ≈ **237 KiB**(大头是 `device/f1/chips.json` 36.1 KiB 与 `memory.json` 34.2 KiB;SVD 那 1.75 MB 属于 `full` profile,不在 core 里)。收尾时已把两份 README 的 180 KB 改成「30 个文件约 237 KiB」,与实测一致。
|
|
2221
|
+
- **engine 模块计数**:reading-guide 的表是「逐条列出来的模块数」(41 → 44),不是目录文件数(42 → 45)——`assets.ts` 从来没单独成行,这次没顺手补(避免把文档任务做成改表任务)。
|
|
2222
|
+
|
|
2223
|
+
## 30. C 阶段:RTT 日志(openocd rtt + stm32_rtt + 模板侧控制块)(2026-10-31)
|
|
2224
|
+
|
|
2225
|
+
这一批只做一件事:**让固件里的 printf 出现在工具输出里,不接串口、不改接线**。做法不是自己写传输,而是把 openocd 自带的 `rtt` 命令用起来,我们只管三头:**控制块**(固件侧,与 SEGGER 兼容)、**帧语法**(级别 + 时间戳)、**工具面**(`stm32_rtt` 的 start / dump / stop / status)。
|
|
2226
|
+
|
|
2227
|
+
### 30.1 为什么走 openocd rtt,而不是自研传输
|
|
2228
|
+
|
|
2229
|
+
RTT 的传输本质很朴素:调试器通过 SWD 直接读目标 RAM 里的环形缓冲,把新数据搬到宿主。这条链路 openocd 早就有——`rtt setup <addr> <size>` 让它在指定 RAM 区间里认控制块、`rtt start` 打开通道、`rtt server start <port> <channel>` 把它暴露成本地 TCP 端口。传输层是现成的,而且就在我们的调试会话里(B3 之后会话本来就带 Tcl 端口),自己再写一遍没有任何收益:
|
|
2230
|
+
|
|
2231
|
+
- 自研传输要么再起一个 openocd(两个进程抢一个探针,正是 §29.2 端口顺延那类翻车的根源),要么自己实现 SWD 批量读(CMSIS-DAP 的 `DAP_TransferBlock` + apswd 那一层,等于把 openocd 重写一遍)。后者远超这一阶段的风险面。
|
|
2232
|
+
- 反过来,**沿用 openocd 的传输,我们只需要让固件里的控制块长得像 SEGGER 的**:首 10 字节 `"SEGGER RTT"`、`MaxNumUpBuffers` / `MaxNumDownBuffers`、每通道一个 `rtt_buffer_desc_t{sName,pBuffer,SizeOfBuffer,WrOff,RdOff,Flags}`。于是 `rtt setup/start/server start` 三条命令直接认(布局见 30.4)。
|
|
2233
|
+
- **帧格式反而是我们自己的**:SEGGER 原生通道只搬裸字节,没有级别、没有时间戳——而「哪条是 error、这条是几秒前打的」恰恰是排查时最先要的信息。所以在通道 0 的字节流上加 13 字节头(见 30.2)。代价写在 30.6:原生客户端(RTT Viewer / J-Link RTT Client)读通道 0 会把这 13 字节当内容,不会自动拆帧。
|
|
2234
|
+
|
|
2235
|
+
一句话:**传输借 openocd,语法归我们**。这也是为什么 src/engine/rtt.ts(724 行,新)里没有一行 SWD 代码,只有「校验控制块 → 发三条 Tcl / 命令行 → 读端口 → 解帧」四件事。
|
|
2236
|
+
|
|
2237
|
+
### 30.2 帧约定:13 字节头 + UTF-8 payload
|
|
2238
|
+
|
|
2239
|
+
一条记录在通道 0 的环形缓冲里是连续的一段字节:
|
|
2240
|
+
|
|
2241
|
+
| 偏移 | 宽度 | 含义 |
|
|
2242
|
+
| --- | --- | --- |
|
|
2243
|
+
| 0 | 4 | 长度 LE,**含级别 + 时间戳 + payload**,即 `9 + payload 字节数`(不含这 4 字节自己) |
|
|
2244
|
+
| 4 | 1 | 级别:1 error / 2 warn / 3 info / 4 debug(固件侧越界夹到 1..4) |
|
|
2245
|
+
| 5 | 8 | 时间戳,毫秒,LE(默认 DWT 周期计数器按 `SystemCoreClock` 换算,弱符号可覆盖成 `HAL_GetTick`) |
|
|
2246
|
+
| 13 | n | UTF-8 payload,不含结尾 0 |
|
|
2247
|
+
|
|
2248
|
+
常量只有一对,两侧都从它派生:`RTT_FRAME_HEADER_BYTES = 13`、`RTT_MIN_FRAME_BYTES = 9`(payload 为空时长度字段的值)。`src/engine/rtt.ts` 里的 `parseRttFrames` / `encodeRttFrame` 一解一编(后者给单测与自检用),`templates/register/Core/Src/rtt.c` 里的 `RTT_FRAME_OVERHEAD` / `RTT_FRAME_MIN_BYTES` 是同名的另一份——`rtt-units` 有一条反算断言钉住「两边算出来的头长与最小长度一致」,改一边不改另一边会红。
|
|
2249
|
+
|
|
2250
|
+
解析的三个细节(都是「真出过一次就会记一辈子」的):
|
|
2251
|
+
|
|
2252
|
+
- **先看长度字段,再决定信不信它**:`len < 9` 或 `len > 4096`(`DEFAULT_MAX_FRAME_BYTES`)一律判失步,按字节滑动重找,绝不用一个错长度去读后面的内存。
|
|
2253
|
+
- **单帧坏掉不炸整次 dump**:丢掉这一帧、记一条 note,能解出来的记录照常返回。
|
|
2254
|
+
- **截断要出声**:本次读到的数据被环覆盖过、或帧头自洽但 payload 已经滚掉时,报告 `truncated: true` 并说明原因,而不是悄悄少几条。
|
|
2255
|
+
|
|
2256
|
+
### 30.3 工具面:`stm32_rtt` 的四个动作
|
|
2257
|
+
|
|
2258
|
+
一个工具四个 action(`src/tools/rtt.ts`,408 行),共用一份 report schema:
|
|
2259
|
+
|
|
2260
|
+
| action | 做什么 | 关键参数 |
|
|
2261
|
+
| --- | --- | --- |
|
|
2262
|
+
| `start` | 校验控制块 → `rtt setup <addr> <size>` → `rtt start` → `rtt server start <port> 0` | `addr`(必填,控制块起始地址)、`size`(默认 `0x400`)、`banner`、`rttPort`(默认 9090) |
|
|
2263
|
+
| `dump` | 连本地 RTT 端口,读 `seconds` 秒或 `maxRecords` 条,解帧、按 `level` 过滤,返回 `records[{t,level,text}]` | `seconds`(默认 3,0.2..60)、`level`(默认 4 = 全要,语义是「保留到哪一级」的上限)、`maxRecords`(默认 200) |
|
|
2264
|
+
| `stop` | 关端口 / 停 server,幂等 | — |
|
|
2265
|
+
| `status` | 报当前有没有在跑(`running` / `startedAt` / `runningMs` / 端口) | — |
|
|
2266
|
+
|
|
2267
|
+
细节:
|
|
2268
|
+
|
|
2269
|
+
- **start 先 `mdw` 三个字确认控制块**:`0x47474553`(`SEGG`)/ `0x52205245`(`ER R`)/ 低 16 位 `0x5454`(`TT`)。读回全 0 → 「没调 `rtt_init()`」;不是这个魔数 → 「`addr` 指错了」。这一步在 `rtt setup` **之前**,所以地址填错不会把 openocd 带进一个坏状态。
|
|
2270
|
+
- **没有调试会话就自己起一个**:`start` 走 `ensureSession`(与 `stm32_regs_read` 同一个单例),notes 写「没有活跃会话,先起了一个调试会话(gdb 端口 N,tcl 端口 M)」;已有会话则写「复用已有调试会话(tcl 端口 N)」。**只有 `start` 跑工具链门禁**(capability `debug`),`dump` / `stop` / `status` 不跑——读一个本地端口不需要 gcc。
|
|
2271
|
+
- **`rtt start` 需要目标在跑**:目标 halt 住时通道不推进(缓冲不写,也就读不到新东西)。工具在 notes 里点明「先 resume 再 dump」;`dump` 自己不发 halt。
|
|
2272
|
+
- **错误复用 `ProbeError` 形状**:`kind` 只用 `unknown` / `timeout`(另外七类是探针故障,与 RTT 无关,硬塞进来只会误导),`cause` 来自真实日志行,`hint` 覆盖六种情形:端口占用(换 `rttPort`)、通道连不上(连接超时 + 目标是否在跑)、无会话、控制块全 0 / 魔数不符(都指向「模板里怎么加 RTT」)、Tcl 超时、帧失步。
|
|
2273
|
+
- **渲染上限 80 条**:超出打「… 还有 N 条(调大 maxRecords 或分批 dump)」,否则一次 200 条会把卡片刷满。
|
|
2274
|
+
- `isConcurrencySafe: false`:RTT 是「一个端口一个会话」的状态机,两个 dump 并发会互抢那条 TCP。
|
|
2275
|
+
|
|
2276
|
+
### 30.4 模板侧:寄存器版自带,HAL 版只给说明
|
|
2277
|
+
|
|
2278
|
+
`templates/register/Core/{Src/rtt.c,Inc/rtt.h}`(282 + 103 行)随 `stm32_project_create route=register` 一起落地(`templateFiles` 7 → 9)。控制块布局:
|
|
2279
|
+
|
|
2280
|
+
| 偏移 | 字段 | 值 / 说明 |
|
|
2281
|
+
| --- | --- | --- |
|
|
2282
|
+
| 0 | `char acID[16]` | `"SEGGER RTT"` —— openocd `rtt setup` 靠它认块 |
|
|
2283
|
+
| 16 | `uint32_t MaxNumUpBuffers` | 3 |
|
|
2284
|
+
| 20 | `uint32_t MaxNumDownBuffers` | 0(不做下行,`aDown` 只留一个占位) |
|
|
2285
|
+
| 24 | `aUp[3]` | 每个 24 字节:`{sName, pBuffer, SizeOfBuffer, WrOff, RdOff, Flags}` |
|
|
2286
|
+
| 96 | `aDown[1]` | 不使用 |
|
|
2287
|
+
|
|
2288
|
+
四条 `_Static_assert` 把布局钉死(`acID` 在 0、`MaxNumUpBuffers` 在 16、`aUp` 在 24、描述符 24 字节)——这些偏移是 SEGGER 的 ABI,改了 openocd 就认不出来,所以用编译期断言,而不是注释提醒。通道名是 `Terminal` / `Channel 1` / `Channel 2`(工具只读通道 0)。
|
|
2289
|
+
|
|
2290
|
+
写入策略:3 个通道各 1 KB 环形缓冲(`s_up_buf[3][1024]`,共 3 KB `.bss`)。`rtt_ring_write` 先 `memcpy` 数据、**最后**才推进 `WrOff`(读侧不会看到半条帧);剩余空间放不下整条就返回 0、**整条丢**,不写半条、不阻塞、也不覆盖还没被读走的数据。`rtt_init()` 的顺序是先 `memset`、再填描述符、**最后**才写 ID 魔数——openocd 看到魔数时描述符一定已就绪。它会打开 DWT 周期计数器,所以必须在时钟初始化之后调用。
|
|
2291
|
+
|
|
2292
|
+
默认不启用是有意的:`main.c` 只在 `USER CODE BEGIN 2` 里给注释示例,`CMakeLists` 列了 `Core/Src/rtt.c`,但工具链开了 `--gc-sections` 且没人引用 `rtt_init()`——不取消注释时那块 3 KB 缓冲和 rtt.c 的代码都被链接器丢掉(实测默认 RAM 1576 B / FLASH 1368 B,`nm` 里没有 `_SEGGER_RTT`)。取消注释后同一工程实测 RAM **1576 → 5232 B**,控制块落在 **`0x20000DE0`**。
|
|
2293
|
+
|
|
2294
|
+
**一个真实链接缺陷(本批唯一改代码的意外)**:只取消 `rtt_init()` / `rtt_printf()` 的注释就去链接,报 `undefined reference to `_sbrk'` —— `vsnprintf` 会牵进 newlib 的堆延伸,而寄存器版模板没有 `syscalls.c`。修法是 rtt.c 里给一份 `__attribute__((weak))` 的 `_sbrk`(直接失败,等于没有堆):用户自己实现 `_sbrk` 或带 `syscalls.c` 时,强符号自动覆盖它。这条写进了 `rtt.h` 的注释与 `templates/scaffold/RTT.md`,因为它是「照文档加了三行代码却链接不过」最容易撞的那堵墙。
|
|
2295
|
+
|
|
2296
|
+
HAL 版**不预置 rtt.c**:`Core/**` 是 CubeMX 生成区,自己的 `.c` 放进去会被下次 `stm32_generate` 覆盖、也违反「只改 USER CODE」的红线。所以只给 `templates/scaffold/RTT.md`(拷到 `App/`、在 `cmake/user/CMakeLists.txt` 里 `target_sources` + `target_include_directories`、只在 USER CODE 块里写 `#include` 与调用),并在 `cmake/user/CMakeLists.txt` 留了钩子注释。
|
|
2297
|
+
|
|
2298
|
+
### 30.5 性能、丢帧与「读不到」的三种原因
|
|
2299
|
+
|
|
2300
|
+
- **成本在 RAM,不在 CPU**:每通道 1 KB、默认 3 通道 = 3 KB `.bss`(C8T6 20 KB 的 15%)。RAM 紧就改 `rtt.h` 的 `RTT_UP_CHANNELS`(例如 1)/ `RTT_BUF_SIZE`(例如 512),单条 payload 上限 `RTT_MSG_MAX=120` 也能改。
|
|
2301
|
+
- **写入 O(payload)、无锁、不阻塞**:主循环和中断都能写;多上下文并发要自己在外面关临界区(rtt.h 明写「不加锁」)。
|
|
2302
|
+
- **丢帧是整条丢,不是半条**:环满 / 放不下整条 → 返回 0、丢弃,丢了多少数 `rtt_dropped_count()`(固件本地变量)。**口径要注意**:`stm32_rtt` 报告里的 `dropped` 统计的是**按 `level` 过滤掉的记录条数**,不是环丢弃——两者不是一回事,rtt.h 与这个文件里都写清了。
|
|
2303
|
+
- **dump 的默认口径**:3 秒、最多 200 条、单帧上限 4096 字节;`level` 是上限(默认 4 全要,`level=3` 就只要 error/warn/info)。长时间盯日志的正确姿势是「多次 dump」,而不是把 `seconds` 拉到 60——单次越长越容易撞上端口读超时。
|
|
2304
|
+
- **「读不到」分三种,工具分开报**:控制块全 0(没 `rtt_init()`)/魔数不符(`addr` 错)/通道连不上(目标停在 halt、会话掉了、端口被占)。这是 §29.1 那套「kind + cause + hint + evidence」的直接延续。
|
|
2305
|
+
|
|
2306
|
+
### 30.6 已知限制
|
|
2307
|
+
|
|
2308
|
+
- **只有通道 0**:工具只读 `Terminal`。通道 1/2 留给应用自己分用途,插件不读,也没有「按通道分文件」的写法。
|
|
2309
|
+
- **没有 defmt 解码**:帧里就是 UTF-8 文本,不理解 Rust `defmt` 的二进制编码,也不解 SEGGER SystemView 的包。要结构化数据只能自己在 payload 里放 JSON,回宿主再解。
|
|
2310
|
+
- **RTT 占目标 RAM**:默认 3 KB。C8T6 上同时开 ADC + 串口 + 3 KB RTT 就要算账了,这 3 KB 是「加日志要不要紧」的真实代价。
|
|
2311
|
+
- **需要固件先调 `rtt_init()`**:openocd 能认控制块,是因为固件先把魔数和描述符写好了。不调初始化就只有一个全 0 的 RAM 区,工具会明确这么报,而不是含糊地说「连不上探针」。
|
|
2312
|
+
- **时间戳是毫秒且不跨复位**:DWT 按 `SystemCoreClock` 换算,时钟不准它就不准;复位后归零。要墙钟就覆盖 `rtt_time_ms()` 接 RTC / `HAL_GetTick`。
|
|
2313
|
+
- **原生客户端读不了我们的帧**:RTT Viewer / J-Link RTT Client 读通道 0 会看到 13 字节头(它们不知道我们的帧语法)。
|
|
2314
|
+
- **真机 dump 还没有记录**(见 30.9)。
|
|
2315
|
+
|
|
2316
|
+
### 30.7 文档口径
|
|
2317
|
+
|
|
2318
|
+
- `README.md` / `README_EN.md`:功能表与工具表各加一行 `stm32_rtt`(start / dump / stop / status),并补一节「固件里怎么加 RTT」的最短示例——固件侧三行(`#include "rtt.h"`、`rtt_init()`、`rtt_printf(...)`),宿主侧先 `arm-none-eabi-nm … | findstr _SEGGER_RTT` 取控制块地址,再三次工具调用 `stm32_rtt`(start / dump / stop);「已知限制」各加一行 RTT 的边界(通道 0 / 帧是我们自己的 / 3 KB RAM)。
|
|
2319
|
+
- `docs/reading-guide.md`:tools 从 20 个增至 21 个(§1.1 行数、§3.1 注册顺序、§4 标题与 §4.2 表加 `stm32_rtt` 行)、engine 从 44 个增至 45 个(§5 标题与 §5.4 加 `rtt.ts`,8 个 3160 行 → 9 个 3884 行)、§9.1 / §9.2 改成 **35 套件 523 例**(CI 521 pass + 2 skipped)并加 `rtt-units` 26 例、§10 加一行「改 RTT 帧格式」、§11 补坑 14(RTT 只有离线验证)。
|
|
2320
|
+
|
|
2321
|
+
### 30.8 验证
|
|
2322
|
+
|
|
2323
|
+
- `npm run build` → exit 0(typecheck 同)。
|
|
2324
|
+
- `node --test test/rtt-units.test.mjs` → **26 pass / 0 fail**,进程正常退出(C1 的 20 例 + C2 的 6 条静态断言:模板文件与 CMakeLists 引用、控制块布局与 `used`、魔数与引擎常量反算一致、帧常量 13/9 与级别 1..4、HAL 只留说明、弱 `_sbrk` 兜底)。
|
|
2325
|
+
- `npm test` → **35 套件 523 pass / 0 fail**(前 34 套件 497 例 + `rtt-units` 26 例,无回归)。
|
|
2326
|
+
- 真工程:用本地真实 CMSIS 缓存(**未联网**)建寄存器工程 → `templateFiles=9`、`Core/Src/rtt.c` 与 `Core/Inc/rtt.h` 就位;`cmake --preset Debug` + `cmake --build` 两次都 exit 0(默认无 `_SEGGER_RTT` 符号,RAM 1576 B);取消 `USER CODE BEGIN 2` 的注释后同一工程链接出 `_SEGGER_RTT @ 0x20000DE0`,RAM 5232 B。
|
|
2327
|
+
- 帧逻辑在主机上编译执行过(64 位布局,帧代码与固件同源),产出的 4 条记录被 `lib/engine/rtt.js` 的 `parseRttFrames` 正确还原成 `{t, level, text}`。
|
|
2328
|
+
|
|
2329
|
+
### 30.9 偏差备案
|
|
2330
|
+
|
|
2331
|
+
- **真机 dump 未达成**:26 例全部离线(假 subprocess + 假 Tcl / 假端口),真机上只做到「建工程 + 编译 + `nm` 取址」,**没有一次「真板子 + 真探针 + 真 dump」**。原因与本批改动无关:手头的 WCH-Link 在 §29.2 就报 `Error: CMSIS-DAP command CMD_INFO failed.`,而 `rtt start` 需要目标真在跑,探针不通就无从验证。**复测方法**:换回 CMSIS-DAP 探针 → `stm32_flash` 烧一个取消注释的寄存器工程 → `arm-none-eabi-nm build/<preset>/<工程名>.elf | findstr _SEGGER_RTT` → `stm32_rtt action=start addr=<addr>` → `stm32_rtt action=dump seconds=3`。
|
|
2332
|
+
- **只有通道 0 / 无 defmt**:见 30.6,是设计取舍不是欠账(多通道要先在帧头里加通道标识,defmt 解码要另一个依赖)。
|
|
2333
|
+
- **行数口径**:reading-guide 的行数是「在既有数字上加增量」,不是重算——tools 19 → 20 个文件 / 5078 → 5486 行、engine 41 → 42 个文件 / 15919 → 16643 行、§5.4 8 → 9 个 / 3160 → 3884 行。目录里的真实数字比表里的旧值大得多(tools 21 个文件 6157 行、engine 46 个文件 18980 行),顺手重算会把文档任务做成改表任务(与 §29.6 同一条原则,这里如实记一笔)。**D 阶段末已改口径**:全书按文件换行符数重数了一遍(`src/tools` 21 个文件 6623 行、`src/data` 10 个 3599 行),本条只记录 C 阶段当时的做法,别再拿 5486 / 16643 这两个数字当现状。
|
|
2334
|
+
|
|
2335
|
+
## 31. D 阶段:SVD 寄存器命名与位域解释(2026-10-31)
|
|
2336
|
+
|
|
2337
|
+
这一批只做一件事:**让寄存器从「一串十六进制地址」变成「有名字、有位域」的东西**。做法不是自己维护一张寄存器表,而是接资源仓库里的 SVD 事实表(`device/f1/svd/<line>.json`):工具层把 `GPIOC.ODR` 解析成 `0x4001100C`,读回来的 `0x00000020` 再按位域拆成 `ODR5=1`。不新增工具、不改 engine、不动固件模板——`stm32_regs_read` 的手感不变,只是它的 `addresses` 多了几种写法、报告多了几个字段。
|
|
2338
|
+
|
|
2339
|
+
### 31.1 为什么用 SVD,而不是内置一张寄存器表
|
|
2340
|
+
|
|
2341
|
+
「这个外设的基址是多少、这个寄存器偏移多少、这一位叫什么」这三件事只有 ST 的 SVD 有完整答案。三条路摆在面前,选了第三条:
|
|
2342
|
+
|
|
2343
|
+
| 方案 | 为什么不选 |
|
|
2344
|
+
| --- | --- |
|
|
2345
|
+
| 插件内置一张 F1 寄存器表 | 等于手工重写一遍 SVD,还写不全:光 103 一条线就有 53 个外设 / 722 个寄存器 / 4833 个位域。手写表从一开始就是过期数据 |
|
|
2346
|
+
| 运行时解析 ST 的原始 `.svd` XML | 每条产品线 0.5–1.5 MB XML,而本插件**零运行时依赖**(不变量 20),带一个 XML 解析器等于自己养一个依赖;而且插件里没有任何地方需要一个通用 XML 解析器 |
|
|
2347
|
+
| **资源仓库把 SVD 先解析成精简 JSON,插件只读** | 解析一次、六条线复用;插件侧只做「查表 + 解码」,零依赖、纯只读(`src/data/svd.ts` 不写盘、不联网、不起进程) |
|
|
2348
|
+
|
|
2349
|
+
资源仓库的 `scripts/build-assets.mjs` 在构建时把 ST 的 `STM32F1<line>xx.svd` 裁成只含**外设基址 / 寄存器偏移 / 字段 bitOffset+bitWidth** 的 JSON(实测 `103.json` 里连一个 `description` 字段都没有),六条产品线合计 **266 个外设 / 3703 个寄存器 / 27881 个位域,1,795,459 字节 ≈ 1.71 MiB**(103 那份 319,901 字节)。
|
|
2350
|
+
|
|
2351
|
+
**许可上这是硬约束**:原始 SVD 是 STMicroelectronics End User License Agreement v1.0(cmsis-svd-data 的 `data/STMicro/License.html`),不能随插件分发。所以资源仓库只存「编译结果」——地址与位宽这类事实,不含 ST 的说明文字——并且标在 `profile: "full"` 里(`manifest.json` 的 `files[].profile`):`full` 是 128 个文件,`core`(30 个文件 ≈ 237 KiB,见 §29.6 那笔账)里**没有 SVD**。用户跑一次 `stm32_assets refresh --profile full` 就装到 `~/.dsh-stm32/assets/<版本>/device/f1/svd/`;插件之后只读本地缓存,不再联网、也不再分发。
|
|
2352
|
+
|
|
2353
|
+
### 31.2 工程 → line:先看 `.ioc`,再按型号兜底
|
|
2354
|
+
|
|
2355
|
+
一份 SVD 事实表对应一条产品线,所以「读哪个 JSON」要先回答「这块板是哪条线」。`resolveProjectSvd(projectDir, env)` 的顺序是:
|
|
2356
|
+
|
|
2357
|
+
1. 工程里的 `.ioc` 读 `Mcu.CPN`(如 `STM32F103C8T6`)→ 资源包的 `device/f1/chips.json` 里这一颗的 `line` 字段 → `device/f1/svd/103.json`。`source: "chips.json"`。
|
|
2358
|
+
2. `.ioc` 有型号但 `chips.json` 里没有这颗(资源包没装 / 直指资源仓库本体而没有 `install.json`):按 `/^STM32F(\d{3})/` 兜底,落在 `SVD_KNOWN_LINES = ["100","101","102","103","105","107"]` 之内就用。`source: "cpn"`,note 里明说「line 是按型号编号兜底推出来的」。
|
|
2359
|
+
3. 都没有:`source: "none"`,`device: null`,`failure` 说明原因——**不抛异常**,因为「没有 SVD」只是少一层增强,不是错误。
|
|
2360
|
+
|
|
2361
|
+
只有这六条线有数据;同一 line 下的所有容量档/封装共享同一份(C8T6 与 RCT6 都是 `103.json`)。105 与 107 各一份、不合并。成功时 note 会写清用的是哪份:「位域解释来自 SVD line=103(STM32F103xx,53 个外设 / 722 个寄存器 / 4833 个位域,资源包 <版本>)」。
|
|
2362
|
+
|
|
2363
|
+
缓存键是 `path+size+mtimeMs`:资源包升级、重装、手改后自动失效,不需要 reset 钩子;`svdCacheStats()` / `resetSvdCache()` 只给单测证明「命中不重复读盘」。
|
|
2364
|
+
|
|
2365
|
+
### 31.3 五种写法,以及它们为什么等价
|
|
2366
|
+
|
|
2367
|
+
`addresses` 的每一项现在可以是下面五种之一,大小写、首尾空格、箭头两侧的空格都容错:
|
|
2368
|
+
|
|
2369
|
+
| 写法 | 例子 | 解析成 | 备注 |
|
|
2370
|
+
| --- | --- | --- | --- |
|
|
2371
|
+
| 地址(带 `0x`) | `0x4001100C` | 原样读 | 没有 SVD 也能用;有 SVD 时反查名字 |
|
|
2372
|
+
| 地址(不带 `0x`) | `4001100C` | 同上 | 八位十六进制,统一成 8 位大写输出 |
|
|
2373
|
+
| 符号名 | `GPIOC.ODR` | 基址 0x4001100C | 手册里的 `GPIOC_ODR` 写成点更顺 |
|
|
2374
|
+
| C 风格箭头 | `GPIOC->ODR` | 同上 | 与 `.` 完全等价 |
|
|
2375
|
+
| 纯外设名 | `GPIOC` | 该外设全部寄存器(升序,上限 64) | 顺带 dump,见 31.6 |
|
|
2376
|
+
|
|
2377
|
+
解析与去重都发生在**碰探针之前**(`planRegReads`):所有 ref 先解析成地址列表、去重、决定每条的目标类型,全绿了才 `ensureSession`。所以符号写错时一个进程都不会 spawn,不会白占探针——这条和 B4 的断点预算(§29.3)是同一个原则。
|
|
2378
|
+
|
|
2379
|
+
去重与别名在 notes 里会出声:
|
|
2380
|
+
|
|
2381
|
+
- `["GPIOC.ODR", "0x4001100C", "RCC.CR"]` → 只读 2 个地址,note:`「0x4001100C」与「GPIOC.ODR」指向同一个地址 0x4001100C,只读一次`。
|
|
2382
|
+
- `["GPIOC.ODR", "RCC.CR", "GPIOC.ODR"]` → note:`「GPIOC.ODR」重复了,只读一次`。
|
|
2383
|
+
|
|
2384
|
+
### 31.4 报告长什么样
|
|
2385
|
+
|
|
2386
|
+
`samples` 从三个字段变成六个**全部必填**(`additionalProperties: false`,不变量 6):
|
|
2387
|
+
|
|
2388
|
+
| 字段 | 含义 |
|
|
2389
|
+
| --- | --- |
|
|
2390
|
+
| `address` | 8 位大写十六进制,如 `0x4001100C` |
|
|
2391
|
+
| `value` | 读到的值,8 位大写十六进制 |
|
|
2392
|
+
| `ok` | 这一条读成功没有 |
|
|
2393
|
+
| `ref` | 用户原样写的那个字符串(`GPIOC.ODR` / `0x4001100C` / `GPIOC`) |
|
|
2394
|
+
| `name` | 规范化名字(`GPIOC.ODR`);纯地址且没有 SVD 时就是地址本身 |
|
|
2395
|
+
| `fields` | **只列置位**的位域,元素 `{name, bits, value}`;`bits` 单 bit 写 `"5"`、区段写 `"3:7"`,`value` 已按 `bitOffset` 右移 |
|
|
2396
|
+
|
|
2397
|
+
渲染出来的样本行长这样(`GPIOC.ODR` 读回 0x20,`RCC.CR` 读回 0x83):
|
|
2398
|
+
|
|
2399
|
+
```text
|
|
2400
|
+
GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1
|
|
2401
|
+
RCC.CR (0x40021000) = 0x00000083 → HSION=1, HSIRDY=1, HSITRIM=16
|
|
2402
|
+
```
|
|
2403
|
+
|
|
2404
|
+
(等号后一个空格、箭头前两个空格;值为 0 时只到等号、没有箭头,`fields: []`。)
|
|
2405
|
+
|
|
2406
|
+
`message` 的单位跟着目标类型走:这次读里只要有一个符号名或外设名,就说「读到 N 个寄存器」;纯地址仍是「N 个地址」。另外 notes 会补一句 line 来源(见 31.2),所以报告本身就能回答「这个解释是哪来的」。
|
|
2407
|
+
|
|
2408
|
+
### 31.5 位域解码的口径
|
|
2409
|
+
|
|
2410
|
+
`decodeRegisterValue(register, value)` 是纯函数,五个输出:
|
|
2411
|
+
|
|
2412
|
+
| 输出 | 含义 |
|
|
2413
|
+
| --- | --- |
|
|
2414
|
+
| `fields` | 值里**为 1** 的字段:`{name, bitOffset, bitWidth, value, bits}`(`bits` 由 `formatBits` 生成,与报告字段同源) |
|
|
2415
|
+
| `set` / `clear` | 置位名与清位名两组(样本只带 `fields`;`clear` 留给以后做「清位建议」的人) |
|
|
2416
|
+
| `uncovered` / `uncoveredBits` | 没被任何字段覆盖的位数与位掩码。`GPIOC.ODR` 是 16 个单 bit 全覆盖,读 0x00000004 → `ODR2=1`、`uncovered=0` |
|
|
2417
|
+
|
|
2418
|
+
三条取舍:
|
|
2419
|
+
|
|
2420
|
+
- **只报置位**。一整屏「ODR0=0、ODR1=0…」没有信息量;值为 0 的字段读者自己知道是 0。
|
|
2421
|
+
- **不猜枚举名**。SVD 里有 `enumeratedValues` 这类东西,但「寄存器这一位等于 2 是什么意思」是数据手册正文的事;事实表里没有,插件也不编。给出的是位名 + 数值。
|
|
2422
|
+
- **位宽按寄存器 `size`**(SVD 33 个,F1 基本都是 32),没有 SVD 时按 32 位处理。`value` 是右移后的原值,不做符号扩展。
|
|
2423
|
+
|
|
2424
|
+
### 31.6 外设 dump:7 条、64 条上限
|
|
2425
|
+
|
|
2426
|
+
只写外设名(`GPIOC`)时,按 `addressOffset` 升序把该外设的全部寄存器读出来并逐条解释:
|
|
2427
|
+
|
|
2428
|
+
- `GPIOC` → **7 条**:`CRL`、`CRH`、`IDR`、`ODR`、`BSRR`、`BRR`、`LCKR`(最后一条 `GPIOC.LCKR @ 0x40011018`),note:`「GPIOC」是外设名:dump 了它的 7 个寄存器(基址 0x40011000)`。
|
|
2429
|
+
- `RCC` → 10 条(基址 0x40021000)。
|
|
2430
|
+
- 上限 `REG_DUMP_MAX = 64`:超过时只 dump 地址最小的前 64 条,并在 note 里写「外设 X 有 N 个寄存器,只 dump 了地址最小的前 64 个(剩下的写 X.寄存器名 单独读)」。没有新增「dump」这种 action,也没新增工具——`addresses` 里的一项就是一个读目标。
|
|
2431
|
+
|
|
2432
|
+
### 31.7 缺 SVD 时的回退:地址照读,符号名报错
|
|
2433
|
+
|
|
2434
|
+
两种情形分开处理,因为它们的「用户预期」不一样:
|
|
2435
|
+
|
|
2436
|
+
- **纯地址**(`0x4001100C` / `4001100C`):照读。`name` 就是地址、`fields` 是空数组,note 写「没有可用的 SVD:这次只给值,没有名字与位域解释(SVD 只在 profile=full 里:先跑 `stm32_assets refresh --profile full`)」。门禁不拦——读一个地址不需要 SVD。
|
|
2437
|
+
- **符号名 / 外设名**:解析不了就是错误(`ok: false`,不 spawn 进程),文案同上并给出可执行下一步:「`「GPIOC.ODR」不是物理地址;符号名/外设名要靠 SVD 才能解析:SVD 只在 profile=full 里:先跑 stm32_assets refresh --profile full(或者直接写 0x 开头的地址)。`」
|
|
2438
|
+
|
|
2439
|
+
有 SVD 但名字写错,则尽量列出现成可用的名字(`REGS_SUGGEST_PERIPHERALS = 10`):
|
|
2440
|
+
|
|
2441
|
+
```text
|
|
2442
|
+
资源包(line=103)里没有外设 GPIOZ;可用外设(前 10 个):FSMC、PWR、RCC、GPIOA、GPIOB、GPIOC、GPIOD、GPIOE、GPIOF、GPIOG(共 53 个)
|
|
2443
|
+
外设 GPIOC 里没有寄存器 ODRX;已知寄存器:CRL、CRH、IDR、ODR、BSRR、BRR、LCKR(共 7 个)。
|
|
2444
|
+
```
|
|
2445
|
+
|
|
2446
|
+
一个名字既不是已知外设、也不像 `X.Y` 时,会同时说这两件事:「`资源包(line=103)里没有外设 FOO,也不像 GPIOC.ODR 这种寄存器写法;可用外设(前 10 个):…(共 53 个)`」。
|
|
2447
|
+
|
|
2448
|
+
`loadSvd` 本身**不抛**(返回 `{device, failure}`),只有「明确要一个寄存器 / 一段地址」的 API(`resolveRegisterRef` / `describeAddress`)才抛 `SvdError`,`code` 收 9 类:`assets-missing` / `svd-missing` / `svd-invalid` / `line-invalid` / `ref-invalid` / `value-invalid` / `peripheral-unknown` / `register-unknown` / `address-unknown`。严格解析是有意的:外设 / 寄存器 / 字段任何一条不合法就整份拒绝——装错文件比没装更危险,半个位域表会解释出错误的位。
|
|
2449
|
+
|
|
2450
|
+
### 31.8 代码落点
|
|
2451
|
+
|
|
2452
|
+
| 文件 | 行数 | 干什么 |
|
|
2453
|
+
| --- | --- | --- |
|
|
2454
|
+
| `src/data/svd.ts` | 837(新) | 加载(`loadSvd` / `loadSvdForLine` / `requireSvd` / `svdLineForChip`)、符号解析(`resolveRegisterRef`)、反向查(`describeAddress`,给一个地址说它属于哪个寄存器的第几字节)、解码(`decodeRegisterValue`)、渲染小件(`formatDecodedFields` / `formatAddress` / `formatOffset`)、`SvdError`、`SVD_FULL_PROFILE_HINT` 一份文案 |
|
|
2455
|
+
| `src/tools/regs.ts` | 735(原 272,+463) | 五种写法的解析与去重(`planRegReads`)、工程 → line(`resolveProjectSvd`)、样本装饰(`decorateSamples`)、渲染(`describeRegSample` / `formatBits`)、`REG_DUMP_MAX` / `REGS_SUGGEST_PERIPHERALS` |
|
|
2456
|
+
| `test/svd-units.test.mjs` | 39 例(新) | 26 例符号解析与解码(D1)+ 13 例工具层端到端(D2,含假 subprocess 与假 Tcl 服务端) |
|
|
2457
|
+
| `test/fixtures/svd/` | 3 种布局 | flat(直接指向资源仓库本体)、versioned(`<root>/<version>/`)、badline(坏数据必须整份拒绝) |
|
|
2458
|
+
|
|
2459
|
+
engine 的 `src/engine/regs.ts` **一行没动**:它仍旧只负责「生成 openocd 脚本 / 解析 mdw 日志」,符号解析与位域解释全在 tools 层与 data 层。这也是这一阶段几乎没有回归风险的原因——21 个工具的数量与 engine 45 个模块都不变。
|
|
2460
|
+
|
|
2461
|
+
### 31.9 文档口径
|
|
2462
|
+
|
|
2463
|
+
- `README.md` / `README_EN.md`:`regs_read` 的示例从纯地址改成符号名与地址并列(`GPIOC.ODR` / `0x4001100C`),并注明符号名要资源包的 `full` profile;工具表那一行重写为「五种写法 + dump 上限 + 缺 SVD 的回退」;「已知限制」加一行(SVD 只在 full、只覆盖 F1 六条线)。
|
|
2464
|
+
- `docs/reading-guide.md`:§0 与 §1.1 与 §6 的 data 层从 9 个模块改成 **10 个模块 3599 行**并加 `svd.ts` 一行;§1.1 / §4.1 / §4.2 / §5 / §6 的行数按「文件换行符数」统一重数过一遍(口径见下文 31.11);§4.2 的 `stm32_regs_read` 行改为 `regs.ts(735)`、「工具层解析符号名」;§5.4 补一句 engine 不动;§8 加不变量 23(寄存器名字只能来自 SVD);§9.1 / §9.2 改成 **36 套件 562 例**并加 `svd-units` 39 例;§10 加两行(改写法 / 更新 SVD 表);§11 加坑 15(真机未复测)。
|
|
2465
|
+
- 数字口径:D1 加 26 例、D2 加 13 例,合计 **39**;`npm test` 从 523 → **562**,套件 35 → **36**;工具数仍是 **21**,engine 仍是 **45** 个模块。
|
|
2466
|
+
|
|
2467
|
+
### 31.10 验证
|
|
2468
|
+
|
|
2469
|
+
- `npm run build` → exit 0(typecheck 同)。
|
|
2470
|
+
- `node --test test/svd-units.test.mjs` → **39 pass / 0 fail**(26 + 13)。
|
|
2471
|
+
- `npm test` → **36 个套件 562 pass / 0 fail**(前 35 套件 523 例 + `svd-units` 39 例,无回归;`run-units.mjs` 里 `svd-units` 排在 `rtt-units` 之后)。
|
|
2472
|
+
- 真实资源包实测(`DSH_STM32_ASSETS` 直指资源仓库,line=103,53 外设 / 722 寄存器 / 4833 位域):
|
|
2473
|
+
- `GPIOC.ODR` → 0x4001100C(基址 0x40011000 + offset 0x0C,16 个位域);`GPIOC->ODR` 同;`RCC.CR` → 0x40021000(10 个位域)。
|
|
2474
|
+
- 反向:`0x4001100C` → `GPIOC.ODR`;`describeAddress(0x4001100E)` → `GPIOC.ODR`、`exact: false`、`offsetInRegister: 2`。
|
|
2475
|
+
- 解码:`GPIOC.ODR` 读 0x00000020 → `ODR5=1`;`RCC.CR` 读 0x00000083 → `HSION=1, HSIRDY=1, HSITRIM=16`;读 0 → `fields: []`、无箭头。
|
|
2476
|
+
- dump:`GPIOC` → 7 条(`CRL`…`LCKR`),`RCC` → 10 条;`BSRR` 读 0x1 → `BS0=1`。
|
|
2477
|
+
- 混传 `["GPIOC.ODR", "0x4001100C", "RCC.CR"]` → 只读 2 个地址,note 说明别名去重。
|
|
2478
|
+
- 端到端用**假 subprocess + 假 Tcl 服务端**跑(不起真 openocd),覆盖「符号名 + 地址混传 / dump / 64 条截断 / 四种写法等价 / 未知外设建议 / 未知寄存器 / 无 SVD 回退 / 去重 / 位域置位 / line 推断 / 未知符号不 spawn」。
|
|
2479
|
+
|
|
2480
|
+
### 31.11 偏差备案
|
|
2481
|
+
|
|
2482
|
+
- **真机未复测**:符号名与位域解释的证据是「真实资源包 + 假探针」,**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**。原因与 §29.2 / §30.9 同源(手头的 WCH-Link 在 `CMD_INFO failed` 上过不去)。**复测方法**:换回 CMSIS-DAP 探针,`stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 line 来源;顺带把 B3 的真机计时(坑 13)与 RTT 的真机 dump(坑 14)一起补掉。
|
|
2483
|
+
- **行数口径**:D 阶段末把全书行数按**文件换行符数**(node `split('\n')`,等价编辑器的「块末行号」)重数了一遍,第 1、4.1、4.2、5、6 章现在都用这个口径:`src/tools` 21 个文件 **6623** 行、`src/data` 10 个文件 **3599** 行、`src/engine` 46 个文件 **18981** 行(第 5 章只表格化了 45 个模块,`engine/assets.ts` 1162 行未单列);`regs.ts` **272 → 735(+463)**、`svd.ts` **837(新)**。之前用 PowerShell `(Get-Content f).Count` / `Measure-Object -Line` 量的会少算几十行(regs.ts 报 705、实际 735),那批数字已作废——教训写进 §31.11 这条。
|
|
2484
|
+
- **用例数口径**:D2 的交付报告里写「追加 12 个用例(文件 39 例)」,实测文件是 39 例 = 26 + 13;文档按 **39** 记。
|
|
2485
|
+
- **SVD 事实表体积**:六条线 1.71 MiB,`full` 档 128 个文件;`core` 仍是 30 个文件 / 237 KiB。与 §29.6 那笔「core 不在 180 KB」的账一致,没有新的口径变化。
|
|
1653
2486
|
|
|
1654
2487
|
|