dsh-stm32 0.1.4 → 0.1.6

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 (38) hide show
  1. package/README.md +517 -459
  2. package/README_EN.md +510 -453
  3. package/assets/device/h7/chips.json +831 -140
  4. package/assets/device/u5/chips.json +375 -64
  5. package/assets/manifest.json +4 -4
  6. package/docs/reading-guide.md +114 -16
  7. package/lib/commands/register.js +1 -1
  8. package/lib/data/cmsis-sources.js +136 -4
  9. package/lib/data/device-facts.js +14 -0
  10. package/lib/data/family.js +14 -14
  11. package/lib/data/firmware-packages.js +35 -14
  12. package/lib/data/firmware-pins.js +128 -0
  13. package/lib/data/search-roots.js +17 -3
  14. package/lib/data/serial-config.js +430 -0
  15. package/lib/engine/doctor.js +85 -8
  16. package/lib/engine/download.js +242 -0
  17. package/lib/engine/fetch.js +1 -1
  18. package/lib/engine/firmware-install.js +158 -35
  19. package/lib/engine/firmware-official.js +113 -65
  20. package/lib/engine/ioc-plan.js +28 -6
  21. package/lib/engine/msys2-install.js +237 -88
  22. package/lib/engine/probe.js +4 -2
  23. package/lib/engine/register-gpio.js +18 -1
  24. package/lib/engine/register-linker.js +25 -6
  25. package/lib/engine/register-template.js +25 -1
  26. package/lib/engine/serial.js +1696 -0
  27. package/lib/engine/tar.js +235 -3
  28. package/lib/index.js +12 -0
  29. package/lib/skill/stm32-workflow.js +2 -2
  30. package/lib/tools/assets.js +8 -3
  31. package/lib/tools/build.js +0 -1
  32. package/lib/tools/doctor.js +9 -3
  33. package/lib/tools/download.js +303 -0
  34. package/lib/tools/ioc-plan.js +17 -7
  35. package/lib/tools/project-create.js +1 -1
  36. package/lib/tools/serial.js +737 -0
  37. package/package.json +70 -70
  38. package/templates/serial/bridge.ps1 +477 -0
@@ -505,8 +505,8 @@
505
505
  },
506
506
  {
507
507
  "path": "device/h7/chips.json",
508
- "bytes": 53921,
509
- "sha256": "ed1ddc949f091f5ead17ec277b948850d161d7ee972c7ecb4195d8eaccc1f0ce",
508
+ "bytes": 69868,
509
+ "sha256": "f56f90a2acf56232728dd09c25063926e09f2bc2e1bae0830cebb26ad9afade7",
510
510
  "source": "CubeMX db/mcu + STM32Cube_FW_H7_V1.11.0(H7 全部 CPN)",
511
511
  "profile": "core"
512
512
  },
@@ -561,8 +561,8 @@
561
561
  },
562
562
  {
563
563
  "path": "device/u5/chips.json",
564
- "bytes": 24718,
565
- "sha256": "e71b81d6ad86686686c9a19a46c6c5fbd4285740e8d35d01289b46797d751bf2",
564
+ "bytes": 32038,
565
+ "sha256": "5a47bb87e1d0ef8f2a51477ffe437dd01899c17f8220534448ed8a45615e3d4f",
566
566
  "source": "CubeMX db/mcu + STM32Cube_FW_U5_V1.8.0(U5 全部 CPN)",
567
567
  "profile": "core"
568
568
  },
@@ -1,7 +1,7 @@
1
1
  # dsh-stm32 源码精读指南
2
2
 
3
3
  > 面向:第一次读这个仓库、并且要改它的人。
4
- > 规模:75 个 TypeScript 文件约 23.2k 行,外加一个手写的浏览器 bundle(client/client.js,682 行)。**芯片事实随包内置**:`src/data/device-facts.ts` 读插件包内 `assets/device/f1/chips.json`(`DSH_STM32_ASSETS` 可覆盖;2026-11 从独立资源仓并入插件),2026-10-31 已删掉手写 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表。
4
+ > 规模:110 个 TypeScript 文件约 42.3k 行,外加一个手写的浏览器 bundle(client/client.js,618 行);第 1–11 章的表与行数保留 D 阶段口径,当前计数见 §13.5。**芯片事实随包内置**:`src/data/device-facts.ts` 读插件包内 `assets/device/f1/chips.json`(`DSH_STM32_ASSETS` 可覆盖;2026-11 从独立资源仓并入插件),2026-10-31 已删掉手写 chip-table.json / f1-ram.generated.ts / 手写容量档表 / 内置引脚表。
5
5
  > 读完这份指南你应该能回答:一次工具调用从宿主进来到 openocd 退出中间经过了谁;哪几条不变量破了一定出事;要改某个功能得动哪几个文件;哪些行为有测试兜着、哪些只能上板子验。
6
6
  >
7
7
  > 配套文档:docs/development-notes.md(按时间记的决策与被坑记录)、docs/logic-audit.md(历史审计条目)、README.md(用户视角)。
@@ -26,7 +26,7 @@
26
26
  | 层 | 目录 | 干什么 | 绝对不能干的事 |
27
27
  | --- | --- | --- | --- |
28
28
  | L4 装配 | src/index.ts、src/commands、src/skill | 把服务接上、把工具/命令/skill 注册进宿主 | 写业务逻辑 |
29
- | L3 契约层 | src/tools(23 个文件:22 个工具 + 1 个基础设施) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
29
+ | L3 契约层 | src/tools(24 个文件:25 个工具 + 1 个基础设施;一个文件可注册多个工具) | 参数 schema、输出 schema、渲染成中文行、门禁 | 直接 spawn 进程、直接拼 openocd 参数 |
30
30
  | L2 逻辑层 | src/engine(46 个 .ts,其中 45 个在下表逐条列) | 全部业务流程、每个流程都可单测 | 读 process.env 里的宿主状态(除配置目录外)、直接 console.log |
31
31
  | L1 事实表 | src/data(10 个数据模块) | 设备事实(`device-facts.ts` 读包内 `assets/device/f1/chips.json`)、由本机 CubeMX db 派生的引脚表、镜像 URL、固件族、F1 时钟树、安装指引、搜索路径、配置读写、SVD 寄存器表(`svd.ts`,来自内置 `assets/device/f1/svd/`,full 逻辑层) | 起进程、写工程文件 |
32
32
 
@@ -44,12 +44,12 @@
44
44
  ```mermaid
45
45
  flowchart TD
46
46
  HOST["DSH 宿主 ctx<br/>tools / subprocess / jobs / webServer / commands / skills"] --> IDX["src/index.ts<br/>apply(ctx) 装配"]
47
- IDX --> TOOLS["src/tools/*<br/>22 个工具"]
47
+ IDX --> TOOLS["src/tools/*<br/>25 个工具"]
48
48
  IDX --> CMDS["src/commands/register.ts<br/>7 条斜杠命令"]
49
49
  IDX --> SKILL["src/skill/stm32-workflow.ts<br/>红线 skill"]
50
50
  IDX --> WEB["src/engine/web-routes.ts<br/>6 条 HTTP 路由"]
51
51
  IDX --> EVT["turn/end、session/disposed、dispose<br/>把探针还回去"]
52
- TOOLS --> ENGINE["src/engine/*<br/>45 个纯逻辑模块"]
52
+ TOOLS --> ENGINE["src/engine/*<br/>65 个纯逻辑模块"]
53
53
  CMDS --> ENGINE
54
54
  WEB --> API["src/engine/web-api.ts<br/>面板 API 纯逻辑"]
55
55
  API --> ENGINE
@@ -67,7 +67,7 @@ flowchart TD
67
67
  | 目录 | 文件数 | 行数 | 说明 |
68
68
  | --- | --- | --- | --- |
69
69
  | src/ | 4 | 803 | index.ts 127、types.ts 196、commands/register.ts 445、skill/stm32-workflow.ts 35 |
70
- | src/tools/ | 23 | 7158 | 22 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 regs.ts 735 行(D 阶段从 272 涨到 735),其次是 route-plan.ts 576 行、rtt.ts 408 行、watch.ts 305 行 |
70
+ | src/tools/ | 24 | 7583 | 25 个工具 + project-dir.ts(共同的工程目录/参数校验基础设施);最大的是 serial.ts 829 行,其次是 regs.ts 735 行、route-plan.ts 576 行、rtt.ts 408 行 |
71
71
  | src/engine/ | 51 | 21712 | 见第 5 章(第 5 章表格化了 45 个模块,另有 assets.ts 1162 行没单列);最大的是 msys2-install.ts 2313 行,其次是 assets.ts 1162 行、clock-plan.ts 801 行 |
72
72
  | src/data/ | 10 | 3599 | 10 个 .ts 数据模块(device-facts.ts 读包内 assets/、svd.ts 读 full 层的寄存器表),见第 6 章 |
73
73
  | templates/ | 20 | — | 工程脚手架与寄存器版模板(CMake、链接脚本、launch/settings、openocd.cfg、demo.ioc;C 阶段加了寄存器版的 `Core/Src/rtt.c` + `Core/Inc/rtt.h` 与 HAL 脚手架 `scaffold/RTT.md`) |
@@ -100,7 +100,7 @@ flowchart TD
100
100
  三件事,只有三件:
101
101
 
102
102
  1. **声明身份与依赖**:`export const name = "dsh-stm32"`、`export const inject = ["tools", "subprocess", "jobs"]`。这三个是硬依赖,缺了插件不加载。
103
- 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 22 个工具**:env_probe → env_install → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → build → flash → debug_run → debug_session → watch → regs_read → route_plan → rtt → assets → cache → doctor → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
103
+ 2. **apply(ctx) 里按「先探测、再操作」的顺序注册 25 个工具**:env_install → download → firmware_install → project_create → project_export → code_patch → generate → ioc_inspect → ioc_plan → ioc_apply → ioc_verify → build → flash → debug_run → debug_session → regs_read → route_plan → rtt → watch → assets → cache → doctor → serial → web_routes。顺序本身不影响功能(工具注册是平铺的),但排列是「用户上手顺序」。
104
104
  3. **注册可选层并挂三个事件**:commands / skills 走 `ctx.inject([...], scope => ...)`,宿主没组合这些服务时静默跳过,工具照常工作;webServer 路由在`registerWebRoutes` 里自己判断。
105
105
 
106
106
  三个事件是本插件唯一的「状态清理入口」,也是很容易读漏的地方:
@@ -154,7 +154,7 @@ ctx.on("dispose", () => { void debugSessions.stop("插件卸载"); });
154
154
 
155
155
  7 条命令里有 6 条最终调用 engine 的同一个函数(build → runBuild,flash → runFlash …),所以它们和工具的唯一差别是:输入来自文本而不是 JSON、输出是一段中文。
156
156
 
157
- ## 4. tools 层:22 个工具 + 1 个基础设施
157
+ ## 4. tools 层:25 个工具 + 1 个基础设施
158
158
 
159
159
  ### 4.1 一个工具文件的固定骨架
160
160
 
@@ -190,12 +190,12 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
190
190
  2. **门禁在工具层,不在 engine。** engine 假设工具链就位;`blockedReport` / `emptyReport` 是门禁拦截与早退时造「同形报告」的工厂,保证失败也是合法输出。
191
191
  3. **`resolveProjectDir` + `validateToolArgs`(tools/project-dir.ts,120 行)是所有工具的共同入口**:前者把 `projectDir` 参数 / 会话工作目录落成绝对路径,后者按 `RequiredArgSpec` 校验必填参数类型,报错文案统一。
192
192
 
193
- ### 4.2 22 个工具一览
193
+ ### 4.2 25 个工具一览
194
194
 
195
195
  | 工具 | 文件(行) | engine 入口 | 门禁能力 |
196
196
  | --- | --- | --- | --- |
197
- | `stm32_doctor` | env-probe.ts(284) | probe.buildTargets / probeAll + search-roots.resolveSearchConfig | 无 |
198
197
  | `stm32_env_install` | env-install.ts(550) | msys2-install.planOrInstallMsys2 | 无 |
198
+ | `stm32_download` | download.ts(300) | download.planDownload / downloadUrlToFile / sha256File / inspectInstallerFile | 无(只下载与校验,绝不执行安装器) |
199
199
  | `stm32_firmware_install` | firmware-install.ts(288) | firmware-install.planOrInstallFirmware | 无 |
200
200
  | `stm32_project_create` | project-create.ts(387) | scaffold.createProjectScaffold(型号 → hal-chip 渲染启动文件/设备宏/.ld/.ioc)/ register-template.createRegisterProject | build(仅 register 路线;hal 路线降级成 warnings) |
201
201
  | `stm32_project_export` | project-export.ts(122) | project-export.runExport | 无 |
@@ -204,6 +204,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
204
204
  | `stm32_ioc_inspect` | ioc-inspect.ts(243) | ioc.summarizeIoc | 无 |
205
205
  | `stm32_ioc_plan` | ioc-plan.ts(398) | ioc-plan.planIocChanges + clock-plan.planClockChanges(引脚 / 键 / 时钟进同一个 candidate) | 无 |
206
206
  | `stm32_ioc_apply` | ioc-apply.ts(137) | ioc-plan.applyIocPlan / rollbackIoc | 无 |
207
+ | `stm32_ioc_verify` | ioc-verify.ts(246) | ioc-verify.runIocVerify(CubeMX 无头 load→save 回读对比) | generate(CubeMX + JRE) |
207
208
  | `stm32_build` | build.ts(243) | build.runBuild | build(gcc + cmake + ninja) |
208
209
  | `stm32_flash` | flash.ts(203) | flash.runFlash | flash(openocd) |
209
210
  | `stm32_debug_run` | debug.ts(252) | debug.runDebugRun | debug(openocd + gdb) |
@@ -212,15 +213,17 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
212
213
  | `stm32_regs_read` | regs.ts(735) | regs.runRegsRead + data/svd 的 `resolveRegisterRef` / `decodeRegisterValue`(工具层先把符号名解析成地址,再进 engine) | debug(解析失败在门禁之前就返回,不 spawn 进程) |
213
214
  | `stm32_rtt` | rtt.ts(408) | rtt.startRtt / dumpRtt / stopRtt / rttStatus + probe-session.ensureSession(parseRttFrames / encodeRttFrame 是纯函数) | debug(仅 start) |
214
215
  | `stm32_route_plan` | route-plan.ts(576) | engine/route-plan.assessRoute + toolchain-gate | register-ok → build;其余 → generate;unclear → 不查 |
216
+ | `stm32_assets` | assets.ts(314) | engine/assets 全套(内置资源定位、manifest 校验、ensureAssets) | 无 |
215
217
  | `stm32_cache` | cache.ts(306) | engine/cache 全套 | 无 |
216
218
  | `stm32_doctor` | doctor.ts(202) | doctor.runDoctor + collectChipConsistency(型号/启动文件/设备宏/.ld/Flash 五项一致性) | 无(它自己就是体检) |
219
+ | `stm32_serial` | serial.ts(829,0.1.5 新增) | 无独立 engine 入口:engine/serial.ts 直接管 PowerShell 桥(文件 IPC:cmd/ done/ rx.ndjson tx.ndjson status.json)与端口记忆(`~/.dsh-stm32/serial.json`) | 无(P1 仅 Windows;非 Windows / 缺 PowerShell 在工具层返回 `unsupported-platform`,不起桥) |
217
220
  | —(基础设施) | project-dir.ts(120) | resolveProjectDir / validateToolArgs | — |
218
221
 
219
- 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**regs.ts 735 行**现在是 tools 层最大的(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**退居第二——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
222
+ 两个「不像工具」的文件:**debug-session.ts 一个文件注册三个工具**(会话开 / eval / stop 共享同一份会话表,所以必须同文件);**serial.ts 829 行**现在是 tools 层最大的,**regs.ts 735 行**次之(D 阶段从 272 涨到 735,+463 行),**route-plan.ts 576 行**第三——后者的输出 schema 要装下「逐外设代价矩阵 + 安装指引 + 缺件清单」三大块。
220
223
 
221
- ## 5. engine 层:45 个模块,十个域
224
+ ## 5. engine 层:D 阶段的 45 个模块,十个域(现 65 个 .ts)
222
225
 
223
- 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。表里列 45 个;`src/engine/` 目录里实际有 46 个 `.ts`——`assets.ts`(内置资源装配与完整性校验,flat 布局)还没单独成行,读内置资源那条链路时直接从 §5.7 与 `src/data/device-facts.ts` 一起看。
226
+ 下面按「读代码时会被一起找到」分组。每个模块给:行数、职责、关键导出、谁调用。这里保留 D 阶段的 45 个模块表;`src/engine/` 现在有 65 个 `.ts`,0.1.5 的 `serial.ts`、`download.ts` 与 `assets.ts`(内置资源装配与完整性校验,flat 布局)等后续模块见 §12、§13 与目录本身;读内置资源链路时从 §5.7 与 `src/data/device-facts.ts` 一起看。
224
227
 
225
228
  ### 5.1 进程与路径(3 个,413 行)
226
229
 
@@ -305,7 +308,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
305
308
 
306
309
  | 模块 | 职责与关键导出 |
307
310
  | --- | --- |
308
- | msys2-install.ts(2313) | 最大也最脏的一块:下载 MSYS2 安装包 → 静默安装 → pacman 装 5 个组件 → 写用户级 PATH → 写配置 → 自检。关键导出:`MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_BYTES`、`DEFAULT_MSYS2_PACKAGES`、`MSYS2_SUGGESTED_ROOT`、`planOrInstallMsys2(subprocess, request)`(plan / install 两条路)、`msys2StepSkeleton`、`parsePacmanQuery`、`resolveInstallerUrls(env)`(**F3a 候选链**:`MSYS2_INSTALLER_URL` 单源 > `MSYS2_MIRROR` > 清华 TUNA / 中科大 USTC / 南大 NJU / 阿里云 × 两个文件名 > GitHub,共 10 个候选;`installerSourceLabel` 把 URL 变成「清华 TUNA」这样的人话)、`installerSourceLabel`、`preferMirrorServers(text, servers)` / `preferChinaMirrors(msys64)`(**F3b**:只把国内镜像插到 `etc/pacman.d/mirrorlist.msys` 与 `mirrorlist.mingw` 最前,官方条目不删,幂等,已有 MSYS2 一个字都不改)、`resolveTargetDir` / `viaLabel`、`formatBytes`、`isDriveRoot` / `ensureParentDir`(盘根不能 mkdir,审计 ③)、`usageNote` / `planMessage`(**计划模式只报缺件**:已装齐时 steps 为空、download.bytes 0、一句话收尾)。**F3d 三道粗检**:缓存要 MZ 头 + ≥ `MIN_INSTALLER_BYTES`(40 MB)才算数(`cachedInstallerBytes`);下载后查退出码/体量/MZ;解压后再查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删)。**F3c**:`curl -C -` 同源续传、`--speed-limit 1024 --speed-time 10` 低速自退(退出码 28 单独说明),退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次,换源前删 `.part`。 |
311
+ | msys2-install.ts(2313) | 最大也最脏的一块:下载 MSYS2 安装包 → 静默安装 → pacman 装 5 个组件 → 写用户级 PATH → 写配置 → 自检。关键导出:`MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_BYTES`、`DEFAULT_MSYS2_PACKAGES`、`MSYS2_SUGGESTED_ROOT`、`planOrInstallMsys2(subprocess, request)`(plan / install 两条路)、`msys2StepSkeleton`、`parsePacmanQuery`、`resolveInstallerUrls(env)`(**P0-1 固定版本**:稳定 release `2026-09-27` 的官方 exe 单源;`MSYS2_INSTALLER_URL` 或 `MSYS2_MIRROR` 可覆盖,但必须同时给 `MSYS2_INSTALLER_SHA256`,否则直接拒绝、不退回官方源;`installerSourceLabel` 只认官方 release 与自定义源)、`installerSourceLabel`、`preferMirrorServers(text, servers)` / `preferChinaMirrors(msys64)`(**F3b**:只把国内镜像插到 `etc/pacman.d/mirrorlist.msys` 与 `mirrorlist.mingw` 最前,官方条目不删,幂等,已有 MSYS2 一个字都不改)、`resolveTargetDir` / `viaLabel`、`formatBytes`、`isDriveRoot` / `ensureParentDir`(盘根不能 mkdir,审计 ③)、`usageNote` / `planMessage`(**计划模式只报缺件**:已装齐时 steps 为空、download.bytes 0、一句话收尾)。**P0-1 四道闸**:`checkInstallerFile` 统一查体量 ≥40 MB、MZ 头、sha256(错误带期望/实际值);缓存复用、下载完成、**解压执行前**各校验一次,哈希不符的下载删 `.part`、哈希不符的缓存保留原文件但重下;缓存名带版本 `msys2-2026-09-27.sfx.exe`。解压后再查 `<msys64>/usr/bin/bash.exe`,缺了就把坏缓存改名 `.broken`(不删)。**F3c**:`curl -C -` 同源续传、`--speed-limit 1024 --speed-time 10` 低速自退(退出码 28 单独说明),退出码 33(服务器不支持 Range)去掉 `-C -` 重下一次,换源前删 `.part`。 |
309
312
 
310
313
  ### 5.9 设置面板的宿主侧(2 个,577 行)
311
314
 
@@ -328,7 +331,7 @@ export function formatFlashReport(report: FlashReport): string[] { ... } // 5.
328
331
  | cmsis-sources.ts | 416 | 寄存器路线的下载源与型号映射:四个镜像(jsdelivr fastly/cdn、raw.githubusercontent、ghproxy)、`CMSIS_FAMILIES`、`startupChoiceFor(mcu)`(委托 resolveF1Chip,兼容 `F1:B` / `F1:8` / `F103:xb` / `STM32F103C8T6` 四种写法;只给容量字母的老写法现在从设备事实里挑一颗同档芯片当代表,优先 F103——原来的「字母 → 档位」常量表已删,没缓存就返回 null 让上层提示 refresh)、`cmsisTemplatePlan(choice)`(10 个文件的目标路径)、四个 sha256 表(DEVICE_HEADER / SYSTEM_C / **STARTUP 14 条** / CORE_HEADER)、缓存条目 id 与解析(`chipOf`、`cmsisGroupKey`、`cmsisEntryId` → `cmsis:F1:103xb`、`chipEntryId`、`parseCmsisEntryRef`、`cmsisEntryAliases`)。**改这里等于改「离线可复现」的边界**:F1 的 14 个容量档 sha256 全部是 2026-10-30 真实下载实测的。 |
329
332
  | stm32f1.ts | 171 | 两条路线共用的**型号解析器**,本身不再存任何事实:`resolveF1Chip(input)` 先做格式/封装/温度档校验,再查 `device-facts.ts`(完整型号按 CPN 精确匹配、无温度后缀按前缀归一化、`F103:xb` 按 line+档取代表芯片),返回 `F1Chip{cpn,prefix,densityLetter,group,startup,deviceDefine,deviceHeader,pinCount,flashBytes,ramBytes,notes}`(签名与结构 0.2 不变);`f1GroupsFor(code)` 从事实聚合该 line 的容量档。错误分四类且都带「先跑 `stm32_assets verify`」提示:内置资源缺失 / 型号不在内置资源 / line 不存在 / 该 line 没有这一容量档。 |
330
333
  | clock-f1.ts | 215 | F1 时钟树的事实表:PLL 源(HSE 8 MHz / HSI÷2 4 MHz / HSI 8 MHz,后者 `selectable=false`)、倍频 ×2..×16、上限(SYSCLK 72 / APB1 36 / APB2 72 / ADC 14 / USB 48 且必须 PLLCLK=72÷1.5)、APB1/APB2/ADC 分频表、14 条外设→总线、UART 波特率档、20 个 RCC IPParameters 名单。 |
331
- | firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES`(目前只有 F1)、`firmwareFamilyOf`、`firmwareVersionTags`、`packageXmlText`、`firmwarePlanFor`、`verifyFirmwarePackage`、`DSH_FIRMWARE_DIR_NAME = "dsh-firmware"`、`dshFirmwareDir`、`firmwareNeedFromIoc`(从 .ioc 的包名推族与版本)、`looksLikeFirmwarePackage`、`locateFirmwarePackage(root, packageName, extraDirs)` → `FirmwareLocation`(source:repository / dsh-firmware / cache / custom)、`firmwareSourceLabel`、`FirmwareExtraDir`。 |
334
+ | firmware-packages.ts | 463 | 固件包事实表:`FIRMWARE_FAMILIES`(17 族:F1/F2/F3/F7/G0/L1/L4/U0/C0/H5/U5/WBA/L5/WB/WL/H7/U3)、`firmwareFamilyOf`、`firmwareVersionTags`、`packageXmlText`、`firmwarePlanFor`、`verifyFirmwarePackage`、`DSH_FIRMWARE_DIR_NAME = "dsh-firmware"`、`dshFirmwareDir`、`firmwareNeedFromIoc`(从 .ioc 的包名推族与版本)、`looksLikeFirmwarePackage`、`locateFirmwarePackage(root, packageName, extraDirs)` → `FirmwareLocation`(source:repository / dsh-firmware / cache / custom)、`firmwareSourceLabel`、`FirmwareExtraDir`。 |
332
335
  | install-guides.ts | 251 | 安装指引文本:`COMPONENT_INSTALLABILITY`(哪些 pacman 能代装、哪些必须人装)、`cubeMxGuide`、`firmwareGuide`、`guideFor`(用 Map 查而不是 in,避免原型链误判)、`guidesFor`、`guideLines`、`firmwareSizeHint`、`familyPrefix`。 |
333
336
  | search-roots.ts | 421 | 见 5.2。 |
334
337
  | toolchain-config.ts | 370 | 见 5.2。 |
@@ -740,7 +743,7 @@ const fake = {
740
743
 
741
744
  ## 11. 已知的坑与未做的事
742
745
 
743
- 1. **只有 F1 在 FIRMWARE_FAMILIES**:其他族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
746
+ 1. **`FIRMWARE_FAMILIES` 目前收 17 族**(F1/F2/F3/F7/G0/L1/L4/U0/C0/H5/U5/WBA/L5/WB/WL/H7/U3):新增族要接入必须先核实真实仓库名(stm32g4xx-hal-driver 之类),不能照 F1 改字母。
744
747
  2. **generate 是否补发 SetCopyLibrary "copy all"** 仍待定:只靠 .ioc 的 ProjectManager.LibraryCopy=1 不会让 CubeMX 从 setCustomFWPath 的包拷 HAL 源码。
745
748
  3. **firmware-install 的 existing 分支 nextStep 文案**偏旧(还停在「直接调 stm32_generate」的说法)。
746
749
  4. **四类探针故障只有单测没有真机**:swd-locked / flash-protected / no-power / target-mismatch 需要真故障才能验(`probeError` 的 kind 与专属 hint 已在 test/probe-error-units 覆盖)。
@@ -756,6 +759,101 @@ const fake = {
756
759
  14. **RTT 已真机验证(2026-11-01)**:`rtt-units` 33 例仍全离线(假 subprocess + 假端口),但真板上跑通了 start → dump(1 kHz 固件打印、`dma` 与 `t` 1:1)→ stop(openocd 一并退出、探针归还)→ flash 的完整链路,见 development-notes §10.2/§39/§40。剩下的设计取舍(只有通道 0 / 无 defmt 解码 / 默认占 3 KB RAM)见 development-notes §30.6。**复现命令**(`_rich_hal` 上验过):`stm32_rtt action=start projectDir=<工程> addr=0x20000f88` → `action=dump seconds=3` → `action=stop`。
757
760
  15. **寄存器符号名与位域解释只有离线验证**:`svd-units` 39 例全离线(真实内置 SVD + 假 subprocess + 假 Tcl 服务端),**没有一次「真板子 + 真探针 + `GPIOC.ODR`」**(与坑 13 同一个 WCH-Link 问题)。**复测方法**:换回 CMSIS-DAP 探针后 `stm32_regs_read addresses=["GPIOC.ODR","0x4001100C"]`,看 `samples[0].name` / `fields` 与 notes 里的 SVD line。
758
761
 
762
+ ## 12. 0.1.5 增补:串口 P1 与寄存器 21 族
763
+
764
+ > 接续第 11 章。上面 1–15 条是 0.1.4 及更早的记录,其中的数字不动;这里只补 0.1.5 新增的两条阅读线。
765
+
766
+ ### 12.1 串口(`stm32_serial`,Windows P1)
767
+
768
+ - 新增文件:`src/engine/serial.ts`(文件 IPC 客户端 + 会话表 + 端口记忆)、`src/tools/serial.ts`(7 个动作的 schema / 渲染 / 错误 hint)、`src/data/serial-config.ts`(默认值与 `serial.json` 读写)、`templates/serial/bridge.ps1`(约 18 KB,纯 ASCII,真正持有 COM 口)、`test/serial-units.test.mjs` 与 `test/fixtures/serial-fake-bridge.mjs`。
769
+ - 阅读顺序:`tools/serial.ts` 的参数 schema 与 `ACTIONS` → `engine/serial.ts` 的 `openSerial` / `sendSerial` / `readSerial` / `transactSerial` / `closeSerial` / `serialStatus` → `templates/serial/bridge.ps1` 的 `Main` 循环(20 ms 轮询串口 / 100 ms 扫 cmd / 1 s 心跳 / 5 s 查父进程)。**契约不是 RPC,而是目录里的文件**:`cmd/<id>.json` 进、`done/<id>.json` 回,流水在 `rx.ndjson` / `tx.ndjson`,状态在 `status.json`。
770
+ - 不要踩的:`spawn` 不能用 `detached`(Windows 上会翻成 `DETACHED_PROCESS`,powershell.exe 5.1 直接 exit 0);`bridge.ps1` 必须保持 ASCII(PS 5.1 按 ANSI 解码无 BOM 脚本);重复 `open` 由引擎的 `openChain` 串行化并返回 `already-open`;`read` 的 `cursor` 是 `rx.ndjson` 的字节偏移(`nextCursor`),跨轮不重贴历史靠它。
771
+ - 边界:P1 只做 Windows;不含 UI 面板 / SSE / 自动重连 / 多会话。真机缺口见 development-notes §86(真桥只验过失败路径)。
772
+ - 计数口径(0.1.5 起):`src/tools/` 共 24 个文件(23 个工具文件 + `project-dir.ts`),注册工具 **25 个**(`debug-session.ts` 一个文件注册 `_session` / `_eval` / `_stop` 三个)。第 4 章已按这个口径更新。
773
+
774
+ ### 12.2 寄存器路线:13 → 21 族
775
+
776
+ - 事实层:`assets/device/<族>/chips.json` 现在有 21 族;`src/data/cmsis-sources.ts` 的 `CMSIS_FAMILIES` 也是 21 项(新增 H5 / H7 / L4+ / L5 / U3 / U5 / WBA / WL)。F1 仍走 `src/data/stm32f1.ts` 的 `resolveF1Chip()`,其余族走 `CMSIS_FAMILIES` + `DeviceFactsChip`。
777
+ - GPIO 使能位分四种:`moder`(原 F1 口径)、`moder-ahb4`(H7,GPIO 在 AHB4ENR)、`moder-ahb2enr1`(U3 / U5,GPIO 在 AHB2ENR1)、`moder-ahb2`(其余)。读 `src/data/register-gpio.ts` 时先看芯片记录选的是哪一种。
778
+ - 链接脚本:`DeviceFactsChip` 新增可选 `linkerRam`(origin / sizeBytes / region),H7 的 138 颗都带 DTCM 128 KiB,U5 按 line 给 256 / 768 / 2496 KiB 窗口;`planRegisterLinker` 优先用它。L4+ 与 L5 是连续单块,不需要 `linkerRam`。
779
+ - 8 族矩阵已跑完(t6):`create→build` 8/8 通过、warning 0 / error 0,逐族 FLASH/RAM 与两处模板修复(按族 `-mcpu`、H7 的 `cachel1_armv7.h`)见 development-notes §87.5;别把「已下载 CMSIS + 生成 .ld」当成「已编译验收」。
780
+
781
+ ## 13. 0.1.5 增补:安装包下载(`stm32_download`)
782
+
783
+ > 接续 §12。只做「拿到安装包」,不做「安装」:插件负责下载与 SHA256 校验,双击安装器、接受许可、过 UAC 都由用户完成。
784
+
785
+ ### 13.1 四种模式
786
+
787
+ | 模式 | 触发 | 行为 |
788
+ | --- | --- | --- |
789
+ | `plan` | `dryRun: true`(默认) | 只返回 URL、文件名、版本、SHA256、下载目录与安装提示,不联网 |
790
+ | `direct` | `dryRun: false` + `confirm: true`,组件是 J-Link | 下载到下载根目录;边写边算哈希,校验通过才原子改名;已有同哈希文件直接复用(`cached: true`) |
791
+ | `manual` | `dryRun: false` + `confirm: true`,组件是 CubeMX / CubeProgrammer | 打开 ST 官方下载页(需要 myST 登录与许可),不猜直链 |
792
+ | `file` | 传了 `file` | 只校验本地安装包的 SHA256(有官方哈希就对比),不执行、不复制 |
793
+
794
+ ### 13.2 阅读顺序
795
+
796
+ - `src/tools/download.ts`:`stm32_download` 的参数 schema(`component` / `dryRun` / `confirm` / `file` / `outDir` / `openPage` / `timeoutMs`)→ `execute` 的模式判定 → 21 个必填字段的 report → `render` 的中文行。`confirm` 只对 `direct` / `manual` 生效;`file` 只读。
797
+ - `src/engine/download.ts`:`planDownload`(URL 与目标路径)→ `downloadUrlToFile`(fetch + `getReader` + `.part-<pid>-<ts>` + 边写边算哈希 + 校验后 rename)→ `sha256File` → `inspectInstallerFile`。下载根目录的优先级是 `DSH_STM32_DOWNLOADS` > `%LOCALAPPDATA%\dsh-stm32\downloads` > `%USERPROFILE%\AppData\Local\...` > 临时目录。
798
+ - `test/download-units.test.mjs`:5 条离线用例——两种计划、下载目录覆盖、本地文件校验、本地 HTTP 直链的下载/缓存/哈希不符清理、工具层三种模式。
799
+
800
+ ### 13.3 安全边界
801
+
802
+ - **不执行安装器**:不 spawn 安装包、不传 `/S` 之类的静默参数;`manual` 只 spawn `cmd /c start` 打开官方页面。
803
+ - **不写注册表、不改 PATH、不请求管理员**。J-Link 的 USB 驱动由安装器自己处理:`-InstAllUsers=1` + UAC;现代探针默认 WinUSB,只有停产老探针才需要 legacy 驱动。
804
+ - **URL 白名单**:只有 SEGGER 官方直链与 ST 的两个官方页面;J-Link 版本与 SHA256 写死在 `JLINK_DOWNLOAD`,升级要同时改 URL 与哈希。
805
+ - **失败清理**:网络中断、超时(默认 10 分钟,下限 5 秒)、超过 `maxBytes`(默认 300 MB)或哈希不符时删除临时文件;目标文件只在哈希通过后出现。
806
+
807
+ ### 13.4 验证边界
808
+
809
+ - J-Link 直链只做了 `HEAD`:HTTP 200、`content-length: 59,012,800`;**没有真的下载 59 MB**,也没有运行安装器(按设计永远不运行)。
810
+ - 下载/校验/缓存/失败清理由本地 HTTP 服务覆盖;ST 的两个页面只验证了 URL 与计划输出,没有打开浏览器。
811
+ - 真机安装、驱动加载、CubeMX/CubeProgrammer 的 myST 下载仍未验。
812
+
813
+ ### 13.5 计数口径(0.1.5 起)
814
+
815
+ | 项 | 当前值 |
816
+ | --- | --- |
817
+ | TypeScript | 111 个文件、43,057 行(`src/`,不含 client) |
818
+ | `src/tools/` | 24 个文件 / 25 个注册工具 / 7,616 行 |
819
+ | `src/engine/` | 65 个 `.ts` / 26,961 行 |
820
+ | `src/data/` | 18 个 `.ts` / 7,785 行 |
821
+ | 单测 | 60 个套件 / 947 pass / 0 fail(`node test/run-units.mjs`) |
822
+ | TypeScript | 110 个文件、42,261 行(`src/`,不含 client) |
823
+ | `src/tools/` | 24 个文件 / 25 个注册工具 / 7,583 行 |
824
+ | `src/engine/` | 65 个 `.ts` / 26,358 行 |
825
+ | `src/data/` | 17 个 `.ts` / 7,625 行 |
826
+ | 单测 | 61 个套件 / 923 pass / 0 fail(`node test/run-units.mjs`,本机实测) |
827
+
828
+ 第 1–11 章的目录表与模块计数保留 D 阶段原样(45 个 engine 模块、23 个 tools 文件),读旧章节时以本节为准。
829
+
830
+ ## 14. 0.1.6 增补:宿主 schema 子集与 `pins` / `parameters` 数组化
831
+
832
+ > 接续 §13,同属 0.1.6。这一节不改业务行为,只让 25 个工具的 schema 落进 DSH 0.2.2-rc.1 允许的子集。
833
+
834
+ ### 14.1 先读哪里
835
+
836
+ - `src/types.ts` 的 `JsonSchema`:现在就是宿主子集本身——`type` / `oneOf` / `properties` / `required` / `additionalProperties`(仅 boolean)/ `items` / `enum` / `const` + 注解 `description` / `title` / `default` / `examples`。`minimum` / `maximum` 已删除,看到需要范围时去 `description` 和执行期校验里找。
837
+ - `src/tools/ioc-plan.ts` 的 `parameters`:`peripherals[].pins` / `parameters` 是 `type:"array"` + `items:{key,value}`,`pllMul` 是 `integer` + `enum[2..16]`。
838
+ - `src/engine/ioc-plan.ts` 的 `KeyValuePair` 与 `keyValueMap()`:数组 → `Map` 的唯一入口,空 key / 重复 key 在这里记 `errors`。
839
+ - `src/engine/serial.ts` 的 `SERIAL_SETTINGS_PROPERTIES`:参数 schema 与输出 `settings` schema 复用同一片段,范围只在 `description` 里;真正的越界判定在 `src/data/serial-config.ts` 的 `normalizeSerialSettings`。
840
+ - `test/schema-subset-units.test.mjs`:镜像校验器 + 从 `app.asar` 抽真校验器做真值对齐。改任何工具的 schema 后先跑它。
841
+
842
+ ### 14.2 三条不变量
843
+
844
+ 1. 任何 schema 节点只出现子集关键字;`additionalProperties` 只能是 boolean,`items` 只在数组上,`properties`/`required` 只在对象上。
845
+ 2. 数值范围**不进 schema**:写 `description`,并在执行期校验(`keep`:非法即 `ok=false` 且不动文件;串口:`normalizeSerialSettings` 记 errors 并保持默认值)。
846
+ 3. 「任意键 → 值」的映射不允许再写成 `additionalProperties: {…}`;要么换成 `[{key,value}]` 数组,要么用 `additionalProperties: true` 兜底。
847
+
848
+ ### 14.3 计数口径(0.1.6 起)
849
+
850
+ | 项 | 当前值 |
851
+ | --- | --- |
852
+ | 注册工具 | 25 个(25/25 schema 合规) |
853
+ | 单测 | 61 个套件 / 923 pass / 0 fail |
854
+
855
+ 本机同基线实测为 921,加 2 条新用例后 923;§13.5 表里原有的 937 是另一台机器的发布记录。
856
+
759
857
  ---
760
858
 
761
- 读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
859
+ 读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
@@ -222,7 +222,7 @@ function envText(rows, configPath) {
222
222
  lines.push(anyMissing ? "要装:回「装」,我跑 stm32_env_install 出计划(先不下载)" : "都齐了:/stm32-build 就能编译");
223
223
  return { kind: "success", text: lines.join("\n") };
224
224
  }
225
- /** 注册六条斜杠命令;宿主没组合 commands 服务时直接返回(工具不受影响)。 */
225
+ /** 注册七条斜杠命令;宿主没组合 commands 服务时直接返回(工具不受影响)。 */
226
226
  export function registerCommands(ctx) {
227
227
  const commands = ctx.commands;
228
228
  if (commands === undefined)
@@ -24,14 +24,19 @@ export function sourceUrls(repo, ref, file) {
24
24
  return [JS_DELIVR_FASTLY(repo, ref, file), JS_DELIVR_CDN(repo, ref, file), RAW_GITHUB(repo, ref, file), GHPROXY(repo, ref, file)];
25
25
  }
26
26
  /**
27
- * 寄存器件模板支持的 13 个族。
27
+ * 寄存器件模板支持的 21 个族。
28
28
  *
29
- * 为什么是这 13 个:内置资源 device/<族>/chips.json 已经收了这 13 族的芯片事实
29
+ * 为什么是这 21 个:内置资源 device/<族>/chips.json 已经收了这 21 族的芯片事实
30
30
  * (启动文件名 / 设备宏 / 设备头 / Flash / RAM 都在里面),寄存器路线需要的事实刚好齐了。
31
- * 其它族(H5/U3/U5/L5/WB/WBA/WL/H7/L4+)等内置资源补了 chips.json 再按同样字段加一条即可。
31
+ * 还没收 chips.json 的族(WB/WB0/WL3/MP1/MP2/N6)不在其中:WB 是双核、MP1/MP2/N6 是
32
+ * MPU/NPU 路线,本插件的寄存器建工程不适用;将来补了 chips.json 再按同样字段加一条 spec。
32
33
  *
33
34
  * 内核头沿用 F1 的口径:从 ST 的 STM32Cube<族> 主仓库取(ST 在主仓里 vendor 了 CMSIS,
34
35
  * 不是子模块;2026-11-08 实测 F4/G0 的 Drivers/CMSIS/Include 都是 200)。
36
+ * 2026-11-09 补 H5/H7/L4+/L5/U3/U5/WBA/WL 时逐族实测过:设备头 / system 头 / system.c /
37
+ * 启动文件 / 内核头在 cmsis-device-<族>@master 与 STM32Cube<族>@master 上都是 200;
38
+ * 唯一的例外是 STM32CubeU3 的 cmsis_gcc.h 在 jsDelivr 上 403(上游树缓存没刷),
39
+ * raw.githubusercontent 与 ghproxy 两条兜底路线正常——sourceUrls 的四条路线就是为这种单点故障准备的。
35
40
  *
36
41
  * 哈希钉:只有 F1 那张表(DEVICE_HEADER_SHA256 / STARTUP_SHA256 / CORE_HEADER_SHA256)
37
42
  * 是逐文件实测的;其它族只锁形状(minBytes + markers),真实哈希在下载时登记进缓存索引。
@@ -170,6 +175,39 @@ export const CMSIS_FAMILIES = {
170
175
  systemC: "system_stm32g4xx.c",
171
176
  mpuHeader: "mpu_armv7.h",
172
177
  },
178
+ H5: {
179
+ family: "H5",
180
+ deviceRepo: "cmsis-device-h5",
181
+ deviceRef: "master",
182
+ deviceIncludeDir: "Include",
183
+ deviceTemplatesDir: "Source/Templates",
184
+ cmsisRepo: "STM32CubeH5",
185
+ cmsisRef: "master",
186
+ coreIncludeDir: "Drivers/CMSIS/Include",
187
+ coreHeader: "core_cm33.h",
188
+ deviceHeaders: ["stm32h5xx.h", "system_stm32h5xx.h"],
189
+ deviceDefinePrefix: "STM32H5",
190
+ systemC: "system_stm32h5xx.c",
191
+ mpuHeader: "mpu_armv8.h",
192
+ },
193
+ H7: {
194
+ family: "H7",
195
+ deviceRepo: "cmsis-device-h7",
196
+ deviceRef: "master",
197
+ deviceIncludeDir: "Include",
198
+ deviceTemplatesDir: "Source/Templates",
199
+ cmsisRepo: "STM32CubeH7",
200
+ cmsisRef: "master",
201
+ coreIncludeDir: "Drivers/CMSIS/Include",
202
+ coreHeader: "core_cm7.h",
203
+ deviceHeaders: ["stm32h7xx.h", "system_stm32h7xx.h"],
204
+ deviceDefinePrefix: "STM32H7",
205
+ systemC: "system_stm32h7xx.c",
206
+ mpuHeader: "mpu_armv7.h",
207
+ // H7 的 stm32h7<line>xx.h 定义 __ICACHE_PRESENT/__DCACHE_PRESENT=1,
208
+ // core_cm7.h 于是 include cachel1_armv7.h(ARM 原版,守卫 ARM_CACHEL1_ARMV7_H)。
209
+ extraCoreHeaders: ["cachel1_armv7.h"],
210
+ },
173
211
  L0: {
174
212
  family: "L0",
175
213
  deviceRepo: "cmsis-device-l0",
@@ -214,6 +252,38 @@ export const CMSIS_FAMILIES = {
214
252
  systemC: "system_stm32l4xx.c",
215
253
  mpuHeader: "mpu_armv7.h",
216
254
  },
255
+ // L4+(L4P5/L4Q5/L4R5/L4S5…)和 L4 共用同一个 cmsis-device-l4 仓库与 STM32CubeL4 固件包:
256
+ // 型号头(stm32l4p5xx.h 等)由 STM32L4xx 这个 umbrella 按设备宏选中,所以前缀仍是 STM32L4。
257
+ "L4+": {
258
+ family: "L4+",
259
+ deviceRepo: "cmsis-device-l4",
260
+ deviceRef: "master",
261
+ deviceIncludeDir: "Include",
262
+ deviceTemplatesDir: "Source/Templates",
263
+ cmsisRepo: "STM32CubeL4",
264
+ cmsisRef: "master",
265
+ coreIncludeDir: "Drivers/CMSIS/Include",
266
+ coreHeader: "core_cm4.h",
267
+ deviceHeaders: ["stm32l4xx.h", "system_stm32l4xx.h"],
268
+ deviceDefinePrefix: "STM32L4",
269
+ systemC: "system_stm32l4xx.c",
270
+ mpuHeader: "mpu_armv7.h",
271
+ },
272
+ L5: {
273
+ family: "L5",
274
+ deviceRepo: "cmsis-device-l5",
275
+ deviceRef: "master",
276
+ deviceIncludeDir: "Include",
277
+ deviceTemplatesDir: "Source/Templates",
278
+ cmsisRepo: "STM32CubeL5",
279
+ cmsisRef: "master",
280
+ coreIncludeDir: "Drivers/CMSIS/Include",
281
+ coreHeader: "core_cm33.h",
282
+ deviceHeaders: ["stm32l5xx.h", "system_stm32l5xx.h"],
283
+ deviceDefinePrefix: "STM32L5",
284
+ systemC: "system_stm32l5xx.c",
285
+ mpuHeader: "mpu_armv8.h",
286
+ },
217
287
  U0: {
218
288
  family: "U0",
219
289
  deviceRepo: "cmsis-device-u0",
@@ -228,6 +298,66 @@ export const CMSIS_FAMILIES = {
228
298
  deviceDefinePrefix: "STM32U0",
229
299
  systemC: "system_stm32u0xx.c",
230
300
  },
301
+ U3: {
302
+ family: "U3",
303
+ deviceRepo: "cmsis-device-u3",
304
+ deviceRef: "master",
305
+ deviceIncludeDir: "Include",
306
+ deviceTemplatesDir: "Source/Templates",
307
+ cmsisRepo: "STM32CubeU3",
308
+ cmsisRef: "master",
309
+ coreIncludeDir: "Drivers/CMSIS/Include",
310
+ coreHeader: "core_cm33.h",
311
+ deviceHeaders: ["stm32u3xx.h", "system_stm32u3xx.h"],
312
+ deviceDefinePrefix: "STM32U3",
313
+ systemC: "system_stm32u3xx.c",
314
+ mpuHeader: "mpu_armv8.h",
315
+ },
316
+ U5: {
317
+ family: "U5",
318
+ deviceRepo: "cmsis-device-u5",
319
+ deviceRef: "master",
320
+ deviceIncludeDir: "Include",
321
+ deviceTemplatesDir: "Source/Templates",
322
+ cmsisRepo: "STM32CubeU5",
323
+ cmsisRef: "master",
324
+ coreIncludeDir: "Drivers/CMSIS/Include",
325
+ coreHeader: "core_cm33.h",
326
+ deviceHeaders: ["stm32u5xx.h", "system_stm32u5xx.h"],
327
+ deviceDefinePrefix: "STM32U5",
328
+ systemC: "system_stm32u5xx.c",
329
+ mpuHeader: "mpu_armv8.h",
330
+ },
331
+ WBA: {
332
+ family: "WBA",
333
+ deviceRepo: "cmsis-device-wba",
334
+ deviceRef: "master",
335
+ deviceIncludeDir: "Include",
336
+ deviceTemplatesDir: "Source/Templates",
337
+ cmsisRepo: "STM32CubeWBA",
338
+ cmsisRef: "master",
339
+ coreIncludeDir: "Drivers/CMSIS/Include",
340
+ coreHeader: "core_cm33.h",
341
+ deviceHeaders: ["stm32wbaxx.h", "system_stm32wbaxx.h"],
342
+ deviceDefinePrefix: "STM32WBA",
343
+ systemC: "system_stm32wbaxx.c",
344
+ mpuHeader: "mpu_armv8.h",
345
+ },
346
+ WL: {
347
+ family: "WL",
348
+ deviceRepo: "cmsis-device-wl",
349
+ deviceRef: "master",
350
+ deviceIncludeDir: "Include",
351
+ deviceTemplatesDir: "Source/Templates",
352
+ cmsisRepo: "STM32CubeWL",
353
+ cmsisRef: "master",
354
+ coreIncludeDir: "Drivers/CMSIS/Include",
355
+ coreHeader: "core_cm4.h",
356
+ deviceHeaders: ["stm32wlxx.h", "system_stm32wlxx.h"],
357
+ deviceDefinePrefix: "STM32WL",
358
+ systemC: "system_stm32wlxx.c",
359
+ mpuHeader: "mpu_armv7.h",
360
+ },
231
361
  };
232
362
  /** line 代号:STM32F103 → F1。 */
233
363
  export function familyOf(chip) {
@@ -530,7 +660,9 @@ export function cmsisTemplatePlan(input) {
530
660
  ?? (spec.coreHeader === "core_cm0.h" ? undefined : /cm33/u.test(spec.coreHeader) ? "mpu_armv8.h" : "mpu_armv7.h");
531
661
  if (mpuHeader !== undefined)
532
662
  coreHeaderMarkers[mpuHeader] = ["ARM_MPU_", "__MPU_"];
533
- const coreHeaders = [spec.coreHeader, "cmsis_compiler.h", "cmsis_gcc.h", "cmsis_version.h", ...(mpuHeader === undefined ? [] : [mpuHeader])];
663
+ // core_cm7.h 条件 include 的缓存头(H7):ARM 原版,真实守卫是 ARM_CACHEL1_ARMV7_H。
664
+ coreHeaderMarkers["cachel1_armv7.h"] = ["ARM_CACHEL1_ARMV7_H"];
665
+ const coreHeaders = [spec.coreHeader, "cmsis_compiler.h", "cmsis_gcc.h", "cmsis_version.h", ...(mpuHeader === undefined ? [] : [mpuHeader]), ...(spec.extraCoreHeaders ?? [])];
534
666
  for (const header of coreHeaders) {
535
667
  targets.push({
536
668
  path: "Drivers/CMSIS/Include/" + header,
@@ -33,6 +33,17 @@ function textOf(value) {
33
33
  function countOf(value) {
34
34
  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
35
35
  }
36
+ /** chips.json 的可选 linkerRam → 结构化窗口;字段不合法就当没写(回退 ramBytes,不猜)。 */
37
+ function linkerRamOf(value) {
38
+ if (!isRecord(value))
39
+ return null;
40
+ const origin = countOf(value["origin"]);
41
+ const sizeBytes = countOf(value["sizeBytes"]);
42
+ if (origin === null || sizeBytes === null || sizeBytes <= 0)
43
+ return null;
44
+ const region = textOf(value["region"]);
45
+ return region === "" ? { origin, sizeBytes } : { origin, sizeBytes, region };
46
+ }
36
47
  /**
37
48
  * 只给 line + group 时按上游命名规则补出三样名字(启动文件 / 设备宏 / 设备头)+ 链接脚本名。
38
49
  *
@@ -96,6 +107,8 @@ function chipFrom(value) {
96
107
  // B4:断点预算(可选字段,chips.json 没写就是没有,调用方回退 F1 默认)。
97
108
  const breakpoints = countOf(value["breakpoints"]);
98
109
  const watchpoints = countOf(value["watchpoints"]);
110
+ // 链接脚本连续 RAM 窗口(可选;H7/U5 这类 RAM 分区的族必须写,否则 _estack 会落进空洞)。
111
+ const linkerRam = linkerRamOf(value["linkerRam"]);
99
112
  if (cpn === "" || line === "" || group === "" || startup === "" || deviceDefine === "" || deviceHeader === "")
100
113
  return null;
101
114
  if (pinCount === null || flashBytes === null || ramBytes === null)
@@ -116,6 +129,7 @@ function chipFrom(value) {
116
129
  linkerScript: textOf(value["linkerScript"]) || derived.linkerScript,
117
130
  ...(breakpoints === null || breakpoints <= 0 ? {} : { breakpoints: Math.trunc(breakpoints) }),
118
131
  ...(watchpoints === null || watchpoints <= 0 ? {} : { watchpoints: Math.trunc(watchpoints) }),
132
+ ...(linkerRam === null ? {} : { linkerRam }),
119
133
  };
120
134
  }
121
135
  function emptyFacts(filePath, version, error) {
@@ -65,8 +65,8 @@ const HAL_CAPS = { ...NO_CAPS, halScaffold: true };
65
65
  */
66
66
  const HAL_REG_CAPS = { ...HAL_CAPS, registerScaffold: true };
67
67
  /** 还没做 HAL 支持的族(双核 / MPU / 范围外):说明为什么,别让工具悄悄退化。 */
68
- const PENDING_HAL = "HAL 建工程只支持 22 个单核族(C0/F0/F1/F2/F3/F4/F7/G0/G4/H5/H7/L0/L1/L4/L4+/L5/U0/U3/U5/WBA/WL,另加双核的 WB 只建 M4 核),本族不在其中";
69
- const PENDING_REG = "寄存器版模板(CMSIS 头 + 启动文件)目前只有 F1 与内置资源已有芯片表的 13 族(C0/F0/F1/F2/F3/F4/F7/G0/G4/L0/L1/L4/U0)";
68
+ const PENDING_HAL = "HAL 建工程只支持 21 个单核族(C0/F0/F1/F2/F3/F4/F7/G0/G4/H5/H7/L0/L1/L4/L4+/L5/U0/U3/U5/WBA/WL,另加双核的 WB 只建 M4 核),本族不在其中";
69
+ const PENDING_REG = "寄存器版模板(CMSIS 头 + 启动文件)目前覆盖内置资源已有芯片表的 21 族(C0/F0/F1/F2/F3/F4/F7/G0/G4/H5/H7/L0/L1/L4/L4+/L5/U0/U3/U5/WBA/WL),本族不在其中";
70
70
  const REG_OK = "寄存器版已按族打通(CMSIS 头 + 启动文件 + 按族 GPIO;时钟留复位默认)";
71
71
  const PENDING_PRESET = ".ioc 外设预设表目前只有 F1(下一步按族从 db 的 RefParameter 生成)";
72
72
  const PENDING_CLOCK = "时钟规划目前只按 F1 的 RCC/PLL 实现";
@@ -79,8 +79,8 @@ const NO_SVD = "内置资源只有 F1 的 SVD(中断名/寄存器名校验暂
79
79
  * 用户看不出到底哪一项挡住了他。
80
80
  */
81
81
  export const CAPABILITY_GAPS = {
82
- halScaffold: "HAL 建工程(模板/启动文件/链接脚本/设备宏)按 22 个单核族的固件包实现",
83
- registerScaffold: "寄存器版模板(CMSIS 头 + 启动文件)只有内置资源已有芯片表的 13 族:C0/F0/F1/F2/F3/F4/F7/G0/G4/L0/L1/L4/U0",
82
+ halScaffold: "HAL 建工程(模板/启动文件/链接脚本/设备宏)按 21 个单核族的固件包实现",
83
+ registerScaffold: "寄存器版模板(CMSIS 头 + 启动文件)覆盖内置资源已有芯片表的 21 族:C0/F0/F1/F2/F3/F4/F7/G0/G4/H5/H7/L0/L1/L4/L4+/L5/U0/U3/U5/WBA/WL",
84
84
  iocPresets: "手写 .ioc 预设表只有 F1(其它族靠 db 派生 USART/UART/LPUART,TIM/ADC/DMA 仍需手写键)",
85
85
  clockPlan: "时钟规划只按 F1 的 RCC/PLL 键实现",
86
86
  svdValidation: "中断名/寄存器名校验要该族的 SVD,内置资源目前只有 F1 的",
@@ -134,11 +134,11 @@ const PROFILES = [
134
134
  note: REG_OK + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
135
135
  }),
136
136
  profile({
137
- id: "STM32H5", line: "H5", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_H5", caps: HAL_CAPS,
137
+ id: "STM32H5", line: "H5", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_H5", caps: HAL_REG_CAPS,
138
138
  note: "openocd 0.12 只有 stm32x5x_common.cfg(公共片段),没有 h5x 目标脚本 —— 不能用 u5x 顶替",
139
139
  }),
140
140
  profile({
141
- id: "STM32H7", line: "H7", core: "Cortex-M7", target: "stm32h7x", firmware: "STM32Cube_FW_H7", caps: HAL_CAPS,
141
+ id: "STM32H7", line: "H7", core: "Cortex-M7", target: "stm32h7x", firmware: "STM32Cube_FW_H7", caps: HAL_REG_CAPS,
142
142
  note: "双 bank 器件可用 openocd.cfg 里改 source target/stm32h7x_dual_bank.cfg" + ";" + PENDING_CLOCK,
143
143
  }),
144
144
  profile({
@@ -154,12 +154,12 @@ const PROFILES = [
154
154
  note: REG_OK + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
155
155
  }),
156
156
  profile({
157
- id: "STM32L4+", line: "L4+", core: "Cortex-M4", target: "stm32l4x", firmware: "STM32Cube_FW_L4", caps: HAL_CAPS,
157
+ id: "STM32L4+", line: "L4+", core: "Cortex-M4", target: "stm32l4x", firmware: "STM32Cube_FW_L4", caps: HAL_REG_CAPS,
158
158
  note: "L4+ 零件(L4P5/L4Q5/L4R5/L4S5…)共用 STM32Cube_FW_L4 固件包与 openocd 的 stm32l4x.cfg" + ";" + PENDING_CLOCK,
159
159
  }),
160
160
  profile({
161
- id: "STM32L5", line: "L5", core: "Cortex-M33", target: "stm32l5x", firmware: "STM32Cube_FW_L5", caps: HAL_CAPS,
162
- note: PENDING_REG + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
161
+ id: "STM32L5", line: "L5", core: "Cortex-M33", target: "stm32l5x", firmware: "STM32Cube_FW_L5", caps: HAL_REG_CAPS,
162
+ note: REG_OK + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
163
163
  }),
164
164
  profile({
165
165
  id: "STM32MP1", line: "MP1", core: "Cortex-A7", target: "stm32mp15x", firmware: "STM32Cube_FW_MP1",
@@ -178,12 +178,12 @@ const PROFILES = [
178
178
  note: "openocd 0.12 没有 u0 目标脚本:插件内置一份适配 0.12 的脚本(templates/openocd/stm32u0x.cfg)",
179
179
  }),
180
180
  profile({
181
- id: "STM32U3", line: "U3", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_U3", caps: HAL_CAPS,
181
+ id: "STM32U3", line: "U3", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_U3", caps: HAL_REG_CAPS,
182
182
  note: "openocd 0.12 没有 u3 目标脚本",
183
183
  }),
184
184
  profile({
185
- id: "STM32U5", line: "U5", core: "Cortex-M33", target: "stm32u5x", firmware: "STM32Cube_FW_U5", caps: HAL_CAPS,
186
- note: PENDING_REG + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
185
+ id: "STM32U5", line: "U5", core: "Cortex-M33", target: "stm32u5x", firmware: "STM32Cube_FW_U5", caps: HAL_REG_CAPS,
186
+ note: REG_OK + ";" + PENDING_PRESET + ";" + PENDING_CLOCK + ";" + NO_SVD,
187
187
  }),
188
188
  profile({
189
189
  id: "STM32WB", line: "WB", core: "Cortex-M4", target: "stm32wbx", firmware: "STM32Cube_FW_WB",
@@ -194,11 +194,11 @@ const PROFILES = [
194
194
  note: "openocd 0.12 没有 wb0 目标脚本;固件包名未确认(STM32CubeWB0 还是并入 WB),运行时不去猜",
195
195
  }),
196
196
  profile({
197
- id: "STM32WBA", line: "WBA", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_WBA", caps: HAL_CAPS,
197
+ id: "STM32WBA", line: "WBA", core: "Cortex-M33", target: null, firmware: "STM32Cube_FW_WBA", caps: HAL_REG_CAPS,
198
198
  note: "openocd 0.12 没有 wba 目标脚本",
199
199
  }),
200
200
  profile({
201
- id: "STM32WL", line: "WL", core: "Cortex-M4", target: "stm32wlx", firmware: "STM32Cube_FW_WL", caps: HAL_CAPS,
201
+ id: "STM32WL", line: "WL", core: "Cortex-M4", target: "stm32wlx", firmware: "STM32Cube_FW_WL", caps: HAL_REG_CAPS,
202
202
  note: "Sub-GHz 无线:M4 应用核可建工程/调试,射频部分不碰" + ";" + PENDING_CLOCK,
203
203
  }),
204
204
  profile({