dsh-stm32 0.1.2 → 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 (225) hide show
  1. package/README.md +92 -40
  2. package/README_EN.md +85 -36
  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 +94 -71
  133. package/lib/data/chips.js +38 -51
  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 +264 -17
  137. package/lib/data/db-presets.js +252 -0
  138. package/lib/data/device-facts.js +274 -0
  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 +95 -150
  148. package/lib/data/svd.js +643 -0
  149. package/lib/data/toolchain-config.js +0 -14
  150. package/lib/engine/assets.js +659 -0
  151. package/lib/engine/breakpoints.js +297 -0
  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 +576 -22
  161. package/lib/engine/debug.js +99 -46
  162. package/lib/engine/doctor.js +162 -19
  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 +317 -76
  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 +1247 -63
  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 +231 -0
  177. package/lib/engine/probe-session.js +347 -0
  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 +130 -45
  183. package/lib/engine/regs.js +43 -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 +758 -0
  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 +12 -2
  192. package/lib/skill/stm32-workflow.js +2 -2
  193. package/lib/tools/assets.js +272 -0
  194. package/lib/tools/cache.js +8 -0
  195. package/lib/tools/debug-session.js +41 -6
  196. package/lib/tools/debug.js +41 -11
  197. package/lib/tools/doctor.js +65 -4
  198. package/lib/tools/firmware-install.js +31 -6
  199. package/lib/tools/flash.js +47 -10
  200. package/lib/tools/generate.js +25 -0
  201. package/lib/tools/ioc-apply.js +2 -0
  202. package/lib/tools/ioc-inspect.js +2 -0
  203. package/lib/tools/ioc-plan.js +59 -2
  204. package/lib/tools/ioc-verify.js +237 -0
  205. package/lib/tools/project-create.js +63 -3
  206. package/lib/tools/regs.js +453 -61
  207. package/lib/tools/route-plan.js +3 -0
  208. package/lib/tools/rtt.js +470 -0
  209. package/lib/tools/watch.js +256 -0
  210. package/package.json +5 -4
  211. package/templates/openocd/stm32c0x.cfg +83 -0
  212. package/templates/openocd/stm32u0x.cfg +64 -0
  213. package/templates/register/CMakeLists.txt +8 -2
  214. package/templates/register/Core/Inc/rtt.h +138 -0
  215. package/templates/register/Core/Src/main.c +42 -25
  216. package/templates/register/Core/Src/rtt.c +373 -0
  217. package/templates/scaffold/RTT.md +90 -0
  218. package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
  219. package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
  220. package/templates/scaffold/openocd.cfg +5 -3
  221. package/templates/scaffold/vscode/launch.json +8 -4
  222. package/docs/development-notes.md +0 -2116
  223. package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
  224. package/docs/logic-audit.md +0 -607
  225. package/lib/data/f1-ram.generated.js +0 -34
@@ -0,0 +1,470 @@
1
+ /**
2
+ * stm32_rtt:RTT 的入口工具。四个动作对应一条最短路径:
3
+ *
4
+ * start —— 确认目标里有控制块 → openocd rtt setup/start → 开通道 TCP 端口
5
+ * dump —— 连上通道读一段时间的记录(可按级别过滤、按条数截断)
6
+ * stop —— 断通道,让 openocd 收掉 rtt server;start 自己起的会话一并释放(探针归还)
7
+ * status —— 只读快照
8
+ *
9
+ * 设计取舍:
10
+ * - 没有活跃调试会话时,start 自己起一个(ensureSession),用户不用记着先开会话;
11
+ * - dump/stop/status 不再跑工具链 gate:RTT 都跑起来了说明 openocd 在,再检查一遍只会碍事;
12
+ * - 失败也返回完整形状的 report(字段全是默认值 + probeError),免得宿主序列化时炸。
13
+ */
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
+ import { PROBE_ERROR_SCHEMA } from "../engine/probe-error.js";
16
+ import { isPortBusy } from "../engine/debug.js";
17
+ import { ensureSession, release, sessionInfo } from "../engine/probe-session.js";
18
+ import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
19
+ import { resolveProjectDir, validateToolArgs } from "./project-dir.js";
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;
30
+ const ENV_CHECK_SCHEMA = {
31
+ type: "string",
32
+ enum: ["block", "warn", "off"],
33
+ description: "工具链检查:block 缺件就拒绝(默认)、warn 只警告、off 不检查",
34
+ };
35
+ const RECORD_SCHEMA = {
36
+ type: "object",
37
+ additionalProperties: false,
38
+ properties: {
39
+ t: { type: "number", description: "模板写进来的毫秒时间戳(通常就是 HAL_GetTick)" },
40
+ level: { type: "number", description: "级别:1=error 2=warn 3=info 4=debug" },
41
+ text: { type: "string", description: "记录正文" },
42
+ },
43
+ required: ["t", "level", "text"],
44
+ };
45
+ const SESSION_SCHEMA = {
46
+ type: "object",
47
+ additionalProperties: false,
48
+ properties: {
49
+ port: { type: "number", description: "gdb 端口(0 表示当时没有会话)" },
50
+ tclPort: { type: "number", description: "openocd 的 Tcl RPC 端口(0 表示没有)" },
51
+ },
52
+ required: ["port", "tclPort"],
53
+ };
54
+ export const reportSchema = {
55
+ type: "object",
56
+ additionalProperties: false,
57
+ properties: {
58
+ ok: { type: "boolean", description: "这次动作成功没有" },
59
+ action: { type: "string", description: "start / dump / stop / status" },
60
+ projectDir: { type: "string", description: "工程目录" },
61
+ addr: { type: "string", description: "RTT 控制块地址(十六进制)" },
62
+ size: { type: "number", description: "控制块预留字节数" },
63
+ banner: { type: "string", description: "控制块标识(rtt setup 的第三个参数)" },
64
+ port: { type: "number", description: "RTT 通道的 TCP 端口" },
65
+ running: { type: "boolean", description: "RTT 当前是否在跑" },
66
+ startedAt: { type: "number", description: "start 的 Unix 毫秒时间戳;没跑时为 0" },
67
+ runningMs: { type: "number", description: "已经跑了多少毫秒;没跑时为 0" },
68
+ durationMs: { type: "number", description: "这次动作花了多少毫秒" },
69
+ records: { type: "array", description: "dump 到的记录(按时间顺序)", items: RECORD_SCHEMA },
70
+ dropped: { type: "number", description: "按 level 过滤掉的条数" },
71
+ firmwareDropped: { type: "number", description: "固件侧累计丢帧(rtt.c 里的 s_dropped,自复位起);读不到时 -1" },
72
+ bytes: { type: "number", description: "从通道读到的字节数" },
73
+ truncated: { type: "boolean", description: "是否因为 maxRecords 提前收尾" },
74
+ stopped: { type: "boolean", description: "通道是否在窗口内被关掉(目标复位或 stop)" },
75
+ session: SESSION_SCHEMA,
76
+ errors: { type: "array", description: "失败原因(一条一行)", items: { type: "string" } },
77
+ message: { type: "string", description: "一句话结论" },
78
+ notes: { type: "array", description: "补充说明", items: { type: "string" } },
79
+ probeError: PROBE_ERROR_SCHEMA,
80
+ },
81
+ required: [
82
+ "ok",
83
+ "action",
84
+ "projectDir",
85
+ "addr",
86
+ "size",
87
+ "banner",
88
+ "port",
89
+ "running",
90
+ "startedAt",
91
+ "runningMs",
92
+ "durationMs",
93
+ "records",
94
+ "dropped",
95
+ "firmwareDropped",
96
+ "bytes",
97
+ "truncated",
98
+ "stopped",
99
+ "session",
100
+ "errors",
101
+ "message",
102
+ "notes",
103
+ ],
104
+ };
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;
120
+ function sessionWire() {
121
+ const session = sessionInfo();
122
+ if (session === null)
123
+ return { port: 0, tclPort: 0 };
124
+ return { port: session.port, tclPort: session.tclPort };
125
+ }
126
+ /** 报告先按默认值填满,再逐项覆盖:任何一条失败路径都不会漏字段。 */
127
+ function baseReport(action, projectDir) {
128
+ const snapshot = rttStatus();
129
+ return {
130
+ ok: false,
131
+ action,
132
+ projectDir,
133
+ addr: snapshot.addr,
134
+ size: snapshot.size,
135
+ banner: snapshot.banner,
136
+ port: snapshot.port,
137
+ running: snapshot.running,
138
+ startedAt: snapshot.startedAt,
139
+ runningMs: snapshot.runningMs,
140
+ durationMs: 0,
141
+ records: [],
142
+ dropped: 0,
143
+ firmwareDropped: -1,
144
+ bytes: 0,
145
+ truncated: false,
146
+ stopped: false,
147
+ session: sessionWire(),
148
+ errors: [],
149
+ message: "",
150
+ notes: [],
151
+ };
152
+ }
153
+ function failure(action, projectDir, message, notes = [], probeError = null) {
154
+ const report = baseReport(action, projectDir);
155
+ report.message = message;
156
+ report.errors = [message];
157
+ report.notes = notes;
158
+ if (probeError !== null)
159
+ report.probeError = probeError;
160
+ return { message, report };
161
+ }
162
+ function formatReport(report) {
163
+ const lines = [];
164
+ lines.push((report.ok ? "完成" : "失败") + "(" + report.action + "):" + report.message);
165
+ if (report.running) {
166
+ lines.push("RTT 在跑:控制块 " + report.addr + "(" + String(report.size) + " 字节),通道端口 " + String(report.port) +
167
+ (report.banner === "" ? "" : ",banner " + report.banner) + ",已跑 " + String(report.runningMs) + " ms");
168
+ }
169
+ const shown = report.records.slice(0, 80);
170
+ for (const record of shown) {
171
+ const name = RTT_LEVEL_NAMES[record.level] ?? String(record.level);
172
+ lines.push(" [" + String(record.t) + " ms][" + name + "] " + record.text);
173
+ }
174
+ if (report.records.length > shown.length)
175
+ lines.push(" … 还有 " + String(report.records.length - shown.length) + " 条(调大 maxRecords 或分批 dump)");
176
+ if (report.truncated)
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,自复位起)");
180
+ if (report.stopped)
181
+ lines.push("· RTT 通道已停(目标复位或 rtt stop)");
182
+ lines.push("· 这次读 " + String(report.bytes) + " 字节" + (report.dropped > 0 ? ",按级别过滤掉 " + String(report.dropped) + " 条" : ""));
183
+ for (const note of report.notes)
184
+ lines.push("· " + note);
185
+ for (const error of report.errors.slice(0, 6))
186
+ lines.push("! " + error);
187
+ return lines;
188
+ }
189
+ function readNumber(value) {
190
+ return typeof value === "number" && Number.isFinite(value) ? value : undefined;
191
+ }
192
+ function readString(value) {
193
+ return typeof value === "string" && value.trim() !== "" ? value : undefined;
194
+ }
195
+ function snapshotInto(report, snapshot) {
196
+ report.addr = snapshot.addr;
197
+ report.size = snapshot.size;
198
+ report.banner = snapshot.banner;
199
+ report.port = snapshot.port;
200
+ report.running = snapshot.running;
201
+ report.startedAt = snapshot.startedAt;
202
+ report.runningMs = snapshot.runningMs;
203
+ report.session = sessionWire();
204
+ }
205
+ export function registerRtt(ctx) {
206
+ ctx.tools.register({
207
+ name: RTT_TOOL,
208
+ description: "RTT(Real Time Transfer):start 起 openocd 的 rtt 通道并给出 TCP 端口,dump 读一段时间的记录(级别过滤/条数截断),follow 连续读一段(只留最新 N 条,并读固件侧 s_dropped 丢帧计数——想确认「到底丢没丢」就用它),stop 收掉通道(start 自己起的调试会话会一并释放、探针归还),status 看状态。",
209
+ parameters: {
210
+ type: "object",
211
+ additionalProperties: false,
212
+ properties: {
213
+ action: { type: "string", enum: [...ACTIONS], description: "start(起 RTT)/ dump(读一段记录)/ follow(持续读一段,只留最新 N 条,顺带读固件侧丢帧数)/ stop(停)/ status(看状态)" },
214
+ projectDir: { type: "string", description: "工程目录;缺省取会话工作目录" },
215
+ addr: { type: "string", description: "RTT 控制块起始地址(十六进制,例如 0x20000000);action=start 必填" },
216
+ size: { type: "number", description: "控制块预留字节数,默认 " + String(DEFAULT_RTT_SIZE) },
217
+ banner: { type: "string", description: "控制块标识(openocd rtt setup 的第三个参数);一般不用填" },
218
+ rttPort: { type: "number", description: "RTT 通道的 TCP 端口,默认 " + String(DEFAULT_RTT_PORT) },
219
+ seconds: { type: "number", description: "采集窗口(秒):dump 默认 " + String(DEFAULT_DUMP_SECONDS) + "(0.2..60),follow 默认 " + String(DEFAULT_FOLLOW_SECONDS) + "(0.2..300)" },
220
+ level: { type: "number", description: "dump 保留到哪一级:1=error 2=warn 3=info 4=debug(默认 4,全要)" },
221
+ maxRecords: { type: "number", description: "dump 最多返回多少条,默认 " + String(DEFAULT_MAX_RECORDS) },
222
+ timeoutMs: { type: "number", description: "Tcl 往返 / 连通道的超时毫秒数" },
223
+ binDirs: { type: "array", description: "工具链目录候选(覆盖默认搜索路径)", items: { type: "string" } },
224
+ envCheck: ENV_CHECK_SCHEMA,
225
+ },
226
+ required: ["action"],
227
+ },
228
+ timeoutMs: 120_000,
229
+ isConcurrencySafe: () => false,
230
+ output: {
231
+ schema: outputSchema,
232
+ render: (_args, value) => [{ type: "text", text: formatReport(value.report).join("\n") }],
233
+ },
234
+ async execute(rawArgs, exec) {
235
+ const args = (rawArgs ?? {});
236
+ const action = typeof args.action === "string" ? args.action.trim() : "";
237
+ const resolution = await resolveProjectDir(ctx, readString(args.projectDir), exec);
238
+ const projectDir = resolution.projectDir;
239
+ const notes = resolution.note === null ? [] : [resolution.note];
240
+ if (!ACTIONS.includes(action)) {
241
+ return failure(action === "" ? "(缺 action)" : action, projectDir, "action 必须是 start / dump / stop / status(收到:" + JSON.stringify(args.action ?? null) + ")", notes);
242
+ }
243
+ // 这些参数都是可选的(addr 只在 start 时必填),所以只校验"用户真的传了的"那几个:
244
+ // validateToolArgs 会把没传的一律算缺参,直接拿全表调用会误伤 dump/stop/status。
245
+ const passed = [
246
+ { name: "addr", kind: "string" },
247
+ { name: "banner", kind: "string" },
248
+ { name: "projectDir", kind: "string" },
249
+ { name: "binDirs", kind: "string[]" },
250
+ ].filter((spec) => args[spec.name] !== undefined);
251
+ const invalid = passed.length === 0 ? null : validateToolArgs(RTT_TOOL, args, passed);
252
+ if (invalid !== null)
253
+ return failure(action, projectDir, invalid, notes);
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
+ };
329
+ if (action === "start") {
330
+ const addr = readString(args.addr);
331
+ if (addr === undefined)
332
+ return failure(action, projectDir, "start 需要 addr:控制块起始地址(十六进制,例如 0x20000000)", notes);
333
+ const gate = await ensureToolchain(ctx, {
334
+ capability: "debug",
335
+ ...(binDirs === undefined ? {} : { binDirs }),
336
+ envCheck: args.envCheck,
337
+ signal: exec.signal,
338
+ });
339
+ if (!gate.ok && gate.mode === "block") {
340
+ return failure(action, projectDir, gate.message, [...notes, ...gateReportNotes(gate)]);
341
+ }
342
+ const gateNotes = gateReportNotes(gate);
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]);
348
+ }
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) {
366
+ notes.push("复用已有调试会话(tcl 端口 " + String(session.tclPort) + ")");
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;
375
+ const started = await startRtt({
376
+ addr,
377
+ ...(readNumber(args.size) === undefined ? {} : { size: readNumber(args.size) ?? DEFAULT_RTT_SIZE }),
378
+ ...(readString(args.banner) === undefined ? {} : { banner: readString(args.banner) ?? "" }),
379
+ ...(readNumber(args.rttPort) === undefined ? {} : { port: readNumber(args.rttPort) ?? DEFAULT_RTT_PORT }),
380
+ ...(readNumber(args.timeoutMs) === undefined ? {} : { timeoutMs: readNumber(args.timeoutMs) ?? 5_000 }),
381
+ signal: exec.signal,
382
+ });
383
+ const report = baseReport(action, projectDir);
384
+ report.ok = started.ok;
385
+ report.addr = started.addr;
386
+ report.size = started.size;
387
+ report.banner = started.banner;
388
+ report.port = started.port;
389
+ report.durationMs = started.durationMs;
390
+ report.message = started.message;
391
+ report.notes = [...notes, ...gateNotes, ...started.notes];
392
+ report.errors = started.ok ? [] : [started.message];
393
+ snapshotInto(report, rttStatus());
394
+ if (started.probeError !== null)
395
+ report.probeError = started.probeError;
396
+ return { message: started.message, report };
397
+ }
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;
404
+ const dumped = await dumpRtt({
405
+ ...(readNumber(args.seconds) === undefined ? {} : { seconds: readNumber(args.seconds) ?? defaultSeconds }),
406
+ ...(readNumber(args.level) === undefined ? {} : { level: readNumber(args.level) ?? 4 }),
407
+ ...(readNumber(args.maxRecords) === undefined ? {} : { maxRecords: readNumber(args.maxRecords) ?? DEFAULT_MAX_RECORDS }),
408
+ ...(readNumber(args.timeoutMs) === undefined ? {} : { timeoutMs: readNumber(args.timeoutMs) ?? 3_000 }),
409
+ keepNewest: isFollow,
410
+ readFirmwareDrop: true,
411
+ signal: exec.signal,
412
+ });
413
+ const report = baseReport(action, projectDir);
414
+ report.ok = dumped.ok;
415
+ report.durationMs = dumped.durationMs;
416
+ report.records = dumped.records;
417
+ report.dropped = dumped.dropped;
418
+ report.firmwareDropped = dumped.firmwareDropped;
419
+ report.bytes = dumped.bytes;
420
+ report.truncated = dumped.truncated;
421
+ report.stopped = dumped.stopped;
422
+ report.message = dumped.message;
423
+ report.notes = [...notes, ...dumped.notes];
424
+ report.errors = dumped.ok ? [] : [dumped.message];
425
+ snapshotInto(report, rttStatus());
426
+ report.port = dumped.port;
427
+ report.addr = dumped.addr === "" ? report.addr : dumped.addr;
428
+ if (dumped.probeError !== null)
429
+ report.probeError = dumped.probeError;
430
+ return { message: dumped.message, report };
431
+ }
432
+ if (action === "stop") {
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
+ }
441
+ const report = baseReport(action, projectDir);
442
+ report.ok = stopped.ok;
443
+ report.durationMs = stopped.durationMs;
444
+ report.stopped = stopped.stopped;
445
+ report.port = stopped.port;
446
+ report.dropped = stopped.dropped;
447
+ report.bytes = stopped.bytes;
448
+ report.message = stopped.message;
449
+ report.notes = [...notes, ...stopped.notes];
450
+ report.errors = stopped.ok ? [] : [stopped.message];
451
+ snapshotInto(report, rttStatus());
452
+ if (stopped.probeError !== null)
453
+ report.probeError = stopped.probeError;
454
+ return { message: stopped.message, report };
455
+ }
456
+ const snapshot = rttStatus();
457
+ const report = baseReport(action, projectDir);
458
+ report.ok = true;
459
+ report.notes = notes;
460
+ snapshotInto(report, snapshot);
461
+ report.dropped = snapshot.dropped;
462
+ report.bytes = snapshot.bytes;
463
+ report.message = snapshot.running
464
+ ? "RTT 在跑:控制块 " + snapshot.addr + ",通道端口 " + String(snapshot.port) + ",已收 " + String(snapshot.records) + " 条 / " + String(snapshot.bytes) + " 字节" +
465
+ (snapshot.lastError === null ? "" : ";上次出错:" + snapshot.lastError)
466
+ : "RTT 没在跑" + (snapshot.lastError === null ? "" : ";上次出错:" + snapshot.lastError);
467
+ return { message: report.message, report };
468
+ },
469
+ });
470
+ }