dsh-stm32 0.1.6 → 0.1.8

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 (125) hide show
  1. package/README.md +410 -517
  2. package/README_EN.md +410 -510
  3. package/client/client.js +4363 -24
  4. package/docs/reading-guide.md +62 -0
  5. package/lib/client.js +4363 -24
  6. package/lib/commands/register.js +5 -5
  7. package/lib/data/chips.js +4 -4
  8. package/lib/data/clock-db.js +24 -24
  9. package/lib/data/clock-f1.js +2 -2
  10. package/lib/data/cmsis-sources.js +6 -6
  11. package/lib/data/db-presets.js +4 -4
  12. package/lib/data/device-facts.js +6 -6
  13. package/lib/data/family.js +16 -16
  14. package/lib/data/firmware-packages.js +10 -10
  15. package/lib/data/install-guides.js +18 -18
  16. package/lib/data/ioc-presets.js +3 -3
  17. package/lib/data/ioc-schema.js +32 -32
  18. package/lib/data/rm-topics.js +6 -6
  19. package/lib/data/search-roots.js +62 -16
  20. package/lib/data/serial-config.js +7 -7
  21. package/lib/data/stm32f1.js +1 -1
  22. package/lib/data/svd.js +7 -7
  23. package/lib/data/toolchain-config.js +3 -3
  24. package/lib/engine/artifacts.js +123 -0
  25. package/lib/engine/assets.js +5 -5
  26. package/lib/engine/breakpoint-hits.js +73 -0
  27. package/lib/engine/breakpoints.js +5 -5
  28. package/lib/engine/build.js +73 -3
  29. package/lib/engine/cache.js +4 -4
  30. package/lib/engine/channel-tap.js +227 -0
  31. package/lib/engine/channels.js +48 -0
  32. package/lib/engine/clock-derived.js +2 -2
  33. package/lib/engine/clock-direct.js +3 -3
  34. package/lib/engine/clock-plan.js +7 -7
  35. package/lib/engine/clock-pllmn.js +6 -6
  36. package/lib/engine/clocks.js +192 -0
  37. package/lib/engine/cmake-sources.js +9 -9
  38. package/lib/engine/code-patch.js +5 -5
  39. package/lib/engine/cube-mx-guard.js +3 -3
  40. package/lib/engine/cube-programmer.js +4 -4
  41. package/lib/engine/cubemx-db.js +7 -7
  42. package/lib/engine/debug-session.js +58 -13
  43. package/lib/engine/debug.js +3 -3
  44. package/lib/engine/doctor.js +12 -12
  45. package/lib/engine/download.js +1 -1
  46. package/lib/engine/event-bus.js +158 -0
  47. package/lib/engine/event-log.js +335 -0
  48. package/lib/engine/facts-acquire.js +3 -3
  49. package/lib/engine/fault-hints.js +146 -0
  50. package/lib/engine/fetch.js +2 -2
  51. package/lib/engine/firmware-install.js +16 -16
  52. package/lib/engine/firmware-official.js +8 -8
  53. package/lib/engine/flash.js +22 -22
  54. package/lib/engine/fs-longpath.js +1 -1
  55. package/lib/engine/gdb-mi.js +7 -7
  56. package/lib/engine/generate-script.js +2 -2
  57. package/lib/engine/generate.js +17 -17
  58. package/lib/engine/hal-chip.js +7 -7
  59. package/lib/engine/interrupts.js +247 -0
  60. package/lib/engine/ioc-diff.js +369 -0
  61. package/lib/engine/ioc-plan.js +52 -52
  62. package/lib/engine/ioc-rules.js +9 -9
  63. package/lib/engine/ioc-sync.js +58 -0
  64. package/lib/engine/ioc-verify.js +34 -34
  65. package/lib/engine/msys2-install.js +81 -56
  66. package/lib/engine/panel-actions.js +103 -0
  67. package/lib/engine/pinout.js +140 -0
  68. package/lib/engine/probe-error.js +8 -8
  69. package/lib/engine/probe-info.js +95 -0
  70. package/lib/engine/probe-session.js +3 -3
  71. package/lib/engine/probe.js +47 -50
  72. package/lib/engine/progress.js +99 -0
  73. package/lib/engine/project-conf.js +199 -0
  74. package/lib/engine/project-export.js +1 -1
  75. package/lib/engine/register-clock.js +5 -5
  76. package/lib/engine/register-gpio.js +3 -3
  77. package/lib/engine/register-linker.js +7 -7
  78. package/lib/engine/register-template.js +22 -22
  79. package/lib/engine/regs.js +3 -3
  80. package/lib/engine/rm-extract.js +2 -2
  81. package/lib/engine/rm-sources.js +1 -1
  82. package/lib/engine/route-plan.js +9 -9
  83. package/lib/engine/rtt.js +18 -18
  84. package/lib/engine/scaffold.js +22 -22
  85. package/lib/engine/serial.js +24 -24
  86. package/lib/engine/session-context.js +19 -0
  87. package/lib/engine/source-slice.js +59 -0
  88. package/lib/engine/tar.js +1 -1
  89. package/lib/engine/text-file.js +1 -1
  90. package/lib/engine/thirdparty.js +3 -3
  91. package/lib/engine/tool-env.js +2 -2
  92. package/lib/engine/tool-events.js +119 -0
  93. package/lib/engine/toolchain-gate.js +8 -8
  94. package/lib/engine/usercode-merge.js +2 -2
  95. package/lib/engine/vscode-config.js +2 -2
  96. package/lib/engine/watch-admin.js +101 -0
  97. package/lib/engine/watch-record.js +39 -0
  98. package/lib/engine/watch-recorder.js +116 -0
  99. package/lib/engine/web-api.js +887 -5
  100. package/lib/engine/web-routes.js +18 -1
  101. package/lib/engine/workspace-memo.js +41 -0
  102. package/lib/engine/xcube-catalog.js +1 -1
  103. package/lib/index.js +72 -29
  104. package/lib/skill/stm32-workflow.js +1 -1
  105. package/lib/tools/assets.js +1 -1
  106. package/lib/tools/cache.js +2 -2
  107. package/lib/tools/debug-session.js +5 -5
  108. package/lib/tools/doctor.js +2 -2
  109. package/lib/tools/download.js +1 -1
  110. package/lib/tools/env-install.js +3 -3
  111. package/lib/tools/firmware-install.js +5 -5
  112. package/lib/tools/flash.js +8 -8
  113. package/lib/tools/generate.js +1 -1
  114. package/lib/tools/ioc-apply.js +10 -1
  115. package/lib/tools/ioc-plan.js +1 -1
  116. package/lib/tools/ioc-verify.js +11 -11
  117. package/lib/tools/project-create.js +32 -4
  118. package/lib/tools/project-dir.js +8 -2
  119. package/lib/tools/regs.js +10 -10
  120. package/lib/tools/route-plan.js +9 -9
  121. package/lib/tools/rtt.js +17 -9
  122. package/lib/tools/serial.js +30 -8
  123. package/lib/tools/watch.js +24 -2
  124. package/package.json +70 -70
  125. package/templates/scaffold/RTT.md +26 -34
@@ -14,7 +14,7 @@
14
14
  *
15
15
  * 环境变量:
16
16
  * DSH_STM32_SERIAL_CONFIG 整体改指配置文件(单测与多工程隔离用;相对路径按主目录解析)
17
- * DSH_STM32_NO_CONFIG=1 让读配置的地方当它不存在(与 config.json 同一套开关语义)
17
+ * DSH_STM32_NO_CONFIG=1 使读取配置的代码按未配置处理(与 config.json 同一套开关语义)
18
18
  */
19
19
  import { randomBytes } from "node:crypto";
20
20
  import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -52,7 +52,7 @@ function asString(value) {
52
52
  }
53
53
  /**
54
54
  * DTR/RTS 只认真正的布尔值,外加 "true"/"false"/"1"/"0" 这些常见字符串写法。
55
- * 认不出来返回 null(由调用方记一条错误)——悄悄回落到缺省值会让"我明明设了 rts"变成静默无效。
55
+ * 无法识别时返回 null(由调用方记录一条错误)——静默回退到缺省值会使「已设置的 rts」静默失效。
56
56
  */
57
57
  function asOptionalBoolean(value) {
58
58
  if (typeof value === "boolean")
@@ -81,7 +81,7 @@ function oneOf(value, allowed) {
81
81
  }
82
82
  /**
83
83
  * 把任意 JSON / 工具参数归一成合法参数:非法的字段按缺省值处理并记一条 errors。
84
- * 不抛异常——参数写错要能变成 settings-invalid 的一次报告,而不是把调用方打崩。
84
+ * 不抛异常——参数写错要能变成 settings-invalid 的一次报告,而非导致调用方失败。
85
85
  */
86
86
  export function normalizeSerialSettings(raw, errors, base = defaultSerialSettings()) {
87
87
  const out = { ...base };
@@ -171,7 +171,7 @@ function isBusPathId(value) {
171
171
  */
172
172
  export function portIdentity(facts) {
173
173
  // 字段声明成 string,但调用方可能是「手工改过的 serial.json / 老版本记录」,
174
- // 缺字段时按空串处理,别让一个半截配置把整条打开流程打崩。
174
+ // 缺字段时按空串处理,避免不完整配置导致整条打开流程失败。
175
175
  const vid = text(facts.vid).toUpperCase();
176
176
  const pid = text(facts.pid).toUpperCase();
177
177
  const serial = text(facts.serialNumber);
@@ -322,7 +322,7 @@ export function readSerialConfig(env = process.env) {
322
322
  path,
323
323
  exists: true,
324
324
  config: null,
325
- errors: ["串口配置文件不是合法 JSON:" + describeError(error) + ";已按无记忆处理(重新写入会覆盖它)"],
325
+ errors: ["串口配置文件不是合法 JSON:" + describeError(error) + ";已按无记忆处理(重新写入将覆盖该值)"],
326
326
  mtimeMs,
327
327
  };
328
328
  cache = { path, mtimeMs, size, read };
@@ -374,7 +374,7 @@ export function findPortMemory(config, facts) {
374
374
  }
375
375
  /**
376
376
  * 取这块板子的历史参数。
377
- * 记忆只是「基准」:调用方显式给的参数永远覆盖它,缺省的字段才落到历史值上。
377
+ * 记忆仅作「基准」:调用方显式给出的参数始终优先,缺省字段才取历史值。
378
378
  */
379
379
  export function recallPortSettings(facts, env = process.env) {
380
380
  const read = readSerialConfig(env);
@@ -393,7 +393,7 @@ export function recallPortSettings(facts, env = process.env) {
393
393
  };
394
394
  }
395
395
  /**
396
- * 打开成功后记一笔:按身份 upsert,其余条目原样保留(别人的板子不能被我们的打开挤掉)。
396
+ * 打开成功后记一笔:按身份 upsert,其余条目原样保留(其他设备的条目不受本插件打开操作影响)。
397
397
  * 只记「这次真的通了」的参数——失败时调用方不该写,否则下次 recover 会复用一个错参数。
398
398
  */
399
399
  export function rememberPort(facts, settings, env = process.env) {
@@ -2,7 +2,7 @@
2
2
  * L1:STM32F1 型号 → 芯片事实(容量档 / 启动文件 / 设备宏 / 设备头 / Flash / RAM / 引脚数)。
3
3
  *
4
4
  * 这里只剩**解析逻辑**,没有事实:事实全部来自内置资源里的 device/f1/chips.json,
5
- * 经 src/data/device-facts.ts 读入(用户 2026-10-31「内置表删了吧」的决定)。
5
+ * 经 src/data/device-facts.ts 读入(用户 2026-10-31 决定删除内置表)。
6
6
  * 所以本文件不再有 F1_LINES / GROUP_BY_LETTER / FLASH_BY_LETTER / RAM_BY_LINE_LETTER
7
7
  * 这类表——加一款芯片只改 scripts/assets/ 的 scripts/build-assets.mjs,插件一个字都不用动。
8
8
  *
package/lib/data/svd.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * L1:SVD 寄存器表(device/f1/svd/<line>.json)——按名字找寄存器、按值解释位域。
3
3
  *
4
4
  * 为什么要这一层:regs_read 以前只认裸地址(0x4001100C),用户手里拿的是手册里的
5
- * "GPIOC_ODR" / "GPIOC.ODR",读回来的 0x00000004 也没人告诉你那是 ODR2(PC2 输出高)。
5
+ * "GPIOC_ODR" / "GPIOC.ODR",读回的 0x00000004 无法指示其为 ODR2(PC2 输出高)。
6
6
  * SVD 里这些都有:外设 baseAddress + 寄存器 addressOffset + 字段 bitOffset/bitWidth。
7
7
  *
8
8
  * 数据来源只有一个:内置资源 插件内置 assets/ 的 device/f1/svd/<line>.json,装到
@@ -12,7 +12,7 @@
12
12
  * · 直接检出/自定义布局:<root>/device/f1/svd/103.json(开发时把 DSH_STM32_ASSETS 指到资源脚本 scripts/assets/)。
13
13
  *
14
14
  * 关键约定:
15
- * · SVD 只在 profile=full 里。缺了不是"静默降级",而是结构化失败 + 一句能照着敲的
15
+ * · SVD 只在 profile=full 里。缺了不是"静默降级",而是结构化失败 + 可直接照做的提示
16
16
  * "随插件内置(profile=full 也随包安装)"(见 SVD_FULL_PROFILE_HINT);
17
17
  * · 读不到不抛:loadSvd() 返回 { device, failure },loadSvdForLine() 复用前者的便捷版(返回 null);
18
18
  * 只有"明确要一个寄存器/一段地址"的 API(resolveRegisterRef / describeAddress)才抛 SvdError,
@@ -71,7 +71,7 @@ function isDirectory(dir) {
71
71
  }
72
72
  /**
73
73
  * SVD 里的数值:内置资源写的是十六进制字符串("0x40011000" / "0x0C"),
74
- * 也接受数字与纯十进制字符串,别的都算坏数据。
74
+ * 也接受数字与纯十进制字符串,其他形式均视为坏数据。
75
75
  */
76
76
  export function parseSvdNumber(value) {
77
77
  if (typeof value === "number")
@@ -139,7 +139,7 @@ function listNames(names, limit = 24) {
139
139
  }
140
140
  const svdCache = new Map();
141
141
  const svdStats = { reads: 0, hits: 0 };
142
- /** 缓存诊断:单测用它证明"第二次没再读盘"(reads 不涨、hits 涨)。 */
142
+ /** 缓存诊断:单测据此证明「第二次未再读盘」(reads 不增加、hits 增加)。 */
143
143
  export function svdCacheStats() {
144
144
  return { reads: svdStats.reads, hits: svdStats.hits, entries: svdCache.size };
145
145
  }
@@ -194,7 +194,7 @@ function fieldFrom(value, where) {
194
194
  return { field: { name, bitOffset, bitWidth, description: textOf(value["description"]) }, error: "" };
195
195
  }
196
196
  /**
197
- * 解析一份 SVD 文本。纯函数:测试可以直接喂字符串,不走磁盘。
197
+ * 解析一份 SVD 文本。纯函数:测试可直接传入字符串,不访问磁盘。
198
198
  * 任何一条外设/寄存器/字段不合法都返回 error(宁缺勿错,见文件头)。
199
199
  */
200
200
  export function parseSvd(text, filePath = "", version = "", expectedLine = "") {
@@ -465,7 +465,7 @@ function locateAddress(device, address) {
465
465
  const exact = device.byAddress.get(address);
466
466
  if (exact !== undefined)
467
467
  return exact;
468
- // flat 已按地址升序:找到最后一条起点 <= address 的,看它是否覆盖该地址。
468
+ // flat 已按地址升序:找到最后一条起点 <= address 的记录,判断其是否覆盖该地址。
469
469
  let low = 0;
470
470
  let high = device.flat.length - 1;
471
471
  let candidate = null;
@@ -505,7 +505,7 @@ export function resolveRegisterRef(ref, line, env = process.env) {
505
505
  return resolvedOf(entry);
506
506
  const inside = locateAddress(device, address);
507
507
  if (inside !== null) {
508
- throw new SvdError("register-unknown", formatAddress(address) + " 不是寄存器起点:它落在 " + inside.peripheral.name + "." + inside.register.name +
508
+ throw new SvdError("register-unknown", formatAddress(address) + " 不是寄存器起点:该地址落在 " + inside.peripheral.name + "." + inside.register.name +
509
509
  "(起点 " + formatAddress(inside.address) + ",位宽 " + String(inside.register.size) + " 位)内部。", { line: device.line, ref: text });
510
510
  }
511
511
  throw new SvdError("address-unknown", "line=" + device.line + " 的 SVD 里没有寄存器覆盖地址 " + formatAddress(address) + "(按裸地址读仍然可以,只是没有名字/位域)。", { line: device.line, ref: text });
@@ -1,12 +1,12 @@
1
1
  /**
2
2
  * 用户级工具链配置:插件自己记住"这台机器把工具装在哪"。
3
3
  *
4
- * 为什么要有它:以前只认三个写死的候选目录 + 两个环境变量,用户把 MSYS2 装在
4
+ * 为什么需要这一层:此前只识别三个写死的候选目录 + 两个环境变量,用户将 MSYS2 安装在
5
5
  * E:/msys64 时,每次都得自己去设 STM32_BIN_DIRS,还得重开 DSH 才生效。这里把
6
6
  * 路径落到一个纯文本 JSON 里,插件每次自己读——装完立刻能用,与进程环境变量无关。
7
7
  *
8
8
  * 位置:%USERPROFILE%/.dsh-stm32/config.json;DSH_STM32_CONFIG 可整体改指到别处
9
- * (单测与多工程隔离用)。DSH_STM32_NO_CONFIG=1 让所有读配置的地方当它不存在。
9
+ * (单测与多工程隔离用)。DSH_STM32_NO_CONFIG=1 使所有读取配置的代码按未配置处理。
10
10
  *
11
11
  * 文件是可选增强,不是前提:读不到、写坏了都只是"没配置",不抛异常给调用方。
12
12
  */
@@ -152,7 +152,7 @@ export function readToolchainConfig(env = process.env) {
152
152
  path,
153
153
  exists: true,
154
154
  config: null,
155
- errors: ["配置文件不是合法 JSON:" + describeError(error) + ";已按未配置处理(重新写入会覆盖它)"],
155
+ errors: ["配置文件不是合法 JSON:" + describeError(error) + ";已按未配置处理(重新写入将覆盖该值)"],
156
156
  mtimeMs,
157
157
  };
158
158
  cache = { path, mtimeMs, size, read };
@@ -0,0 +1,123 @@
1
+ /**
2
+ * 产物与内存:读构建目录里的 elf / hex / bin,配上芯片的 Flash / RAM 容量,供调试台显示。
3
+ *
4
+ * 只读文件属性,不跑 size / objdump:内存占用来自上一次 `stm32_build` 的
5
+ * `--print-memory-usage` 结果(面板从事件流里取),避免为了一个数字再起一个子进程。
6
+ */
7
+ import { createHash } from "node:crypto";
8
+ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
9
+ import { basename, join } from "node:path";
10
+ import { findChipFact } from "../data/device-facts.js";
11
+ import { detectBuildDir, findElf } from "./build.js";
12
+ import { readIocCpn } from "./breakpoints.js";
13
+ function statFile(file) {
14
+ try {
15
+ const info = statSync(file);
16
+ return { name: basename(file), path: file, size: info.size, mtimeMs: info.mtimeMs, sha256: "" };
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ }
22
+ /** 给一个产物补上校验和;超过上限的文件保持空串,调用方据此提示(S62)。 */
23
+ function withHash(file) {
24
+ if (file === null)
25
+ return null;
26
+ return { ...file, sha256: hashFile(file) };
27
+ }
28
+ /** 与 elf 同名、扩展名不同的兄弟产物。 */
29
+ function sibling(elfPath, extension) {
30
+ const dot = elfPath.lastIndexOf(".");
31
+ const base = dot === -1 ? elfPath : elfPath.slice(0, dot);
32
+ return statFile(base + extension);
33
+ }
34
+ /** 超过这个大小的 elf 不算校验和:调试台每 10 秒轮询一次,不值得。 */
35
+ export const ARTIFACT_HASH_MAX_BYTES = 8 * 1024 * 1024;
36
+ /** 单个文件的 SHA-256(S68):构建摘要用它标出「这次 elf 和上次是不是同一个」。 */
37
+ export function sha256OfPath(filePath) {
38
+ const file = statFile(filePath);
39
+ return file === null ? "" : hashFile(file);
40
+ }
41
+ function hashFile(file) {
42
+ if (file.size > ARTIFACT_HASH_MAX_BYTES)
43
+ return "";
44
+ try {
45
+ return createHash("sha256").update(readFileSync(file.path)).digest("hex");
46
+ }
47
+ catch {
48
+ return "";
49
+ }
50
+ }
51
+ function listElves(buildDir) {
52
+ let names;
53
+ try {
54
+ names = readdirSync(buildDir);
55
+ }
56
+ catch {
57
+ return [];
58
+ }
59
+ const files = [];
60
+ for (const name of names) {
61
+ if (!name.toLowerCase().endsWith(".elf"))
62
+ continue;
63
+ const file = statFile(join(buildDir, name));
64
+ if (file !== null)
65
+ files.push(file);
66
+ }
67
+ return files;
68
+ }
69
+ export function readArtifacts(projectDir, env = process.env) {
70
+ const dir = projectDir.trim();
71
+ if (dir === "")
72
+ return { ok: false, error: "projectDir 不能为空" };
73
+ const notes = [];
74
+ const buildDir = detectBuildDir(dir) ?? "";
75
+ if (buildDir === "") {
76
+ notes.push("还没有可识别的构建目录:先执行 stm32_build 或 cmake --preset。");
77
+ }
78
+ let elfInfo = null;
79
+ if (buildDir !== "")
80
+ elfInfo = findElf(buildDir);
81
+ const elf = withHash(elfInfo === null ? null : statFile(elfInfo.path));
82
+ const hex = withHash(elf === null ? null : sibling(elf.path, ".hex"));
83
+ const bin = withHash(elf === null ? null : sibling(elf.path, ".bin"));
84
+ const otherElves = buildDir === "" ? [] : listElves(buildDir).filter((file) => file.path !== elf?.path);
85
+ if (otherElves.length > 0) {
86
+ notes.push("构建目录里有 " + String(otherElves.length + 1) + " 个 .elf,当前显示按工程名/修改时间挑出的那个。");
87
+ }
88
+ const sha256 = elf?.sha256 ?? "";
89
+ if (elf !== null && sha256 === "") {
90
+ notes.push("elf 超过 " + String(Math.round(ARTIFACT_HASH_MAX_BYTES / 1024 / 1024)) + " MB,跳过校验和。");
91
+ }
92
+ const cpn = readIocCpn(dir);
93
+ let chip = null;
94
+ if (cpn !== "") {
95
+ const fact = findChipFact(cpn, env);
96
+ if (fact === null)
97
+ notes.push("资源包里没有 " + cpn + " 的容量数据,内存占用只能看构建输出。");
98
+ else
99
+ chip = { cpn, flashBytes: fact.flashBytes, ramBytes: fact.ramBytes };
100
+ }
101
+ else {
102
+ notes.push("工程里没有 .ioc 的 Mcu.CPN,无法给出容量上限。");
103
+ }
104
+ return {
105
+ ok: true,
106
+ report: {
107
+ projectDir: dir,
108
+ buildDir,
109
+ elf,
110
+ hex,
111
+ bin,
112
+ otherElves,
113
+ chip,
114
+ sha256,
115
+ notes,
116
+ },
117
+ };
118
+ }
119
+ /** 构建目录存在但还没有产物的判断,供面板给出下一步。 */
120
+ export function hasBuildDir(projectDir) {
121
+ const dir = detectBuildDir(projectDir);
122
+ return dir !== null && existsSync(dir);
123
+ }
@@ -20,13 +20,13 @@ import fs from "node:fs";
20
20
  import path from "node:path";
21
21
  import { fileURLToPath } from "node:url";
22
22
  export const ASSETS_MANIFEST_FILE = "manifest.json";
23
- /** 老版本安装布局的标记文件(flat 内置资源没有它)。 */
23
+ /** 老版本安装布局的标记文件(flat 内置资源不含该文件)。 */
24
24
  export const ASSETS_INSTALL_FILE = "install.json";
25
25
  /** 设备事实在资源根里的相对路径(插件唯一的芯片事实来源)。 */
26
26
  export const ASSETS_DEVICE_FACTS_FILE = "device/f1/chips.json";
27
- /** 缺资源时对用户说的那句话(工具卡片、错误、note 都复用它,避免各写一套)。 */
27
+ /** 缺资源时面向用户的固定提示(工具卡片、错误与 note 共用该文案,避免各处重复编写)。 */
28
28
  export const ASSETS_REFRESH_HINT = "资源随插件内置(assets/):缺文件说明插件安装不完整,重装插件后重试;stm32_assets verify 可定位缺了哪些";
29
- /** 只给 core / full;空串按 core 处理,别的值返回 null(由调用方给可读报错,不瞎猜)。 */
29
+ /** 仅接受 core / full;空串按 core 处理,其他值返回 null(由调用方给出可读报错,不做猜测)。 */
30
30
  export function normalizeProfile(value) {
31
31
  const text = (value ?? "core").trim().toLowerCase();
32
32
  if (text === "")
@@ -171,7 +171,7 @@ export function normalizeAssetPath(raw) {
171
171
  return null;
172
172
  return parts.join("/");
173
173
  }
174
- /** glob → 正则:** 跨目录,* 不跨目录,? 单字符。manifest 的 profiles 就靠它筛文件。 */
174
+ /** glob → 正则:** 跨目录,* 不跨目录,? 匹配单字符。manifest 的 profiles 依赖该规则筛选文件。 */
175
175
  function globToRegExp(pattern) {
176
176
  let out = "^";
177
177
  let index = 0;
@@ -528,7 +528,7 @@ export function resolveAssetFile(profile, relPath, env = process.env) {
528
528
  return empty("资源清单里没有这个文件:" + normalized + "(action=list 看这一版有哪些文件)");
529
529
  const allowed = profileFiles(state.manifest, normalizedProfile).some((file) => file.path === normalized);
530
530
  if (!allowed) {
531
- return empty("文件 " + normalized + " 不在 profile=" + normalizedProfile + " 里(它属于 profile=" + entry.profile + ");用 profile=full 查一次。");
531
+ return empty("文件 " + normalized + " 不在 profile=" + normalizedProfile + " 里(该项属于 profile=" + entry.profile + ");用 profile=full 查一次。");
532
532
  }
533
533
  const localPath = path.join(state.versionDir, normalized);
534
534
  try {
@@ -0,0 +1,73 @@
1
+ /**
2
+ * 断点命中记录:从 gdb 的输出里认出「停在哪」,攒成一份可回看的短历史。
3
+ *
4
+ * 只解析文本,不订阅 MI 事件——eval 的两条路径(常驻 MI / gdb -batch)都产出同一种
5
+ * 停点描述,在这里统一处理,面板与命令行看到的是同一份记录。
6
+ */
7
+ /** 历史长度:一次联调最多回看这么多条停点。 */
8
+ export const HIT_LIMIT = 50;
9
+ const BREAKPOINT_LINE = /^Breakpoint (\d+), (.+)$/u;
10
+ const WATCHPOINT_LINE = /^(?:Hardware |Software |)watchpoint (\d+): (.+)$/u;
11
+ const STOPPED_LINE = /已停下 —— (.+)$/u;
12
+ const OLD_VALUE = /^Old value = (.+)$/u;
13
+ const NEW_VALUE = /^New value = (.+)$/u;
14
+ /** 从一段 gdb 输出里抽出停点;不认识的行走掉。 */
15
+ export function parseStops(output) {
16
+ const stops = [];
17
+ const lines = output.split(/\r?\n/u);
18
+ for (let index = 0; index < lines.length; index += 1) {
19
+ const line = (lines[index] ?? "").trim();
20
+ if (line === "")
21
+ continue;
22
+ const plain = BREAKPOINT_LINE.exec(line);
23
+ if (plain !== null && plain[1] !== undefined && plain[2] !== undefined) {
24
+ stops.push({ id: Number(plain[1]), text: plain[2].trim() });
25
+ continue;
26
+ }
27
+ const watched = WATCHPOINT_LINE.exec(line);
28
+ if (watched !== null && watched[1] !== undefined && watched[2] !== undefined) {
29
+ // 观察点命中后紧跟两行旧值/新值,拼进同一条更有用。
30
+ const parts = [watched[2].trim()];
31
+ const old = OLD_VALUE.exec((lines[index + 1] ?? "").trim());
32
+ const fresh = NEW_VALUE.exec((lines[index + 2] ?? "").trim());
33
+ if (old !== null && old[1] !== undefined)
34
+ parts.push("原值 " + old[1]);
35
+ if (fresh !== null && fresh[1] !== undefined)
36
+ parts.push("新值 " + fresh[1]);
37
+ stops.push({ id: Number(watched[1]), text: parts.join(",") });
38
+ continue;
39
+ }
40
+ const stopped = STOPPED_LINE.exec(line);
41
+ if (stopped !== null && stopped[1] !== undefined) {
42
+ const detail = stopped[1].replace(/(本次 eval 结束会按默认再 resume.*$/u, "").trim();
43
+ if (detail !== "")
44
+ stops.push({ id: 0, text: detail });
45
+ }
46
+ }
47
+ return stops;
48
+ }
49
+ /** 环形历史:满了丢最旧的一条。 */
50
+ export class HitHistory {
51
+ items = [];
52
+ limit;
53
+ constructor(limit = HIT_LIMIT) {
54
+ this.limit = Math.max(1, Math.trunc(limit));
55
+ }
56
+ /** 把一段输出的停点追加进历史,返回本次新增条数。 */
57
+ record(output, nowMs = Date.now()) {
58
+ const stops = parseStops(output);
59
+ const time = new Date(nowMs).toISOString();
60
+ for (const stop of stops) {
61
+ this.items.push({ id: stop.id, text: stop.text, time: time });
62
+ if (this.items.length > this.limit)
63
+ this.items.splice(0, this.items.length - this.limit);
64
+ }
65
+ return stops.length;
66
+ }
67
+ list() {
68
+ return this.items.map((item) => ({ ...item }));
69
+ }
70
+ clear() {
71
+ this.items.length = 0;
72
+ }
73
+ }
@@ -10,7 +10,7 @@
10
10
  * 预算来源(优先级从高到低):
11
11
  * 1. 内置资源 chips.json 里给这颗芯片写的 breakpoints / watchpoints;
12
12
  * 2. 按内核的硬件上限(data/family.ts 的 debugBudgetForCore):M0/M0+ 4/2、M3/M4 6/4、M7/M33/M55 8/4;
13
- * 3. 都没有(没有 .ioc / 认不出族)→ F1 实测值 6 / 4,并在 note 里说清是兜底。
13
+ * 3. 均无(没有 .ioc / 无法识别族)→ F1 实测值 6 / 4,并在 note 中说明属回退值。
14
14
  *
15
15
  * 为什么不按族写死:比较器个数是**内核**属性(FPB/DWT),同族不同内核会对不上;
16
16
  * 按内核算一次就对,也能覆盖 MPU 之外的所有 STM32。
@@ -73,7 +73,7 @@ export function readIocCpn(projectDir) {
73
73
  /**
74
74
  * `.ioc` 里的 `Mcu.Name`(db 分组名,例如 STM32F103C(8-B)Tx);读不到返回空串。
75
75
  *
76
- * 用它去查本机 CubeMX db 的 `<Core>`:族画像里的 core 是"手写兜底",db 才是逐型号的真源
76
+ * 以该名称查询本机 CubeMX db 的 `<Core>`:族画像中的 core 为手工回退值,db 才是逐型号的权威来源
77
77
  * (同一族里 MPU/双核/单核写法不同,见 cubemx-db.ts 里 CubemxMcuFacts.core 的注释)。
78
78
  */
79
79
  function readIocMcuName(projectDir) {
@@ -123,7 +123,7 @@ export function resolveBreakpointBudget(projectDir, env = process.env) {
123
123
  budget: coreBudget,
124
124
  source: "core",
125
125
  chip: cpn,
126
- note: "断点预算按内核 " + coreText + "(" + (coreSource === "db" ? "本机 CubeMX db 的 <Core>" : "族画像兜底") + ")的硬件上限:"
126
+ note: "断点预算按内核 " + coreText + "(" + (coreSource === "db" ? "本机 CubeMX db 的 <Core>" : "族画像回退值") + ")的硬件上限:"
127
127
  + String(coreBudget.code) + " 个硬件断点 / " + String(coreBudget.data) + " 个观察点(" + why + ")",
128
128
  };
129
129
  };
@@ -232,7 +232,7 @@ export function collectBreakpointRequests(input) {
232
232
  }
233
233
  return { requested, notes };
234
234
  }
235
- /** 超预算时的一句话(放进 errors[0],用户最先看到的就是它)。 */
235
+ /** 超预算时的提示语(放入 errors[0],用户首先看到该条)。 */
236
236
  function overflowDetail(codeAsked, dataAsked, budget, overCode, overData) {
237
237
  const parts = [];
238
238
  if (overCode > 0)
@@ -246,7 +246,7 @@ function overflowDetail(codeAsked, dataAsked, budget, overCode, overData) {
246
246
  function overflowSuggestion(budget, overCode, overData) {
247
247
  const parts = [];
248
248
  if (overCode > 0) {
249
- parts.push("删掉多出来的 " + String(overCode) + " 个 break:硬件断点占 FPB 比较器,第 " + String(budget.code + 1) + " 个 gdb 只会报 Cannot insert breakpoint 并把整次调试带崩;要连着停几个点就改用 tbreak(命中即删),或者先 break 一个、到点再换下一个");
249
+ parts.push("删除多余的 " + String(overCode) + " 个 break:硬件断点占用 FPB 比较器,第 " + String(budget.code + 1) + " 个 gdb 只会报 Cannot insert breakpoint 并导致整次调试失败;需要连续停在多个位置时改用 tbreak(命中即删),或先设一个 break,到达后再改为下一个");
250
250
  }
251
251
  if (overData > 0) {
252
252
  parts.push("观察点同理:DWT 只有 " + String(budget.data) + " 个数据比较器,超出的改成一次 watch 一个、或用 print / x 轮询变量");
@@ -7,7 +7,9 @@
7
7
  */
8
8
  import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
9
9
  import { join, resolve } from "node:path";
10
+ import { findChipFact } from "../data/device-facts.js";
10
11
  import { resolveSearchConfig } from "../data/search-roots.js";
12
+ import { readIocCpn } from "./breakpoints.js";
11
13
  import { runCapture, runStreaming } from "./subprocess-runner.js";
12
14
  import { resolveToolIn } from "./probe.js";
13
15
  import { envWithBinDirs } from "./tool-env.js";
@@ -35,6 +37,64 @@ export function parseMemoryUsage(text) {
35
37
  }
36
38
  return usages;
37
39
  }
40
+ /**
41
+ * `arm-none-eabi-size` 的 berkeley 行:`text data bss dec hex filename`(S80)。
42
+ * 用于增量构建没链接、链接器没打印占用时,直接量一次已存在的 elf。
43
+ */
44
+ export function parseBerkeleySize(text) {
45
+ for (const line of text.split(/\r?\n/u)) {
46
+ const parts = line.trim().split(/\s+/u);
47
+ if (parts.length < 5)
48
+ continue;
49
+ const [textBytes, dataBytes, bssBytes] = parts.slice(0, 3).map((item) => Number.parseInt(item, 10));
50
+ if (!Number.isFinite(textBytes) || !Number.isFinite(dataBytes) || !Number.isFinite(bssBytes))
51
+ continue;
52
+ return { text: textBytes, data: dataBytes, bss: bssBytes };
53
+ }
54
+ return null;
55
+ }
56
+ /**
57
+ * 增量构建的占用兜底(S80):没有链接输出时,用同一套工具链的 size 量 elf。
58
+ *
59
+ * 只在「构建成功 + 有 elf + 日志里没有占用」时才跑;总量来自器件事实(同样只在有 .ioc 时才有)。
60
+ */
61
+ async function measureElfUsage(subprocess, elfPath, binDirs, projectDir, signal) {
62
+ try {
63
+ const size = await resolveToolIn(subprocess, ["arm-none-eabi-size"], [...binDirs], signal);
64
+ if (size === null)
65
+ return [];
66
+ const captured = await runCapture(subprocess, {
67
+ argv: [size, elfPath],
68
+ cwd: projectDir,
69
+ env: envWithBinDirs([...binDirs]),
70
+ ...(signal === undefined ? {} : { signal }),
71
+ });
72
+ if (captured.exitCode !== 0)
73
+ return [];
74
+ const parsed = parseBerkeleySize(captured.stdout);
75
+ if (parsed === null)
76
+ return [];
77
+ const chip = findChipFact(readIocCpn(projectDir));
78
+ const out = [];
79
+ const add = (region, usedBytes, totalBytes) => {
80
+ if (totalBytes === null || totalBytes <= 0)
81
+ return;
82
+ out.push({
83
+ region,
84
+ usedBytes,
85
+ totalBytes,
86
+ percent: Math.round((usedBytes / totalBytes) * 1000) / 10,
87
+ raw: region + ": " + String(usedBytes) + " B / " + String(totalBytes) + " B",
88
+ });
89
+ };
90
+ add("FLASH", parsed.text + parsed.data, chip?.flashBytes ?? null);
91
+ add("RAM", parsed.data + parsed.bss, chip?.ramBytes ?? null);
92
+ return out;
93
+ }
94
+ catch {
95
+ return [];
96
+ }
97
+ }
38
98
  /** 从编译器/链接器输出里挑出错误行;重复行去重(同一头文件可能被多个 translation unit 报一次)。 */
39
99
  export function parseBuildErrors(text) {
40
100
  const errors = [];
@@ -342,8 +402,13 @@ export async function runBuild(subprocess, request) {
342
402
  const durationMs = Date.now() - startedAt;
343
403
  const log = outcome.stdout + "\n" + outcome.stderr;
344
404
  const errors = parseBuildErrors(log);
345
- const memoryUsage = parseMemoryUsage(log);
405
+ const logMemory = parseMemoryUsage(log);
346
406
  const elf = findElf(buildDir);
407
+ /* 增量构建不重新链接,链接器不会打印占用;用 size 现量一次(S80)。 */
408
+ const memoryUsage = logMemory.length === 0 && elf !== null && outcome.exitCode === 0
409
+ ? await measureElfUsage(subprocess, elf.path, config.binDirs, projectDir, request.signal)
410
+ : logMemory;
411
+ const measured = logMemory.length === 0 && memoryUsage.length > 0;
347
412
  const base = {
348
413
  projectDir,
349
414
  buildDir,
@@ -363,10 +428,15 @@ export async function runBuild(subprocess, request) {
363
428
  if (selectionNote !== "")
364
429
  notes.push(selectionNote);
365
430
  }
366
- if (memoryUsage.length > 0)
431
+ if (memoryUsage.length > 0) {
367
432
  notes.push("占用:" + memoryUsage.map((item) => item.region + " " + String(item.percent) + "%").join(","));
368
- else if (elf !== null)
433
+ // 占用不是链接器给的,就得说明来源,否则读者会以为这次真的链接了(S80)。
434
+ if (measured)
435
+ notes.push("本次没有重新链接;占用由 arm-none-eabi-size 直接量 elf 得到");
436
+ }
437
+ else if (elf !== null) {
369
438
  notes.push("本次是增量构建,没有重新链接,因此没有内存占用数据(需要时用 clean 构建)");
439
+ }
370
440
  if (outcome.spawnError !== null) {
371
441
  return fail(request, "cmake 启动失败:" + outcome.spawnError, { ...base, errors: [outcome.spawnError] });
372
442
  }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * 下载缓存("可检索的缓存目录")。
3
3
  *
4
- * 为什么要有它:寄存器版模板、未来的各类模板与工具链产物都不能预置进插件(用户 2026-10-24 决定:
4
+ * 设计原因:寄存器版模板、后续各类模板与工具链产物都不能预置进插件(用户 2026-10-24 决定:
5
5
  * 插件要能覆盖任意 STM32,不可能每颗芯片都打一份进 npm 包)。做法是第一次用时从网上下载,
6
6
  * 落到一个**可检索**的本地缓存目录,之后一律复用——所以缓存必须自带一份 index.json:
7
7
  * 谁、哪一代、从哪个 URL 下的、多大、什么时候下的,都要能直接读出来,而不是靠猜目录里有什么。
@@ -67,7 +67,7 @@ export function readCacheIndex(env = process.env) {
67
67
  };
68
68
  }
69
69
  catch (error) {
70
- return { index: emptyCacheIndex(), error: "缓存索引读不了(" + info.indexPath + "):" + errorText(error) + ";当作空索引,重新下载会覆盖它。", path: info.indexPath };
70
+ return { index: emptyCacheIndex(), error: "缓存索引读不了(" + info.indexPath + "):" + errorText(error) + ";当作空索引,重新下载会覆盖该索引。", path: info.indexPath };
71
71
  }
72
72
  }
73
73
  function isCacheEntry(value) {
@@ -78,7 +78,7 @@ function isCacheEntry(value) {
78
78
  }
79
79
  /**
80
80
  * 写索引失败(可识别、带路径)。单独一个类型是为了让调用方把「索引没写成」和
81
- * 「网络挂了」分开,并且能依赖一条硬承诺:抛错时旧索引逐字节没动。
81
+ * 「网络故障」分开,并且可依赖一条硬承诺:抛错时旧索引逐字节未变。
82
82
  */
83
83
  export class CacheIndexWriteError extends Error {
84
84
  indexPath;
@@ -121,7 +121,7 @@ function safeRemove(remove, file) {
121
121
  }
122
122
  /**
123
123
  * 索引读不出来时先留一份 index.json.broken-<ts> 再重建:
124
- * 坏文件里其它条目还有人工救回来的价值,直接覆盖等于把它们一起抹掉。
124
+ * 损坏文件中其余条目仍有手工恢复的价值,直接覆盖会将其一并清除。
125
125
  */
126
126
  function preserveBrokenIndex(indexPath, reason) {
127
127
  const backup = freeBackupPath(indexPath, "broken");