dsh-stm32 0.1.3 → 0.1.4

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 (221) hide show
  1. package/README.md +52 -38
  2. package/README_EN.md +44 -33
  3. package/assets/README.md +85 -0
  4. package/assets/VERSION +1 -0
  5. package/assets/device/c0/chips.json +1108 -0
  6. package/assets/device/f0/chips.json +1570 -0
  7. package/assets/device/f1/chips.json +1238 -0
  8. package/assets/device/f1/svd/100.json +943 -0
  9. package/assets/device/f1/svd/101.json +901 -0
  10. package/assets/device/f1/svd/102.json +522 -0
  11. package/assets/device/f1/svd/103.json +1139 -0
  12. package/assets/device/f1/svd/105.json +1117 -0
  13. package/assets/device/f1/svd/107.json +1195 -0
  14. package/assets/device/f2/chips.json +674 -0
  15. package/assets/device/f3/chips.json +1318 -0
  16. package/assets/device/f4/chips.json +2942 -0
  17. package/assets/device/f7/chips.json +1710 -0
  18. package/assets/device/g0/chips.json +2102 -0
  19. package/assets/device/g4/chips.json +2494 -0
  20. package/assets/device/h5/chips.json +898 -0
  21. package/assets/device/h7/chips.json +1948 -0
  22. package/assets/device/l0/chips.json +2494 -0
  23. package/assets/device/l1/chips.json +1234 -0
  24. package/assets/device/l4/chips.json +2130 -0
  25. package/assets/device/l4+/chips.json +856 -0
  26. package/assets/device/l5/chips.json +226 -0
  27. package/assets/device/u0/chips.json +688 -0
  28. package/assets/device/u3/chips.json +310 -0
  29. package/assets/device/u5/chips.json +884 -0
  30. package/assets/device/wba/chips.json +506 -0
  31. package/assets/device/wl/chips.json +184 -0
  32. package/assets/headers/f1/stm32f100xb.h +5972 -0
  33. package/assets/headers/f1/stm32f100xe.h +6587 -0
  34. package/assets/headers/f1/stm32f101x6.h +5315 -0
  35. package/assets/headers/f1/stm32f101xb.h +5446 -0
  36. package/assets/headers/f1/stm32f101xe.h +6503 -0
  37. package/assets/headers/f1/stm32f101xg.h +6713 -0
  38. package/assets/headers/f1/stm32f102x6.h +6448 -0
  39. package/assets/headers/f1/stm32f102xb.h +6570 -0
  40. package/assets/headers/f1/stm32f103x6.h +10109 -0
  41. package/assets/headers/f1/stm32f103xb.h +10240 -0
  42. package/assets/headers/f1/stm32f103xe.h +11767 -0
  43. package/assets/headers/f1/stm32f103xg.h +11951 -0
  44. package/assets/headers/f1/stm32f105xc.h +14340 -0
  45. package/assets/headers/f1/stm32f107xc.h +15253 -0
  46. package/assets/headers/f1/stm32f1xx.h +273 -0
  47. package/assets/headers/f1/system_stm32f1xx.h +96 -0
  48. package/assets/ioc/family/C0.ioc +82 -0
  49. package/assets/ioc/family/F0.ioc +71 -0
  50. package/assets/ioc/family/F2.ioc +91 -0
  51. package/assets/ioc/family/F3.ioc +94 -0
  52. package/assets/ioc/family/F4.ioc +91 -0
  53. package/assets/ioc/family/F7.ioc +102 -0
  54. package/assets/ioc/family/G0.ioc +90 -0
  55. package/assets/ioc/family/G4.ioc +110 -0
  56. package/assets/ioc/family/H5.ioc +116 -0
  57. package/assets/ioc/family/H7.ioc +133 -0
  58. package/assets/ioc/family/L0.ioc +92 -0
  59. package/assets/ioc/family/L1.ioc +87 -0
  60. package/assets/ioc/family/L4+.ioc +92 -0
  61. package/assets/ioc/family/L4.ioc +93 -0
  62. package/assets/ioc/family/L5.ioc +91 -0
  63. package/assets/ioc/family/U0.ioc +103 -0
  64. package/assets/ioc/family/U3.ioc +113 -0
  65. package/assets/ioc/family/U5.ioc +102 -0
  66. package/assets/ioc/family/WBA.ioc +100 -0
  67. package/assets/ioc/family/WL.ioc +93 -0
  68. package/assets/ioc/minimal/STM32F100C8Tx.ioc +113 -0
  69. package/assets/ioc/minimal/STM32F100RCTx.ioc +113 -0
  70. package/assets/ioc/minimal/STM32F101C4Tx.ioc +113 -0
  71. package/assets/ioc/minimal/STM32F101C8Tx.ioc +113 -0
  72. package/assets/ioc/minimal/STM32F101RCTx.ioc +113 -0
  73. package/assets/ioc/minimal/STM32F101RFTx.ioc +113 -0
  74. package/assets/ioc/minimal/STM32F102C4Tx.ioc +113 -0
  75. package/assets/ioc/minimal/STM32F102C8Tx.ioc +113 -0
  76. package/assets/ioc/minimal/STM32F103C4Tx.ioc +113 -0
  77. package/assets/ioc/minimal/STM32F103C8Tx.ioc +113 -0
  78. package/assets/ioc/minimal/STM32F103RCTx.ioc +113 -0
  79. package/assets/ioc/minimal/STM32F103RFTx.ioc +113 -0
  80. package/assets/ioc/minimal/STM32F105RCTx.ioc +113 -0
  81. package/assets/ioc/minimal/STM32F107RCTx.ioc +113 -0
  82. package/assets/ld/f1/STM32F100C8Tx_FLASH.ld +249 -0
  83. package/assets/ld/f1/STM32F100RCTx_FLASH.ld +249 -0
  84. package/assets/ld/f1/STM32F101C4Tx_FLASH.ld +249 -0
  85. package/assets/ld/f1/STM32F101C8Tx_FLASH.ld +249 -0
  86. package/assets/ld/f1/STM32F101RCTx_FLASH.ld +249 -0
  87. package/assets/ld/f1/STM32F101RFTx_FLASH.ld +249 -0
  88. package/assets/ld/f1/STM32F102C4Tx_FLASH.ld +249 -0
  89. package/assets/ld/f1/STM32F102C8Tx_FLASH.ld +249 -0
  90. package/assets/ld/f1/STM32F103C4Tx_FLASH.ld +249 -0
  91. package/assets/ld/f1/STM32F103C8Tx_FLASH.ld +249 -0
  92. package/assets/ld/f1/STM32F103RCTx_FLASH.ld +249 -0
  93. package/assets/ld/f1/STM32F103RFTx_FLASH.ld +249 -0
  94. package/assets/ld/f1/STM32F105RCTx_FLASH.ld +249 -0
  95. package/assets/ld/f1/STM32F107RCTx_FLASH.ld +249 -0
  96. package/assets/manifest.json +1130 -0
  97. package/assets/startup/f1/startup_stm32f100xb.s +407 -0
  98. package/assets/startup/f1/startup_stm32f100xe.s +449 -0
  99. package/assets/startup/f1/startup_stm32f101x6.s +322 -0
  100. package/assets/startup/f1/startup_stm32f101xb.s +338 -0
  101. package/assets/startup/f1/startup_stm32f101xe.s +423 -0
  102. package/assets/startup/f1/startup_stm32f101xg.s +439 -0
  103. package/assets/startup/f1/startup_stm32f102x6.s +330 -0
  104. package/assets/startup/f1/startup_stm32f102xb.s +346 -0
  105. package/assets/startup/f1/startup_stm32f103x6.s +348 -0
  106. package/assets/startup/f1/startup_stm32f103xb.s +364 -0
  107. package/assets/startup/f1/startup_stm32f103xe.s +470 -0
  108. package/assets/startup/f1/startup_stm32f103xg.s +466 -0
  109. package/assets/startup/f1/startup_stm32f105xc.s +463 -0
  110. package/assets/startup/f1/startup_stm32f107xc.s +472 -0
  111. package/assets/templates/family/C0.ioc +82 -0
  112. package/assets/templates/family/F0.ioc +71 -0
  113. package/assets/templates/family/F2.ioc +91 -0
  114. package/assets/templates/family/F3.ioc +94 -0
  115. package/assets/templates/family/F4.ioc +91 -0
  116. package/assets/templates/family/F7.ioc +102 -0
  117. package/assets/templates/family/G0.ioc +90 -0
  118. package/assets/templates/family/G4.ioc +110 -0
  119. package/assets/templates/family/H5.ioc +116 -0
  120. package/assets/templates/family/H7.ioc +133 -0
  121. package/assets/templates/family/L0.ioc +92 -0
  122. package/assets/templates/family/L1.ioc +87 -0
  123. package/assets/templates/family/L4+.ioc +92 -0
  124. package/assets/templates/family/L4.ioc +93 -0
  125. package/assets/templates/family/L5.ioc +91 -0
  126. package/assets/templates/family/U0.ioc +103 -0
  127. package/assets/templates/family/U3.ioc +113 -0
  128. package/assets/templates/family/U5.ioc +102 -0
  129. package/assets/templates/family/WB.ioc +81 -0
  130. package/assets/templates/family/WBA.ioc +100 -0
  131. package/assets/templates/family/WL.ioc +93 -0
  132. package/docs/reading-guide.md +37 -35
  133. package/lib/data/chips.js +3 -3
  134. package/lib/data/clock-db.js +830 -0
  135. package/lib/data/clock-f1.js +12 -45
  136. package/lib/data/cmsis-sources.js +239 -18
  137. package/lib/data/db-presets.js +252 -0
  138. package/lib/data/device-facts.js +99 -26
  139. package/lib/data/family.js +515 -0
  140. package/lib/data/firmware-packages.js +562 -0
  141. package/lib/data/install-guides.js +2 -2
  142. package/lib/data/ioc-presets.js +248 -0
  143. package/lib/data/ioc-schema.js +1058 -0
  144. package/lib/data/rm-topics/stm32c0.json +227 -0
  145. package/lib/data/rm-topics.js +103 -0
  146. package/lib/data/search-roots.js +42 -1
  147. package/lib/data/stm32f1.js +15 -14
  148. package/lib/data/svd.js +32 -16
  149. package/lib/data/toolchain-config.js +0 -14
  150. package/lib/engine/assets.js +191 -456
  151. package/lib/engine/breakpoints.js +66 -11
  152. package/lib/engine/clock-derived.js +101 -0
  153. package/lib/engine/clock-direct.js +313 -0
  154. package/lib/engine/clock-plan.js +96 -52
  155. package/lib/engine/clock-pllmn.js +319 -0
  156. package/lib/engine/cmake-sources.js +67 -13
  157. package/lib/engine/cube-mx-guard.js +44 -0
  158. package/lib/engine/cube-programmer.js +137 -0
  159. package/lib/engine/cubemx-db.js +273 -0
  160. package/lib/engine/debug-session.js +423 -17
  161. package/lib/engine/debug.js +25 -6
  162. package/lib/engine/doctor.js +160 -17
  163. package/lib/engine/facts-acquire.js +416 -0
  164. package/lib/engine/facts.js +134 -0
  165. package/lib/engine/firmware-install.js +176 -5
  166. package/lib/engine/firmware-official.js +451 -0
  167. package/lib/engine/flash.js +290 -21
  168. package/lib/engine/gdb-mi.js +476 -0
  169. package/lib/engine/generate.js +9 -2
  170. package/lib/engine/hal-chip.js +124 -41
  171. package/lib/engine/ioc-plan.js +1244 -60
  172. package/lib/engine/ioc-rules.js +698 -0
  173. package/lib/engine/ioc-verify.js +706 -0
  174. package/lib/engine/ioc.js +43 -4
  175. package/lib/engine/msys2-install.js +4 -4
  176. package/lib/engine/probe-error.js +25 -6
  177. package/lib/engine/probe-session.js +50 -14
  178. package/lib/engine/probe.js +18 -3
  179. package/lib/engine/register-clock.js +41 -0
  180. package/lib/engine/register-gpio.js +115 -0
  181. package/lib/engine/register-linker.js +12 -7
  182. package/lib/engine/register-template.js +101 -40
  183. package/lib/engine/regs.js +41 -8
  184. package/lib/engine/rm-extract.js +144 -0
  185. package/lib/engine/rm-sources.js +360 -0
  186. package/lib/engine/rm-text.js +56 -0
  187. package/lib/engine/rtt.js +188 -30
  188. package/lib/engine/scaffold.js +185 -18
  189. package/lib/engine/toolchain-gate.js +0 -4
  190. package/lib/engine/watch.js +227 -0
  191. package/lib/index.js +4 -2
  192. package/lib/skill/stm32-workflow.js +2 -2
  193. package/lib/tools/assets.js +39 -108
  194. package/lib/tools/cache.js +2 -2
  195. package/lib/tools/debug-session.js +2 -2
  196. package/lib/tools/doctor.js +55 -5
  197. package/lib/tools/firmware-install.js +31 -6
  198. package/lib/tools/flash.js +32 -4
  199. package/lib/tools/generate.js +22 -0
  200. package/lib/tools/ioc-inspect.js +1 -1
  201. package/lib/tools/ioc-plan.js +56 -2
  202. package/lib/tools/ioc-verify.js +237 -0
  203. package/lib/tools/project-create.js +41 -5
  204. package/lib/tools/regs.js +8 -8
  205. package/lib/tools/route-plan.js +1 -1
  206. package/lib/tools/rtt.js +157 -34
  207. package/lib/tools/watch.js +256 -0
  208. package/package.json +5 -4
  209. package/templates/openocd/stm32c0x.cfg +83 -0
  210. package/templates/openocd/stm32u0x.cfg +64 -0
  211. package/templates/register/CMakeLists.txt +2 -2
  212. package/templates/register/Core/Inc/rtt.h +37 -2
  213. package/templates/register/Core/Src/main.c +17 -25
  214. package/templates/register/Core/Src/rtt.c +85 -9
  215. package/templates/scaffold/RTT.md +6 -2
  216. package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
  217. package/templates/scaffold/openocd.cfg +5 -3
  218. package/templates/scaffold/vscode/launch.json +8 -4
  219. package/docs/development-notes.md +0 -2487
  220. package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
  221. package/docs/logic-audit.md +0 -607
package/lib/tools/rtt.js CHANGED
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * start —— 确认目标里有控制块 → openocd rtt setup/start → 开通道 TCP 端口
5
5
  * dump —— 连上通道读一段时间的记录(可按级别过滤、按条数截断)
6
- * stop —— 断通道,让 openocd 收掉 rtt server
6
+ * stop —— 断通道,让 openocd 收掉 rtt server;start 自己起的会话一并释放(探针归还)
7
7
  * status —— 只读快照
8
8
  *
9
9
  * 设计取舍:
@@ -13,10 +13,20 @@
13
13
  */
14
14
  import { DEFAULT_DUMP_SECONDS, DEFAULT_MAX_RECORDS, DEFAULT_RTT_PORT, DEFAULT_RTT_SIZE, RTT_LEVEL_NAMES, dumpRtt, rttStatus, startRtt, stopRtt, } from "../engine/rtt.js";
15
15
  import { PROBE_ERROR_SCHEMA } from "../engine/probe-error.js";
16
- import { ensureSession, sessionInfo } from "../engine/probe-session.js";
16
+ import { isPortBusy } from "../engine/debug.js";
17
+ import { ensureSession, release, sessionInfo } from "../engine/probe-session.js";
17
18
  import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
18
19
  import { resolveProjectDir, validateToolArgs } from "./project-dir.js";
19
20
  export const RTT_TOOL = "stm32_rtt";
21
+ /**
22
+ * RTT 自己起的调试会话的 startedAt(复用的会话不记)。
23
+ *
24
+ * 为什么记这个:RTT 只用了 openocd 的 rtt 通道,而会话归 probe-session 管(空闲 90 s 才自动收)。
25
+ * 实测踩过:stop 只关通道,openocd 还握着探针,紧接着 stm32_flash 就撞 CMSIS-DAP command mismatch。
26
+ * 所以 stop 时,只要当前会话还是 start 那一次起的(startedAt 没变),就顺手 release 掉;
27
+ * 复用的会话不动(那是别人起的)。
28
+ */
29
+ let rttOwnedSessionStartedAt = null;
20
30
  const ENV_CHECK_SCHEMA = {
21
31
  type: "string",
22
32
  enum: ["block", "warn", "off"],
@@ -41,7 +51,7 @@ const SESSION_SCHEMA = {
41
51
  },
42
52
  required: ["port", "tclPort"],
43
53
  };
44
- export const outputSchema = {
54
+ export const reportSchema = {
45
55
  type: "object",
46
56
  additionalProperties: false,
47
57
  properties: {
@@ -58,6 +68,7 @@ export const outputSchema = {
58
68
  durationMs: { type: "number", description: "这次动作花了多少毫秒" },
59
69
  records: { type: "array", description: "dump 到的记录(按时间顺序)", items: RECORD_SCHEMA },
60
70
  dropped: { type: "number", description: "按 level 过滤掉的条数" },
71
+ firmwareDropped: { type: "number", description: "固件侧累计丢帧(rtt.c 里的 s_dropped,自复位起);读不到时 -1" },
61
72
  bytes: { type: "number", description: "从通道读到的字节数" },
62
73
  truncated: { type: "boolean", description: "是否因为 maxRecords 提前收尾" },
63
74
  stopped: { type: "boolean", description: "通道是否在窗口内被关掉(目标复位或 stop)" },
@@ -81,6 +92,7 @@ export const outputSchema = {
81
92
  "durationMs",
82
93
  "records",
83
94
  "dropped",
95
+ "firmwareDropped",
84
96
  "bytes",
85
97
  "truncated",
86
98
  "stopped",
@@ -90,7 +102,21 @@ export const outputSchema = {
90
102
  "notes",
91
103
  ],
92
104
  };
93
- const ACTIONS = ["start", "dump", "stop", "status"];
105
+ /** 宿主按 `{ message, report }` 校验工具返回(与其它工具一致);report 是上面这份扁平形状。
106
+ * 历史 bug:这里曾直接把扁平 report 形状当成 outputSchema 导出,宿主校验时每次都报
107
+ * "missing required property value.ok",导致 stm32_rtt 任何调用都失败。 */
108
+ export const outputSchema = {
109
+ type: "object",
110
+ additionalProperties: false,
111
+ properties: {
112
+ message: { type: "string" },
113
+ report: reportSchema,
114
+ },
115
+ required: ["message", "report"],
116
+ };
117
+ const ACTIONS = ["start", "dump", "follow", "stop", "status"];
118
+ /** follow 的默认窗口:比 dump 长得多——它存在的意义就是"整段时间都挂着读者",让环不被灌满。 */
119
+ const DEFAULT_FOLLOW_SECONDS = 10;
94
120
  function sessionWire() {
95
121
  const session = sessionInfo();
96
122
  if (session === null)
@@ -114,6 +140,7 @@ function baseReport(action, projectDir) {
114
140
  durationMs: 0,
115
141
  records: [],
116
142
  dropped: 0,
143
+ firmwareDropped: -1,
117
144
  bytes: 0,
118
145
  truncated: false,
119
146
  stopped: false,
@@ -147,7 +174,9 @@ function formatReport(report) {
147
174
  if (report.records.length > shown.length)
148
175
  lines.push(" … 还有 " + String(report.records.length - shown.length) + " 条(调大 maxRecords 或分批 dump)");
149
176
  if (report.truncated)
150
- lines.push("· 达到 maxRecords 上限,提前收尾");
177
+ lines.push(report.action === "follow" ? "· 超过 maxRecords,只保留最新 " + String(report.records.length) + " 条" : "· 达到 maxRecords 上限,提前收尾");
178
+ if (report.firmwareDropped >= 0)
179
+ lines.push("· 固件侧累计丢帧 " + String(report.firmwareDropped) + " 条(s_dropped,自复位起)");
151
180
  if (report.stopped)
152
181
  lines.push("· RTT 通道已停(目标复位或 rtt stop)");
153
182
  lines.push("· 这次读 " + String(report.bytes) + " 字节" + (report.dropped > 0 ? ",按级别过滤掉 " + String(report.dropped) + " 条" : ""));
@@ -176,18 +205,18 @@ function snapshotInto(report, snapshot) {
176
205
  export function registerRtt(ctx) {
177
206
  ctx.tools.register({
178
207
  name: RTT_TOOL,
179
- description: "RTT(Real Time Transfer):start 起 openocd 的 rtt 通道并给出 TCP 端口,dump 读一段时间的记录(级别过滤/条数截断),stop 收掉,status 看状态。",
208
+ description: "RTT(Real Time Transfer):start 起 openocd 的 rtt 通道并给出 TCP 端口,dump 读一段时间的记录(级别过滤/条数截断),follow 连续读一段(只留最新 N 条,并读固件侧 s_dropped 丢帧计数——想确认「到底丢没丢」就用它),stop 收掉通道(start 自己起的调试会话会一并释放、探针归还),status 看状态。",
180
209
  parameters: {
181
210
  type: "object",
182
211
  additionalProperties: false,
183
212
  properties: {
184
- action: { type: "string", enum: [...ACTIONS], description: "start(起 RTT)/ dump(读记录)/ stop(停)/ status(看状态)" },
213
+ action: { type: "string", enum: [...ACTIONS], description: "start(起 RTT)/ dump(读一段记录)/ follow(持续读一段,只留最新 N 条,顺带读固件侧丢帧数)/ stop(停)/ status(看状态)" },
185
214
  projectDir: { type: "string", description: "工程目录;缺省取会话工作目录" },
186
215
  addr: { type: "string", description: "RTT 控制块起始地址(十六进制,例如 0x20000000);action=start 必填" },
187
216
  size: { type: "number", description: "控制块预留字节数,默认 " + String(DEFAULT_RTT_SIZE) },
188
217
  banner: { type: "string", description: "控制块标识(openocd rtt setup 的第三个参数);一般不用填" },
189
218
  rttPort: { type: "number", description: "RTT 通道的 TCP 端口,默认 " + String(DEFAULT_RTT_PORT) },
190
- seconds: { type: "number", description: "dump 的采集窗口(秒),默认 " + String(DEFAULT_DUMP_SECONDS) + ",范围 0.2..60" },
219
+ seconds: { type: "number", description: "采集窗口(秒):dump 默认 " + String(DEFAULT_DUMP_SECONDS) + "(0.2..60),follow 默认 " + String(DEFAULT_FOLLOW_SECONDS) + "(0.2..300)" },
191
220
  level: { type: "number", description: "dump 保留到哪一级:1=error 2=warn 3=info 4=debug(默认 4,全要)" },
192
221
  maxRecords: { type: "number", description: "dump 最多返回多少条,默认 " + String(DEFAULT_MAX_RECORDS) },
193
222
  timeoutMs: { type: "number", description: "Tcl 往返 / 连通道的超时毫秒数" },
@@ -223,6 +252,80 @@ export function registerRtt(ctx) {
223
252
  if (invalid !== null)
224
253
  return failure(action, projectDir, invalid, notes);
225
254
  const binDirs = Array.isArray(args.binDirs) ? args.binDirs : undefined;
255
+ // follow / dump 共用:通道没在跑就自动起一个(addr 取参数,其次上次 start 记住的地址)。
256
+ // 以前这两个动作要求先手动 action=start,多一步而且容易忘;自动起也顺手把会话/探针错误带出来。
257
+ const bringUpChannel = async (actionName) => {
258
+ // 「通道在跑」只是内存里的状态:openocd 死了这个标志还亮着。先连一下通道端口确认它真的在,
259
+ // 不然 follow 会直接卡到 connect ECONNREFUSED,而不是把死会话清掉重起。
260
+ if (rttStatus().running) {
261
+ const livePort = rttStatus().port;
262
+ const listening = livePort > 0 && (await isPortBusy(livePort, 300));
263
+ if (listening)
264
+ return null;
265
+ notes.push("RTT 通道端口 " + String(livePort) + " 连不上(openocd 多半已退出),清理后重起");
266
+ }
267
+ const explicit = readString(args.addr);
268
+ const remembered = rttStatus().addr;
269
+ const target = explicit ?? (remembered === "" ? undefined : remembered);
270
+ if (target === undefined) {
271
+ return failure(actionName, projectDir, actionName + " 需要 RTT 通道:先 action=start(给 addr),或本动作里直接带 addr 自动起", notes);
272
+ }
273
+ const gate = await ensureToolchain(ctx, {
274
+ capability: "debug",
275
+ ...(binDirs === undefined ? {} : { binDirs }),
276
+ envCheck: args.envCheck,
277
+ signal: exec.signal,
278
+ });
279
+ if (!gate.ok && gate.mode === "block") {
280
+ return failure(actionName, projectDir, gate.message, [...notes, ...gateReportNotes(gate)]);
281
+ }
282
+ const gateNotes = gateReportNotes(gate);
283
+ const subprocess = ctx.get("subprocess");
284
+ if (subprocess === undefined) {
285
+ return failure(actionName, projectDir, "宿主没有 subprocess 服务,起不了 openocd 会话", [...notes, ...gateNotes]);
286
+ }
287
+ const ensured = await ensureSession(projectDir, {
288
+ subprocess,
289
+ ...(binDirs === undefined ? {} : { binDirs }),
290
+ ...(exec.agent?.id === undefined ? {} : { owner: exec.agent.id }),
291
+ });
292
+ if (!ensured.ok || ensured.session === null) {
293
+ const report = baseReport(actionName, projectDir);
294
+ report.message = ensured.message;
295
+ report.errors = [ensured.message];
296
+ report.notes = [...notes, ...gateNotes];
297
+ if (ensured.probeError !== null)
298
+ report.probeError = ensured.probeError;
299
+ return { message: ensured.message, report };
300
+ }
301
+ const session = ensured.session;
302
+ notes.push(ensured.reused
303
+ ? "复用已有调试会话(tcl 端口 " + String(session.tclPort) + ")"
304
+ : "没有活跃会话,先起了一个调试会话(gdb 端口 " + String(session.port) + ",tcl 端口 " + String(session.tclPort) + ")");
305
+ if (ensured.replacedDead)
306
+ notes.push("旧会话的 openocd 已经不在了(tcl 端口连不上),已清理并重起");
307
+ rttOwnedSessionStartedAt = ensured.reused ? null : session.startedAt;
308
+ const started = await startRtt({
309
+ addr: target,
310
+ ...(readNumber(args.size) === undefined ? {} : { size: readNumber(args.size) ?? DEFAULT_RTT_SIZE }),
311
+ ...(readString(args.banner) === undefined ? {} : { banner: readString(args.banner) ?? "" }),
312
+ ...(readNumber(args.rttPort) === undefined ? {} : { port: readNumber(args.rttPort) ?? DEFAULT_RTT_PORT }),
313
+ ...(readNumber(args.timeoutMs) === undefined ? {} : { timeoutMs: readNumber(args.timeoutMs) ?? 5_000 }),
314
+ signal: exec.signal,
315
+ });
316
+ if (!started.ok) {
317
+ const report = baseReport(actionName, projectDir);
318
+ report.ok = false;
319
+ report.message = started.message;
320
+ report.errors = [started.message];
321
+ report.notes = [...notes, ...gateNotes, ...started.notes];
322
+ if (started.probeError !== null)
323
+ report.probeError = started.probeError;
324
+ return { message: started.message, report };
325
+ }
326
+ notes.push("没有 RTT 通道,已自动 start:控制块 " + started.addr + ",通道端口 " + String(started.port));
327
+ return null;
328
+ };
226
329
  if (action === "start") {
227
330
  const addr = readString(args.addr);
228
331
  if (addr === undefined)
@@ -237,33 +340,38 @@ export function registerRtt(ctx) {
237
340
  return failure(action, projectDir, gate.message, [...notes, ...gateReportNotes(gate)]);
238
341
  }
239
342
  const gateNotes = gateReportNotes(gate);
240
- let session = sessionInfo();
241
- if (session === null) {
242
- const subprocess = ctx.get("subprocess");
243
- if (subprocess === undefined) {
244
- return failure(action, projectDir, "宿主没有 subprocess 服务,起不了 openocd 会话", [...notes, ...gateNotes]);
245
- }
246
- const ensured = await ensureSession(projectDir, {
247
- subprocess,
248
- ...(binDirs === undefined ? {} : { binDirs }),
249
- ...(exec.agent?.id === undefined ? {} : { owner: exec.agent.id }),
250
- });
251
- if (!ensured.ok || ensured.session === null) {
252
- const probeError = ensured.probeError;
253
- const report = baseReport(action, projectDir);
254
- report.message = ensured.message;
255
- report.errors = [ensured.message];
256
- report.notes = [...notes, ...gateNotes];
257
- if (probeError !== null)
258
- report.probeError = probeError;
259
- return { message: ensured.message, report };
260
- }
261
- session = ensured.session;
262
- notes.push("没有活跃会话,先起了一个调试会话(gdb 端口 " + String(session.port) + ",tcl 端口 " + String(session.tclPort) + ")");
343
+ // 一律走 ensureSession(哪怕 sessionInfo() 看起来有会话):只有它会在复用前确认 openocd 还活着。
344
+ // 真机踩过:探针掉线后 openocd 自己退出,会话记录还在,于是 start 一直"复用"一个死会话。
345
+ const subprocess = ctx.get("subprocess");
346
+ if (subprocess === undefined) {
347
+ return failure(action, projectDir, "宿主没有 subprocess 服务,起不了 openocd 会话", [...notes, ...gateNotes]);
263
348
  }
264
- else {
349
+ const ensured = await ensureSession(projectDir, {
350
+ subprocess,
351
+ ...(binDirs === undefined ? {} : { binDirs }),
352
+ ...(exec.agent?.id === undefined ? {} : { owner: exec.agent.id }),
353
+ });
354
+ if (!ensured.ok || ensured.session === null) {
355
+ const probeError = ensured.probeError;
356
+ const report = baseReport(action, projectDir);
357
+ report.message = ensured.message;
358
+ report.errors = [ensured.message];
359
+ report.notes = [...notes, ...gateNotes];
360
+ if (probeError !== null)
361
+ report.probeError = probeError;
362
+ return { message: ensured.message, report };
363
+ }
364
+ const session = ensured.session;
365
+ if (ensured.reused) {
265
366
  notes.push("复用已有调试会话(tcl 端口 " + String(session.tclPort) + ")");
266
367
  }
368
+ else {
369
+ notes.push("没有活跃会话,先起了一个调试会话(gdb 端口 " + String(session.port) + ",tcl 端口 " + String(session.tclPort) + ")");
370
+ }
371
+ if (ensured.replacedDead)
372
+ notes.push("旧会话的 openocd 已经不在了(tcl 端口连不上),已清理并重起");
373
+ // 记下"这是我起的":stop 时据此决定要不要把 openocd 一起收掉(复用别人的就不动)。
374
+ rttOwnedSessionStartedAt = ensured.reused ? null : session.startedAt;
267
375
  const started = await startRtt({
268
376
  addr,
269
377
  ...(readNumber(args.size) === undefined ? {} : { size: readNumber(args.size) ?? DEFAULT_RTT_SIZE }),
@@ -287,12 +395,19 @@ export function registerRtt(ctx) {
287
395
  report.probeError = started.probeError;
288
396
  return { message: started.message, report };
289
397
  }
290
- if (action === "dump") {
398
+ if (action === "dump" || action === "follow") {
399
+ const isFollow = action === "follow";
400
+ const autoError = await bringUpChannel(action);
401
+ if (autoError !== null)
402
+ return autoError;
403
+ const defaultSeconds = isFollow ? DEFAULT_FOLLOW_SECONDS : DEFAULT_DUMP_SECONDS;
291
404
  const dumped = await dumpRtt({
292
- ...(readNumber(args.seconds) === undefined ? {} : { seconds: readNumber(args.seconds) ?? DEFAULT_DUMP_SECONDS }),
405
+ ...(readNumber(args.seconds) === undefined ? {} : { seconds: readNumber(args.seconds) ?? defaultSeconds }),
293
406
  ...(readNumber(args.level) === undefined ? {} : { level: readNumber(args.level) ?? 4 }),
294
407
  ...(readNumber(args.maxRecords) === undefined ? {} : { maxRecords: readNumber(args.maxRecords) ?? DEFAULT_MAX_RECORDS }),
295
408
  ...(readNumber(args.timeoutMs) === undefined ? {} : { timeoutMs: readNumber(args.timeoutMs) ?? 3_000 }),
409
+ keepNewest: isFollow,
410
+ readFirmwareDrop: true,
296
411
  signal: exec.signal,
297
412
  });
298
413
  const report = baseReport(action, projectDir);
@@ -300,6 +415,7 @@ export function registerRtt(ctx) {
300
415
  report.durationMs = dumped.durationMs;
301
416
  report.records = dumped.records;
302
417
  report.dropped = dumped.dropped;
418
+ report.firmwareDropped = dumped.firmwareDropped;
303
419
  report.bytes = dumped.bytes;
304
420
  report.truncated = dumped.truncated;
305
421
  report.stopped = dumped.stopped;
@@ -315,6 +431,13 @@ export function registerRtt(ctx) {
315
431
  }
316
432
  if (action === "stop") {
317
433
  const stopped = await stopRtt();
434
+ // RTT 起的会话由 RTT 收尾:只关 rtt 通道时 openocd 还握着探针,下一次烧录会撞 CMSIS-DAP。
435
+ const live = sessionInfo();
436
+ if (live !== null && rttOwnedSessionStartedAt !== null && live.startedAt === rttOwnedSessionStartedAt) {
437
+ rttOwnedSessionStartedAt = null;
438
+ const released = await release("rtt stop", exec.agent?.id === undefined ? {} : { requireOwner: exec.agent.id });
439
+ notes.push(released.stopped ? "RTT 起的调试会话已释放(openocd 退出,探针归还)" : released.message);
440
+ }
318
441
  const report = baseReport(action, projectDir);
319
442
  report.ok = stopped.ok;
320
443
  report.durationMs = stopped.durationMs;
@@ -0,0 +1,256 @@
1
+ /**
2
+ * P3:stm32_watch —— 变量监视(值采样)与硬件观察点。
3
+ *
4
+ * - action=add:kind=value 登记一个"每次 sample 求值"的表达式;kind=write/read/access 用真实观察点
5
+ * (gdb watch / rwatch / awatch,F1 有 4 个数据比较器,与硬件断点共用);
6
+ * - action=sample:目标在跑就先 -exec-interrupt 停住,逐项求值,给出与上次的差值,再按原状态放回去;
7
+ * - action=list / remove / clear:看登记表、按 id 删、全清。
8
+ *
9
+ * 为什么单独一个工具而不是塞进 stm32_debug_eval:观察点会消耗芯片比较器预算、值监视需要
10
+ * "停下→读→放回"这一整套语义,混进 eval 的裸命令里没人管得住上限。
11
+ * 登记表住在插件进程内(engine/watch.ts 的单例),会话一关就清空(观察点在 gdb 进程里随会话消失)。
12
+ */
13
+ import { debugSessions } from "../engine/debug-session.js";
14
+ import { WATCH_KIND_LABELS, hardwareWatchpoints, isWatchKind, normalizeWatchExpression, registerWatch, watchState, } from "../engine/watch.js";
15
+ export const WATCH_TOOL = "stm32_watch";
16
+ const quotaSchema = {
17
+ type: "object",
18
+ additionalProperties: false,
19
+ properties: {
20
+ used: { type: "number" },
21
+ limit: { type: "number" },
22
+ remaining: { type: "number" },
23
+ },
24
+ required: ["used", "limit", "remaining"],
25
+ };
26
+ const entrySchema = {
27
+ type: "object",
28
+ additionalProperties: false,
29
+ properties: {
30
+ id: { type: "number" },
31
+ expression: { type: "string" },
32
+ kind: { type: "string" },
33
+ kindLabel: { type: "string" },
34
+ gdbNumber: { type: "number" },
35
+ lastValue: { type: "string" },
36
+ lastAt: { type: "number" },
37
+ lastError: { type: "string" },
38
+ delta: { type: "string" },
39
+ },
40
+ required: ["id", "expression", "kind", "kindLabel", "gdbNumber", "lastValue", "lastAt", "lastError", "delta"],
41
+ };
42
+ export const watchOutputSchema = {
43
+ type: "object",
44
+ additionalProperties: false,
45
+ properties: {
46
+ message: { type: "string" },
47
+ report: {
48
+ type: "object",
49
+ additionalProperties: false,
50
+ properties: {
51
+ ok: { type: "boolean" },
52
+ action: { type: "string" },
53
+ entries: { type: "array", items: entrySchema },
54
+ watchpoints: quotaSchema,
55
+ halted: { type: "boolean" },
56
+ resumed: { type: "boolean" },
57
+ durationMs: { type: "number" },
58
+ errors: { type: "array", items: { type: "string" } },
59
+ notes: { type: "array", items: { type: "string" } },
60
+ message: { type: "string" },
61
+ },
62
+ required: ["ok", "action", "entries", "watchpoints", "halted", "resumed", "durationMs", "errors", "notes", "message"],
63
+ },
64
+ },
65
+ required: ["message", "report"],
66
+ };
67
+ function entryView(entry, delta = "") {
68
+ return {
69
+ id: entry.id,
70
+ expression: entry.expression,
71
+ kind: entry.kind,
72
+ kindLabel: WATCH_KIND_LABELS[entry.kind],
73
+ gdbNumber: entry.gdbNumber,
74
+ lastValue: entry.lastValue,
75
+ lastAt: entry.lastAt,
76
+ lastError: entry.lastError,
77
+ delta,
78
+ };
79
+ }
80
+ function currentQuota() {
81
+ return debugSessions.status().watchpoints;
82
+ }
83
+ /** 值监视清单的人话描述(limit=0 时别写成 "0/0" 让人以为超了)。 */
84
+ function describeQuota(quota) {
85
+ return "硬件观察点 " + String(quota.used) + "/" + String(quota.limit);
86
+ }
87
+ function emptyReport(action, message, errors = [], notes = []) {
88
+ return {
89
+ ok: errors.length === 0, action, entries: [], watchpoints: currentQuota(),
90
+ halted: false, resumed: false, durationMs: 0, errors, notes, message,
91
+ };
92
+ }
93
+ /** 把 addWatchpoints 的报告翻成本工具的 report(entries 换成视图)。 */
94
+ function fromAddReport(report) {
95
+ return {
96
+ ok: report.ok, action: "add", entries: report.added.map((entry) => entryView(entry)),
97
+ watchpoints: report.budget, halted: false, resumed: report.resumed, durationMs: report.durationMs,
98
+ errors: report.errors, notes: report.notes, message: report.message,
99
+ };
100
+ }
101
+ /** 把 sampleWatches 的报告翻成本工具的 report(值 + 差值一起给)。 */
102
+ function fromSampleReport(report) {
103
+ const byId = new Map();
104
+ for (const sample of report.samples)
105
+ byId.set(sample.id, sample.delta);
106
+ const errors = report.errors.slice();
107
+ for (const sample of report.samples) {
108
+ if (!sample.ok)
109
+ errors.push(sample.expression + ":" + sample.error);
110
+ }
111
+ return {
112
+ ok: report.ok, action: "sample", entries: watchState.entries.map((entry) => entryView(entry, byId.get(entry.id) ?? "")),
113
+ watchpoints: currentQuota(), halted: report.halted, resumed: report.resumed, durationMs: report.durationMs,
114
+ errors, notes: [], message: report.message,
115
+ };
116
+ }
117
+ export function registerWatchTool(ctx) {
118
+ ctx.tools.register({
119
+ name: WATCH_TOOL,
120
+ description: "变量监视与硬件观察点。action=add 登记表达式(kind=value 每次 sample 求值;kind=write/read/access 装真正的硬件观察点,F1 只有 4 个数据比较器,与硬件断点共用);action=sample 把目标停下读一遍、给与上次的差值、再按原状态放回去;action=list/remove/clear 管理登记表。值监视项每次 sample 都会求值,观察点是被动拦截(命中时由 gdb 报停)。会话关闭时登记表随之清空。",
121
+ parameters: {
122
+ type: "object",
123
+ additionalProperties: false,
124
+ properties: {
125
+ action: { type: "string", enum: ["add", "sample", "list", "remove", "clear"], description: "要做什么,默认 list(看登记表)。" },
126
+ expressions: { type: "array", items: { type: "string" }, description: "action=add 要监视的表达式,例如 g_tick_1k、g_adc_dma[0]、*(unsigned int *)0x4001100C。" },
127
+ kind: { type: "string", enum: ["value", "write", "read", "access"], description: "action=add 的类型:value(默认,采样求值)、write(写观察点)、read(读观察点)、access(读写观察点)。" },
128
+ ids: { type: "array", items: { type: "number" }, description: "action=remove 要删的 id(action=list 里能看到)。" },
129
+ timeoutMs: { type: "number", description: "单条求值/装观察点的超时毫秒数,默认 20000。" },
130
+ resume: { type: "boolean", description: "采样时目标原本在跑:采完是否放回去(默认 true)。" },
131
+ },
132
+ },
133
+ timeoutMs: 90_000,
134
+ isConcurrencySafe: () => false,
135
+ output: {
136
+ schema: watchOutputSchema,
137
+ render: (_args, value) => {
138
+ const typed = value;
139
+ const lines = [typed.report.message];
140
+ for (const entry of typed.report.entries) {
141
+ const delta = entry.delta === "" ? "" : "(Δ " + entry.delta + ")";
142
+ const where = entry.gdbNumber > 0 ? " [gdb #" + String(entry.gdbNumber) + "]" : "";
143
+ const value = entry.lastValue === "" ? "(还没采过)" : entry.lastValue;
144
+ lines.push("#" + String(entry.id) + " " + entry.expression + " = " + value + delta + where);
145
+ if (entry.lastError !== "")
146
+ lines.push(" x " + entry.lastError);
147
+ }
148
+ if (typed.report.entries.length === 0)
149
+ lines.push("(登记表是空的:先用 action=add 加表达式)");
150
+ lines.push("· " + describeQuota(typed.report.watchpoints));
151
+ for (const note of typed.report.notes.slice(0, 6))
152
+ lines.push("- " + note);
153
+ for (const error of typed.report.errors.slice(0, 6))
154
+ lines.push("x " + error);
155
+ return [{ type: "text", text: lines.join("\n") }];
156
+ },
157
+ },
158
+ async execute(rawArgs, exec) {
159
+ const args = rawArgs ?? {};
160
+ const action = args.action ?? "list";
161
+ const startedAt = Date.now();
162
+ const timeout = args.timeoutMs;
163
+ if (action === "add") {
164
+ const expressions = args.expressions ?? [];
165
+ const kind = args.kind === undefined ? "value" : args.kind;
166
+ if (!isWatchKind(kind)) {
167
+ return { message: "kind 不认识:" + String(kind) + "(只认 value/write/read/access)", report: emptyReport(action, "没加:kind 不认识", ["kind 不认识:" + String(kind)]) };
168
+ }
169
+ if (expressions.length === 0) {
170
+ return { message: "没给 expressions:例如 action=add,expressions 传 [g_tick_1k]", report: emptyReport(action, "没加:没给表达式", ["expressions 是空的"]) };
171
+ }
172
+ // 值监视只是登记(求值要等 sample),所以不需要会话;观察点必须现在装进 gdb。
173
+ if (kind === "value") {
174
+ const errors = [];
175
+ const added = [];
176
+ for (const text of expressions) {
177
+ const expression = normalizeWatchExpression(text);
178
+ if (expression === null) {
179
+ errors.push("表达式不合法:" + JSON.stringify(text));
180
+ continue;
181
+ }
182
+ const registered = registerWatch(watchState, expression, "value", Date.now());
183
+ if (registered.entry === null) {
184
+ errors.push(registered.error);
185
+ continue;
186
+ }
187
+ added.push(registered.entry);
188
+ }
189
+ const report = {
190
+ ok: errors.length === 0, action: "add", entries: added.map((entry) => entryView(entry)),
191
+ watchpoints: currentQuota(), halted: false, resumed: false, durationMs: Date.now() - startedAt,
192
+ errors, notes: [], message: errors.length === 0 ? "登记了 " + String(added.length) + " 个值监视项(用 action=sample 取值)" : "有 " + String(errors.length) + " 条没登记上",
193
+ };
194
+ return { message: report.message, report };
195
+ }
196
+ const entries = expressions.map((expression) => ({ expression, kind }));
197
+ const added = await debugSessions.addWatchpoints({ entries, ...(timeout === undefined ? {} : { timeoutMs: timeout }) });
198
+ const report = fromAddReport(added);
199
+ return { message: report.message, report };
200
+ }
201
+ if (action === "sample") {
202
+ const report = fromSampleReport(await debugSessions.sampleWatches({
203
+ ...(timeout === undefined ? {} : { timeoutMs: timeout }),
204
+ ...(args.resume === undefined ? {} : { resume: args.resume }),
205
+ signal: exec.signal,
206
+ }));
207
+ return { message: report.message, report };
208
+ }
209
+ if (action === "list") {
210
+ const entries = watchState.entries.map((entry) => entryView(entry));
211
+ const sampled = watchState.entries.filter((entry) => entry.kind === "value").length;
212
+ const message = entries.length === 0
213
+ ? "登记表是空的:先用 action=add 加表达式"
214
+ : "登记了 " + String(entries.length) + " 项(值监视 " + String(sampled) + "、观察点 " + String(hardwareWatchpoints(watchState).length) + ")";
215
+ return {
216
+ message,
217
+ report: { ok: true, action: "list", entries, watchpoints: currentQuota(), halted: false, resumed: false, durationMs: Date.now() - startedAt, errors: [], notes: [], message },
218
+ };
219
+ }
220
+ if (action === "remove") {
221
+ const ids = args.ids ?? [];
222
+ if (ids.length === 0) {
223
+ return { message: "没给 ids:先 action=list 看编号,或 action=clear 全清", report: emptyReport(action, "没删:没给 ids", ["ids 是空的"]) };
224
+ }
225
+ const removed = await debugSessions.removeWatchpoints(ids);
226
+ return {
227
+ message: removed.message,
228
+ report: {
229
+ ok: removed.ok, action: "remove", entries: removed.removed.map((entry) => entryView(entry)),
230
+ watchpoints: removed.budget, halted: false, resumed: removed.resumed, durationMs: removed.durationMs,
231
+ errors: removed.errors, notes: [], message: removed.message,
232
+ },
233
+ };
234
+ }
235
+ if (action === "clear") {
236
+ const ids = watchState.entries.map((entry) => entry.id);
237
+ if (ids.length === 0) {
238
+ return { message: "登记表本来就是空的", report: emptyReport(action, "没清:登记表本来就是空的") };
239
+ }
240
+ const removed = await debugSessions.removeWatchpoints(ids);
241
+ const message = "清空了登记表(" + String(removed.removed.length) + " 项)";
242
+ return {
243
+ message: removed.ok ? message : message + ",但有问题:" + (removed.errors[0] ?? ""),
244
+ report: {
245
+ ok: removed.ok, action: "clear", entries: [], watchpoints: removed.budget, halted: false,
246
+ resumed: removed.resumed, durationMs: removed.durationMs, errors: removed.errors, notes: [], message,
247
+ },
248
+ };
249
+ }
250
+ return {
251
+ message: "action 不认识:" + action + "(只认 add/sample/list/remove/clear)",
252
+ report: emptyReport(action, "没做:action 不认识", ["action 不认识:" + action]),
253
+ };
254
+ },
255
+ });
256
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-stm32",
3
- "version": "0.1.3",
4
- "description": "DSH 插件:STM32(F103C8T6)全流程工具层 —— 环境探测、.ioc 事务、生成工程、编译、只烧录、按需调试",
3
+ "version": "0.1.4",
4
+ "description": "DSH 插件:STM32 全流程工具层(HAL 多族 + 寄存器 13 族)—— 环境探测、.ioc 事务、生成工程、编译、烧录、调试;芯片事实与模板随包内置",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "exports": {
@@ -13,7 +13,8 @@
13
13
  "lib",
14
14
  "client",
15
15
  "templates",
16
- "docs/*.md",
16
+ "assets",
17
+ "docs/reading-guide.md",
17
18
  "cordis.patch.yml",
18
19
  "README.md",
19
20
  "README_EN.md",
@@ -23,7 +24,7 @@
23
24
  "node": ">=20"
24
25
  },
25
26
  "scripts": {
26
- "build": "tsc -p tsconfig.json && node scripts/copy-client.mjs",
27
+ "build": "tsc -p tsconfig.json && node scripts/copy-client.mjs && node scripts/copy-data.mjs",
27
28
  "typecheck": "tsc -p tsconfig.json --noEmit",
28
29
  "test": "node test/run-units.mjs",
29
30
  "prepublishOnly": "npm run build",