dsh-stm32 0.1.0 → 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.
- package/README.md +127 -29
- package/README_EN.md +125 -29
- package/client/client.js +682 -0
- package/docs/development-notes.md +1385 -5
- package/docs/logic-audit.md +607 -0
- package/docs/reading-guide.md +738 -0
- package/lib/client.js +682 -0
- package/lib/commands/register.js +214 -12
- package/lib/data/chips.js +134 -4
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +316 -0
- package/lib/data/f1-ram.generated.js +34 -0
- package/lib/data/firmware-packages.js +352 -0
- package/lib/data/install-guides.js +190 -0
- package/lib/data/search-roots.js +135 -15
- package/lib/data/stm32f1.js +186 -0
- package/lib/data/toolchain-config.js +310 -0
- package/lib/engine/build.js +121 -16
- package/lib/engine/cache.js +336 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/code-patch.js +18 -6
- package/lib/engine/debug-session.js +163 -4
- package/lib/engine/debug.js +84 -19
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +287 -0
- package/lib/engine/firmware-install.js +668 -0
- package/lib/engine/flash.js +145 -15
- package/lib/engine/fs-longpath.js +107 -0
- package/lib/engine/generate-cache.js +118 -0
- package/lib/engine/generate-script.js +30 -8
- package/lib/engine/generate.js +296 -14
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +47 -8
- package/lib/engine/msys2-install.js +1870 -0
- package/lib/engine/probe.js +57 -6
- package/lib/engine/project-export.js +129 -0
- package/lib/engine/register-clock.js +132 -0
- package/lib/engine/register-linker.js +129 -0
- package/lib/engine/register-template.js +449 -0
- package/lib/engine/regs.js +18 -4
- package/lib/engine/route-plan.js +553 -0
- package/lib/engine/scaffold.js +303 -72
- package/lib/engine/subprocess-runner.js +2 -0
- package/lib/engine/tar.js +250 -0
- package/lib/engine/text-file.js +150 -0
- package/lib/engine/thirdparty.js +243 -0
- package/lib/engine/tool-env.js +51 -0
- package/lib/engine/toolchain-gate.js +386 -0
- package/lib/engine/vscode-config.js +99 -0
- package/lib/engine/web-api.js +375 -0
- package/lib/engine/web-routes.js +100 -0
- package/lib/engine/xcube-catalog.js +102 -0
- package/lib/engine/xcube.js +254 -0
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +44 -2
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/build.js +55 -3
- package/lib/tools/cache.js +250 -0
- package/lib/tools/code-patch.js +29 -2
- package/lib/tools/debug-session.js +56 -14
- package/lib/tools/debug.js +43 -2
- package/lib/tools/doctor.js +16 -3
- package/lib/tools/env-install.js +472 -0
- package/lib/tools/env-probe.js +6 -2
- package/lib/tools/firmware-install.js +255 -0
- package/lib/tools/flash.js +41 -2
- package/lib/tools/generate.js +96 -10
- package/lib/tools/ioc-apply.js +27 -11
- package/lib/tools/ioc-inspect.js +4 -2
- package/lib/tools/ioc-plan.js +209 -11
- package/lib/tools/project-create.js +229 -21
- package/lib/tools/project-dir.js +95 -0
- package/lib/tools/project-export.js +100 -0
- package/lib/tools/regs.js +82 -7
- package/lib/tools/route-plan.js +467 -0
- package/package.json +11 -4
- package/templates/register/CMakeLists.txt +52 -0
- package/templates/register/Core/Src/main.c +72 -0
- package/templates/scaffold/openocd.cfg +8 -0
- package/templates/scaffold/vscode/launch.json +8 -6
- package/templates/scaffold/vscode/settings.json +5 -11
|
@@ -1,30 +1,53 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* L3:stm32_project_create —— 空目录 → 可编译工程骨架(一条命令)。
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
4
|
+
* 两条路线(用户 2026-10-24 决定:不能只有 HAL 一条路):
|
|
5
|
+
* route=hal(默认):拷模板 + 从本机 CubeMX 固件包复制 Drivers/startup/system,
|
|
6
|
+
* Core/ 下的 C 源接着交给 stm32_generate(CubeMX 无头生成)。
|
|
7
|
+
* —— 复杂外设(USB/ETH/FDCAN/SDIO…)只有这条路。
|
|
8
|
+
* route=register: 不用 CubeMX、不用固件包;CMSIS 设备头与启动文件从**下载缓存**取
|
|
9
|
+
* (第一次联网、之后复用),main.c 是寄存器版示例,生成即可编译。
|
|
10
|
+
* —— 小而定型的外设(GPIO/USART 轮询/TIM/EXTI/单通道 ADC)够用。
|
|
11
|
+
*
|
|
12
|
+
* 两条路线的门禁不同:HAL 路线要 CubeMX(capability=generate),
|
|
13
|
+
* 寄存器路线只要编译工具链(capability=build)——这正是"缺 CubeMX 也能干活"的落点。
|
|
7
14
|
*/
|
|
8
|
-
import { createProjectScaffold } from "../engine/scaffold.js";
|
|
15
|
+
import { createProjectScaffold, preflightTarget } from "../engine/scaffold.js";
|
|
16
|
+
import { createRegisterProject } from "../engine/register-template.js";
|
|
17
|
+
import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
|
|
9
18
|
import { resolveSearchConfig } from "../data/search-roots.js";
|
|
19
|
+
import { validateToolArgs } from "./project-dir.js";
|
|
10
20
|
export const PROJECT_CREATE_TOOL = "stm32_project_create";
|
|
11
21
|
const reportSchema = {
|
|
12
22
|
type: "object",
|
|
13
23
|
additionalProperties: false,
|
|
14
24
|
properties: {
|
|
15
25
|
ok: { type: "boolean" },
|
|
26
|
+
route: { type: "string", enum: ["hal", "register"] },
|
|
16
27
|
targetDir: { type: "string" },
|
|
17
28
|
projectName: { type: "string" },
|
|
18
|
-
|
|
19
|
-
firmwareRoot: { type: "string" },
|
|
20
|
-
templateDir: { type: "string" },
|
|
29
|
+
message: { type: "string" },
|
|
21
30
|
templateFiles: { type: "number" },
|
|
22
31
|
driverFiles: { type: "number" },
|
|
23
32
|
durationMs: { type: "number" },
|
|
24
33
|
warnings: { type: "array", items: { type: "string" } },
|
|
25
|
-
|
|
34
|
+
iocPath: { type: "string" },
|
|
35
|
+
firmwareRoot: { type: "string" },
|
|
36
|
+
templateDir: { type: "string" },
|
|
37
|
+
mcu: { type: "string" },
|
|
38
|
+
family: { type: "string" },
|
|
39
|
+
startup: { type: "string" },
|
|
40
|
+
deviceDefine: { type: "string" },
|
|
41
|
+
linkerScript: { type: "string" },
|
|
42
|
+
deviceId: { type: "string" },
|
|
43
|
+
flashBytes: { type: "number" },
|
|
44
|
+
ramBytes: { type: "number" },
|
|
45
|
+
sysclkHz: { type: "number" },
|
|
46
|
+
clockSummary: { type: "string" },
|
|
47
|
+
cacheDir: { type: "string" },
|
|
48
|
+
cacheHit: { type: "boolean" },
|
|
26
49
|
},
|
|
27
|
-
required: ["ok", "
|
|
50
|
+
required: ["ok", "route", "targetDir", "projectName", "message", "templateFiles", "driverFiles", "durationMs", "warnings"],
|
|
28
51
|
};
|
|
29
52
|
export const outputSchema = {
|
|
30
53
|
type: "object",
|
|
@@ -35,32 +58,77 @@ export const outputSchema = {
|
|
|
35
58
|
},
|
|
36
59
|
required: ["message", "report"],
|
|
37
60
|
};
|
|
38
|
-
|
|
61
|
+
/** 门禁档位参数:三个档位的说明文字与 build 工具保持一致。 */
|
|
62
|
+
const ENV_CHECK_SCHEMA = {
|
|
63
|
+
type: "string",
|
|
64
|
+
enum: ["block", "warn", "off"],
|
|
65
|
+
description: "工具链检查:block 缺件就拒绝(默认)、warn 只警告、off 不检查",
|
|
66
|
+
};
|
|
67
|
+
export function formatProjectReport(report) {
|
|
39
68
|
const lines = [];
|
|
40
|
-
|
|
69
|
+
const routeLabel = report.route === "register" ? "寄存器版" : "HAL 版";
|
|
70
|
+
lines.push((report.ok ? "骨架已建好(" + routeLabel + ")" : "建骨架失败(" + routeLabel + ")") + ":" + report.message);
|
|
41
71
|
if (report.ok) {
|
|
42
72
|
lines.push("工程:" + report.projectName + " → " + report.targetDir);
|
|
43
|
-
lines.push("文件:" + String(report.templateFiles) + " 个工程文件 + " + String(report.driverFiles) + "
|
|
44
|
-
|
|
45
|
-
|
|
73
|
+
lines.push("文件:" + String(report.templateFiles) + " 个工程文件 + " + String(report.driverFiles) + " 个驱动源文件");
|
|
74
|
+
if (report.route === "hal" && report.mcu !== undefined) {
|
|
75
|
+
lines.push("芯片:" + report.mcu + ",启动文件 " + (report.startup ?? "") + ",设备宏 " + (report.deviceDefine ?? "") +
|
|
76
|
+
",链接脚本 " + (report.linkerScript ?? ""));
|
|
77
|
+
}
|
|
78
|
+
if (report.route === "hal" && report.iocPath !== undefined)
|
|
79
|
+
lines.push(".ioc:" + report.iocPath);
|
|
80
|
+
if (report.route === "hal" && report.firmwareRoot !== undefined)
|
|
46
81
|
lines.push("固件包:" + report.firmwareRoot);
|
|
82
|
+
if (report.route === "register") {
|
|
83
|
+
lines.push("芯片:" + (report.mcu ?? "") + "(" + (report.family ?? "") + "),启动文件 " + (report.startup ?? "") + ",设备宏 " + (report.deviceDefine ?? ""));
|
|
84
|
+
lines.push("模板:" + (report.cacheHit === true ? "复用缓存" : "本次下载") + (report.cacheDir === undefined ? "" : "(" + report.cacheDir + ")"));
|
|
85
|
+
}
|
|
47
86
|
}
|
|
48
87
|
for (const warning of report.warnings)
|
|
49
88
|
lines.push("· " + warning);
|
|
50
89
|
return lines;
|
|
51
90
|
}
|
|
91
|
+
/** 门禁拒绝时的报告:targetDir 保持参数值,好让用户知道"本来要建在哪"。 */
|
|
92
|
+
function blockedReport(targetDir, projectName, route, gate) {
|
|
93
|
+
return {
|
|
94
|
+
ok: false,
|
|
95
|
+
route,
|
|
96
|
+
targetDir,
|
|
97
|
+
projectName,
|
|
98
|
+
message: gate.message,
|
|
99
|
+
templateFiles: 0,
|
|
100
|
+
driverFiles: 0,
|
|
101
|
+
durationMs: 0,
|
|
102
|
+
warnings: gateReportNotes(gate),
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
function normalizeRoute(value) {
|
|
106
|
+
const text = (value ?? "hal").trim().toLowerCase();
|
|
107
|
+
if (text === "hal" || text === "cube" || text === "cubemx")
|
|
108
|
+
return "hal";
|
|
109
|
+
if (text === "register" || text === "reg" || text === "bare")
|
|
110
|
+
return "register";
|
|
111
|
+
return null;
|
|
112
|
+
}
|
|
52
113
|
export function registerProjectCreate(ctx) {
|
|
53
114
|
ctx.tools.register({
|
|
54
115
|
name: PROJECT_CREATE_TOOL,
|
|
55
|
-
description: "空目录 → 可编译的
|
|
116
|
+
description: "空目录 → 可编译的 STM32 工程骨架。route=hal(默认):拷 CMake 工程文件、链接脚本、.ioc 与 .vscode,并从本机 CubeMX 固件包复制 Drivers/、startup、system(Core/ 的 C 源还要 stm32_generate 生成,要 CubeMX)。route=register:不用 CubeMX、不用固件包,CMSIS 设备头与启动文件从下载缓存取(第一次联网、之后复用),直接给出寄存器版 main.c,建完即可编译(需要 gcc/cmake/ninja)。目标目录非空时默认拒绝。",
|
|
56
117
|
parameters: {
|
|
57
118
|
type: "object",
|
|
58
119
|
additionalProperties: false,
|
|
59
120
|
properties: {
|
|
60
121
|
targetDir: { type: "string", description: "新工程目录(可以是还不存在的路径)。" },
|
|
122
|
+
route: { type: "string", enum: ["hal", "register"], description: "hal(默认,要 CubeMX 固件包)或 register(寄存器版,不要 CubeMX)" },
|
|
61
123
|
projectName: { type: "string", description: "工程名(C 标识符);缺省取目录名。" },
|
|
62
|
-
|
|
63
|
-
|
|
124
|
+
mcu: {
|
|
125
|
+
type: "string",
|
|
126
|
+
description: "芯片型号,例如 STM32F103C8T6 / STM32F103RCT6 / STM32F107VCT6(两条路线都吃)。route=hal:决定启动文件、设备宏与链接脚本(按 <DeviceId>_FLASH.ld 命名),缺省 STM32F103C8T6;route=register:决定启动文件与设备宏,缺省按 F103C8T6 处理。",
|
|
127
|
+
},
|
|
128
|
+
family: { type: "string", description: "只给族时写这里,例如 F1(route=register;按中容量档处理)。" },
|
|
129
|
+
firmwarePackage: { type: "string", description: "CubeMX 固件包目录名,默认 STM32Cube_FW_F1_V1.8.7(只 route=hal 用)。" },
|
|
130
|
+
cubeMxRoots: { type: "array", items: { type: "string" }, description: "STM32CubeMX 安装根目录候选(固件包在 <root>/Repository 下);缺省用默认值/环境变量(只 route=hal 用)。" },
|
|
131
|
+
envCheck: ENV_CHECK_SCHEMA,
|
|
64
132
|
overwrite: { type: "boolean", description: "目标目录非空时是否继续(默认 false)。" },
|
|
65
133
|
},
|
|
66
134
|
required: ["targetDir"],
|
|
@@ -71,20 +139,160 @@ export function registerProjectCreate(ctx) {
|
|
|
71
139
|
schema: outputSchema,
|
|
72
140
|
render: (_args, value) => {
|
|
73
141
|
const typed = value;
|
|
74
|
-
return [{ type: "text", text:
|
|
142
|
+
return [{ type: "text", text: formatProjectReport(typed.report).join("\n") }];
|
|
75
143
|
},
|
|
76
144
|
},
|
|
77
|
-
async execute(rawArgs,
|
|
145
|
+
async execute(rawArgs, exec) {
|
|
78
146
|
const args = rawArgs ?? {};
|
|
147
|
+
// 洞 C:缺 targetDir 时以前会带着 undefined 一路走下去,宿主只报 "value is not lossless JSON"。
|
|
148
|
+
const invalid = validateToolArgs(PROJECT_CREATE_TOOL, args, [
|
|
149
|
+
{ name: "targetDir", kind: "string" },
|
|
150
|
+
]);
|
|
151
|
+
if (invalid !== null) {
|
|
152
|
+
return {
|
|
153
|
+
message: invalid,
|
|
154
|
+
report: {
|
|
155
|
+
ok: false,
|
|
156
|
+
route: "hal",
|
|
157
|
+
targetDir: typeof args.targetDir === "string" ? args.targetDir : "",
|
|
158
|
+
projectName: args.projectName ?? "",
|
|
159
|
+
message: invalid,
|
|
160
|
+
templateFiles: 0,
|
|
161
|
+
driverFiles: 0,
|
|
162
|
+
durationMs: 0,
|
|
163
|
+
warnings: [invalid],
|
|
164
|
+
},
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
const route = normalizeRoute(args.route);
|
|
168
|
+
if (route === null) {
|
|
169
|
+
const message = "route 只能是 hal 或 register(收到:" + String(args.route) + ")。";
|
|
170
|
+
return {
|
|
171
|
+
message,
|
|
172
|
+
report: {
|
|
173
|
+
ok: false,
|
|
174
|
+
route: "hal",
|
|
175
|
+
targetDir: args.targetDir,
|
|
176
|
+
projectName: args.projectName ?? "",
|
|
177
|
+
message,
|
|
178
|
+
templateFiles: 0,
|
|
179
|
+
driverFiles: 0,
|
|
180
|
+
durationMs: 0,
|
|
181
|
+
warnings: [message],
|
|
182
|
+
},
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
// 先判目标目录能不能写,再谈"要不要装工具":顺序反过来的话,用户会先被要求装 CubeMX,
|
|
186
|
+
// 装完才发现目录非空(HAL 路线还可能发现里面有份 .ioc)——白折腾一趟。
|
|
187
|
+
// 判定逻辑与引擎共用同一份(preflightTarget),不在这里另写一套。
|
|
188
|
+
const refusal = preflightTarget({
|
|
189
|
+
targetDir: args.targetDir,
|
|
190
|
+
route,
|
|
191
|
+
...(args.projectName === undefined ? {} : { projectName: args.projectName }),
|
|
192
|
+
...(args.overwrite === undefined ? {} : { overwrite: args.overwrite }),
|
|
193
|
+
});
|
|
194
|
+
if (refusal !== null) {
|
|
195
|
+
return {
|
|
196
|
+
message: refusal,
|
|
197
|
+
report: {
|
|
198
|
+
ok: false,
|
|
199
|
+
route,
|
|
200
|
+
targetDir: args.targetDir,
|
|
201
|
+
projectName: args.projectName ?? "",
|
|
202
|
+
message: refusal,
|
|
203
|
+
templateFiles: 0,
|
|
204
|
+
driverFiles: 0,
|
|
205
|
+
durationMs: 0,
|
|
206
|
+
warnings: [refusal],
|
|
207
|
+
},
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
// 门禁:两条路线要的东西不一样。
|
|
211
|
+
// register(寄存器版)建完就能编译 → 按 build 能力查 gcc/cmake/ninja。
|
|
212
|
+
// hal(默认)这一步**只拷文件**(CMake 工程文件 / 链接脚本 / Drivers),既不需要
|
|
213
|
+
// STM32CubeMX 启动器,也不需要它的内置 JRE,所以以前用 generate 能力来的门禁是过度的:
|
|
214
|
+
// 用户会被要求装一整套 GUI 才能拷几个文件。缺固件包由 scaffold 自己报(会列出找过的路径)。
|
|
215
|
+
const gate = route === "register"
|
|
216
|
+
? await ensureToolchain(ctx, {
|
|
217
|
+
capability: "build",
|
|
218
|
+
...(args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots }),
|
|
219
|
+
envCheck: args.envCheck,
|
|
220
|
+
signal: exec.signal,
|
|
221
|
+
})
|
|
222
|
+
: null;
|
|
223
|
+
if (gate !== null && !gate.ok && gate.mode === "block") {
|
|
224
|
+
const blocked = blockedReport(args.targetDir, args.projectName ?? "", route, gate);
|
|
225
|
+
return { message: blocked.message, report: blocked };
|
|
226
|
+
}
|
|
227
|
+
if (route === "register") {
|
|
228
|
+
const report = await createRegisterProject({
|
|
229
|
+
targetDir: args.targetDir,
|
|
230
|
+
...(args.projectName === undefined ? {} : { projectName: args.projectName }),
|
|
231
|
+
...(args.mcu === undefined ? {} : { mcu: args.mcu }),
|
|
232
|
+
...(args.family === undefined ? {} : { family: args.family }),
|
|
233
|
+
...(args.overwrite === undefined ? {} : { overwrite: args.overwrite }),
|
|
234
|
+
onProgress: () => undefined,
|
|
235
|
+
});
|
|
236
|
+
const normalized = {
|
|
237
|
+
ok: report.ok,
|
|
238
|
+
route: "register",
|
|
239
|
+
targetDir: report.targetDir,
|
|
240
|
+
projectName: report.projectName,
|
|
241
|
+
message: report.message,
|
|
242
|
+
templateFiles: report.templateFiles,
|
|
243
|
+
driverFiles: report.driverFiles,
|
|
244
|
+
durationMs: report.durationMs,
|
|
245
|
+
warnings: report.warnings,
|
|
246
|
+
mcu: report.mcu,
|
|
247
|
+
family: report.family,
|
|
248
|
+
startup: report.startup,
|
|
249
|
+
deviceDefine: report.deviceDefine,
|
|
250
|
+
// 两条路线的报告字段对齐(HAL 与寄存器都能看到链接脚本、器件代号与容量)。
|
|
251
|
+
linkerScript: report.linkerScript,
|
|
252
|
+
deviceId: report.deviceId,
|
|
253
|
+
flashBytes: report.flashBytes,
|
|
254
|
+
ramBytes: report.ramBytes,
|
|
255
|
+
sysclkHz: report.sysclkHz,
|
|
256
|
+
clockSummary: report.clockSummary,
|
|
257
|
+
cacheDir: report.cacheRoot,
|
|
258
|
+
cacheHit: report.cacheHit,
|
|
259
|
+
};
|
|
260
|
+
if (gate !== null && !gate.ok)
|
|
261
|
+
normalized.warnings.unshift(gate.message);
|
|
262
|
+
return { message: normalized.message, report: normalized };
|
|
263
|
+
}
|
|
79
264
|
const config = resolveSearchConfig(process.env, args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots });
|
|
80
|
-
const
|
|
265
|
+
const scaffold = createProjectScaffold({
|
|
81
266
|
targetDir: args.targetDir,
|
|
82
267
|
...(args.projectName === undefined ? {} : { projectName: args.projectName }),
|
|
268
|
+
...(args.mcu === undefined ? {} : { mcu: args.mcu }),
|
|
83
269
|
...(args.firmwarePackage === undefined ? {} : { firmwarePackage: args.firmwarePackage }),
|
|
84
270
|
...(args.overwrite === undefined ? {} : { overwrite: args.overwrite }),
|
|
85
271
|
cubeMxRoots: config.cubeMxRoots,
|
|
272
|
+
binDirs: config.binDirs,
|
|
86
273
|
});
|
|
87
|
-
|
|
274
|
+
// ScaffoldReport 没有 notes 字段,warn 档的警告并进 warnings(卡片照样打出来)。
|
|
275
|
+
if (gate !== null && !gate.ok)
|
|
276
|
+
scaffold.warnings.unshift(gate.message);
|
|
277
|
+
const halReport = {
|
|
278
|
+
ok: scaffold.ok,
|
|
279
|
+
route: "hal",
|
|
280
|
+
targetDir: scaffold.targetDir,
|
|
281
|
+
projectName: scaffold.projectName,
|
|
282
|
+
message: scaffold.message,
|
|
283
|
+
templateFiles: scaffold.templateFiles,
|
|
284
|
+
driverFiles: scaffold.driverFiles,
|
|
285
|
+
durationMs: scaffold.durationMs,
|
|
286
|
+
warnings: scaffold.warnings,
|
|
287
|
+
iocPath: scaffold.iocPath,
|
|
288
|
+
...(scaffold.firmwareRoot === undefined ? {} : { firmwareRoot: scaffold.firmwareRoot }),
|
|
289
|
+
templateDir: scaffold.templateDir,
|
|
290
|
+
...(scaffold.mcu === undefined ? {} : { mcu: scaffold.mcu }),
|
|
291
|
+
...(scaffold.startup === undefined ? {} : { startup: scaffold.startup }),
|
|
292
|
+
...(scaffold.deviceDefine === undefined ? {} : { deviceDefine: scaffold.deviceDefine }),
|
|
293
|
+
...(scaffold.linkerScript === undefined ? {} : { linkerScript: scaffold.linkerScript }),
|
|
294
|
+
};
|
|
295
|
+
return { message: halReport.message, report: halReport };
|
|
88
296
|
},
|
|
89
297
|
});
|
|
90
298
|
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 工具入口的两个共用动作:定"工程目录"、校验必填参数。
|
|
3
|
+
*
|
|
4
|
+
* 洞 A(真缺陷):以前每个工具都写 args.projectDir ?? process.cwd(),而插件宿主进程的 cwd 是
|
|
5
|
+
* profile 目录(例如 C:\\Users\\<用户>\\.dsh\\profiles\\desktop),于是省略 projectDir 时会去检查
|
|
6
|
+
* 一个根本不存在的"工程",还可能照样报 ok。这里改成先问宿主的 workingDirectory 服务(会话工作
|
|
7
|
+
* 目录 = 用户在 IDE 里打开的工程),只有宿主没这个服务或调用失败时才退回 process.cwd(),并且把
|
|
8
|
+
* "退回了"写进报告 notes,让用户知道该显式传 projectDir。
|
|
9
|
+
*
|
|
10
|
+
* 洞 C:参数名写错(例如把 file/block/code 写成 edits)时,报告的必需字段会是 undefined,宿主
|
|
11
|
+
* 序列化时直接抛 "returned invalid output: value is not lossless JSON",真正原因被淹没。入口先
|
|
12
|
+
* 校验,缺参数就回一句中文说明,报告字段一律填默认值。
|
|
13
|
+
*/
|
|
14
|
+
function usableDir(value) {
|
|
15
|
+
if (typeof value !== "string")
|
|
16
|
+
return null;
|
|
17
|
+
const trimmed = value.trim();
|
|
18
|
+
return trimmed === "" ? null : trimmed;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* 决定这次工具该操作哪个工程目录。
|
|
22
|
+
*
|
|
23
|
+
* 顺序:显式 projectDir → 宿主 workingDirectory 服务(会话工作目录)→ 插件进程 cwd(并警告)。
|
|
24
|
+
*/
|
|
25
|
+
export async function resolveProjectDir(ctx, explicit, exec) {
|
|
26
|
+
const given = usableDir(explicit);
|
|
27
|
+
if (given !== null)
|
|
28
|
+
return { projectDir: given, note: null, fallbackToProcessCwd: false };
|
|
29
|
+
let failure = null;
|
|
30
|
+
const service = typeof ctx.get === "function" ? ctx.get("workingDirectory") : undefined;
|
|
31
|
+
if (service !== undefined && typeof service.ensure === "function") {
|
|
32
|
+
try {
|
|
33
|
+
const sessionDir = usableDir(await service.ensure(exec?.agent, exec?.signal));
|
|
34
|
+
if (sessionDir !== null) {
|
|
35
|
+
return {
|
|
36
|
+
projectDir: sessionDir,
|
|
37
|
+
note: "工程目录缺省取会话工作目录:" + sessionDir,
|
|
38
|
+
fallbackToProcessCwd: false,
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
failure = "会话工作目录是空的";
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
failure = error instanceof Error ? error.message : String(error);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
else {
|
|
48
|
+
failure = "宿主没有 workingDirectory 服务";
|
|
49
|
+
}
|
|
50
|
+
const fallback = process.cwd();
|
|
51
|
+
return {
|
|
52
|
+
projectDir: fallback,
|
|
53
|
+
note: "拿不到会话工作目录(" + (failure ?? "未知原因") + "),缺省用了插件进程的 cwd(" + fallback +
|
|
54
|
+
");如果这不是你的工程,请显式传 projectDir",
|
|
55
|
+
fallbackToProcessCwd: true,
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
function isBlank(value) {
|
|
59
|
+
return typeof value === "string" && value.trim() === "";
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* 校验必填参数。返回 null 表示通过,否则返回一句可以直接给用户看的中文说明。
|
|
63
|
+
*
|
|
64
|
+
* 只做"形状"校验(缺没缺、是不是字符串/字符串数组),值本身合不合法交给引擎层。
|
|
65
|
+
*/
|
|
66
|
+
export function validateToolArgs(toolName, args, required) {
|
|
67
|
+
const missing = [];
|
|
68
|
+
const wrongKind = [];
|
|
69
|
+
for (const spec of required) {
|
|
70
|
+
const value = args[spec.name];
|
|
71
|
+
if (value === undefined || value === null || isBlank(value)) {
|
|
72
|
+
missing.push(spec.name);
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
75
|
+
if (spec.kind === "string") {
|
|
76
|
+
if (typeof value !== "string")
|
|
77
|
+
wrongKind.push(spec.name);
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
|
|
81
|
+
wrongKind.push(spec.name);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
if (missing.length === 0 && wrongKind.length === 0)
|
|
85
|
+
return null;
|
|
86
|
+
const parts = [];
|
|
87
|
+
if (missing.length > 0)
|
|
88
|
+
parts.push("缺少 " + missing.join("、"));
|
|
89
|
+
if (wrongKind.length > 0)
|
|
90
|
+
parts.push(wrongKind.map((name) => name + " 的类型不对").join("、"));
|
|
91
|
+
const expected = required
|
|
92
|
+
.map((spec) => spec.name + (spec.kind === "string[]" ? "(字符串数组)" : "(字符串)"))
|
|
93
|
+
.join("、");
|
|
94
|
+
return toolName + " 参数不正确:" + parts.join(";") + "。必填参数:" + expected + "。";
|
|
95
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* L3:stm32_project_export —— 把"能编译的工程"打成一个 zip 交给别人(发同学、发板厂、存档)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么要这个工具:直接把工程目录压缩的常见做法会把 build/ 一起带走,而 build/CMakeCache.txt
|
|
5
|
+
* 里记的是本机绝对路径 —— 对方 cmake 退出码 0,产物却是旧的(实测)。所以排除规则必须由插件负责,
|
|
6
|
+
* 不能指望用户自己记得。
|
|
7
|
+
*/
|
|
8
|
+
import { runExport } from "../engine/project-export.js";
|
|
9
|
+
import { resolveProjectDir } from "./project-dir.js";
|
|
10
|
+
export const EXPORT_TOOL = "stm32_project_export";
|
|
11
|
+
const prebuiltSchema = {
|
|
12
|
+
type: "object",
|
|
13
|
+
additionalProperties: false,
|
|
14
|
+
properties: {
|
|
15
|
+
path: { type: "string" },
|
|
16
|
+
size: { type: "number" },
|
|
17
|
+
},
|
|
18
|
+
required: ["path", "size"],
|
|
19
|
+
};
|
|
20
|
+
export const outputSchema = {
|
|
21
|
+
type: "object",
|
|
22
|
+
additionalProperties: false,
|
|
23
|
+
properties: {
|
|
24
|
+
message: { type: "string" },
|
|
25
|
+
report: {
|
|
26
|
+
type: "object",
|
|
27
|
+
additionalProperties: false,
|
|
28
|
+
properties: {
|
|
29
|
+
ok: { type: "boolean" },
|
|
30
|
+
projectDir: { type: "string" },
|
|
31
|
+
zipPath: { type: "string" },
|
|
32
|
+
zipBytes: { type: "number" },
|
|
33
|
+
fileCount: { type: "number" },
|
|
34
|
+
prebuilt: { type: "array", items: prebuiltSchema },
|
|
35
|
+
durationMs: { type: "number" },
|
|
36
|
+
message: { type: "string" },
|
|
37
|
+
notes: { type: "array", items: { type: "string" } },
|
|
38
|
+
},
|
|
39
|
+
required: ["ok", "projectDir", "zipPath", "zipBytes", "fileCount", "prebuilt", "durationMs", "message", "notes"],
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
required: ["message", "report"],
|
|
43
|
+
};
|
|
44
|
+
function formatReport(report) {
|
|
45
|
+
const lines = [];
|
|
46
|
+
lines.push((report.ok ? "导出完成" : "导出失败") + ":" + report.message);
|
|
47
|
+
if (report.ok) {
|
|
48
|
+
lines.push("zip:" + report.zipPath + "(" + String(report.zipBytes) + " 字节)");
|
|
49
|
+
lines.push("进包文件:" + String(report.fileCount) + " 个;耗时 " + String(report.durationMs) + " ms");
|
|
50
|
+
if (report.prebuilt.length > 0) {
|
|
51
|
+
lines.push("prebuilt/ 里的产物:");
|
|
52
|
+
for (const item of report.prebuilt)
|
|
53
|
+
lines.push(" · " + item.path + "(" + String(item.size) + " 字节)");
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
for (const note of report.notes)
|
|
57
|
+
lines.push("· " + note);
|
|
58
|
+
return lines;
|
|
59
|
+
}
|
|
60
|
+
export function registerProjectExport(ctx) {
|
|
61
|
+
ctx.tools.register({
|
|
62
|
+
name: EXPORT_TOOL,
|
|
63
|
+
description: "把工程打成一个 zip(默认放在工程同级 <工程名>-export.zip):排除 build/、.dsh-stm32/、node_modules/、.git/,因为 build 里的缓存记着本机绝对路径,带过去会让对方 cmake 静默复用旧缓存;可选 includePrebuilt 把 build 里的 elf/hex/bin 拷进包内 prebuilt/(拿到就能烧),并自动写一份包内 README(怎么编译、build 为什么不在)。",
|
|
64
|
+
parameters: {
|
|
65
|
+
type: "object",
|
|
66
|
+
additionalProperties: false,
|
|
67
|
+
properties: {
|
|
68
|
+
projectDir: { type: "string", description: "工程根目录;缺省为当前工作目录。" },
|
|
69
|
+
outDir: { type: "string", description: "zip 输出目录;缺省为工程目录的上一级。" },
|
|
70
|
+
includePrebuilt: { type: "boolean", description: "把编译产物(elf/hex/bin)拷进包内 prebuilt/;默认 false(只带源码)。" },
|
|
71
|
+
readme: { type: "boolean", description: "是否自动写包内 README(怎么编译、build/ 为什么不在);默认 true。" },
|
|
72
|
+
},
|
|
73
|
+
required: [],
|
|
74
|
+
},
|
|
75
|
+
timeoutMs: 3 * 60_000,
|
|
76
|
+
isConcurrencySafe: () => false,
|
|
77
|
+
output: {
|
|
78
|
+
schema: outputSchema,
|
|
79
|
+
render: (_args, value) => {
|
|
80
|
+
const typed = value;
|
|
81
|
+
return [{ type: "text", text: formatReport(typed.report).join("\n") }];
|
|
82
|
+
},
|
|
83
|
+
},
|
|
84
|
+
async execute(rawArgs, exec) {
|
|
85
|
+
const args = rawArgs ?? {};
|
|
86
|
+
const resolution = await resolveProjectDir(ctx, typeof args.projectDir === "string" ? args.projectDir : undefined, exec);
|
|
87
|
+
const request = {
|
|
88
|
+
projectDir: resolution.projectDir,
|
|
89
|
+
includePrebuilt: args.includePrebuilt === true,
|
|
90
|
+
readme: args.readme !== false,
|
|
91
|
+
signal: exec.signal,
|
|
92
|
+
...(typeof args.outDir === "string" && args.outDir.trim() !== "" ? { outDir: args.outDir } : {}),
|
|
93
|
+
};
|
|
94
|
+
const report = await runExport(request);
|
|
95
|
+
if (resolution.note !== null)
|
|
96
|
+
report.notes.push(resolution.note);
|
|
97
|
+
return { message: report.message, report };
|
|
98
|
+
},
|
|
99
|
+
});
|
|
100
|
+
}
|
package/lib/tools/regs.js
CHANGED
|
@@ -5,6 +5,9 @@
|
|
|
5
5
|
* 比看 LED 更可靠。
|
|
6
6
|
*/
|
|
7
7
|
import { describeSample, runRegsRead } from "../engine/regs.js";
|
|
8
|
+
import { debugSessions } from "../engine/debug-session.js";
|
|
9
|
+
import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
|
|
10
|
+
import { resolveProjectDir, validateToolArgs } from "./project-dir.js";
|
|
8
11
|
export const REGS_TOOL = "stm32_regs_read";
|
|
9
12
|
const sampleSchema = {
|
|
10
13
|
type: "object",
|
|
@@ -47,6 +50,12 @@ export const outputSchema = {
|
|
|
47
50
|
},
|
|
48
51
|
required: ["message", "report"],
|
|
49
52
|
};
|
|
53
|
+
/** 门禁档位参数:三个档位的说明文字与 build 工具保持一致。 */
|
|
54
|
+
const ENV_CHECK_SCHEMA = {
|
|
55
|
+
type: "string",
|
|
56
|
+
enum: ["block", "warn", "off"],
|
|
57
|
+
description: "工具链检查:block 缺件就拒绝(默认)、warn 只警告、off 不检查",
|
|
58
|
+
};
|
|
50
59
|
function formatReport(report) {
|
|
51
60
|
const lines = [];
|
|
52
61
|
lines.push((report.ok ? "读取完成" : "读取失败") + ":" + report.message);
|
|
@@ -67,6 +76,12 @@ function formatReport(report) {
|
|
|
67
76
|
}
|
|
68
77
|
return lines;
|
|
69
78
|
}
|
|
79
|
+
function failureReport(projectDir, message, errors) {
|
|
80
|
+
return {
|
|
81
|
+
ok: false, projectDir, configFile: "", command: "", script: "", pc: "",
|
|
82
|
+
samples: [], durationMs: 0, errors, message, logTail: "", notes: [],
|
|
83
|
+
};
|
|
84
|
+
}
|
|
70
85
|
export function registerRegsRead(ctx) {
|
|
71
86
|
ctx.tools.register({
|
|
72
87
|
name: REGS_TOOL,
|
|
@@ -81,6 +96,7 @@ export function registerRegsRead(ctx) {
|
|
|
81
96
|
adapterSpeed: { type: "number", description: "adapter speed(kHz)。" },
|
|
82
97
|
timeoutMs: { type: "number", description: "超时毫秒数,默认 30000。" },
|
|
83
98
|
binDirs: { type: "array", items: { type: "string" }, description: "工具链目录候选。" },
|
|
99
|
+
envCheck: ENV_CHECK_SCHEMA,
|
|
84
100
|
},
|
|
85
101
|
required: ["addresses"],
|
|
86
102
|
},
|
|
@@ -94,19 +110,74 @@ export function registerRegsRead(ctx) {
|
|
|
94
110
|
},
|
|
95
111
|
},
|
|
96
112
|
async execute(rawArgs, exec) {
|
|
97
|
-
const
|
|
98
|
-
|
|
99
|
-
|
|
113
|
+
const args = rawArgs ?? {};
|
|
114
|
+
// 洞 C:参数名写错(例如把 addresses 写成 addresses_list)时先给一句人话,不要让宿主去报
|
|
115
|
+
// "returned invalid output: value is not lossless JSON"。
|
|
116
|
+
const invalid = validateToolArgs(REGS_TOOL, args, [
|
|
117
|
+
{ name: "addresses", kind: "string[]" },
|
|
118
|
+
]);
|
|
119
|
+
if (invalid !== null) {
|
|
120
|
+
return { message: invalid, report: failureReport(typeof args.projectDir === "string" ? args.projectDir : "", invalid, [invalid]) };
|
|
121
|
+
}
|
|
122
|
+
const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
|
|
123
|
+
// 门禁:读寄存器要 openocd(或已有会话里的那个)。放在借用会话之前判断,
|
|
124
|
+
// 两种取词方式都不会在缺件时白跑一趟。
|
|
125
|
+
const gate = await ensureToolchain(ctx, {
|
|
126
|
+
capability: "debug",
|
|
127
|
+
...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
|
|
128
|
+
envCheck: args.envCheck,
|
|
129
|
+
signal: exec.signal,
|
|
130
|
+
});
|
|
131
|
+
if (!gate.ok && gate.mode === "block") {
|
|
132
|
+
const blocked = failureReport(resolution.projectDir, gate.message, []);
|
|
133
|
+
blocked.notes = gateReportNotes(gate);
|
|
134
|
+
return { message: blocked.message, report: blocked };
|
|
135
|
+
}
|
|
136
|
+
// 洞 D:有调试会话时不能再起一个 openocd —— 同一块 CMSIS-DAP 被两个进程抢会报
|
|
137
|
+
// "CMSIS-DAP transfer count mismatch"。直接借会话的 gdb 读,halt → 读 → resume。
|
|
138
|
+
if (debugSessions.isActive()) {
|
|
139
|
+
const words = await debugSessions.readWords({
|
|
140
|
+
addresses: args.addresses,
|
|
141
|
+
...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
|
|
142
|
+
signal: exec.signal,
|
|
143
|
+
});
|
|
144
|
+
const notes = gate.ok ? [] : [gate.message];
|
|
145
|
+
notes.push("复用调试会话(端口 " + String(words.port) + ")的 openocd,没有另起一个");
|
|
146
|
+
// A19:借用会话时 openocd 是会话里那个,这两个参数没法改,别让用户以为生效了。
|
|
147
|
+
if ((args.configFile !== undefined && args.configFile !== "") || args.adapterSpeed !== undefined) {
|
|
148
|
+
notes.push("这次借用了已有会话:configFile / adapterSpeed 不生效(openocd 是会话里那个,已按会话参数在跑)。" +
|
|
149
|
+
"要按新参数读,先 stm32_debug_stop 再调 stm32_regs_read。");
|
|
150
|
+
}
|
|
151
|
+
if (resolution.note !== null)
|
|
152
|
+
notes.push(resolution.note);
|
|
153
|
+
if (words.projectDir !== "" && words.projectDir !== resolution.projectDir) {
|
|
154
|
+
notes.push("会话的工程目录是 " + words.projectDir + ",与本次参数的 " + resolution.projectDir + " 不同(读值用的是会话里的那个)");
|
|
155
|
+
}
|
|
100
156
|
return {
|
|
101
|
-
message:
|
|
157
|
+
message: words.message,
|
|
102
158
|
report: {
|
|
103
|
-
ok:
|
|
104
|
-
|
|
159
|
+
ok: words.ok,
|
|
160
|
+
projectDir: words.projectDir === "" ? resolution.projectDir : words.projectDir,
|
|
161
|
+
configFile: "",
|
|
162
|
+
command: words.command,
|
|
163
|
+
script: "",
|
|
164
|
+
pc: words.pc,
|
|
165
|
+
samples: words.samples,
|
|
166
|
+
durationMs: words.durationMs,
|
|
167
|
+
errors: words.errors,
|
|
168
|
+
message: words.message,
|
|
169
|
+
logTail: words.output.split(/\r?\n/u).slice(-12).join("\n"),
|
|
170
|
+
notes,
|
|
105
171
|
},
|
|
106
172
|
};
|
|
107
173
|
}
|
|
174
|
+
const subprocess = ctx.get("subprocess");
|
|
175
|
+
if (subprocess === undefined) {
|
|
176
|
+
const message = "宿主缺少 subprocess 服务,无法读寄存器";
|
|
177
|
+
return { message, report: failureReport(resolution.projectDir, message, [message]) };
|
|
178
|
+
}
|
|
108
179
|
const report = await runRegsRead(subprocess, {
|
|
109
|
-
projectDir:
|
|
180
|
+
projectDir: resolution.projectDir,
|
|
110
181
|
addresses: args.addresses,
|
|
111
182
|
...(args.configFile === undefined ? {} : { configFile: args.configFile }),
|
|
112
183
|
...(args.adapterSpeed === undefined ? {} : { adapterSpeed: args.adapterSpeed }),
|
|
@@ -114,6 +185,10 @@ export function registerRegsRead(ctx) {
|
|
|
114
185
|
...(args.binDirs === undefined ? {} : { binDirs: args.binDirs }),
|
|
115
186
|
signal: exec.signal,
|
|
116
187
|
});
|
|
188
|
+
if (!gate.ok)
|
|
189
|
+
report.notes.unshift(gate.message);
|
|
190
|
+
if (resolution.note !== null)
|
|
191
|
+
report.notes.push(resolution.note);
|
|
117
192
|
return { message: report.message, report };
|
|
118
193
|
},
|
|
119
194
|
});
|