dsh-stm32 0.1.1 → 0.1.2

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 (42) hide show
  1. package/README.md +52 -23
  2. package/README_EN.md +50 -21
  3. package/docs/development-notes.md +466 -4
  4. package/docs/reading-guide.md +738 -0
  5. package/lib/commands/register.js +49 -0
  6. package/lib/data/chips.js +134 -4
  7. package/lib/data/clock-f1.js +158 -0
  8. package/lib/data/cmsis-sources.js +211 -42
  9. package/lib/data/f1-ram.generated.js +34 -0
  10. package/lib/data/stm32f1.js +186 -0
  11. package/lib/engine/build.js +115 -16
  12. package/lib/engine/cache.js +56 -0
  13. package/lib/engine/clock-plan.js +608 -0
  14. package/lib/engine/cmake-sources.js +428 -0
  15. package/lib/engine/debug.js +75 -10
  16. package/lib/engine/doctor.js +395 -4
  17. package/lib/engine/fetch.js +174 -30
  18. package/lib/engine/flash.js +95 -6
  19. package/lib/engine/generate.js +11 -0
  20. package/lib/engine/hal-chip.js +230 -0
  21. package/lib/engine/ioc-plan.js +28 -2
  22. package/lib/engine/msys2-install.js +332 -61
  23. package/lib/engine/project-export.js +129 -0
  24. package/lib/engine/register-clock.js +132 -0
  25. package/lib/engine/register-linker.js +129 -0
  26. package/lib/engine/register-template.js +88 -17
  27. package/lib/engine/scaffold.js +104 -28
  28. package/lib/engine/zip.js +142 -0
  29. package/lib/index.js +2 -0
  30. package/lib/skill/stm32-workflow.js +3 -3
  31. package/lib/tools/build.js +12 -0
  32. package/lib/tools/cache.js +39 -8
  33. package/lib/tools/debug.js +7 -0
  34. package/lib/tools/doctor.js +11 -2
  35. package/lib/tools/flash.js +3 -0
  36. package/lib/tools/ioc-plan.js +195 -4
  37. package/lib/tools/project-create.js +26 -1
  38. package/lib/tools/project-export.js +100 -0
  39. package/package.json +5 -3
  40. package/templates/register/CMakeLists.txt +19 -6
  41. package/templates/register/Core/Src/main.c +18 -9
  42. package/templates/scaffold/openocd.cfg +8 -0
@@ -0,0 +1,230 @@
1
+ /**
2
+ * L2.5:HAL 路线的「具体型号 → 工程文件事实」派生。
3
+ *
4
+ * 为什么单独一层:脚手架里原本写死了 C8T6 的四样东西(startup_stm32f103xb.s、
5
+ * 设备宏 STM32F103xB、链接脚本 STM32F103XX_FLASH.ld、demo.ioc 里的 Mcu.CPN)。
6
+ * 要支持 F1 全系,这四样都得按型号算出来。算它们需要的数据来自三处,缺一不可:
7
+ *
8
+ * 1. 容量档 → 启动文件 / 设备宏 / 设备头 / Flash / RAM:src/data/stm32f1.ts 的 resolveF1Chip
9
+ * (上游启动文件是实测出来的事实,别在这里再抄一份)。
10
+ * 2. 型号 → CubeMX 的 db/mcu 分组名(Mcu.Name,带括号,例如 STM32F103R(C-D-E)Tx):
11
+ * 本文件内置分组表,来源是本机 CubeMX db/mcu/*.xml 的真实文件名。
12
+ * 3. 型号 → 工程文件里的名字:具体型号名(STM32F103RCTx)+ _FLASH.ld
13
+ * —— 和 ST 自己 Projects/<board>/SW4STM32/ 下的链接脚本命名一致(实测
14
+ * STM32F103RBTx_FLASH.ld / STM32F107VCTx_FLASH.ld)。
15
+ *
16
+ * 两种「名字」必须分清(.ioc 里同时出现,写错 CubeMX 会认不出芯片):
17
+ * - ProjectManager.DeviceId = Mcu.UserName = 具体型号名 STM32F103C8Tx
18
+ * - Mcu.Name = db/mcu 的分组名 STM32F103C(8-B)Tx
19
+ *
20
+ * 本文件只做纯计算与纯渲染(不读盘、不依赖 CubeMX 是否装了),这样能单测。
21
+ */
22
+ import { resolveF1Chip } from "../data/stm32f1.js";
23
+ /** HAL 路线不给型号时按蓝丸(STM32F103C8T6)建,与历史行为一致。 */
24
+ export const DEFAULT_HAL_MCU = "STM32F103C8T6";
25
+ /**
26
+ * 老工程兼容用的链接脚本名。模板里那份是 C8T6 的(64K/20K),
27
+ * 新工程一律另有 <DeviceId>_FLASH.ld;这个旧名只为「已有工程的 cmake 还指着它」而留。
28
+ */
29
+ export const LEGACY_LINKER_SCRIPT = "STM32F103XX_FLASH.ld";
30
+ /** 模板里写死的 C8T6 事实(渲染时被替换掉;C8T6 本身替换后逐字节不变)。 */
31
+ const TEMPLATE_DEVICE_DEFINE = "STM32F103xB";
32
+ const TEMPLATE_STARTUP = "startup_stm32f103xb.s";
33
+ /** 封装字母 → 引脚数(与 CubeMX db/mcu 的 LQFP48/64/100/144 对应)。 */
34
+ const PIN_COUNT_BY_PACKAGE = { T: 36, C: 48, R: 64, V: 100, Z: 144 };
35
+ /**
36
+ * 型号 → CubeMX db/mcu 分组名用的「容量档分组」表。
37
+ * 键:line(三位数字)→ 封装字母 → 该封装在 db 里真实出现过的分组(升序,靠前的先命中)。
38
+ * 只收 Tx/Ux/Yx 这种带封装后缀的条目;特殊单型号(STM32F103C6Ux、STM32F107VCHx 之类)
39
+ * 走「退回具体型号名」的兜底,不在这里硬编。
40
+ */
41
+ const MCU_NAME_GROUPS = {
42
+ "100": { C: ["4-6", "8-B"], R: ["4-6", "8-B", "C-D-E"], V: ["8-B", "C-D-E"], Z: ["C-D-E"] },
43
+ "101": { C: ["4-6", "8-B"], R: ["4-6", "8-B", "C-D-E", "F-G"], T: ["4-6", "8-B"], V: ["8-B", "C-D-E", "F-G"], Z: ["C-D-E", "F-G"] },
44
+ "102": { C: ["4-6", "8-B"], R: ["4-6", "8-B"] },
45
+ "103": { C: ["4-6", "8-B"], R: ["4-6", "8-B", "C-D-E", "F-G"], T: ["4-6", "8-B"], V: ["8-B", "C-D-E", "F-G"], Z: ["C-D-E", "F-G"] },
46
+ "105": { R: ["8-B-C"], V: ["8-B-C"] },
47
+ "107": { R: ["B-C"], V: ["B-C"] },
48
+ };
49
+ /** 分组标签 → 它覆盖的容量字母。 */
50
+ const GROUP_LETTERS = {
51
+ "4-6": ["4", "6"],
52
+ "8-B": ["8", "B"],
53
+ "C-D-E": ["C", "D", "E"],
54
+ "F-G": ["F", "G"],
55
+ "B-C": ["B", "C"],
56
+ "8-B-C": ["8", "B", "C"],
57
+ };
58
+ /** 型号拆解:STM32F103RCT6 → line 103 / 封装 R / 容量 C / 后缀 T / 温度 6。 */
59
+ const PART_PATTERN = /^STM32F(\d{3})([A-Z])([0-9A-G])([A-Z])?([0-9])?$/u;
60
+ /**
61
+ * 型号 → HAL 路线的芯片事实。
62
+ *
63
+ * 与 resolveF1Chip 的分工:那里回答「启动文件/设备宏/Flash/RAM」,这里再补上
64
+ * 「.ioc 里的名字 + 链接脚本名 + 封装」,并拒绝 HAL 路线没法处理的输入:
65
+ * - 只给容量档(F103:xb):定不了封装、引脚与型号名,HAL 路线必须给完整型号;
66
+ * - RAM 未收录:链接脚本的 RAM 大小不能猜(宁可报错也不生成一个错的内存布局)。
67
+ */
68
+ export function resolveHalChip(input) {
69
+ const raw = (input ?? "").trim();
70
+ const mcu = raw.length === 0 ? DEFAULT_HAL_MCU : raw.toUpperCase();
71
+ const resolved = resolveF1Chip(mcu);
72
+ if (resolved.chip === null) {
73
+ return {
74
+ facts: null,
75
+ reason: resolved.reason +
76
+ "。HAL 路线要完整型号(封装字母要写全),例如 STM32F103C8T6 / STM32F103RCT6 / STM32F107VCT6",
77
+ };
78
+ }
79
+ const chip = resolved.chip;
80
+ const parts = PART_PATTERN.exec(mcu);
81
+ if (parts === null) {
82
+ return {
83
+ facts: null,
84
+ reason: "HAL 路线要完整型号(带封装字母),例如 STM32F103RCT6;" + mcu +
85
+ " 只给了容量档,定不了 .ioc 里的封装与型号名",
86
+ };
87
+ }
88
+ const code = parts[1] ?? "";
89
+ const packageLetter = parts[2] ?? "";
90
+ const suffixLetter = (parts[4] ?? "").length > 0 ? (parts[4] ?? "") : "T";
91
+ if (suffixLetter !== "T" && suffixLetter !== "U" && suffixLetter !== "Y") {
92
+ return {
93
+ facts: null,
94
+ reason: ".ioc 模板只覆盖 T/U/Y 三种封装后缀,认不出 " + suffixLetter + ":" + mcu,
95
+ };
96
+ }
97
+ const flashBytes = chip.flashBytes;
98
+ if (flashBytes === null)
99
+ return { facts: null, reason: "认不出 " + mcu + " 的 Flash 大小,链接脚本没法渲染" };
100
+ const ramBytes = chip.ramBytes;
101
+ if (ramBytes === null) {
102
+ return {
103
+ facts: null,
104
+ reason: (chip.notes.length > 0 ? chip.notes.join(";") + ";" : "") +
105
+ "链接脚本里的 RAM 大小不能猜:先按 CubeMX 的 db/mcu 补上 " + chip.prefix + chip.densityLetter + " 的 RAM 再建",
106
+ };
107
+ }
108
+ const notes = [];
109
+ const pinCount = chip.pinCount ?? PIN_COUNT_BY_PACKAGE[packageLetter] ?? null;
110
+ const deviceId = chip.prefix + packageLetter + chip.densityLetter + suffixLetter + "x";
111
+ // db/mcu 的分组名只在「该封装 + 该后缀确实按分组收录」时成立:
112
+ // Tx 全是分组名;Ux 只有 T 封装分组(STM32F103T(8-B)Ux),C 封装是单型号(STM32F103C6Ux);
113
+ // Yx 只有 R 封装分组(STM32F103R(C-D-E)Yx)。
114
+ const grouped = suffixLetter === "T" || (suffixLetter === "U" && packageLetter === "T") || (suffixLetter === "Y" && packageLetter === "R");
115
+ let mcuName = deviceId;
116
+ if (grouped) {
117
+ const groups = MCU_NAME_GROUPS[code]?.[packageLetter] ?? [];
118
+ const hit = groups.find((entry) => (GROUP_LETTERS[entry] ?? []).includes(chip.densityLetter));
119
+ if (hit === undefined) {
120
+ notes.push("CubeMX 的 db/mcu 里没有 " + deviceId + " 这一分组名,Mcu.Name 按具体型号名写(CubeMX 打不开 .ioc 的话把型号换成同容量档的常见型号)");
121
+ }
122
+ else {
123
+ mcuName = chip.prefix + packageLetter + "(" + hit + ")" + suffixLetter + "x";
124
+ }
125
+ }
126
+ const packageKind = suffixLetter === "U" ? "VFQFPN" : suffixLetter === "Y" ? "WLCSP" : "LQFP";
127
+ const packageName = pinCount === null ? packageKind : packageKind + String(pinCount);
128
+ return {
129
+ facts: {
130
+ mcu,
131
+ deviceId,
132
+ mcuName,
133
+ packageName,
134
+ pinCount,
135
+ startup: chip.startup,
136
+ deviceDefine: chip.deviceDefine,
137
+ deviceHeader: chip.deviceHeader,
138
+ flashBytes,
139
+ ramBytes,
140
+ linkerScript: deviceId + "_FLASH.ld",
141
+ // 旧名只有蓝丸(C8T6 的 64K Flash / 20K RAM)对得上;别的芯片写旧名 = 一份骗人的内存布局。
142
+ keepLegacyLinkerScript: deviceId === "STM32F103C8Tx" && flashBytes === 64 * 1024 && ramBytes === 20 * 1024,
143
+ notes,
144
+ },
145
+ reason: "",
146
+ };
147
+ }
148
+ /** 一句话说清这款芯片会变成什么(报告/warning 里用)。 */
149
+ export function describeHalChip(facts) {
150
+ return (facts.mcu + "(" + facts.deviceId + "," + facts.packageName + "):启动文件 " + facts.startup +
151
+ "、设备宏 " + facts.deviceDefine + "、链接脚本 " + facts.linkerScript);
152
+ }
153
+ function kiloText(bytes) {
154
+ return String(Math.round(bytes / 1024));
155
+ }
156
+ /**
157
+ * 链接脚本按芯片渲染。
158
+ *
159
+ * 只改三处(其余 SECTIONS 与芯片无关;F1 全是 RAM 0x20000000 / FLASH 0x08000000):
160
+ * - 头注释里的型号名
161
+ * - 头注释里的 "NKbytes FLASH and MKbytes RAM"
162
+ * - MEMORY 里的 LENGTH 值
163
+ * 模板缺任何一处都抛错:宁可建不出来,也不生成一个 Flash/RAM 是错的链接脚本。
164
+ */
165
+ export function renderLinkerScript(template, facts) {
166
+ const flashK = kiloText(facts.flashBytes);
167
+ const ramK = kiloText(facts.ramBytes);
168
+ const abstract = /(\*\*\s+Abstract\s+:\s+Linker script for )[^\r\n]+/u;
169
+ const sizes = /\d+Kbytes FLASH and \d+Kbytes RAM/u;
170
+ const ramLine = /(RAM \(xrw\)[ \t]*:[ \t]*ORIGIN = 0x20000000,[ \t]*LENGTH = )[^\r\n]+/u;
171
+ const flashLine = /(FLASH \(rx\)[ \t]*:[ \t]*ORIGIN = 0x8000000,[ \t]*LENGTH = )[^\r\n]+/u;
172
+ for (const [pattern, what] of [
173
+ [abstract, "Abstract 行(Linker script for …)"],
174
+ [sizes, "『NKbytes FLASH and MKbytes RAM』行"],
175
+ [ramLine, "MEMORY 里的 RAM 行"],
176
+ [flashLine, "MEMORY 里的 FLASH 行"],
177
+ ]) {
178
+ if (!pattern.test(template)) {
179
+ throw new Error("链接脚本模板缺 " + what + ",没法按芯片渲染(模板被改过?)");
180
+ }
181
+ }
182
+ let text = template.replace(abstract, (_match, head) => head + facts.deviceId + " series");
183
+ text = text.replace(sizes, (_match) => flashK + "Kbytes FLASH and " + ramK + "Kbytes RAM");
184
+ text = text.replace(ramLine, (_match, head) => head + ramK + "K");
185
+ text = text.replace(flashLine, (_match, head) => head + flashK + "K");
186
+ return text;
187
+ }
188
+ /**
189
+ * .ioc 按芯片渲染:只改这五行,引脚/时钟树沿用模板的最小集(PA13/PA14 SWD + 一个 GPIO)。
190
+ * 缺键就抛错——没把握的 .ioc 宁可不写,写一份 CubeMX 认不出的配置更糟。
191
+ */
192
+ export function renderIoc(template, facts) {
193
+ const values = [
194
+ ["Mcu.CPN", facts.mcu],
195
+ ["Mcu.Name", facts.mcuName],
196
+ ["Mcu.Package", facts.packageName],
197
+ ["Mcu.UserName", facts.deviceId],
198
+ ["ProjectManager.DeviceId", facts.deviceId],
199
+ ];
200
+ const eol = template.includes("\r\n") ? "\r\n" : "\n";
201
+ const seen = new Set();
202
+ const lines = template.split(/\r?\n/u).map((line) => {
203
+ for (const [key, value] of values) {
204
+ if (line.startsWith(key + "=")) {
205
+ seen.add(key);
206
+ return key + "=" + value;
207
+ }
208
+ }
209
+ return line;
210
+ });
211
+ const missing = values.map(([key]) => key).filter((key) => !seen.has(key));
212
+ if (missing.length > 0) {
213
+ throw new Error(".ioc 模板缺这些键:" + missing.join("、") + "(模板被改过?)");
214
+ }
215
+ return lines.join(eol);
216
+ }
217
+ /** 工具链 cmake 文件里的 -T 指向渲染后的链接脚本名。 */
218
+ export function pointLinkerFlagAt(text, facts) {
219
+ if (!text.includes(LEGACY_LINKER_SCRIPT)) {
220
+ throw new Error("工具链 cmake 文件里找不到 -T …" + LEGACY_LINKER_SCRIPT + "(模板被改过?)");
221
+ }
222
+ return text.split(LEGACY_LINKER_SCRIPT).join(facts.linkerScript);
223
+ }
224
+ /** cmake/stm32cubemx/CMakeLists.txt 里的设备宏与启动文件名按芯片替换。 */
225
+ export function renderStartupAndDefine(text, facts) {
226
+ if (!text.includes(TEMPLATE_DEVICE_DEFINE) || !text.includes(TEMPLATE_STARTUP)) {
227
+ throw new Error("cmake/stm32cubemx/CMakeLists.txt 里找不到 " + TEMPLATE_DEVICE_DEFINE + " 或 " + TEMPLATE_STARTUP + "(模板被改过?)");
228
+ }
229
+ return text.split(TEMPLATE_DEVICE_DEFINE).join(facts.deviceDefine).split(TEMPLATE_STARTUP).join(facts.startup);
230
+ }
@@ -15,6 +15,7 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameS
15
15
  import { basename, isAbsolute, join, resolve, sep } from "node:path";
16
16
  import { findIocFile, STATE_DIR } from "./generate.js";
17
17
  import { parseIocEntries, summarizeIoc } from "./ioc.js";
18
+ import { emptyClockPlan, formatHz, planClock } from "./clock-plan.js";
18
19
  import { isKnownPin } from "../data/chips.js";
19
20
  export function sha256Hex(text) {
20
21
  return createHash("sha256").update(text, "utf8").digest("hex");
@@ -235,6 +236,7 @@ export function planIocChanges(request) {
235
236
  const empty = {
236
237
  ok: false, projectDir, iocPath: iocPath ?? "", planId: "", sourceSha256: "", candidateSha256: "",
237
238
  changes: [], warnings: [], notes: [], errors: [], message: "",
239
+ clockPlan: emptyClockPlan("还没读到 .ioc,时钟没算"),
238
240
  };
239
241
  if (iocPath === null || !existsSync(iocPath)) {
240
242
  return { ...empty, errors: ["找不到 .ioc(工程根目录下必须有且只有一个 *.ioc,或用 iocPath 指定)"], message: "没生成计划:找不到 .ioc" };
@@ -282,6 +284,29 @@ export function planIocChanges(request) {
282
284
  }
283
285
  after.delete(trimmed);
284
286
  }
287
+ // 时钟:.ioc 里的一段键,和 entries 一起算(不单开工具)。复用 after,所以同一调用里的
288
+ // entries(例如 RCC.MCOSource)对时钟规划是可见的;规划出的键也是"候选文件"的一部分。
289
+ const clockPlan = request.clock === undefined
290
+ ? planClock(undefined, { entries: after })
291
+ : planClock(request.clock, { entries: after });
292
+ if (request.clock === undefined) {
293
+ const achieved = clockPlan.achieved;
294
+ notes.push("时钟(只读,未请求改动):SYSCLK " + formatHz(achieved.sysclkHz) +
295
+ " / APB1 " + formatHz(achieved.apb1Hz) +
296
+ " / APB2 " + formatHz(achieved.apb2Hz) +
297
+ " / ADC " + formatHz(achieved.adcHz));
298
+ }
299
+ else {
300
+ warnings.push(...clockPlan.warnings);
301
+ if (clockPlan.note !== "")
302
+ notes.push("时钟:" + clockPlan.note);
303
+ for (const item of clockPlan.entries)
304
+ after.set(item.key, item.value);
305
+ for (const key of clockPlan.unset)
306
+ after.delete(key);
307
+ for (const error of clockPlan.errors)
308
+ errors.push("时钟:" + error);
309
+ }
285
310
  // 安全闸:这两条是踩过坑的硬约束,不满足就不给 plan。
286
311
  const candidateText = renderIocText(source, compareEntries(before, after));
287
312
  const summary = summarizeIoc(candidateText, iocPath);
@@ -292,11 +317,11 @@ export function planIocChanges(request) {
292
317
  errors.push("改完之后 ProjectManager.KeepUserCode=false:重新生成会丢掉 USER CODE 区,拒绝。");
293
318
  }
294
319
  if (errors.length > 0) {
295
- return { ...empty, iocPath, sourceSha256, errors, warnings, notes, message: "没生成计划:" + errors[0] };
320
+ return { ...empty, iocPath, sourceSha256, errors, warnings, notes, clockPlan, message: "没生成计划:" + errors[0] };
296
321
  }
297
322
  const changes = compareEntries(before, after);
298
323
  if (changes.length === 0) {
299
- return { ...empty, iocPath, sourceSha256, warnings, notes, message: "没有变化:这些键本来就是这个值" };
324
+ return { ...empty, iocPath, sourceSha256, warnings, notes, clockPlan, message: "没有变化:这些键本来就是这个值" };
300
325
  }
301
326
  const candidateSha256 = sha256Hex(candidateText);
302
327
  const planId = sha256Hex(sourceSha256 + "\n" + candidateSha256).slice(0, 16);
@@ -323,6 +348,7 @@ export function planIocChanges(request) {
323
348
  errors: [],
324
349
  message: "已生成计划 " + planId + ":" + String(changes.length) + " 个键变化(新增 " + String(added) + "、删除 " + String(removedCount) + "、修改 " + String(changes.length - added - removedCount) + ")",
325
350
  summaryAfter: summary,
351
+ clockPlan,
326
352
  };
327
353
  }
328
354
  export function loadPlan(projectDir, planId) {