dsh-stm32 0.1.6 → 0.1.7

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 (98) hide show
  1. package/README.md +517 -517
  2. package/README_EN.md +510 -510
  3. package/client/client.js +24 -24
  4. package/lib/client.js +24 -24
  5. package/lib/commands/register.js +5 -5
  6. package/lib/data/chips.js +4 -4
  7. package/lib/data/clock-db.js +24 -24
  8. package/lib/data/clock-f1.js +2 -2
  9. package/lib/data/cmsis-sources.js +6 -6
  10. package/lib/data/db-presets.js +4 -4
  11. package/lib/data/device-facts.js +6 -6
  12. package/lib/data/family.js +16 -16
  13. package/lib/data/firmware-packages.js +10 -10
  14. package/lib/data/install-guides.js +18 -18
  15. package/lib/data/ioc-presets.js +3 -3
  16. package/lib/data/ioc-schema.js +32 -32
  17. package/lib/data/rm-topics.js +6 -6
  18. package/lib/data/search-roots.js +62 -16
  19. package/lib/data/serial-config.js +7 -7
  20. package/lib/data/stm32f1.js +1 -1
  21. package/lib/data/svd.js +7 -7
  22. package/lib/data/toolchain-config.js +3 -3
  23. package/lib/engine/assets.js +5 -5
  24. package/lib/engine/breakpoints.js +5 -5
  25. package/lib/engine/cache.js +4 -4
  26. package/lib/engine/clock-derived.js +2 -2
  27. package/lib/engine/clock-direct.js +3 -3
  28. package/lib/engine/clock-plan.js +7 -7
  29. package/lib/engine/clock-pllmn.js +6 -6
  30. package/lib/engine/cmake-sources.js +9 -9
  31. package/lib/engine/code-patch.js +5 -5
  32. package/lib/engine/cube-mx-guard.js +3 -3
  33. package/lib/engine/cube-programmer.js +4 -4
  34. package/lib/engine/cubemx-db.js +7 -7
  35. package/lib/engine/debug-session.js +12 -12
  36. package/lib/engine/debug.js +3 -3
  37. package/lib/engine/doctor.js +12 -12
  38. package/lib/engine/download.js +1 -1
  39. package/lib/engine/facts-acquire.js +3 -3
  40. package/lib/engine/fetch.js +2 -2
  41. package/lib/engine/firmware-install.js +16 -16
  42. package/lib/engine/firmware-official.js +8 -8
  43. package/lib/engine/flash.js +22 -22
  44. package/lib/engine/fs-longpath.js +1 -1
  45. package/lib/engine/gdb-mi.js +7 -7
  46. package/lib/engine/generate-script.js +2 -2
  47. package/lib/engine/generate.js +17 -17
  48. package/lib/engine/hal-chip.js +7 -7
  49. package/lib/engine/ioc-plan.js +52 -52
  50. package/lib/engine/ioc-rules.js +9 -9
  51. package/lib/engine/ioc-verify.js +34 -34
  52. package/lib/engine/msys2-install.js +50 -50
  53. package/lib/engine/probe-error.js +8 -8
  54. package/lib/engine/probe-session.js +3 -3
  55. package/lib/engine/probe.js +47 -50
  56. package/lib/engine/project-export.js +1 -1
  57. package/lib/engine/register-clock.js +5 -5
  58. package/lib/engine/register-gpio.js +3 -3
  59. package/lib/engine/register-linker.js +7 -7
  60. package/lib/engine/register-template.js +22 -22
  61. package/lib/engine/regs.js +3 -3
  62. package/lib/engine/rm-extract.js +2 -2
  63. package/lib/engine/rm-sources.js +1 -1
  64. package/lib/engine/route-plan.js +9 -9
  65. package/lib/engine/rtt.js +18 -18
  66. package/lib/engine/scaffold.js +22 -22
  67. package/lib/engine/serial.js +24 -24
  68. package/lib/engine/tar.js +1 -1
  69. package/lib/engine/text-file.js +1 -1
  70. package/lib/engine/thirdparty.js +3 -3
  71. package/lib/engine/tool-env.js +2 -2
  72. package/lib/engine/toolchain-gate.js +8 -8
  73. package/lib/engine/usercode-merge.js +2 -2
  74. package/lib/engine/vscode-config.js +2 -2
  75. package/lib/engine/web-api.js +1 -1
  76. package/lib/engine/xcube-catalog.js +1 -1
  77. package/lib/index.js +5 -5
  78. package/lib/skill/stm32-workflow.js +1 -1
  79. package/lib/tools/assets.js +1 -1
  80. package/lib/tools/cache.js +2 -2
  81. package/lib/tools/debug-session.js +5 -5
  82. package/lib/tools/doctor.js +2 -2
  83. package/lib/tools/download.js +1 -1
  84. package/lib/tools/env-install.js +3 -3
  85. package/lib/tools/firmware-install.js +5 -5
  86. package/lib/tools/flash.js +8 -8
  87. package/lib/tools/generate.js +1 -1
  88. package/lib/tools/ioc-apply.js +1 -1
  89. package/lib/tools/ioc-plan.js +1 -1
  90. package/lib/tools/ioc-verify.js +11 -11
  91. package/lib/tools/project-create.js +4 -4
  92. package/lib/tools/project-dir.js +1 -1
  93. package/lib/tools/regs.js +10 -10
  94. package/lib/tools/route-plan.js +9 -9
  95. package/lib/tools/rtt.js +9 -9
  96. package/lib/tools/serial.js +8 -8
  97. package/package.json +70 -70
  98. package/templates/scaffold/RTT.md +26 -34
@@ -19,7 +19,7 @@ const JS_DELIVR_FASTLY = (repo, ref, file) => "https://fastly.jsdelivr.net/gh/ST
19
19
  const JS_DELIVR_CDN = (repo, ref, file) => "https://cdn.jsdelivr.net/gh/STMicroelectronics/" + repo + "@" + ref + "/" + file;
20
20
  const RAW_GITHUB = (repo, ref, file) => "https://raw.githubusercontent.com/STMicroelectronics/" + repo + "/" + ref + "/" + file;
21
21
  const GHPROXY = (repo, ref, file) => "https://ghproxy.net/https://raw.githubusercontent.com/STMicroelectronics/" + repo + "/" + ref + "/" + file;
22
- /** 一个文件的多条下载路线,顺序 = 优先级(实测 jsDelivr 最稳,raw 兜底)。 */
22
+ /** 一个文件的多条下载路线,顺序 = 优先级(实测 jsDelivr 最稳定,raw 作为回退)。 */
23
23
  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
  }
@@ -36,10 +36,10 @@ export function sourceUrls(repo, ref, file) {
36
36
  * 2026-11-09 补 H5/H7/L4+/L5/U3/U5/WBA/WL 时逐族实测过:设备头 / system 头 / system.c /
37
37
  * 启动文件 / 内核头在 cmsis-device-<族>@master 与 STM32Cube<族>@master 上都是 200;
38
38
  * 唯一的例外是 STM32CubeU3 的 cmsis_gcc.h 在 jsDelivr 上 403(上游树缓存没刷),
39
- * raw.githubusercontent 与 ghproxy 两条兜底路线正常——sourceUrls 的四条路线就是为这种单点故障准备的。
39
+ * raw.githubusercontent 与 ghproxy 两条回退路线正常——sourceUrls 的四条路线即为此类单点故障准备。
40
40
  *
41
41
  * 哈希钉:只有 F1 那张表(DEVICE_HEADER_SHA256 / STARTUP_SHA256 / CORE_HEADER_SHA256)
42
- * 是逐文件实测的;其它族只锁形状(minBytes + markers),真实哈希在下载时登记进缓存索引。
42
+ * 是逐文件实测的;其他族仅锁定形状(minBytes + markers),真实哈希在下载时登记进缓存索引。
43
43
  * 这与 SVD 的处理同口径:上游同族文件会随版本漂移,锁死哈希会让"上游发新版"变成插件故障。
44
44
  */
45
45
  export const CMSIS_FAMILIES = {
@@ -629,7 +629,7 @@ export function cmsisTemplatePlan(input) {
629
629
  urls: sourceUrls(spec.deviceRepo, spec.deviceRef, spec.deviceTemplatesDir + "/" + spec.systemC),
630
630
  minBytes: 1_000,
631
631
  markers: ["SystemInit"],
632
- // SYSTEM_C_SHA256 只是 F1 那一份的实测值;别的族按形状校验(见 CMSIS_FAMILIES 注释)。
632
+ // SYSTEM_C_SHA256 只是 F1 那一份的实测值;其他族按形状校验(见 CMSIS_FAMILIES 注释)。
633
633
  sha256: spec.family === "F1" ? SYSTEM_C_SHA256 : undefined,
634
634
  });
635
635
  targets.push({
@@ -670,14 +670,14 @@ export function cmsisTemplatePlan(input) {
670
670
  minBytes: 500,
671
671
  markers: coreHeaderMarkers[header] ?? ["__CMSIS", "__CORE_"],
672
672
  // CORE_HEADER_SHA256 是 F1 那份(STM32CubeF1@master)的实测值。各族的 CMSIS 内核版本不同
673
- // (U0 的 cmsis_compiler.h 与 F1 内容差一版),拿 F1 的哈希去校验别的族只会全灭。
673
+ // (U0 的 cmsis_compiler.h 与 F1 内容差一版),以 F1 的哈希校验其他族会全部失败。
674
674
  sha256: spec.family === "F1" ? CORE_HEADER_SHA256[header] : undefined,
675
675
  });
676
676
  }
677
677
  const license = "STMicroelectronics CMSIS device headers / startup / CMSIS core headers — Apache License 2.0."
678
678
  + "\n来源仓库:github.com/STMicroelectronics/" + spec.deviceRepo + "(" + spec.deviceRef + ")、"
679
679
  + "github.com/STMicroelectronics/" + spec.cmsisRepo + "(" + spec.cmsisRef + ")。"
680
- + "\n本目录是下载缓存,不是插件源码;删掉它不影响插件,下次用时会重新下载。\n";
680
+ + "\n本目录是下载缓存,不是插件源码;删除该目录不影响插件,下次使用时重新下载。\n";
681
681
  // 0.2:条目按 line+档位分(cmsis:F1:103xb),目录同名。没有 chip 的旧调用退化成 startup 文件名。
682
682
  const groupKey = chip !== null
683
683
  ? cmsisGroupKey(chip)
@@ -10,11 +10,11 @@
10
10
  * - db 推不出来的留手写表:`TIMx:timebase`(不占脚、只有 Prescaler/Period 取值)、
11
11
  * `DMA:<IP>`(DMA 请求表不在 db 的引脚信息里)、`ADC1:1,4,5`(多 Rank 扫描的通道顺序)。
12
12
  *
13
- * 两个「.ioc 里的写法与 db 不同」的坑(语料实证:CubeMX 官方板级 .ioc 504 份):
13
+ * 两处「.ioc 写法与 db 不同」的差异(语料实证:CubeMX 官方板级 .ioc 504 份):
14
14
  * 1. 定时器通道:db 写 `TIM2_CH1`,.ioc 里的 <pin>.Signal 要写 `S_TIM2_CH1`(共享信号加 S_ 前缀);
15
15
  * 2. ADC 通道:db 写 `ADC1_IN1`,.ioc 里统一写 `ADCx_IN1`(x = 任意 ADC 实例),
16
16
  * 具体是哪个 ADC 由 SH 块的 `ADC1_IN1,IN1` 表达。
17
- * 这两条不能靠猜:写错就会被 CubeMX 静默丢掉(§60 记过这个坑)。
17
+ * 这两条不可推测:写错会被 CubeMX 静默丢弃(§60 记录过该问题)。
18
18
  */
19
19
  import { logicalPinName } from "../engine/cubemx-db.js";
20
20
  const SERIAL_RE = /^(USART|UART|LPUART)([0-9]+)$/u;
@@ -34,8 +34,8 @@ function pinOrder(hit) {
34
34
  /**
35
35
  * db 里带某条复用例信号的引脚,按端口/脚号升序。
36
36
  *
37
- * 为什么用 `logicalPinName` 而不是直接丢带后缀的引脚:F1 的 PA0 在 db 里叫 PA0-WKUP,
38
- * 它就是 TIM2_CH1 的默认脚。按「带 - 就跳过」会把它整根脚丢掉(F1 上 TIM2 就再也选不到脚)。
37
+ * 使用 `logicalPinName` 的原因:直接丢弃带后缀的引脚会造成误删。F1 的 PA0 在 db 里叫 PA0-WKUP,
38
+ * 该引脚即 TIM2_CH1 的默认脚。按「带 - 就跳过」会丢弃整根引脚(F1 上 TIM2 将无法选到引脚)。
39
39
  */
40
40
  function pinsWithSignal(facts, signal) {
41
41
  const wanted = signal.trim().toUpperCase();
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * L1:设备事实(device facts)——唯一来源是本地内置资源里的 device/f1/chips.json。
3
3
  *
4
- * 用户 2026-10-31 的决定(原话「内置表删了吧」):插件不再自带任何手写芯片事实表。型号 → 容量档 /
4
+ * 用户 2026-10-31 决定删除内置表:插件不再自带任何手写芯片事实表。型号 → 容量档 /
5
5
  * 启动文件 / 设备宏 / 设备头 / Flash / RAM / 引脚数,全部取自随插件包发布的 assets/device/<族>/chips.json
6
6
  * (flat 布局,2026-11 起不再走独立资源仓与联网下载)。
7
7
  *
@@ -18,9 +18,9 @@ import fs from "node:fs";
18
18
  import path from "node:path";
19
19
  import { ASSETS_DEVICE_FACTS_FILE, ASSETS_REFRESH_HINT, errText, readLocalManifest } from "../engine/assets.js";
20
20
  import { familyIdOfPart, familyProfileOf } from "./family.js";
21
- /** chips.json 在内置资源里的相对路径(manifest 的 profiles.core 也按 device/** 收录它)。 */
21
+ /** chips.json 在内置资源里的相对路径(manifest 的 profiles.core 也按 device/** 收录该文件)。 */
22
22
  export const DEVICE_FACTS_REL = ASSETS_DEVICE_FACTS_FILE;
23
- /** 没缓存/没这颗芯片时,给用户的那句可执行提示(所有结构化错误都带上它)。 */
23
+ /** 无缓存/无该芯片时提供给用户的可执行提示(所有结构化错误均携带该提示)。 */
24
24
  export const DEVICE_FACTS_HINT = ASSETS_REFRESH_HINT;
25
25
  /** 每个族的 chips.json 各缓存一份(键里带 path:size:mtimeMs)。 */
26
26
  const cache = new Map();
@@ -87,7 +87,7 @@ export function defineSuffix(group) {
87
87
  /**
88
88
  * 一条 chips.json 记录 → DeviceFactsChip。
89
89
  * 关键字段(cpn / line / group / Flash / RAM / 引脚数)缺一个就丢掉:
90
- * 半条事实比没有事实更危险——它会算出错误的链接脚本内存布局。
90
+ * 不完整事实比缺失事实更危险——会算出错误的链接脚本内存布局。
91
91
  * 启动文件 / 设备宏 / 设备头 缺失时按 line + group 现算(见 namingFrom)。
92
92
  */
93
93
  function chipFrom(value) {
@@ -145,7 +145,7 @@ function emptyFacts(filePath, version, error) {
145
145
  error,
146
146
  };
147
147
  }
148
- /** 解析 chips.json 文本 → DeviceFacts(纯函数,测试可直接喂字符串)。 */
148
+ /** 解析 chips.json 文本 → DeviceFacts(纯函数,测试可直接传入字符串)。 */
149
149
  export function parseDeviceFacts(text, filePath, version = "") {
150
150
  let parsed;
151
151
  try {
@@ -200,7 +200,7 @@ export function loadDeviceFacts(env = process.env) {
200
200
  * STM32L4+ → device/l4+/chips.json;STM32WBA → device/wba/chips.json。
201
201
  *
202
202
  * 目录名取族画像的族段(小写、保留 +)—— 资源脚本就是这么建的目录。
203
- * 不能按「前两个字符」推:WBA 会被推成 wb、L4+ 会被推成 l4(都是别的族,读到的芯片表是错的)。
203
+ * 不能按「前两个字符」推:WBA 会被推成 wb、L4+ 会被推成 l4(均属于其他族,读到的芯片表是错的)。
204
204
  */
205
205
  export function familyFactsRelOf(familyId) {
206
206
  const raw = familyId.trim().toUpperCase();
@@ -6,7 +6,7 @@
6
6
  * 这些事实**CubeMX 的 db 里没有**(db 只给族 id/内核/主频/封装/引脚/IP),
7
7
  * 所以集中放在这里,按族查一次。
8
8
  *
9
- * 反过来,族 id / 内核 / 最高主频 / Flash / RAM / 引脚数**不进这张表**:它们由
9
+ * 反过来,族 id / 内核 / 最高主频 / Flash / RAM / 引脚数**不进这张表**:这些字段由
10
10
  * engine/cubemx-db.ts 的 parseMcuXml 从本机 db/mcu/<Mcu.Name>.xml 读(Family/Core/
11
11
  * Frequency/Flash/Ram/IONb)。db 一升级,那些数字自动跟着走,不用改代码。
12
12
  *
@@ -16,7 +16,7 @@
16
16
  * f0x f1x f2x f3x f4x f7x g0x g4x h7x(+dual_bank) l0(+dual_bank) l1(+dual_bank) l4x
17
17
  * l5x mp13x mp15x u5x wbx wlx x5x_common xl w108xx。
18
18
  * —— 没有 C0/H5/N6/U0/U3/WBA/WB0/WL3/MP2 的专用脚本,这些族 openocdTarget = null,
19
- * 烧录/调试时给明确拒绝理由,而不是拿别的族的 target 硬连。
19
+ * 烧录/调试时给明确拒绝理由,而不是以其他族的 target 强行连接。
20
20
  *
21
21
  * 能力闸门(capabilities)是**诚实降级**:值为 false 表示插件这条路线还没按该族实现,
22
22
  * 调用方应当直接报"不支持"并说清原因,绝不能悄悄用 F1 的表去凑。
@@ -72,7 +72,7 @@ const PENDING_PRESET = ".ioc 外设预设表目前只有 F1(下一步按族从
72
72
  const PENDING_CLOCK = "时钟规划目前只按 F1 的 RCC/PLL 实现";
73
73
  const NO_SVD = "内置资源只有 F1 的 SVD(中断名/寄存器名校验暂不可用)";
74
74
  /**
75
- * 每项能力"缺什么"的一句话(给工具报错用,不是给文档用)。
75
+ * 每项能力「缺什么」的简要说明(供工具报错使用,不用于文档)。
76
76
  *
77
77
  * 为什么不复用族 note:note 是给人看的整段理由(HAL/寄存器/预设/时钟/SVD 全塞在一条里),
78
78
  * 工具拒绝某个参数时只需要那一项的原因。之前直接把 note 拼进 errors,一条报错 300 多字,
@@ -81,7 +81,7 @@ const NO_SVD = "内置资源只有 F1 的 SVD(中断名/寄存器名校验暂
81
81
  export const CAPABILITY_GAPS = {
82
82
  halScaffold: "HAL 建工程(模板/启动文件/链接脚本/设备宏)按 21 个单核族的固件包实现",
83
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
- iocPresets: "手写 .ioc 预设表只有 F1(其它族靠 db 派生 USART/UART/LPUART,TIM/ADC/DMA 仍需手写键)",
84
+ iocPresets: "手写 .ioc 预设表只有 F1(其他族靠 db 派生 USART/UART/LPUART,TIM/ADC/DMA 仍需手写键)",
85
85
  clockPlan: "时钟规划只按 F1 的 RCC/PLL 键实现",
86
86
  svdValidation: "中断名/寄存器名校验要该族的 SVD,内置资源目前只有 F1 的",
87
87
  };
@@ -213,7 +213,7 @@ export function familyProfiles() {
213
213
  }
214
214
  /**
215
215
  * 型号 → 族 id。只做字符串判定,不查 db(db 里 MCU xml 的 Family 属性是更权威的来源,
216
- * 见 engine/cubemx-db.ts 的 parseMcuXml;这里用于没有 db 的场合与 .ioc 缺失时的兜底)。
216
+ * 见 engine/cubemx-db.ts 的 parseMcuXml;本函数用于没有 db 的场合与 .ioc 缺失时的回退)。
217
217
  *
218
218
  * 例:STM32F103C8T6 → STM32F1;STM32L4R5ZIT6 → STM32L4+;STM32WBA55CG → STM32WBA;
219
219
  * STM32H563ZI → STM32H5;STM32U575ZI → STM32U5;STM32G071RB → STM32G0。
@@ -241,7 +241,7 @@ export function familyIdOfPart(part) {
241
241
  continue;
242
242
  const next = tail.slice(segment.length, segment.length + 1);
243
243
  // 后面跟字母时,只有「字母+数字」这种子族段才算继续(H7A3 的 A3、H7B0 的 B0);
244
- // 单纯的字母说明这是别的族(L4R5 已在上面按 L4+ 处理,WB55 的 B 后面是 5 但 segment WB 更短、不冲突)。
244
+ // 纯字母说明属于其他族(L4R5 已在上面按 L4+ 处理,WB55 的 B 后面是 5 但 segment WB 更短、不冲突)。
245
245
  const after = tail.slice(segment.length + 1, segment.length + 2);
246
246
  if (next !== "" && /[A-Z]/u.test(next) && !/[0-9]/u.test(after))
247
247
  continue;
@@ -297,7 +297,7 @@ export function isF1(profile) {
297
297
  * Cortex-M0 / M0+ → 4 断点 / 2 观察点(FPB 只有 4 个比较器、DWT 2 个)
298
298
  * Cortex-M3 / M4 → 6 / 4
299
299
  * Cortex-M7 / M33 / M55 → 8 / 4
300
- * 单型号可以在内置资源 chips.json 里写 breakpoints/watchpoints 覆盖(breakpoints.ts 优先用它)。
300
+ * 单型号可以在内置资源 chips.json 里写 breakpoints/watchpoints 覆盖(breakpoints.ts 优先使用该覆盖值)。
301
301
  */
302
302
  // 顺序有讲究:M33 里含有 "m3" 子串,所以 M7/M33/M55 必须排在 M3/M4 前面判。
303
303
  const CORE_BUDGETS = [
@@ -305,9 +305,9 @@ const CORE_BUDGETS = [
305
305
  [/cortex-m7|cortex-m33|cortex-m55/i, { code: 8, data: 4 }],
306
306
  [/cortex-m3|cortex-m4/i, { code: 6, data: 4 }],
307
307
  ];
308
- /** F1(Cortex-M3)的实测值,也是所有查不到内核时的兜底。 */
308
+ /** F1(Cortex-M3)的实测值,也是所有查不到内核时的回退值。 */
309
309
  export const FALLBACK_DEBUG_BUDGET = { code: 6, data: 4 };
310
- /** 内核名 → 硬件断点/观察点预算;查不到返回 F1 的 6/4(调用方应在 notes 里说明是兜底)。 */
310
+ /** 内核名 → 硬件断点/观察点预算;查不到返回 F1 的 6/4(调用方应在 notes 里说明使用了回退值)。 */
311
311
  export function debugBudgetForCore(core) {
312
312
  const raw = core.trim();
313
313
  if (raw === "")
@@ -321,7 +321,7 @@ export function debugBudgetForCore(core) {
321
321
  /**
322
322
  * 族画像 → 预算(MPU 的 A7/A35 不用这个模型,返回 null 让调用方跳过比较器预算)。
323
323
  * 内核未知(空串)也返回 null:不知道内核就不该假装算得出一条数值预算,
324
- * 让调用方退回"按 F1 兜底并说明原因"的老路径。
324
+ * 使调用方退回「按 F1 回退并说明原因」的原有路径。
325
325
  */
326
326
  export function debugBudgetOfFamily(profile) {
327
327
  const core = profile.core.trim();
@@ -336,9 +336,9 @@ export function debugBudgetOfFamily(profile) {
336
336
  *
337
337
  * 为什么要内置:openocd 0.12(2023-01 的最后一个正式版)没有 stm32c0x.cfg / stm32u0x.cfg,
338
338
  * 而这两族已经在 14 个单核族的支持范围里。上游 master 版脚本只用了 0.13 才有的
339
- * `dap create ... -tap`,把它换成 0.12 认的 `-chain-position` 就能完整加载(adapter/target/flash bank
339
+ * `dap create ... -tap`,将其换成 0.12 支持的 `-chain-position` 即可完整加载(adapter/target/flash bank
340
340
  * 全部通过,只有没接探针时 init 会报 CMSIS-DAP CMD_INFO failed)。
341
- * 文件放在插件模板目录而不是系统 openocd 目录:升级/卸载 openocd 不会把支持弄丢,
341
+ * 文件放在插件模板目录而非系统 openocd 目录:升级/卸载 openocd 不会丢失该支持,
342
342
  * 也不去改用户机器上的 openocd 安装。
343
343
  */
344
344
  export function bundledOpenocdConfig(name) {
@@ -352,7 +352,7 @@ export function bundledOpenocdConfig(name) {
352
352
  * 族 → openocd target 配置。
353
353
  *
354
354
  * family 传 null 表示"工程里没有 .ioc / 认不出族":保持历史行为回退 stm32f1x,
355
- * 但在 note 里说明这是兜底(用户可自己在 openocd.cfg 里写 target)。
355
+ * 但在 note 里说明使用的是回退值(用户可在 openocd.cfg 中自行写 target)。
356
356
  */
357
357
  export function chooseOpenocdTarget(family) {
358
358
  if (family === null) {
@@ -388,7 +388,7 @@ export function chooseOpenocdTarget(family) {
388
388
  note: family.note,
389
389
  error: "本机 openocd 没有 " + family.id + " 的 target 脚本(" + family.note + "):" +
390
390
  "请在工程根目录放一份 openocd.cfg 写死 source [find target/xxx.cfg],或用 openocd 的 -f 显式指定;" +
391
- "不要拿别的族的 target 硬连(会连不上或读错 flash 布局)",
391
+ "不得以其他族的 target 强行连接(会导致无法连接或读错 flash 布局)",
392
392
  bundled: false,
393
393
  };
394
394
  }
@@ -487,11 +487,11 @@ const PER_LINE_EXTI_VECTORS = Array.from({ length: 16 }, (_, line) => ({
487
487
  from: line,
488
488
  to: line,
489
489
  }));
490
- /** 认不出内核时的兜底:F1 的 M3 分组(保持历史行为,调用方应在 notes 里说明)。 */
490
+ /** 无法识别内核时的回退:F1 的 M3 分组(保持历史行为,调用方应在 notes 里说明)。 */
491
491
  export const FALLBACK_EXTI_VECTORS = M3M4M7_EXTI_VECTORS;
492
492
  /**
493
493
  * 族 → EXTI 向量分组。profile 为 null(工程里读不到族)时返回 F1 的 M3 分组,
494
- * 这是历史行为,调用方要自行在报告里说明"分组按 M3 兜底"。
494
+ * 这是历史行为,调用方要自行在报告里说明「分组按 M3 回退」。
495
495
  */
496
496
  export function extiVectorsOf(profile) {
497
497
  const core = (profile?.core ?? "").trim();
@@ -2,9 +2,9 @@
2
2
  * 固件包(STM32Cube_FW_<族>_V<版本>)的组装清单。
3
3
  *
4
4
  * 背景(2026-10 实测,见 docs §14):ST 的固件包不是整体下载的,GitHub 上的 STM32Cube<族>
5
- * 主仓库把 HAL 驱动与 CMSIS 设备支持都挂成了 git 子模块 —— 只拉主仓库 tarball,
5
+ * 主仓库将 HAL 驱动与 CMSIS 设备支持均设为 git 子模块 —— 仅拉取主仓库 tarball,
6
6
  * Drivers/STM32F1xx_HAL_Driver 与 Drivers/CMSIS/Device/ST/STM32F1xx 是**空目录**,
7
- * 编译必挂。所以要分别拉:
7
+ * 编译必然失败。因此需分别拉取:
8
8
  * ① HAL 驱动仓库(stm32f1xx-hal-driver)→ Drivers/STM32F1xx_HAL_Driver/{Inc,Src}
9
9
  * ② CMSIS 设备仓库(cmsis-device-f1) → Drivers/CMSIS/Device/ST/STM32F1xx/{Include,Source}
10
10
  * ③ CMSIS 内核头(STM32CubeF1 主仓库 Drivers/CMSIS/Include 下的 5 个头文件,逐个拉)
@@ -18,9 +18,9 @@ import { FIRMWARE_ARCHIVE_PINS, FIRMWARE_CORE_PINS } from "./firmware-pins.js";
18
18
  /**
19
19
  * 归档只有一条官方地址(P0-2):codeload 直连。
20
20
  *
21
- * 为什么砍掉 ghproxy / api 兜底:同一个 commit 经不同入口打包,gzip 头与顶层目录名不同,
22
- * 字节哈希对不上——一个 sha256 不能同时校验三条链路。留着它们要么是「校验形同虚设」,
23
- * 要么是「第二条永远失败」。ghproxy 还是第三方中间人,没有理由让固件包依赖它。
21
+ * 移除 ghproxy / api 回退的原因:同一个 commit 经不同入口打包,gzip 头与顶层目录名不同,
22
+ * 字节哈希不一致——单个 sha256 不能同时校验三条链路。保留这类回退要么使「校验形同虚设」,
23
+ * 要么使「第二条始终失败」。ghproxy 还为第三方中间人,固件包不应依赖该服务。
24
24
  */
25
25
  function archiveUrls(repo, ref) {
26
26
  return ["https://codeload.github.com/STMicroelectronics/" + repo + "/tar.gz/refs/heads/" + ref];
@@ -562,7 +562,7 @@ export const FIRMWARE_FAMILIES = {
562
562
  coreRepo: "STM32CubeH7",
563
563
  coreRef: "master",
564
564
  coreIncludeDir: "Drivers/CMSIS/Include",
565
- // CM7 的 core_cm7.h 会 include cachel1_armv7.h(L1 cache 维护):漏了它编译直接 fatal error。
565
+ // CM7 的 core_cm7.h 会 include cachel1_armv7.h(L1 cache 维护):缺失该文件将导致编译直接 fatal error。
566
566
  coreHeaders: ["cmsis_compiler.h", "cmsis_gcc.h", "cmsis_version.h", "mpu_armv7.h", "cachel1_armv7.h", "core_cm7.h"],
567
567
  archives: [
568
568
  {
@@ -725,7 +725,7 @@ export function firmwarePlanFor(request) {
725
725
  "- CMSIS 设备支持(cmsis-device-f1):Apache-2.0。",
726
726
  "- CMSIS 内核头(STM32CubeF1 / Drivers/CMSIS/Include):Apache-2.0。",
727
727
  "",
728
- "CubeMX 认这个目录(实测),但 ST 的包管理器不会维护它:要升级请用 CubeMX 包管理器重装官方包。",
728
+ "CubeMX 识别该目录(实测),但 ST 的包管理器不会维护该目录:升级时请用 CubeMX 包管理器重装官方包。",
729
729
  "",
730
730
  ].join("\n");
731
731
  return {
@@ -766,7 +766,7 @@ function hasStartup(dir) {
766
766
  * 三条判据(与 scaffold.ts 的 resolveFirmwareRoot 一致,多加一条 startup 检查):
767
767
  * ① Drivers/CMSIS/Include 有内核头 ② Drivers/<族>_HAL_Driver 有 Inc 与 Src
768
768
  * ③ Drivers/CMSIS/Device/ST/<族>/{Include,Source/Templates/gcc/startup_*.s}
769
- * 为什么必须自查:CubeMX 找不到包时**不报错**(docs §14),只看它打印 Code succesfully generated 会被骗。
769
+ * 必须自查的原因:CubeMX 找不到包时**不报错**(docs §14),仅凭其打印 Code succesfully generated 会造成误判。
770
770
  */
771
771
  export function verifyFirmwarePackage(root, family) {
772
772
  const spec = FIRMWARE_FAMILIES[family];
@@ -801,7 +801,7 @@ export function dshFirmwareDir(cubeMxRoot) {
801
801
  return base + "/" + DSH_FIRMWARE_DIR_NAME;
802
802
  }
803
803
  /**
804
- * 从 .ioc 正文里读它要哪个固件包。
804
+ * 从 .ioc 正文中读取所需的固件包。
805
805
  * 首选 ProjectManager.FirmwarePackage=STM32Cube FW_F1 V1.8.7;
806
806
  * 缺这一条时退回 Mcu.CPN 推族 + 该族默认版本。
807
807
  */
@@ -860,7 +860,7 @@ export function firmwareSourceLabel(source) {
860
860
  /**
861
861
  * 在 CubeMX 根下找 .ioc 要的固件包。两处都找:Repository(官方)与 dsh-firmware(插件组装)。
862
862
  * 排序:包名精确匹配最优先 → 版本号大的 → 同版本优先 Repository。
863
- * 为什么两处都找:官方包零拷贝直接用;没有官方包时才用我们组装的那份。
863
+ * 两处都查找的原因:官方包零拷贝直接使用;没有官方包时才使用插件组装的那份。
864
864
  */
865
865
  export function locateFirmwarePackage(cubeMxRoots, request = {}) {
866
866
  const wanted = (request.packageName ?? "").trim();
@@ -1,12 +1,12 @@
1
1
  /**
2
- * L1:装不上(或不该由插件代装)的东西,怎么把话说清楚。
2
+ * L1:无法安装(或不应由插件代装)的组件,如何清晰说明。
3
3
  *
4
4
  * 门禁把缺件分成两档,因为这两档的"下一步"完全不同:
5
5
  * auto —— MSYS2 里一条 pacman 就能补(gcc / gdb / openocd / cmake / ninja),
6
6
  * 插件能跑 stm32_env_install 出计划、确认后自己装;
7
7
  * manual —— 装不了或不该代装:STM32CubeMX 是 InstallAnywhere 的 GUI 向导(要 ST 账号 +
8
8
  * 同意许可),固件包只由 CubeMX 的包管理器维护(st.com 包清单 + 22 个 git 子模块)。
9
- * 这两样只能给人一步步的指引,插件顶多帮它把路径写进配置。
9
+ * 这两种只能提供分步指引,插件至多将其路径写入配置。
10
10
  *
11
11
  * 本文件只有文案与元数据,不起进程、不读盘,便于单测与审计(改文案不用碰引擎)。
12
12
  */
@@ -37,7 +37,7 @@ export function cubeMxGuide() {
37
37
  label: CUBEMX_LABEL,
38
38
  installability: "manual",
39
39
  why: "CubeMX 是 GUI 安装向导,没有官方静默参数,下载前还要登录 ST 账号并同意许可,"
40
- + "插件代装等于替你点同意、替你输账号 —— 这一步不做。",
40
+ + "插件代为安装等于代用户确认许可、代用户输入账号 —— 此步骤不执行。",
41
41
  sizeHint: "安装包数百 MB,装完约 1.5 GB(不含固件包);固件包另算,见固件包那条指引(实测 250 MB – 1.7 GB)。",
42
42
  needsAccount: true,
43
43
  steps: [
@@ -47,7 +47,7 @@ export function cubeMxGuide() {
47
47
  },
48
48
  {
49
49
  title: "GUI 装一遍(默认选项即可)",
50
- detail: "双击安装包按向导走完;装到哪个盘都行,别放在受保护目录(例如 C:\\Program Files 需要管理员权限,插件写固件包时会失败)。",
50
+ detail: "双击安装包按向导走完;安装盘符不限,不要放在受保护目录(例如 C:\\Program Files 需要管理员权限,插件写固件包时会失败)。",
51
51
  },
52
52
  {
53
53
  title: "把安装根写进配置",
@@ -55,7 +55,7 @@ export function cubeMxGuide() {
55
55
  },
56
56
  {
57
57
  title: "自检",
58
- detail: "stm32_doctor 的 tools 里 cubemx 与 cubemx-java 都应带 path;缺 jre 的话无头生成会直接报 java 找不到。",
58
+ detail: "stm32_doctor 的 tools 里 cubemx 与 cubemx-java 都应带 path;缺 jre 时无头生成会直接报 java 找不到。",
59
59
  },
60
60
  ],
61
61
  verify: "stm32_doctor → capabilities.generate 为 true(cubemx 与 cubemx-java 都找到)。",
@@ -71,7 +71,7 @@ export function familyPrefix(family) {
71
71
  /**
72
72
  * 各系列的固件包实测体积(2026-10 本机 D:\app\STM32CubeMX\Repository 直接量的)。
73
73
  *
74
- * 写死一句话会被别的系列看笑话:F1 293 MB、G4 471 MB、F4 1.67 GB,差 6 倍。
74
+ * 固定单一数字不适用于其他系列:F1 293 MB、G4 471 MB、F4 1.67 GB,相差 6 倍。
75
75
  * 表里没有的系列给区间,不给具体数字。
76
76
  */
77
77
  const FIRMWARE_SIZE_HINTS = {
@@ -84,8 +84,8 @@ const FIRMWARE_SIZE_HINTS = {
84
84
  L0: "258 MB / 17,504 个文件(v1.12.4 实测);装完占盘约 258 MB。",
85
85
  L4: "约 300 MB / 两万个文件;装完占盘约 300 MB。",
86
86
  };
87
- const FIRMWARE_SIZE_FALLBACK = "一个系列通常 250 MB – 1.7 GB / 一万到四万个文件(不同系列差很多,最多差 6 倍);装完占盘同量级。";
88
- /** 固件包体积提示:认识的系列精确、不认识给区间(别把 F1 的数字扣到 H7 头上)。 */
87
+ const FIRMWARE_SIZE_FALLBACK = "一个系列通常 250 MB – 1.7 GB / 一万到四万个文件(不同系列差异较大,最多相差 6 倍);装完占盘同量级。";
88
+ /** 固件包体积提示:已知系列给精确值、未知系列给区间(不将 F1 的数字套用到 H7)。 */
89
89
  export function firmwareSizeHint(family) {
90
90
  const key = family.trim().toUpperCase();
91
91
  return FIRMWARE_SIZE_HINTS[key] ?? FIRMWARE_SIZE_FALLBACK;
@@ -94,9 +94,9 @@ export function firmwareSizeHint(family) {
94
94
  * 固件包(HAL + CMSIS + startup)的安装指引。
95
95
  *
96
96
  * 为什么不做成自动下载(2026-10 取证):GitHub 上 STMicroelectronics/STM32CubeF1 有 v1.8.7 标签,
97
- * 但主仓库挂了 22 个 git 子模块,tarball 里 Drivers/CMSIS/Device/ST/STM32F1xx 与
98
- * Drivers/STM32F1xx_HAL_Driver 是**空目录**;拼出来的包 CubeMX 认不认还没验证。
99
- * 所以现在归 manual:让 CubeMX 自己的包管理器装(它写的 package.xml / 包清单才是权威)。
97
+ * 但主仓库包含 22 个 git 子模块,tarball 里 Drivers/CMSIS/Device/ST/STM32F1xx 与
98
+ * Drivers/STM32F1xx_HAL_Driver 是**空目录**;拼接出的包 CubeMX 是否识别尚未验证。
99
+ * 所以现在归入 manual:由 CubeMX 自身的包管理器安装(其写入的 package.xml / 包清单才是权威)。
100
100
  */
101
101
  export function firmwareGuide(input) {
102
102
  const prefix = familyPrefix(input.family);
@@ -109,17 +109,17 @@ export function firmwareGuide(input) {
109
109
  label: "固件包 " + name,
110
110
  installability: "manual",
111
111
  why: "固件包不在 CubeMX 安装包里,而且不是单个压缩包:HAL 驱动、CMSIS 设备头、启动文件分在不同的 git 仓库里,"
112
- + "GitHub 的源码压缩包拿到的是空目录。可靠的来源只有 CubeMX 自己的包管理器(它写包清单与 package.xml)。",
112
+ + "GitHub 的源码压缩包拿到的是空目录。可靠的来源只有 CubeMX 自己的包管理器(由 CubeMX 写入包清单与 package.xml)。",
113
113
  sizeHint: firmwareSizeHint(input.family),
114
114
  needsAccount: true,
115
115
  steps: [
116
116
  {
117
117
  title: autoDownloadable
118
- ? "先试插件代下(这一代已接入)"
119
- : "插件还不会代下这一代",
118
+ ? "先试插件代下载(该系列已接入)"
119
+ : "插件尚不支持该系列代下载",
120
120
  detail: autoDownloadable
121
- ? "调 stm32_firmware_install(family 给 " + input.family + ",dryRun:false + confirm:true):插件从 GitHub 拉 HAL 驱动与 CMSIS 设备两个子模块仓库 + 内核头,自己补 package.xml,实测 CubeMX 认;约 2 MB,几十秒。拉不到或想用官方包再走下面三步。"
122
- : "目前只有 F1 接入自动下载(其余代按同样字段补一条即可);这一代请走下面的 CubeMX 包管理器。",
121
+ ? "调 stm32_firmware_install(family 给 " + input.family + ",dryRun:false + confirm:true):插件从 GitHub 拉取 HAL 驱动与 CMSIS 设备两个子模块仓库 + 内核头,自行补齐 package.xml,实测 CubeMX 可识别;约 2 MB,数十秒。拉取失败或需使用官方包时,按下面三步操作。"
122
+ : "目前只有 F1 接入自动下载(其余系列按同样字段补充一条即可);该系列请使用下面的 CubeMX 包管理器。",
123
123
  },
124
124
  {
125
125
  title: "在 CubeMX 里打开包管理器",
@@ -131,7 +131,7 @@ export function firmwareGuide(input) {
131
131
  },
132
132
  {
133
133
  title: "离线机器:整目录拷贝",
134
- detail: "从有网的机器把 " + name + " 整个目录(或整个 Repository 目录)拷到目标机同一位置即可,不需要重装 CubeMX。",
134
+ detail: "从联网机器把 " + name + " 整个目录(或整个 Repository 目录)拷到目标机同一位置即可,不需要重装 CubeMX。",
135
135
  },
136
136
  {
137
137
  title: "自检",
@@ -142,7 +142,7 @@ export function firmwareGuide(input) {
142
142
  };
143
143
  }
144
144
  /**
145
- * 组件 id → 指引;auto 组件没有指引(它们走 stm32_env_install)。cubemx 与 cubemx-java 共用一份。
145
+ * 组件 id → 指引;auto 组件无指引(走 stm32_env_install)。cubemx 与 cubemx-java 共用一份。
146
146
  *
147
147
  * firmware 需要族名/包名/仓库目录才说得具体,所以第二个参数是可选的补充信息:
148
148
  * 调用方(route_plan)手里有这些字段就传,只拿组件 id 的人(门禁、命令卡)也能拿到通用指引 ——
@@ -2,7 +2,7 @@
2
2
  * L2 数据:`.ioc` 外设预设 —— "启用一个外设"到底要写哪些键。
3
3
  *
4
4
  * 为什么必须做成预设:CubeMX **不是**「读到 USART1.VirtualMode 就建 USART1」。
5
- * 它按「某根脚的 Mode + Signal」推导复用模式,再核对 Mcu.IPn 里有这个实例,才生成
5
+ * CubeMX 按「某根脚的 Mode + Signal」推导复用模式,再核对 Mcu.IPn 中有该实例,才生成
6
6
  * MX_xxx_Init。实测(C8T6 + CubeMX 6.15.0 + STM32Cube_FW_F1_V1.8.7):只写
7
7
  * Mcu.IPn=USART1 + USART1.IPParameters/VirtualMode + PA9.Signal=USART1_TX 时,
8
8
  * CubeMX 静默丢弃整个 USART1(生成结果里没有 MX_USART1_UART_Init,
@@ -16,9 +16,9 @@
16
16
  * 换族时按同样的规则加一份表即可(`family` 字段是唯一的族相关入口)。
17
17
  */
18
18
  /**
19
- * 族相关的引脚别名:**离线兜底表**,只在读不到 CubeMX db 时用。
19
+ * 族相关的引脚别名:**离线回退表**,仅在读不到 CubeMX db 时使用。
20
20
  *
21
- * 正常路径是 src/engine/ioc-plan.ts 的 createPinNameResolver:它按 .ioc 里的 Mcu.Name 去本机
21
+ * 正常路径是 src/engine/ioc-plan.ts 的 createPinNameResolver:该解析器按 .ioc 里的 Mcu.Name 去本机
22
22
  * CubeMX 的 `db/mcu/<Mcu.Name>.xml` 查真实引脚名(R16),db 里叫什么就写什么。
23
23
  * 这张表只收 F1 的 6 根带后缀的脚(PA0→PA0-WKUP、PC13→PC13-TAMPER-RTC、PC14/PC15、PD0/PD1),
24
24
  * 没装 CubeMX 或 db 里没有这颗时才会用到;CubeMX 换版本后 db 名可能变,那时这里就会写错脚,