dsh-stm32 0.1.7 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +256 -363
- package/README_EN.md +257 -357
- package/client/client.js +4340 -1
- package/docs/reading-guide.md +62 -0
- package/lib/client.js +4340 -1
- package/lib/engine/artifacts.js +123 -0
- package/lib/engine/breakpoint-hits.js +73 -0
- package/lib/engine/build.js +73 -3
- package/lib/engine/channel-tap.js +227 -0
- package/lib/engine/channels.js +48 -0
- package/lib/engine/clocks.js +192 -0
- package/lib/engine/debug-session.js +46 -1
- package/lib/engine/event-bus.js +158 -0
- package/lib/engine/event-log.js +335 -0
- package/lib/engine/fault-hints.js +146 -0
- package/lib/engine/interrupts.js +247 -0
- package/lib/engine/ioc-diff.js +369 -0
- package/lib/engine/ioc-sync.js +58 -0
- package/lib/engine/msys2-install.js +31 -6
- package/lib/engine/panel-actions.js +103 -0
- package/lib/engine/pinout.js +140 -0
- package/lib/engine/probe-info.js +95 -0
- package/lib/engine/progress.js +99 -0
- package/lib/engine/project-conf.js +199 -0
- package/lib/engine/session-context.js +19 -0
- package/lib/engine/source-slice.js +59 -0
- package/lib/engine/tool-events.js +119 -0
- package/lib/engine/watch-admin.js +101 -0
- package/lib/engine/watch-record.js +39 -0
- package/lib/engine/watch-recorder.js +116 -0
- package/lib/engine/web-api.js +886 -4
- package/lib/engine/web-routes.js +18 -1
- package/lib/engine/workspace-memo.js +41 -0
- package/lib/index.js +67 -24
- package/lib/tools/ioc-apply.js +9 -0
- package/lib/tools/project-create.js +28 -0
- package/lib/tools/project-dir.js +7 -1
- package/lib/tools/rtt.js +8 -0
- package/lib/tools/serial.js +22 -0
- package/lib/tools/watch.js +24 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,301 +1,260 @@
|
|
|
1
1
|
# dsh-stm32
|
|
2
2
|
|
|
3
|
-
> 让 DSH 接管 **STM32 全系列**(27 个族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3)的整条开发链:探测工具链 → 建工程 → 改 .ioc(含时钟) → 生成代码 → 编译 → 调试 → 烧录,以及串口交互(`stm32_serial`,Windows P1)。族画像从 `.ioc` 的 `Mcu.Family` 判定:引脚名、SWD 调试信号名、EXTI 的 NVIC 向量分组、openocd target、硬件断点/观察点预算都随族与内核走;**HAL 建工程**(固件包 / 启动文件 / 设备宏 / 链接脚本 / .ioc 模板 / cmake 与调试配置)已按族实现并覆盖 21 个单核族(C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL);寄存器版覆盖 21 族(C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL;21 族都过了 create→build 编译矩阵,新增 8 族的逐族结果见 development-notes §87.5);时钟规划覆盖 18 族(其中 PLL1 四族 H5 / U5 / WBA / L4+),.ioc 外设预设已改为按 CubeMX db 派生;SVD 校验仍只有 F1 —— 未覆盖的能力会**明确拒绝并说明原因**,不会悄悄套 F1 的表(见[已知限制](#已知限制))。
|
|
4
|
-
|
|
5
|
-
**English:** STM32 across 27 families (C0 / F0 / F1 / … / WL3) for DeepSeek Harness — probe the toolchain, scaffold a CMake project, edit .ioc as a transaction, build, flash without starting a debug session, and debug only when you ask for it. Pin names, SWD debug signals, EXTI NVIC vector grouping, the openocd target and the hardware breakpoint budget all follow the family and its core; HAL scaffolding covers 21 single-core families, the register route 21, clock planning 18 (PLL1 on four families), and .ioc peripheral presets are derived from the CubeMX db; SVD validation is still F1-only, and uncovered capabilities are refused explicitly instead of silently reusing F1 tables.
|
|
6
|
-
|
|
7
|
-
[English](./README_EN.md) · [快速开始](#快速开始最小验证空目录到灯在闪) · [功能一览](#功能一览) · [工具参考](#工具参考) · [斜杠命令](#斜杠命令) · [设计要点](#设计要点) · [已知限制](#已知限制) · [排错](#排错) · [规格书](docs/dsh-stm32-plugin-规格.md)
|
|
8
|
-
|
|
9
3
|
[](https://github.com/JingYu-er/dsh-stm32)
|
|
10
4
|
[](LICENSE)
|
|
11
5
|
[](#已知限制)
|
|
12
6
|
[](#已知限制)
|
|
13
|
-
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
14
8
|
|
|
15
|
-
|
|
9
|
+
STM32 全流程工具层,以 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 插件形式分发:25 个工具、7 条斜杠命令与 1 个随包下发的 SKILL,把「工具链探测 → 建工程 → 改 `.ioc`(含时钟)→ 生成代码 → 编译 → 烧录 → 调试 → 回读寄存器」这条链交给模型执行,另含串口交互(Windows)与会话内的「调试台」面板。
|
|
16
10
|
|
|
17
|
-
|
|
11
|
+
在支持范围内,同一套工具从 F1 到 H7 用法一致;遇到不支持的芯片或功能,调用时会直接说明缺什么,不会给出一份猜出来的结果。
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
| 能力面 | 覆盖范围 |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| 芯片族 | 27 个族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3 |
|
|
16
|
+
| HAL 建工程 | 21 个单核族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL |
|
|
17
|
+
| 寄存器建工程 | 21 族,均通过 create→build 编译矩阵 |
|
|
18
|
+
| 时钟规划 | 18 族;其中 PLL1 为 H5 / U5 / WBA / L4+ |
|
|
19
|
+
| `.ioc` 外设预设 | 按 CubeMX 官方数据派生:串口 / TIM PWM / ADC |
|
|
20
|
+
| 寄存器名与位域 | F1 |
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
**English:** [README_EN.md](./README_EN.md)
|
|
22
23
|
|
|
23
|
-
|
|
24
|
+
[快速开始](#快速开始最小验证空目录到灯在闪) · [工具参考](#工具参考) · [斜杠命令](#斜杠命令) · [调试台](#调试台面板) · [配置](#配置) · [已知限制](#已知限制) · [排错](#排错) · [规格书](docs/dsh-stm32-plugin-规格.md)
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
| --- | --- | --- |
|
|
27
|
-
| 建工程 | GUI 里点时钟树、引脚、工程设置,生成 CMake,再手写 `launch.json` | 一句话:`stm32_project_create` 2 s 出模板工程(与 GUI 产物逐字节一致),`.vscode` 里两份配置已就位 |
|
|
28
|
-
| 改配置 | GUI 里改完重新生成,祈祷 USER CODE 不丢 | `stm32_ioc_plan` 先给 diff(不动源文件)→ 你点头 → `stm32_ioc_apply` 带 SHA 校验、备份、失败回滚 |
|
|
29
|
-
| 写代码 | 整文件编辑,一不小心写进生成区,重新生成就没了 | `stm32_code_patch` 只写 `USER CODE` 块,块外逐字节不动 |
|
|
30
|
-
| 编译 | 使用keil编译或使用vscode插件编写cmake文件 | DSH 通过/stm32-build [dir] [--clean] 自动编译 |
|
|
31
|
-
| 烧录 | 使用keil烧录或自己写 `tasks.json` 调 openocd | DSH 通过/stm32-debug [dir]自动烧录 |
|
|
32
|
-
| 验证 | 断点调试,自己查看寄存器的值 | 烧完用 `stm32_regs_read` 把状态读回来:`GPIOC.ODR` 两次采样看计数器递增(有 SVD 时直接显示 `ODR5=1`),`AFIO.MAPR` 确认 SWD 没被固件关掉 |
|
|
33
|
-
| 调试 | `F5` + 手动下断点、看完再关会话 | `stm32_debug_run` 停在 `main` 抓一次现场即释放;要连续调才开 `stm32_debug_session`,空闲自动关 |
|
|
26
|
+
## 它能做什么
|
|
34
27
|
|
|
28
|
+
多数「让 AI 编写 STM32 代码」的方案止于代码层:产出一段 `main.c`,能否编译、烧录后灯是否按预期闪烁,仍要在 CubeMX、终端与调试器之间手工确认。模型看不到板子,也就无法对结果负责。
|
|
35
29
|
|
|
36
|
-
|
|
30
|
+
本插件把硬件侧接入 DSH:`.ioc` 可读可改(事务 + 回滚),代码只写入 `USER CODE` 块,生成与编译返回真实报错行,烧录不与调试器抢占探针,烧录后读回寄存器状态。每一步都有可核对的结果(计划编号、`文件:行:列`、`Verified OK`、`GPIOC.ODR` 的 bit13,有寄存器表时直接给出 `ODR13=1`),模型据此决定下一步。
|
|
37
31
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
| 依赖 | 用途 | 缺了会怎样 |
|
|
32
|
+
| 环节 | 手工流程 | 本插件 |
|
|
41
33
|
| --- | --- | --- |
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
34
|
+
| 建工程 | GUI 配置时钟树、引脚与工程参数,生成 CMake,手写 `launch.json` | `stm32_project_create` 约 2 秒产出模板工程(与 CubeMX GUI 产物一致,`.vscode` 内两份配置就位) |
|
|
35
|
+
| 改配置 | GUI 修改后重新生成,担心 `USER CODE` 丢失 | `stm32_ioc_plan` 先出差异(不写盘)→ 确认 → `stm32_ioc_apply` 带校验、备份与失败回滚 |
|
|
36
|
+
| 写代码 | 整文件编辑,易写入生成区,重新生成后丢失 | `stm32_code_patch` 只写 `USER CODE` 块,块外逐字节保留 |
|
|
37
|
+
| 编译 | Keil,或自行维护 CMake 与 VS Code 任务 | `/stm32-build [目录] [--clean]` |
|
|
38
|
+
| 烧录 | Keil,或手写 `tasks.json` 调 openocd | `/stm32-flash [目录]` |
|
|
39
|
+
| 验证 | 断点调试,手工查看寄存器 | `stm32_regs_read` 回读状态:`GPIOC.ODR` 两次采样确认计数递增,`AFIO.MAPR` 确认 SWD 未被固件关闭 |
|
|
40
|
+
| 调试 | 按 F5 手动下断点,结束再关会话 | `stm32_debug_run` 停在 `main` 抓取一次现场后释放探针;连续调试才开 `stm32_debug_session`,空闲自动关闭 |
|
|
41
|
+
|
|
42
|
+
## 安装
|
|
49
43
|
|
|
44
|
+
### 安装插件
|
|
50
45
|
|
|
51
|
-
|
|
46
|
+
只需先具备 DSH 本体,工具链可以稍后补。
|
|
52
47
|
|
|
53
48
|
```powershell
|
|
54
49
|
dsh plugin --profile desktop add dsh-stm32
|
|
55
50
|
```
|
|
56
51
|
|
|
57
|
-
`dsh plugin`
|
|
52
|
+
`dsh plugin` 等价于在 profile 目录执行 `pnpm add`,并把 `dsh-stm32` 写入该 profile 的 `dsh.profile.bundles`。安装后完全退出 DSH 再启动(插件层只在进程启动时加载)。
|
|
53
|
+
|
|
54
|
+
- 校验:`dsh plugin --profile desktop why dsh-stm32` 显示 `0.1.8`
|
|
55
|
+
- 卸载:`dsh plugin --profile desktop remove dsh-stm32`,随后重启 DSH
|
|
56
|
+
- 装到 Web:把 `desktop` 换成 `web`
|
|
57
|
+
|
|
58
|
+
### 补齐工具链
|
|
59
|
+
|
|
60
|
+
插件装好后即可解析 `.ioc`、查看引脚 / 时钟 / 中断、预览计划;真正编译、烧录、调试时才需要编译器与探针工具。
|
|
61
|
+
|
|
62
|
+
| 要做什么 | 需要什么 | 怎么补 |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| 编译 | `arm-none-eabi-gcc`、`cmake`、`ninja` | `/stm32-setup` 一条命令装齐(MSYS2 + 工具链,约 300 MB),或自行安装后由插件自动发现 |
|
|
65
|
+
| 烧录、调试 | `openocd`、`arm-none-eabi-gdb`(或 `gdb-multiarch`)、CMSIS-DAP / ST-Link 探针 | 同上;探针驱动由系统识别,无需额外配置 |
|
|
66
|
+
| 生成代码、建 HAL 工程 | STM32CubeMX(含内置 JRE)与其固件包 | 从 ST 官网安装 CubeMX(需 ST 账号),插件自动定位安装位置;固件包在 CubeMX 包管理器内安装 |
|
|
67
|
+
|
|
68
|
+
不确定缺什么时,先看诊断:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
/stm32-env # 编译 / 烧录 / 调试 / 生成四项能力逐项列出缺件、安装位置与安装方式
|
|
72
|
+
/stm32-setup # 先出计划,确认后执行安装,结束后自检
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`/stm32-env` 在没有装任何工具链时也能用:它只执行版本查询,不写盘、不联网。
|
|
76
|
+
|
|
77
|
+
### 开工前检查
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
/stm32-doctor
|
|
81
|
+
```
|
|
58
82
|
|
|
59
|
-
|
|
83
|
+
只读体检:工具链是否齐备、是否有残留的 openocd / gdb 进程占用探针、gdb 端口是否被占用、工程内 `.elf` 与 `.ioc` 是否就位、`.ioc` 是否存在会导致烧录后失联的配置。
|
|
60
84
|
|
|
61
|
-
|
|
85
|
+
### 内置资源
|
|
62
86
|
|
|
87
|
+
芯片型号到启动文件、设备宏、Flash / RAM 容量的映射,以及 `.ioc` 模板、链接脚本与寄存器表,随插件一起分发,安装后离线可用,不需要下载资源包。`stm32_assets verify` 校验完整性;报缺文件时按提示重装插件即可。
|
|
63
88
|
|
|
64
|
-
|
|
89
|
+
### 从源码安装
|
|
65
90
|
|
|
66
|
-
|
|
91
|
+
仅开发或需要改代码时使用。`npm install` 与 `npm run build` 的说明见[开发与测试](#开发与测试)。
|
|
67
92
|
|
|
68
93
|
```powershell
|
|
69
94
|
git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
70
95
|
cd dsh-stm32
|
|
71
|
-
npm install --no-audit --no-fund #
|
|
72
|
-
npm run build
|
|
73
|
-
npm test # 可选:947 个离线用例、60 个套件,不需要板子
|
|
74
|
-
npm run test:pack # 打包 tarball → 解包 → 用解包出来的 lib 真建一次寄存器工程
|
|
75
|
-
npm run test:size # 包体护栏:tarball ≤3.9 MB、templates 里的运行时资产(.ioc/.xml/.ld/.json/.cfg)≤40 KB、包内不许二进制/图表
|
|
96
|
+
npm install --no-audit --no-fund # 仅安装 typescript
|
|
97
|
+
npm run build # tsc -> lib/,提交前必须执行
|
|
76
98
|
```
|
|
77
99
|
|
|
78
|
-
|
|
100
|
+
挂载到 profile 时用 `link:`,不要用 `file:`:
|
|
79
101
|
|
|
80
102
|
```powershell
|
|
81
103
|
cd "$env:USERPROFILE\.dsh\profiles\desktop"
|
|
82
104
|
pnpm add "link:D:\path\to\dsh-stm32"
|
|
83
105
|
|
|
84
|
-
#
|
|
85
|
-
#
|
|
106
|
+
# 在同一目录的 package.json 中把 "dsh-stm32" 追加到 dsh.profile.bundles
|
|
107
|
+
# 随后重启 dsh(插件层只在进程启动时加载)
|
|
86
108
|
```
|
|
87
109
|
|
|
88
|
-
|
|
110
|
+
原因:`nodeLinker: hoisted` 下 `file:` 会被复制成真实目录,重新编译出的 `lib/` 不会被宿主读取,表现为「改完代码、重启仍为旧行为」。`link:` 读取工作区里的 `lib/`,改完仍需重启 DSH 重新加载。
|
|
89
111
|
|
|
90
112
|
## 快速开始:最小验证(空目录到灯在闪)
|
|
91
113
|
|
|
92
|
-
|
|
114
|
+
这条链路已在真板验证,全程由模型调用工具完成。各步使用同一套工具,闪灯只是最小样例。
|
|
93
115
|
|
|
94
|
-
| 步 |
|
|
116
|
+
| 步 | 动作 | 工具 | 实测耗时 |
|
|
95
117
|
| --- | --- | --- | --- |
|
|
96
|
-
| 1 |
|
|
97
|
-
| 2 | 空目录建 CMake
|
|
98
|
-
| 3 | 按 `.ioc`
|
|
99
|
-
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` |
|
|
100
|
-
| 5 |
|
|
101
|
-
| 6 |
|
|
102
|
-
|
|
103
|
-
> 第 6 步用的是符号写法(`GPIOC.ODR`),靠插件内置的 SVD 表(`assets/device/f1/svd/`,full 逻辑层)。只装 `core` 或安装不完整也能读——但要写地址 `0x4001100C`,报告里没有寄存器名,也没有位域解释。
|
|
118
|
+
| 1 | 体检:工具链、被占用探针、端口、`.elf`、`.ioc` 告警 | `stm32_doctor` | 约 2 秒 |
|
|
119
|
+
| 2 | 空目录建 CMake 工程骨架(含已配置 SWD 的 `.ioc`) | `stm32_project_create` | 约 2 秒 |
|
|
120
|
+
| 3 | 按 `.ioc` 无头运行 CubeMX,产物落到 `Core/` | `stm32_generate` | 首次 130–175 秒;`.ioc` 与产物未变时跳过(小于 1 秒) |
|
|
121
|
+
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` | 配置约 5 秒 + 编译 3 秒 |
|
|
122
|
+
| 5 | 只烧录:program + verify + reset | `stm32_flash` | 2.1–2.6 秒 |
|
|
123
|
+
| 6 | 回读 `GPIOC.ODR`(或地址 `0x4001100C`),确认状态翻转 | `stm32_regs_read` | 0.4–1.3 秒 |
|
|
104
124
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
```text
|
|
108
|
-
/stm32-doctor # 开工前体检
|
|
109
|
-
/stm32-env # 只看四项能力缺什么(缺件也能看)
|
|
110
|
-
/stm32-build # 编译,打印内存占用与错误
|
|
111
|
-
/stm32-flash # 只烧录,不进调试会话
|
|
112
|
-
/stm32-debug # 烧录 + 停在 main
|
|
113
|
-
/stm32-stop # 关掉调试会话,把探针还给 VS Code
|
|
114
|
-
/stm32-setup # 体检 + 安装计划(说「装」才真装)
|
|
115
|
-
```
|
|
125
|
+
第 6 步的符号写法依赖内置寄存器表;安装不完整时可改用地址 `0x4001100C`,报告中不会有寄存器名与位域解释。
|
|
116
126
|
|
|
117
|
-
|
|
127
|
+
模型侧只需一句:「在 `D:\work\blink` 建一个 STM32F103C8T6 的闪灯工程,编译并烧录」。
|
|
118
128
|
|
|
119
|
-
|
|
129
|
+
最小验证覆盖「建工程 → 生成 → 编译 → 烧录 → 回读」整条链路,没有闪灯专用步骤;真实项目走同一链路,差异在于 `.ioc` 里的外设数量、`USER CODE` 块数量与代码规模。
|
|
120
130
|
|
|
121
|
-
|
|
|
131
|
+
| 完整项目中的操作 | 路径 | 验证状态 |
|
|
122
132
|
| --- | --- | --- |
|
|
123
|
-
| 外设配置:GPIO / 定时器 / USART / I2C / SPI / ADC / DMA / 中断 | `stm32_ioc_plan
|
|
124
|
-
| 新增外设后补 HAL 源 | 在 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src`
|
|
125
|
-
|
|
|
126
|
-
| 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 |
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
133
|
+
| 外设配置:GPIO / 定时器 / USART / I2C / SPI / ADC / DMA / 中断 | `stm32_ioc_plan`(GPIO 按芯片引脚表校验)→ `stm32_ioc_apply` → `stm32_generate` | GPIO、时钟、SWD 已上板实测;其余外设机制相同,未逐项实测 |
|
|
134
|
+
| 新增外设后补 HAL 源 | 在 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src` 中加入 `stm32f1xx_hal_<外设>.c`,或写入 `cmake/user/CMakeLists.txt` | 需手工补齐:插件只放置 `Src/` 与 `Inc/`,CubeMX 生成的 `cmake/**` 不搬运 |
|
|
135
|
+
| 多源文件与自定义模块 | 写入 `cmake/user/CMakeLists.txt`,模板已留位置 | 位置就位,未单独实测 |
|
|
136
|
+
| 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 | 已实测(追加 / 替换;标签写错时会列出全部可用标签) |
|
|
137
|
+
| 调参、改时钟 | `.ioc` 事务:先出差异 → 校验 → 备份 → 失败回滚 | 已实测 |
|
|
138
|
+
| 确认外设运行 | `stm32_regs_read` 读任意外设寄存器:符号名 `TIM2.CNT` / `USART1.SR` / `ADC1.DR`,或物理地址 `0x40000024`;只写外设名 `GPIOC` 时输出该外设全部寄存器 | 地址写法已上板实测;符号名与位域复测中 |
|
|
139
|
+
| 查看现场 | `stm32_debug_run` 停在 `main` 抓取一次;连续调试用 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
|
|
130
140
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
## 功能一览
|
|
134
|
-
|
|
135
|
-
| 能力 | 提供方式 |
|
|
136
|
-
| --- | --- |
|
|
137
|
-
| 环境体检 | `stm32_doctor`(只读)、`stm32_doctor`(工具链 + 探针占用 + 端口 + 工程告警) |
|
|
138
|
-
| 开工前门禁 | 每个会动工具链的工具先过 `ensureToolchain`:缺件就拦住并写清装什么、缺了会怎样;`envCheck: "block"`(默认)/ `"warn"` / `"off"` 由调用方决定 |
|
|
139
|
-
| 装工具链 | `stm32_env_install`:先只出计划(下载什么、多大、要改哪条 PATH),你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH,装完自己写进配置文件 |
|
|
140
|
-
| 装安装包(只下载) | `stm32_download`:J-Link 官方直链 + SHA256;CubeMX / CubeProgrammer 给官方页或校验本地文件;只下载/校验,绝不执行安装器、不请求管理员 |
|
|
141
|
-
| 选技术路线 | `stm32_route_plan`:先按**这个工程**的需求,把每个外设的 HAL 版与寄存器版代价摆出来(效率 / 可读性 / 排错),再告诉你缺的是「能代装的」还是「只能人装的」(CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护) |
|
|
142
|
-
| 设备事实(型号 → 启动文件 / 设备宏 / 容量) | 插件**内置芯片表**(随 npm 包分发):型号、启动文件、设备宏、Flash/RAM 只从包内 `assets/device/f1/chips.json` 读(`lib/engine/assets.js` 从包根解析 `assets/`;`DSH_STM32_ASSETS` 仍可指向外部目录做开发覆盖)。文件缺失只说明安装不完整:`stm32_assets verify` 定位,重装插件即可,不需要联网 |
|
|
143
|
-
| 从零建工程 | `stm32_project_create`:`route: "hal"` 用模板快照 + 固件包 Drivers(与 CubeMX GUI 新建的工程逐字节一致);`route: "register"` 建不用 CubeMX 的寄存器版工程,CMSIS 模板首次从网上下到缓存、之后复用(每个文件都钉了上游 sha256,改过就拒绝落盘);`mcu` 指定型号(两条路线都吃;HAL 路线按型号渲染启动文件 / 设备宏 / `<DeviceId>_FLASH.ld`);两条路线都会带一份 `openocd.cfg`(CMSIS-DAP + `hla_swd` + 2 MHz) |
|
|
144
|
-
| 导出工程 | `stm32_project_export`:源码打成一个 zip(默认不带 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`),可选把 `.elf` 一起带上,并写一份开箱 README |
|
|
145
|
-
| `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
|
|
146
|
-
| 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
|
|
147
|
-
| 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
|
|
148
|
-
| 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用;`artifacts` 里要 `hex` / `bin` 就用同一套 `arm-none-eabi-objcopy` 转出来 |
|
|
149
|
-
| 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire;失败时给结构化 `probeError`(`kind` / `cause` / `hint` / `evidence` / `retryable`,`kind` 收 9 类) |
|
|
150
|
-
| 调试 | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
151
|
-
| 验证"真的在跑" | `stm32_regs_read`:按地址或符号名(`GPIOC.ODR`)把任意外设寄存器读回来,有 SVD 时顺带解位域(`→ ODR5=1`);halt 读值后 `resume`,不复位芯片 |
|
|
152
|
-
| 固件日志(RTT) | `stm32_rtt`:控制块按 SEGGER 约定放在 RAM,openocd 的 `rtt setup/start/server start` 把通道 0 搬成 TCP 流,再按 13 字节头解出级别与时间戳——不接串口、不改接线 |
|
|
153
|
-
| 变量监视 / 观察点 | `stm32_watch`:`action=add` 登记表达式(`kind=value` 只是采样,不用开会话);`action=sample` 停下→逐项求值→算 delta→原本在跑就放回;`kind=write/read/access` 装成硬件观察点(gdb `watch`/`rwatch`/`awatch`),受 F1 的 4 个数据比较器预算约束 |
|
|
154
|
-
| 串口交互(Windows P1) | `stm32_serial`:`list` / `open` / `read` / `send` / `transact` / `status` / `close` 七个动作;零 npm 依赖(PowerShell 5.1 + `System.IO.Ports` 常驻桥持有 COM 口),默认 115200 8N1、DTR/RTS 不拉高、`persist=false`、单会话;**不含 GUI 面板、SSE、Linux/macOS 与自动重连**(见[串口](#串口windows-p1)) |
|
|
155
|
-
| 给模型的工作纪律 | 随插件下发 SKILL `stm32-workflow`(只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据) |
|
|
141
|
+
边界集中在[已知限制](#已知限制):HAL 建工程覆盖 21 个单核族,寄存器建工程覆盖 21 族(验证板为 C8T6),宿主仅在 Windows 验证,探针默认 CMSIS-DAP,新增外设需手工补 HAL 源。外设种类不受工具限制:`.ioc` 里能配置的能力都走同一链路;除闪灯外的外设尚未逐项上板实测,正式开工前建议先执行 `/stm32-doctor`。
|
|
156
142
|
|
|
157
143
|
## 工具参考
|
|
158
144
|
|
|
159
145
|
### 环境与工程
|
|
160
146
|
|
|
161
|
-
| 工具 |
|
|
147
|
+
| 工具 | 用途 |
|
|
162
148
|
| --- | --- |
|
|
163
|
-
| `stm32_doctor` |
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `stm32_project_export` |
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
| 工具 | 作用 |
|
|
149
|
+
| `stm32_doctor` | 只读体检:工具链是否齐备、是否有残留 openocd / gdb、gdb 端口是否占用、`.elf` 与 `.ioc` 是否就位;按芯片输出能力与已知问题 |
|
|
150
|
+
| `stm32_route_plan` | 按具体工程与需求评估 HAL 路线与寄存器路线的开发代价,并区分可自动安装与需人工安装的缺件 |
|
|
151
|
+
| `stm32_env_install` | 安装 MSYS2 与工具链组件(gcc / gdb / openocd / cmake / ninja),默认只出计划,`dryRun:false` + `confirm:true` 才执行;只写用户级 PATH,不请求管理员权限 |
|
|
152
|
+
| `stm32_download` | 只下载不安装:J-Link 官方直链 + 校验和;CubeMX / CubeProgrammer 打开官方页或校验本地文件 |
|
|
153
|
+
| `stm32_firmware_install` | 下载并组装 STM32Cube 固件包,优先官方压缩包,失败回退 GitHub 拼包;默认只出计划 |
|
|
154
|
+
| `stm32_assets` | 查看、校验、清理包内资源(芯片数据、`.ioc` 模板、链接脚本、启动文件、寄存器表) |
|
|
155
|
+
| `stm32_cache` | 查看、校验、拉取、清理下载缓存(寄存器版 CMSIS 模板) |
|
|
156
|
+
| `stm32_project_create` | 建工程:`route:"hal"` 用模板 + 固件包,`route:"register"` 建不依赖 CubeMX 的寄存器工程;两条路线均生成 `openocd.cfg` |
|
|
157
|
+
| `stm32_project_export` | 工程打包为 zip,默认排除 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`,可附编译产物 |
|
|
158
|
+
|
|
159
|
+
### `.ioc`:查看与修改
|
|
160
|
+
|
|
161
|
+
| 工具 | 用途 |
|
|
177
162
|
| --- | --- |
|
|
178
|
-
| `stm32_ioc_inspect` |
|
|
179
|
-
| `stm32_ioc_plan` |
|
|
180
|
-
| `stm32_ioc_apply` |
|
|
181
|
-
| `stm32_ioc_verify` |
|
|
163
|
+
| `stm32_ioc_inspect` | 只读解析:型号、引脚、信号、使能外设、中断、时钟树、工程设置与风险提示 |
|
|
164
|
+
| `stm32_ioc_plan` | 计算逐键差异(不写盘):支持外设预设、引脚、中断、调试口、时钟规划与批量置键 |
|
|
165
|
+
| `stm32_ioc_apply` | 写入计划:源文件校验 → 备份 → 原子替换;支持按备份回滚 |
|
|
166
|
+
| `stm32_ioc_verify` | 由 CubeMX 自己重读 `.ioc`,指出被静默丢弃的外设与缺失的初始化 |
|
|
182
167
|
|
|
183
168
|
### 代码与构建
|
|
184
169
|
|
|
185
|
-
| 工具 |
|
|
170
|
+
| 工具 | 用途 |
|
|
186
171
|
| --- | --- |
|
|
187
|
-
| `stm32_code_patch` |
|
|
188
|
-
| `stm32_generate` |
|
|
189
|
-
| `stm32_build` |
|
|
172
|
+
| `stm32_code_patch` | 只写 `USER CODE BEGIN/END` 块内内容,块外逐字节保留;写前备份 |
|
|
173
|
+
| `stm32_generate` | 无头运行 CubeMX,产物落到 `Core/`,`USER CODE` 按标签搬回;`.ioc` 未变时跳过 |
|
|
174
|
+
| `stm32_build` | 编译:自动推断构建目录与 `.elf`,返回错误行、警告数、FLASH / RAM 占用;可转出 hex / bin |
|
|
190
175
|
|
|
191
|
-
###
|
|
176
|
+
### 烧录、调试与运行时
|
|
192
177
|
|
|
193
|
-
| 工具 |
|
|
178
|
+
| 工具 | 用途 |
|
|
194
179
|
| --- | --- |
|
|
195
|
-
| `stm32_flash` |
|
|
196
|
-
| `stm32_debug_run` |
|
|
197
|
-
| `stm32_debug_session` |
|
|
198
|
-
| `stm32_debug_eval` |
|
|
199
|
-
| `stm32_debug_stop` |
|
|
200
|
-
| `stm32_regs_read` |
|
|
201
|
-
| `stm32_watch` |
|
|
202
|
-
| `stm32_rtt` |
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
寄存器版工程(`route: "register"`)已经把 `Core/Src/rtt.c` 与 `Core/Inc/rtt.h` 建好,但**默认没启用**:没人引用时 `--gc-sections` 会把它们连同 3 KB 环形缓冲一起丢掉(默认固件 1576 B RAM / 1368 B FLASH,`nm` 里没有 `_SEGGER_RTT`)。要开日志,只往 USER CODE 块里加三行:
|
|
180
|
+
| `stm32_flash` | 只烧录:program + verify + reset,烧完释放探针;烧前检查 Serial Wire;失败时给出探针错误的分类与处理建议 |
|
|
181
|
+
| `stm32_debug_run` | 烧录后停在 `main`,抓取寄存器、调用栈与局部变量,随后复位运行并释放探针 |
|
|
182
|
+
| `stm32_debug_session` | 开启长调试会话(空闲与总时长受限),供 `stm32_debug_eval` 连续使用 |
|
|
183
|
+
| `stm32_debug_eval` | 在调试会话中执行 gdb 命令:读变量、寄存器、调用栈、内存 |
|
|
184
|
+
| `stm32_debug_stop` | 关闭调试会话并释放探针 |
|
|
185
|
+
| `stm32_regs_read` | 按地址或符号名读寄存器,有寄存器表时解析位域;读取时短暂暂停,读完继续运行,不复位芯片 |
|
|
186
|
+
| `stm32_watch` | 登记表达式并采样(含差值);`kind=write/read/access` 装为硬件观察点,受芯片观察点数量限制 |
|
|
187
|
+
| `stm32_rtt` | RTT 通道:固件侧把控制块放在 RAM,主机侧经 openocd 读取,输出带级别与时间戳 |
|
|
188
|
+
| `stm32_serial` | 串口交互(Windows):`list` / `open` / `read` / `send` / `transact` / `status` / `close` |
|
|
189
|
+
|
|
190
|
+
### 固件中的 RTT 接入(最短示例)
|
|
207
191
|
|
|
208
192
|
```c
|
|
209
|
-
/* USER CODE BEGIN
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
/*
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
(`rtt.h` 已经在 `Core/Inc` 里,也可以再显式写一行 `#include "rtt.h"` 到 `USER CODE BEGIN Includes`。)编译后在宿主侧取控制块地址:
|
|
216
|
-
|
|
217
|
-
```powershell
|
|
218
|
-
arm-none-eabi-nm build/Debug/<工程名>.elf | findstr _SEGGER_RTT
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
然后让模型跑这三步(下面是 `stm32_rtt` 的三次工具调用,参数名与工具 schema 一致):
|
|
222
|
-
|
|
223
|
-
```text
|
|
224
|
-
stm32_rtt action=start addr=0x20000DE0 # 控制块地址,来自上面那行 nm
|
|
225
|
-
stm32_rtt action=dump seconds=3 level=3 # 读 3 秒内 info 及以上级别
|
|
226
|
-
stm32_rtt action=stop # 释放端口;turn 结束也会自动停
|
|
193
|
+
/* USER CODE BEGIN 0 */
|
|
194
|
+
static char rtt_buf[3][1024];
|
|
195
|
+
static void rtt_init(void) {
|
|
196
|
+
/* 控制块按 SEGGER 约定放在 RAM:acId / acName / 三个环,见 templates/ 中的 rtt.h */
|
|
197
|
+
}
|
|
198
|
+
/* USER CODE END 0 */
|
|
227
199
|
```
|
|
228
200
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
## 串口(Windows P1)
|
|
201
|
+
完整实现见 `templates/` 内的 RTT 模板;通道数与环大小由 `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` 控制(默认 3×1 KB = 3 KB `.bss`,C8T6 只有 20 KB RAM)。
|
|
232
202
|
|
|
233
|
-
|
|
203
|
+
## 斜杠命令
|
|
234
204
|
|
|
235
|
-
|
|
|
205
|
+
| 命令 | 说明 |
|
|
236
206
|
| --- | --- |
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
| `
|
|
243
|
-
| `
|
|
207
|
+
| `/stm32-doctor` | 体检:工具链、残留进程、端口、`.elf` 与 `.ioc` 告警 |
|
|
208
|
+
| `/stm32-env` | 工具链体检:编译 / 烧录 / 调试 / 生成四项能力缺什么、装在哪、如何安装 |
|
|
209
|
+
| `/stm32-setup` | 体检 → 安装计划 → 确认后安装 → 自检 |
|
|
210
|
+
| `/stm32-build [目录] [--clean]` | 编译(CMake + Ninja,默认 `build/Debug`),`--clean` 先全清 |
|
|
211
|
+
| `/stm32-flash [目录]` | 只烧录:program + verify + reset,结束后释放探针 |
|
|
212
|
+
| `/stm32-debug [目录]` | 烧录并进入调试,停在 `main`,之后可用 `stm32_debug_eval` |
|
|
213
|
+
| `/stm32-stop` | 关闭调试会话、释放探针,之后可在 VS Code 中按 F5 |
|
|
244
214
|
|
|
245
|
-
|
|
215
|
+
## 调试台(面板)
|
|
246
216
|
|
|
247
|
-
|
|
248
|
-
stm32_serial action=list
|
|
249
|
-
stm32_serial action=open port=COM3 baudRate=115200
|
|
250
|
-
stm32_serial action=send text="AT"
|
|
251
|
-
stm32_serial action=transact text="AT" until="OK|ERROR" timeoutMs=1000
|
|
252
|
-
stm32_serial action=read cursor=0
|
|
253
|
-
stm32_serial action=close
|
|
254
|
-
```
|
|
217
|
+
会话页签内的「调试台」用于人机同看同一条时间线:`stm32_*` 调用的开始、成功、失败与耗时,以及串口、RTT、监视、引脚、时钟、中断与 `.ioc` 变更。
|
|
255
218
|
|
|
256
|
-
|
|
219
|
+
| 页签 | 内容 | 操作 |
|
|
220
|
+
| --- | --- | --- |
|
|
221
|
+
| 概览 | 工程、型号、SYSCLK、容量、调试会话、工具链、构建与烧录、证据占用、告警摘要 | 跳转失败筛选与实时通道,导出操作记录 Markdown |
|
|
222
|
+
| 事件 | 调用起止、耗时、慢调用标记、参数摘要 | 只看失败、按工具筛选、按耗时排序、批量引用、导出 JSONL、事件深链 |
|
|
223
|
+
| 实时通道 | 串口 / RTT / 监视输出 | 暂停、清空、关键字过滤、RTT 级别过滤、发送串口行、常驻采集、导出 |
|
|
224
|
+
| 引脚 | 按外设分组、按端口排布、按封装方框 | 筛选、复制引用、查看 `.ioc` 键、导出 CSV |
|
|
225
|
+
| 时钟 | 树与流向两种视图、各节点频率与分频 | 超限标记与「改为 ÷N」建议(按父时钟计算) |
|
|
226
|
+
| 中断 | NVIC 使能、抢占与子优先级 | 筛选、排序、就地修改、批量修改 |
|
|
227
|
+
| 故障 | 失败事件原文、规则解码、按规则合并 | 分类筛选、复制组提示、导出 CSV |
|
|
228
|
+
| 产物 | elf / hex / bin、大小、校验和、容量、两次构建对比 | 复制校验和 |
|
|
229
|
+
| 变更 | `.ioc` 与基线的差异 | 记基线、恢复单键、一次恢复全部 |
|
|
257
230
|
|
|
258
|
-
|
|
231
|
+
打开面板会先补齐本会话最近的记录,之后实时追加。事件每 30 秒写入 `~/.dsh-stm32/evidence/<日期>/<会话>/`,可回放、导出;默认保留 7 天、最近 20 个会话,可在配置里调整。面板只展示本插件自己的工具调用,不含其他工具的调用。
|
|
259
232
|
|
|
260
|
-
|
|
233
|
+
## 串口(Windows)
|
|
261
234
|
|
|
262
|
-
|
|
235
|
+
`stm32_serial` 提供七个动作:`list` / `open` / `read` / `send` / `transact` / `status` / `close`。打开端口后由插件持有,一次一个端口,默认 115200 8N1、无流控、DTR / RTS 不拉高,回合结束时自动关闭。
|
|
263
236
|
|
|
264
|
-
|
|
237
|
+
- 平台:仅 Windows;Linux 与 macOS 返回 `unsupported-platform`。
|
|
238
|
+
- 端口:`list` 枚举可用端口;端口参数按设备记忆,换 COM 号后可复用。
|
|
239
|
+
- 读:`read` 支持游标,只返回游标之后的新行。
|
|
240
|
+
- 写入:`send` 发送一行,`transact` 发送并等待匹配回包(正则)。
|
|
241
|
+
- 保留:`persist=true` 跨回合保留端口。
|
|
265
242
|
|
|
266
|
-
|
|
267
|
-
| --- | --- | --- |
|
|
268
|
-
| `/stm32-doctor` | 体检:工具链、被占用的调试进程、端口、`.elf`、`.ioc` 告警 | 否 |
|
|
269
|
-
| `/stm32-setup` | 体检 + 安装计划一次跑完;命令里带「装」字才真装(例如 `/stm32-setup 装上缺的`) | 否 |
|
|
270
|
-
| `/stm32-env` | 看四项能力(编译 / 烧录 / 调试 / 生成代码)各缺什么、装什么、装完怎么自检;缺件也照常出卡片 | 否 |
|
|
271
|
-
| `/stm32-build [dir] [--clean]` | 编译,打印内存占用 / `.elf` / 错误 | 否 |
|
|
272
|
-
| `/stm32-flash [dir]` | **烧录**:program + verify + reset,不建调试会话、不下断点 | 是 |
|
|
273
|
-
| `/stm32-debug [dir]` | **烧录 + 调试**:烧完停到 `main`,会话保留(空闲 3 分钟 / 上限 10 分钟,本轮结束也会自动关) | 是 |
|
|
274
|
-
| `/stm32-stop` | 关掉 `/stm32-debug` 开的会话,把探针还给 VS Code | 否 |
|
|
275
|
-
|
|
276
|
-
`[dir]` 省略时用当前会话的工作目录。
|
|
243
|
+
参考验证板为 CH340(`1A86:7523`,COM5,115200)。同一板上的 DAPLink 虚拟串口(`c251:f001`,COM4)不承载应用串口数据。
|
|
277
244
|
|
|
278
245
|
## 设计要点
|
|
279
246
|
|
|
280
|
-
-
|
|
281
|
-
-
|
|
282
|
-
-
|
|
283
|
-
-
|
|
284
|
-
-
|
|
285
|
-
|
|
286
|
-
## 芯片、链接脚本与时钟
|
|
287
|
-
|
|
288
|
-
- **型号是参数,不是常量。** `stm32_project_create` / `stm32_generate` 按 `mcu` 一起换三样:启动文件(`startup_stm32f103xe.s`)、设备宏(`STM32F103xE`)、链接脚本(`STM32F103RCTx_FLASH.ld`)。HAL 路线走 `src/engine/hal-chip.ts`(`resolveHalChip()` 按族分发:F1 走手写 RAM 表,其它族走内置资源的 `device/<族>/chips.json`;`renderStartupAndDefine` / `renderLinkerScript` / `renderIoc` / `renderCmakeLists` / `renderOpenocdTarget`),寄存器路线走 `src/data/stm32f1.ts`(`resolveF1Chip()`,14 个容量档,每个启动文件都钉了上游 sha256)。认不出的型号直接给原因,不猜一个上游不存在的启动文件名。
|
|
289
|
-
- **链接脚本按 `DeviceId` 命名:`<DeviceId>_FLASH.ld`。** C8T6 → `STM32F103C8Tx_FLASH.ld`(64 KiB Flash / 20 KiB RAM),RCT6 → `STM32F103RCTx_FLASH.ld`(256 / 48),F107VCT6 → `STM32F107VCTx_FLASH.ld`(256 / 64)。模板里那份旧的 `STM32F103XX_FLASH.ld` 只作 C8T6 的兼容副本;CMake 的 `-T` 一律指向按型号渲染的那份(`pointLinkerFlagAt()` 把工具链文件里的旧名改指过去,避免两个 `-T` 让 ld 取错脚本)。
|
|
290
|
-
- **时钟就近,不可达就明说。** `stm32_ioc_plan` 的 `clock: { targetHz }`(也可 `pllMul` 钉死倍频、`pllSource` 选 HSE / HSI)枚举全部可行的 PLL 组合,取 |SYSCLK − 目标| 最小的一档,并把差距写进结论:要 60 MHz 时 F1 的 PLL 只能整数倍频、HSE 8 MHz 拼不出这一档,于是选 64 MHz 并标注「不可达,已选 64 MHz(+4 MHz)」(同距取更高档)。同一次 plan 里把 `SYSCLKFreq_VALUE` / `HCLKFre` / `PLLMUL` / APB1·APB2·ADC 分频这些派生键**全量重算**——只改 SYSCLK 不动它们,CubeMX 会按旧值重算或干脆不认;同时列出逐外设频率、UART 波特率的整除误差与几个备选档。超限(SYSCLK > 72 MHz、APB1 > 36 MHz、ADC > 14 MHz、USB 要 48 MHz 却不在 PLLCLK/1.5 这条路上)时**一个键都不写**。
|
|
291
|
-
- **烧前五项一致。** `stm32_doctor` 核对「`.ioc` 型号 ↔ 启动文件名 ↔ cmake 里的设备宏 ↔ `.ld` 的 MEMORY 容量 ↔ `.elf` 的 Flash 占用」,任一错配报 blocker。`.elf` 那份占用是读 ELF program header 的 `p_filesz` 累加,不是文件大小——带 `-g3` 时 20 KiB 固件的 `.elf` 能有 600 KB,按文件大小判会误报「超 Flash」。
|
|
292
|
-
- **寄存器路线按芯片给内存映射,不按族套一张表。** 21 族的启动文件、设备宏、Flash/RAM 都来自 `assets/device/<族>/chips.json`;H7 默认只用 DTCM 128 KiB(`0x20000000`,138 颗都带 `linkerRam`),U5 按 line 给 256 KiB / 768 KiB / 2496 KiB 的 SRAM 窗口,L4+ 与 L5 是单块连续(L5 的 192+64 KiB 相邻,合并成 256 KiB)。链接脚本的 `MEMORY` ORIGIN/LENGTH 随之渲染,`_estack` 落在窗口顶上——不会出现「编译过、上电 HardFault」的静默越界(见 development-notes §87)。
|
|
247
|
+
- **只写自有文件**:`.ioc` 走事务(计划 → 校验 → 备份 → 替换),生成区只写 `USER CODE` 块,其余生成文件不由插件修改。
|
|
248
|
+
- **烧录与调试分离**:`stm32_flash` 不建立调试会话,烧完即释放探针;需要调试时才开 `stm32_debug_session`,空闲自动关闭,避免与 VS Code 抢占探针。
|
|
249
|
+
- **结论附证据**:失败时给出编译器 `文件:行:列`、探针错误分类、寄存器读数,而不是模糊描述。
|
|
250
|
+
- **缺什么就说什么**:芯片、时钟或调试脚本不受支持时,报错直接说明缺哪一项,不猜测、不静默跳过。
|
|
251
|
+
- **不接管宿主**:面板只展示状态与执行明确的工程动作,不做代码编辑与 Git 操作。
|
|
293
252
|
|
|
294
253
|
## 配置
|
|
295
254
|
|
|
296
|
-
###
|
|
255
|
+
### 配置文件(`~/.dsh-stm32/config.json`)
|
|
297
256
|
|
|
298
|
-
|
|
257
|
+
工具链位置由插件维护:`stm32_env_install` 安装后写入该文件,后续工具直接读取,无需重启 DSH 或设置环境变量。也可手工编辑:
|
|
299
258
|
|
|
300
259
|
```json
|
|
301
260
|
{
|
|
@@ -308,89 +267,51 @@ stm32_serial action=close
|
|
|
308
267
|
}
|
|
309
268
|
```
|
|
310
269
|
|
|
311
|
-
`binDirs`
|
|
312
|
-
|
|
313
|
-
**优先级**:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 这个配置文件 > 内置默认值;自动发现只追加在"没点名参数"的那一档尾部。
|
|
314
|
-
|
|
315
|
-
**内置默认值里没有任何"某台机器专属"的路径**:只有 `C:/msys64/...` 与 `C:/Program Files/...` 这种 Windows 默认安装位置,装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在(典型情况:配置是从别的机器拷过来的,带着 `D:/app/msys64` 这种路径),门禁与 `stm32_doctor` 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」,而**不会**悄悄改你的配置;安装器也不会拿这种路径当安装目标(盘符都没有时只提示、并要求你给 `targetDir`)。
|
|
270
|
+
`binDirs` 为空时由 `msys64` 推导 `<msys64>/ucrt64/bin`。文件损坏(JSON 非法)视为不存在,不影响其他功能。
|
|
316
271
|
|
|
317
|
-
|
|
272
|
+
优先级:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 配置文件 > 内置默认值。内置默认值只含 Windows 常见位置,不含任何机器专属路径。
|
|
318
273
|
|
|
319
|
-
|
|
274
|
+
### 设置面板
|
|
320
275
|
|
|
321
|
-
|
|
322
|
-
- **缺什么**:跑一次探测(会执行各工具的版本命令,不装任何东西),逐项显示找到的路径与版本、缺件的 `hint`,以及编译 / 烧录 / 调试 / 生成四项能力徽章;
|
|
323
|
-
- **装工具链**:先出计划(步骤、下载体积、PATH 与配置会怎么改),**再点一次确认**才真装;装的过程实时显示步骤与日志尾巴,实际执行与 `stm32_env_install` 是同一个安装器。工具链已经完整时,计划只回一句话「工具链完整,不需要装任何东西」,不列那七行「已跳过」。
|
|
276
|
+
DSH 设置内的「STM32 工具链」页提供三张卡片:
|
|
324
277
|
|
|
325
|
-
|
|
278
|
+
- **装在哪**:读取并保存 `msys64` / `cubeMxRoot` / 额外 `binDirs`,保存后下一条工具调用即生效。
|
|
279
|
+
- **缺什么**:执行一次探测(只读版本查询),逐项显示路径、版本、缺失原因,以及编译 / 烧录 / 调试 / 生成四项能力徽章。
|
|
280
|
+
- **装工具链**:先出计划(步骤、下载体积、PATH 与配置变更),确认后执行;过程显示步骤与日志尾部。
|
|
326
281
|
|
|
327
|
-
###
|
|
282
|
+
### 下载缓存与固件包
|
|
328
283
|
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
-
|
|
332
|
-
- 索引:缓存根下 `index.json` 记录每条源 URL、字节数、许可(`THIRD_PARTY_NOTICES.md` 随条目一起写);
|
|
333
|
-
- 下载源:按 `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy` 的顺序回退,HTTP 错误 / 内容像网页 / 字节数明显不对都算该源失败;
|
|
334
|
-
- 半截缓存会被整条删掉(比没有缓存更糟);条目文件缺失或大小对不上时下次自动重下;
|
|
335
|
-
- 看得见、清得掉:`stm32_cache` 的 `list` / `verify` / `fetch` / `purge`。
|
|
336
|
-
|
|
337
|
-
### 固件包下载(HAL 路线)
|
|
338
|
-
|
|
339
|
-
CubeMX 装好也不一定有**这一颗芯片**的固件包(安装包里不带,得在包管理器里另装)。`stm32_firmware_install` 有两条通道,默认先试官网:
|
|
340
|
-
|
|
341
|
-
- 官网直取(`source: "auto"` 的第一步):按 db 里那颗芯片的 `FwLibrary`(多数族为空,按族名兜底;H7RS / MP13 / WB0 / WL3 有专名)拼 `https://sw-center.st.com/packs/resource/firmware/stm32cube_fw_<族小写>_v<版本去点>.zip`,下载后验 `Content-Length` 与 zip 里每一条的 CRC32,再调 CubeMX 的 `swmgr install <本地 zip> ask` 装进 `Repository`——这个包是 CubeMX 自己记账的,包管理器里看得见、删得掉;
|
|
342
|
-
- 三种失败会把原因写进 `notes` 再回退下面的 GitHub 拼包:没装 CubeMX、CubeMX 正开着 GUI、**首次装某族的新版本时 CubeMX 要弹许可协议窗等人点同意**(无头只能超时,插件不替你点,也不代勾);`source: "official"` 则只走这条,失败直接报错;
|
|
343
|
-
|
|
344
|
-
回退通道(GitHub 拼包):
|
|
345
|
-
|
|
346
|
-
- 下什么:`stm32f1xx-hal-driver`(HAL 驱动,BSD-3-Clause)+ `cmsis-device-f1`(设备头与启动文件,Apache-2.0)+ 5 个 CMSIS 内核头,合计约 2 MB、几秒钟;
|
|
347
|
-
- 完整性:每个归档只走 `codeload.github.com/<repo>/tar.gz/refs/heads/<ref>` 一条源,归档与每个内核头都在 `src/data/firmware-pins.ts` 钉了 sha256(维护脚本 `scripts/firmware/pin-firmware.mjs` 重算);下载内容对不上哈希就整包拒收,不会解压落盘。上游 master 挪动文件时,报错会给出期望/实际哈希;
|
|
348
|
-
- 为什么不能直接解压 `STM32CubeF1` 的源码包:它的 HAL 与 CMSIS 设备目录是 **git 子模块**,tarball 里是空目录——解压出来编译必挂(缺 startup、缺 HAL 源文件);
|
|
349
|
-
- 装到哪:默认 `<CubeMX 根>/dsh-firmware/<包名>`(与 `Repository` 并列、插件自建,不动官方包);这个根写不进去才退回用户缓存目录。**别往 `Repository` 里塞自造版本号**——实测 CubeMX 认不出那个版本名,不报错地退回它自己认识的包(生成「成功」,HAL 却是旧版);
|
|
350
|
-
- 生成时怎么用上它:`stm32_generate` 按 `.ioc` 的 `ProjectManager.FirmwarePackage` 找包(`Repository` 与 `<CubeMX 根>/dsh-firmware` 都找),并在 CubeMX 脚本里发 `project setCustomFWPath <包目录>`——这是唯一被实测有效的机制,不往 `.ioc` 里写绝对路径;
|
|
351
|
-
- 组装包与官方包同构:自写 6 行 `package.xml`(版本串 `FW.<族>.<x.y.z>`)与 `THIRD_PARTY_NOTICES.md`;`package.xml` 里不写哈希清单(CubeMX 不校验来源),完整性由下载阶段逐文件 sha256 保证——已实测:用 `setCustomFWPath` 指过去生成,拷出的 HAL 源文件逐字节来自我们目录;
|
|
352
|
-
- 但「生成成功」不能当验收:`.ioc` 点名了不存在的包时 CubeMX 不报错、退出码 0、只是不拷 HAL。所以装完必须过五条判据(内核头 / HAL Inc / HAL Src / 设备头 / `startup_*.s`),插件装完自己就验一遍。
|
|
353
|
-
|
|
354
|
-
### 安装包下载(只下载,不安装)
|
|
355
|
-
|
|
356
|
-
`stm32_download` 把「拿到安装包」和「装它」分开:插件只负责下载/校验,安装由你自己双击。
|
|
357
|
-
|
|
358
|
-
| 组件 | 行为 |
|
|
359
|
-
| --- | --- |
|
|
360
|
-
| `jlink` | 从 SEGGER 官方直链下载 8.18.0(约 59 MB),边下边算 SHA256,和官方值 `63110b6fc55e494d197d6efa156d7f61c0dd0c1f776424995a05407e2d7f566f` 对比;已存在且哈希正确直接复用;失败/哈希不符删临时文件 |
|
|
361
|
-
| `cubemx` / `cubeprogrammer` | ST 官网要登录 myST、接受许可,直链会过期:默认只返回官方页;`dryRun:false + confirm:true` 打开浏览器。也可 `file: "D:/.../installer.exe"` 只计算 SHA256,供你自己核对 |
|
|
362
|
-
|
|
363
|
-
默认 `dryRun:true`,只出计划,不联网。下载目录 `%LOCALAPPDATA%\dsh-stm32\downloads`,可用 `DSH_STM32_DOWNLOADS` 或 `outDir` 覆盖。工具不会执行安装器、不写注册表、不改 PATH;J-Link 的 USB 驱动需要你在安装器里选 all users 并允许 UAC(现代探针默认 WinUSB,老探针才需要 legacy 驱动)。
|
|
284
|
+
- 寄存器版 CMSIS 模板首次使用时下载到缓存(默认 `%LOCALAPPDATA%\dsh-stm32\cache`),之后复用;逐文件校验,变更即拒收。`stm32_cache` 可查看、校验、拉取与清理。
|
|
285
|
+
- HAL 路线使用本机 CubeMX 固件包:F1 默认 `STM32Cube_FW_F1_V1.8.7`,其他族取已安装的最高版本;可用 `firmwarePackage` 指定。缺失时先在 CubeMX 包管理器中安装,或用 `stm32_firmware_install` 下载组装。
|
|
286
|
+
- `stm32_download` 只下载或校验安装包(默认目录 `%LOCALAPPDATA%\dsh-stm32\downloads`),不执行安装器,不请求管理员权限。
|
|
364
287
|
|
|
365
288
|
### 环境变量(可选)
|
|
366
289
|
|
|
367
290
|
| 变量 | 作用 | 默认 |
|
|
368
291
|
| --- | --- | --- |
|
|
369
|
-
| `STM32_BIN_DIRS` | 工具链目录候选,`;`
|
|
370
|
-
| `STM32_CUBEMX_ROOT` |
|
|
371
|
-
| `STM32_NO_DISCOVER` | 设为 `1`
|
|
372
|
-
| `DSH_STM32_CONFIG` |
|
|
373
|
-
| `DSH_STM32_NO_CONFIG` | 设为 `1`
|
|
374
|
-
| `DSH_STM32_CACHE` |
|
|
375
|
-
| `DSH_STM32_DOWNLOADS` |
|
|
376
|
-
| `
|
|
377
|
-
| `
|
|
378
|
-
| `
|
|
379
|
-
| `
|
|
380
|
-
| `
|
|
381
|
-
| `
|
|
382
|
-
| `
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
### openocd.cfg(工程内,优先于内置回退)
|
|
292
|
+
| `STM32_BIN_DIRS` | 工具链目录候选,`;` 分隔,整份替换内置列表(自动发现仍追加在尾部) | `C:/msys64/ucrt64/bin`、`C:/msys64/mingw64/bin` |
|
|
293
|
+
| `STM32_CUBEMX_ROOT` | CubeMX 安装根,整份替换内置列表 | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
294
|
+
| `STM32_NO_DISCOVER` | 设为 `1` 关闭自动发现(仅用内置列表) | 不设 |
|
|
295
|
+
| `DSH_STM32_CONFIG` | 替换配置文件路径 | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
296
|
+
| `DSH_STM32_NO_CONFIG` | 设为 `1` 完全不读配置文件 | 不设 |
|
|
297
|
+
| `DSH_STM32_CACHE` | 下载缓存根目录,支持 `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
298
|
+
| `DSH_STM32_DOWNLOADS` | 安装包下载目录,支持 `~` | `%LOCALAPPDATA%\dsh-stm32\downloads` |
|
|
299
|
+
| `DSH_STM32_HOME` | 插件数据根目录(配置、证据、快照、备忘) | `%USERPROFILE%\.dsh-stm32` |
|
|
300
|
+
| `DSH_STM32_EVIDENCE` | 证据目录 | `~/.dsh-stm32/evidence` |
|
|
301
|
+
| `DSH_STM32_EVIDENCE_FLUSH_SECONDS` | 证据落盘间隔(5–3600 秒) | 30 |
|
|
302
|
+
| `DSH_STM32_EVIDENCE_KEEP_DAYS` | 证据保留天数(0–365,0 = 不清理) | 7 |
|
|
303
|
+
| `DSH_STM32_EVIDENCE_KEEP_SESSIONS` | 证据保留会话数(1–200) | 20 |
|
|
304
|
+
| `DSH_STM32_SNAPSHOTS` | `.ioc` 基线目录 | `~/.dsh-stm32/ioc-snapshots` |
|
|
305
|
+
| `DSH_STM32_OFFLINE` | 设为 `1` 禁止联网下载(模板与固件包仅用本地缓存) | 不设 |
|
|
306
|
+
| `MSYS2_MIRROR` | 安装包镜像,必须与 `MSYS2_INSTALLER_SHA256` 同时设置 | 官方 → TUNA → NJU → 阿里云 |
|
|
307
|
+
| `MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_SHA256` | 覆盖安装包地址与校验和,必须成对设置 | 官方固定版本 |
|
|
308
|
+
| `DSH_STM32_JLINK_URL` / `DSH_STM32_JLINK_SHA256` | 覆盖 J-Link 直链与校验和,必须成对设置 | SEGGER 官方 |
|
|
309
|
+
|
|
310
|
+
工具参数与上述变量等价:烧录与调试类接受 `binDirs`、`elfPath`、`buildDir`、`configFile`、`adapterSpeed`;生成与建工程类接受 `cubeMxRoots`、`firmwarePackage`。
|
|
311
|
+
|
|
312
|
+
工具链位置通常无需配置:未指定 `binDirs` / `STM32_BIN_DIRS` 时,插件会在常见位置查找并追加候选——`<盘>/msys64`、`<盘>/msys2`、`<盘>/app/msys64`、`<盘>/tools/msys64`、`%LOCALAPPDATA%/Programs/msys64` 下的 `ucrt64/bin`、`mingw64/bin`、`clang64/bin`,以及 `STM32CubeMX_PATH` 环境变量、CubeMX 卸载登记项、`Program Files\STMicroelectronics\STM32Cube` 等位置下的 CubeMX。找不到时,错误与 `stm32_doctor` 会列出已检查的目录。
|
|
313
|
+
|
|
314
|
+
### openocd.cfg(工程内优先)
|
|
394
315
|
|
|
395
316
|
CMSIS-DAP(默认):
|
|
396
317
|
|
|
@@ -400,7 +321,7 @@ source [find target/stm32f1x.cfg]
|
|
|
400
321
|
adapter speed 4000
|
|
401
322
|
```
|
|
402
323
|
|
|
403
|
-
ST-Link
|
|
324
|
+
ST-Link:
|
|
404
325
|
|
|
405
326
|
```text
|
|
406
327
|
source [find interface/stlink.cfg]
|
|
@@ -408,109 +329,81 @@ transport select hla_swd
|
|
|
408
329
|
source [find target/stm32f1x.cfg]
|
|
409
330
|
```
|
|
410
331
|
|
|
411
|
-
|
|
412
|
-
C0 / U0 这两族 openocd 0.12 里没有官方脚本,插件自带一份适配版:建工程时会复制到工程的 `openocd/stm32c0x.cfg`(U0 同理),
|
|
413
|
-
`openocd.cfg` 里写 `source [find openocd/stm32c0x.cfg]`,`.vscode/launch.json` 用 `${workspaceFolder}/openocd/stm32c0x.cfg`。
|
|
414
|
-
其它没有脚本的族(H5 / N6 / U3 / WBA / WB0 / WL3 / MP2)会**明确拒绝烧录**,不会拿别的族的脚本硬连。ST-Link 用户把上面第二段写进工程根目录的 `openocd.cfg` 即可。
|
|
332
|
+
工程内没有 `openocd.cfg` 时按 `.ioc` 的芯片族选择调试脚本(F1 → `stm32f1x`、F4 → `stm32f4x`、G4 → `stm32g4x`;L4 与 L4+ 共用 `stm32l4x`)。C0 / U0 的脚本随插件提供并在建工程时复制到工程的 `openocd/` 目录;H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 暂无脚本,烧录会被明确拒绝。
|
|
415
333
|
|
|
416
|
-
###
|
|
334
|
+
### `.ioc` 的两个硬要求
|
|
417
335
|
|
|
418
|
-
1. **SYS
|
|
419
|
-
2. **`ProjectManager.KeepUserCode=true`**;否则重新生成时 USER CODE
|
|
336
|
+
1. **SYS 调试口为 Serial Wire**(PA13 = `SYS_JTMS-SWDIO`、PA14 = `SYS_JTCK-SWCLK`);缺失时用 `stm32_ioc_plan` 的 `serialWire: true` 补齐。
|
|
337
|
+
2. **`ProjectManager.KeepUserCode=true`**;否则重新生成时 `USER CODE` 内容不保留。
|
|
420
338
|
|
|
421
339
|
## 已知限制
|
|
422
340
|
|
|
423
|
-
| 限制 | 说明 |
|
|
341
|
+
| 限制 | 说明 | 处理方式 |
|
|
424
342
|
| --- | --- | --- |
|
|
425
|
-
|
|
|
426
|
-
|
|
|
427
|
-
|
|
|
428
|
-
| 深层能力按族分级 |
|
|
429
|
-
| 探针按 USB
|
|
430
|
-
|
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
|
|
|
434
|
-
|
|
|
435
|
-
| **串口成功路径未上真机** | 真桥只验过失败路径(`COM99` → `port-not-found`);`state=open`、真实收数、DTR/RTS 实际电平、桥 5 s 看门狗与 idle 自动放口都没有硬件证据(假桥按同一契约覆盖) | 插一块板子跑 `list` → `open` → `read` → `close`;细节见 development-notes §86 |
|
|
436
|
-
| **寄存器新增 8 族已通过独立验收** | 0.1.5 把寄存器建工程从 13 族扩到 21 族(+ H5 / H7 / L4+ / L5 / U3 / U5 / WBA / WL):8 族 `create→build` 矩阵全过(warning 0 / error 0,逐族 FLASH/RAM 见 development-notes §87.5);H7 的 `-mcpu` 按族生成与 `cachel1_armv7.h` 已随模板修掉 | t8 独立复验已通过(21 族清单、GPIO 门、linkerRam、296 条事实断言、8 族重建全 exit 0,见 development-notes §87.6);新增 8 族可按 §87.5 的型号试 |
|
|
437
|
-
| **寄存器符号名与位域解释要靠内置 SVD(full 逻辑层)** | `GPIOC.ODR` / `GPIOC->ODR` 与外设 dump(只写 `GPIOC`)都从 `assets/device/f1/svd/<line>.json` 解析(ST SVD 派生,1.71 MiB),只覆盖 100/101/102/103/105/107。没有 SVD 时纯地址照读,只是没有名字和位域;符号名会报错并提示重装插件(full 也随包) | 写 `0x` 开头的地址;或 `stm32_assets verify` 确认安装完整性 |
|
|
343
|
+
| 仅在 Windows 验证 | 生成代码依赖 CubeMX 的 Windows 安装形态 | 暂无可替代方案;烧录、调试、读寄存器在其他平台理论可用,未验证 |
|
|
344
|
+
| 部分芯片暂无官方调试脚本 | C0 / U0 用插件自带的适配脚本(未上板验证);H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 暂无脚本 | 烧录前会明确说明,不会静默失败 |
|
|
345
|
+
| HAL 建工程不覆盖双核与 MPU 系列 | 双核 WB、MP1 / MP2 / N6、WB0 / WL3 不在范围内 | 建工程时直接说明不支持 |
|
|
346
|
+
| 深层能力按族分级 | HAL 21 族、寄存器 21 族、时钟 18 族;寄存器名与位域目前只有 F1 | 缺哪项就在调用时说明哪项 |
|
|
347
|
+
| 探针按 USB 实见选择 | ST-Link、DAPLink / CMSIS-DAP、J-Link 自动区分;工程内 `openocd.cfg` 优先 | 需要固定选择时手写 `openocd.cfg` |
|
|
348
|
+
| 新增外设需手工补 HAL 源 | 插件只放置 `Src/` 与 `Inc/`,CubeMX 生成的 `cmake/**` 不搬运 | 修改 `STM32_Drivers_Src` 或写入 `cmake/user/CMakeLists.txt` |
|
|
349
|
+
| 生成与建工程需要 CubeMX 与对应固件包 | F1 默认 `STM32Cube_FW_F1_V1.8.7` | 传 `firmwarePackage`,或先在 CubeMX 内安装固件包 |
|
|
350
|
+
| RTT 仅通道 0,帧头为自定义格式 | 13 字节头(长度 + 级别 + 时间戳 + UTF-8 正文) | 用级别过滤;结构化内容写入正文;通道与环大小见 `rtt.h` |
|
|
351
|
+
| 串口仅 Windows | 不含推流、自动重连,一次一个端口 | 使用系统串口工具,或等待后续版本 |
|
|
352
|
+
| 寄存器名与位域依赖内置寄存器表 | 目前覆盖 F1 的 100 / 101 / 102 / 103 / 105 / 107 | 使用 `0x` 开头的地址;`stm32_assets verify` 检查安装完整性 |
|
|
438
353
|
|
|
439
354
|
## 排错
|
|
440
355
|
|
|
441
|
-
| 现象 |
|
|
442
|
-
| --- | --- |
|
|
443
|
-
| 装插件时 `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` | 这是**取包这一跳**连不上 GitHub(`dsh plugin add github:…` 会走 git 去拉仓库),跟 pnpm 11 的 `allowBuilds` 白名单、包体签名、包本身都没关系——换个网络就能装上。三条路按省事程度排:① 用 npm 上的正式包:`dsh plugin --profile desktop add dsh-stm32`(走 npm registry,不碰 GitHub);② 一定要从 GitHub 装,就只给这一条命令挂代理,用进程级 `GIT_CONFIG_*` 临时生效、**不动你的全局 git 配置**:`$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main`(端口换成你自己的);③ 绕开 git、直接吃 HTTPS 包:`dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`。**装最新**永远用 `github:JingYu-er/dsh-stm32#main`,已经 publish 的版本用 `dsh-stm32@latest`——两者内容一致,后者不依赖 GitHub |
|
|
444
|
-
| 烧完连不上、SWD 失联 | 固件里生成了 `__HAL_AFIO_REMAP_SWJ_DISABLE()`。按住 BOOT0 上电进系统 bootloader 重烧,然后把 SYS 设回 Serial Wire——`stm32_flash` 现在会先拦这种情况 |
|
|
445
|
-
| `Error: No device found` / `transfer count mismatch` | 探针被别的进程占着。先 `/stm32-stop`,再用 `stm32_doctor` 看 openocd / gdb 进程与 3333 端口。调试会话开着时读寄存器不会再有这个问题:`stm32_regs_read` 复用会话的 openocd,不另起第二个 |
|
|
446
|
-
| 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read` 借用会话里那个 openocd,notes 会写清「复用调试会话(gdb 端口 N,tcl 端口 M),没有另起 openocd」。B3 之后默认走 **Tcl RPC 直读**(一条 TCP 连接:halt → 读 pc → 连续 `mdw` → resume,毫秒级),所以 `report.command` 是 `gdb-multiarch …` 只说明 Tcl 快路径没成、回退到了会话里的 gdb,原因写在 notes 里;只有没有会话时才另起 openocd。旧版在这里会报 `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
447
|
-
| 编译"成功"但跑的是旧固件 | 复制或改名过带 `build/` 的工程:CMakeCache 里的目录对不上,ninja 仍退出 0。`stm32_build` 会判失败;按提示 clean 或删 `build/Debug` |
|
|
448
|
-
| 工具直接回「缺 arm-none-eabi-gcc…,这次没有开始编译」 | 这是开工前门禁(`envCheck` 默认 `block`)拦下来的,不是 bug:它比跑到一半才发现省时间。回一句「装」,模型调 `stm32_env_install` 出计划;确认后装好并写配置文件,**下一条命令就能用,不必重启**。想先看全貌就 `/stm32-env`;只想先跑起来就传 `envCheck: "warn"`(照做但写警告)或 `"off"`(不查) |
|
|
449
|
-
| 第一次建工程回「设备事实还没就绪……」 | 插件随包内置芯片表(`assets/device/f1/chips.json`),正常安装不会出现;报这个说明插件安装不完整。跑 `stm32_assets verify` 看缺了哪些文件,重装插件即可(无需联网);`DSH_STM32_ASSETS` 只用于开发时覆盖资源根 |
|
|
450
|
-
| `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_doctor`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
|
|
451
|
-
| `stm32_generate` 很慢或像卡住 | 首次(冷启动、无缓存)3.5–4 分钟属正常,之后 .ioc 与产物没变会直接跳过(<1 s)。默认后台 job,用 `job_output` 看进度,或传 `foreground: true` 同步等。想确认是不是漏命中缓存,看返回里的 `skipped` 与 notes 给的 reason |
|
|
452
|
-
| 生成没变化却每次都跑满 3 分钟 | 缓存键里含 CubeMX 的 size+mtime 与产物 hash:换过 CubeMX、改过生成区文件、或改过落位布局都会失效。看 notes 里的 reason,或删 `.dsh-stm32/generate-cache.json` 从干净状态重来 |
|
|
453
|
-
| 生成变快了,但 CubeMX GUI 里看不到扩展包了 | `thirdpartyPacks: "auto"` 会在不需要扩展包时把 `thirdparties/pdsc` 停放成 `pdsc.dsh-parked`,生成结束自动还原。若正在 CubeMX GUI 里手工选包,传 `thirdpartyPacks: "keep"` |
|
|
454
|
-
| notes 说「本机第三方包索引里没有这个包」 | 工程要用的 X-CUBE 包本机没装(判定靠 `.ioc` 里的 `Mcu.ThirdParty<k>` 与内置包目录对名字)。在 CubeMX 的 Manage embedded software packages 里装上它再生成。这条在**生成失败的报告里也会出现**(超时/报错时照样带 notes,先看 notes 再猜原因)。内置目录是快照,装了新包后重跑 `node scripts/gen-xcube-catalog.mjs` 更新(旧的目录只是不认识新包,不会误判成「不需要」) |
|
|
455
|
-
| `stm32_code_patch` 说块不存在 | `main.c` 里是短标签(`PV`=私有变量、`PFP`=函数原型、`2`=while 前初始化、`3`=循环体);报错会列出该文件全部可用标签,照抄即可 |
|
|
456
|
-
|
|
457
|
-
## 开发与测试
|
|
458
|
-
|
|
459
|
-
```powershell
|
|
460
|
-
npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
|
|
461
|
-
npm test # 60 个离线套件、947 个用例;不需要板子、CubeMX、工具链
|
|
462
|
-
npm run test:pack # 把包打成 tarball、解开、用解包出来的 lib 真建一次寄存器工程
|
|
463
|
-
npm run test:size # 包体护栏:tarball ≤3.9 MB、templates 里的运行时资产(.ioc/.xml/.ld/.json/.cfg)≤40 KB、包内不许二进制/图表
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test → test:pack → test:size`(windows-latest)。
|
|
467
|
-
|
|
468
|
-
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上会 skip 那 2 条,开发机上是 **947 pass / 0 fail** 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
|
|
469
|
-
|
|
470
|
-
### 发布形态三分法(先把东西放哪想清楚,再写包)
|
|
471
|
-
|
|
472
|
-
| 放哪 | 内容 | 量级 |
|
|
356
|
+
| 现象 | 原因 | 处理 |
|
|
473
357
|
| --- | --- | --- |
|
|
474
|
-
|
|
|
475
|
-
|
|
|
476
|
-
|
|
|
477
|
-
|
|
|
478
|
-
|
|
|
358
|
+
| 插件未加载 | profile 的 `dsh.profile.bundles` 未包含 `dsh-stm32`,或未重启 | 重装并重启 DSH;用 `dsh plugin --profile desktop why dsh-stm32` 校验 |
|
|
359
|
+
| 修改代码后行为未变 | 用 `file:` 安装,宿主读取的是拷贝 | 改用 `link:`,重新 `npm run build` 并重启 DSH |
|
|
360
|
+
| 报缺工具链 | 未安装或路径未收录 | 先跑 `/stm32-env` 看缺什么,再 `/stm32-setup` 安装;或手工设置 `binDirs` |
|
|
361
|
+
| 烧录报探针占用 | 其他调试器(VS Code、残留 openocd)持有探针 | `/stm32-stop`,关闭其他调试器后重试;`stm32_doctor` 会列出残留进程 |
|
|
362
|
+
| 烧录后 SWD 失联 | `.ioc` 未启用 Serial Wire | 用 `stm32_ioc_plan` 的 `serialWire: true` 补齐后重新生成并烧录 |
|
|
363
|
+
| 生成后外设被丢弃 | `.ioc` 键与外设推导不一致 | 用 `stm32_ioc_verify` 让 CubeMX 诊断 |
|
|
364
|
+
| 面板空白或数据不更新 | 服务端改动未重启,或 `lib` 比进程新 | 完全退出 DSH 再启动;面板状态条会提示「有新构建」 |
|
|
365
|
+
| 串口无数据 | 端口选择错误(如选到 DAPLink 虚拟串口) | `stm32_serial list` 确认端口;应用串口通常在 CH340 等 USB 转串口设备上 |
|
|
479
366
|
|
|
480
|
-
|
|
367
|
+
## 开发与测试
|
|
481
368
|
|
|
482
|
-
|
|
369
|
+
| 命令 | 作用 |
|
|
370
|
+
| --- | --- |
|
|
371
|
+
| `npm run build` | `tsc` 编译到 `lib/`,并复制客户端与数据资源 |
|
|
372
|
+
| `node test/run-units.mjs` | 离线单测:80 个套件 / 1088 个用例,不需要板子 |
|
|
373
|
+
| `node .dsh-stm32/acceptance.mjs` | 本机验收脚本:面板 API、事件流、证据、产物、故障、中断、串口与探针 |
|
|
374
|
+
| `npm run test:pack` | 打包 tarball、解包、用解包产物实际建一次寄存器工程 |
|
|
375
|
+
| `npm run test:size` | 包体与资产护栏 |
|
|
483
376
|
|
|
484
|
-
|
|
485
|
-
$env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
|
|
486
|
-
node test\e2e-flash.mjs
|
|
487
|
-
```
|
|
377
|
+
发布形态:随包发布的内容限定在 `package.json` 的 `files`(`lib`、`client`、`templates`、`assets`、`docs/reading-guide.md`、`cordis.patch.yml`、两份 README、`LICENSE`)。开发用的 `docs/`、`test/`、`scripts/` 不进包。
|
|
488
378
|
|
|
489
|
-
|
|
379
|
+
开发调试用的环境变量(日常使用无需设置):`DSH_STM32_ASSETS`、`DSH_STM32_FACTS` 覆盖资源目录,`DSH_STM32_SERIAL_BRIDGE`、`DSH_STM32_SERIAL_POWERSHELL` 覆盖串口桥路径,`DSH_STM32_PYTHON` 指定解析用的 Python 解释器。
|
|
490
380
|
|
|
491
381
|
## 目录结构
|
|
492
382
|
|
|
493
383
|
```text
|
|
494
384
|
src/
|
|
495
|
-
index.ts
|
|
496
|
-
tools/
|
|
497
|
-
engine/
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
385
|
+
index.ts 插件入口:注册工具、斜杠命令、面板 API 与 SKILL
|
|
386
|
+
tools/ 25 个工具的注册与参数校验
|
|
387
|
+
engine/ 引擎:工程、.ioc、生成、构建、烧录、调试、事件与面板 API
|
|
388
|
+
data/ 芯片数据、CubeMX 数据、时钟、搜索根、工具链配置
|
|
389
|
+
commands/ 7 条斜杠命令
|
|
390
|
+
skill/ 随包下发的 stm32-workflow SKILL
|
|
391
|
+
client/client.js 面板源码(纯 JS + react,无打包器)
|
|
392
|
+
lib/ tsc 产物与复制后的资源(随包发布)
|
|
393
|
+
assets/ 芯片数据、.ioc 模板、链接脚本、启动文件、寄存器表
|
|
394
|
+
templates/ 建工程模板、寄存器模板、串口桥与 RTT 模板
|
|
395
|
+
test/ 80 个离线套件与 e2e 脚本
|
|
396
|
+
scripts/ 构建、打包、体积与冒烟脚本
|
|
397
|
+
docs/ 开发笔记、精读指南、规格书、图表
|
|
505
398
|
```
|
|
506
399
|
|
|
507
400
|
## 文档
|
|
508
401
|
|
|
509
|
-
- [规格书](docs/dsh-stm32-plugin-规格.md)
|
|
510
|
-
- [开发笔记](docs/development-notes.md)
|
|
511
|
-
- [源码精读指南](docs/reading-guide.md)
|
|
512
|
-
-
|
|
513
|
-
- 可视化:[架构总览](docs/diagrams/dsh-stm32-architecture.html) / [主线旅程](docs/diagrams/dsh-stm32-journey.html)(单文件 HTML
|
|
402
|
+
- [规格书](docs/dsh-stm32-plugin-规格.md):工具契约、状态机、验收判定标准
|
|
403
|
+
- [开发笔记](docs/development-notes.md):里程碑、宿主契约问题、各工具实现细节与实测数据
|
|
404
|
+
- [源码精读指南](docs/reading-guide.md):分层阅读顺序、文件职责与关键导出、流程图与不变量
|
|
405
|
+
- 发布说明:按版本随发布页提供,历史见 git 历史与开发笔记
|
|
406
|
+
- 可视化:[架构总览](docs/diagrams/dsh-stm32-architecture.html) / [主线旅程](docs/diagrams/dsh-stm32-journey.html)(单文件 HTML,离线可开)
|
|
514
407
|
|
|
515
408
|
## 许可证
|
|
516
409
|
|