dsh-stm32 0.1.2 → 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.
Files changed (44) hide show
  1. package/README.md +59 -21
  2. package/README_EN.md +59 -21
  3. package/docs/development-notes.md +374 -3
  4. package/docs/reading-guide.md +87 -66
  5. package/lib/data/chips.js +38 -51
  6. package/lib/data/cmsis-sources.js +27 -1
  7. package/lib/data/device-facts.js +201 -0
  8. package/lib/data/stm32f1.js +94 -150
  9. package/lib/data/svd.js +627 -0
  10. package/lib/engine/assets.js +924 -0
  11. package/lib/engine/breakpoints.js +242 -0
  12. package/lib/engine/debug-session.js +153 -5
  13. package/lib/engine/debug.js +75 -41
  14. package/lib/engine/doctor.js +2 -2
  15. package/lib/engine/flash.js +31 -59
  16. package/lib/engine/ioc-plan.js +5 -5
  17. package/lib/engine/probe-error.js +212 -0
  18. package/lib/engine/probe-session.js +311 -0
  19. package/lib/engine/register-template.js +32 -8
  20. package/lib/engine/regs.js +2 -0
  21. package/lib/engine/rtt.js +600 -0
  22. package/lib/index.js +8 -0
  23. package/lib/tools/assets.js +341 -0
  24. package/lib/tools/cache.js +8 -0
  25. package/lib/tools/debug-session.js +40 -5
  26. package/lib/tools/debug.js +41 -11
  27. package/lib/tools/doctor.js +11 -0
  28. package/lib/tools/flash.js +15 -6
  29. package/lib/tools/generate.js +3 -0
  30. package/lib/tools/ioc-apply.js +2 -0
  31. package/lib/tools/ioc-inspect.js +2 -0
  32. package/lib/tools/ioc-plan.js +3 -0
  33. package/lib/tools/project-create.js +24 -0
  34. package/lib/tools/regs.js +453 -61
  35. package/lib/tools/route-plan.js +3 -0
  36. package/lib/tools/rtt.js +347 -0
  37. package/package.json +1 -1
  38. package/templates/register/CMakeLists.txt +7 -1
  39. package/templates/register/Core/Inc/rtt.h +103 -0
  40. package/templates/register/Core/Src/main.c +25 -0
  41. package/templates/register/Core/Src/rtt.c +297 -0
  42. package/templates/scaffold/RTT.md +86 -0
  43. package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
  44. package/lib/data/f1-ram.generated.js +0 -34
@@ -29,7 +29,7 @@ git clone git@github.com:JingYu-er/dsh-stm32.git # 或 https://github.com
29
29
  cd dsh-stm32
30
30
  npm install --no-audit --no-fund # 只装 typescript
31
31
  npm run build # tsc -> lib/
32
- npm test # 可选:418 个离线用例(29 个套件)
32
+ npm test # 可选:497 个离线用例(34 个套件)
33
33
  ```
34
34
 
35
35
  然后把 `lib/` 用 `link:` 挂进 dsh 的 profile 并重启 dsh(见下一节)。宿主要求:
@@ -2071,7 +2071,7 @@ npm run build exit 0;npm test 26 套件 374 pass / 0 fail(CI 372 + 2 skipped
2071
2071
 
2072
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
2073
 
2074
- `src/data/chips.ts`(202 行,+162):保留原 `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 校验」,都没有就说明未知引脚一律放行。
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
2075
 
2076
2076
  ### 28.5 包体三分法与护栏
2077
2077
 
@@ -2086,7 +2086,7 @@ npm run build exit 0;npm test 26 套件 374 pass / 0 fail(CI 372 + 2 skipped
2086
2086
 
2087
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
2088
 
2089
- ### 28.6 芯片薄表:scripts/gen-chip-table.mjs(371 行)
2089
+ ### 28.6 芯片薄表:scripts/gen-chip-table.mjs(371 行)——**2026-10-31 已整体删除,见 §28.9**
2090
2090
 
2091
2091
  目标是一份「不联网、不依赖 CubeMX 运行时」的芯片事实表,供将来扩族时查容量与封装,也方便人肉核对。
2092
2092
 
@@ -2114,3 +2114,374 @@ skill 的 R2 现在点名「本型号的启动文件 + 本型号的 `.ld`」,R
2114
2114
  - `npm run test:size` → exit 0(tarball 525.7 KB / 上限 1171.9 KB,templates 38.5 KB / 上限 60 KB)。
2115
2115
 
2116
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」的账一致,没有新的口径变化。
2486
+
2487
+