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
|
@@ -0,0 +1,553 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* L1:一条路线怎么走 —— HAL(.ioc + CubeMX 生成)还是寄存器(手写 main.c)。
|
|
3
|
+
*
|
|
4
|
+
* 为什么必须绑到具体工程才能答:同一个外设,"读一下温度"和"多通道 DMA 连续采样 + 过采样 + 校准"
|
|
5
|
+
* 是两件事。抽象的"HAL vs 寄存器"对照表看着整齐,实际会让用户在一个他并没说清的场景上做选择。
|
|
6
|
+
* 所以这里的输入是:这台芯片 + 这个工程 + 这句话要做什么;输出是逐个外设的代价与风险。
|
|
7
|
+
*
|
|
8
|
+
* 评判坐标只有两个,都按 1(最省)到 5(最费):
|
|
9
|
+
* effort —— 写通它要动多少代码/多少个寄存器(开发效率);
|
|
10
|
+
* risk —— 时序/状态机/勘误上出错的机会(可靠性)。
|
|
11
|
+
* 二者都不带"我更喜欢哪个"的偏好:寄存器版在 risk<=2 且 effort<=2 时才会被推荐。
|
|
12
|
+
*
|
|
13
|
+
* 纯函数:不读盘、不起进程,便于单测。固件包是否存在由 findFirmwarePackage 单独判(要读盘)。
|
|
14
|
+
*/
|
|
15
|
+
import { existsSync, readdirSync } from "node:fs";
|
|
16
|
+
import { join } from "node:path";
|
|
17
|
+
import { FIRMWARE_FAMILIES } from "../data/firmware-packages.js";
|
|
18
|
+
const HAL_ONLY_CORE = "CubeMX 生成 + HAL 是唯一可靠路径";
|
|
19
|
+
/** 外设规则表。加外设只改这里(与 chips.ts 同一思路)。 */
|
|
20
|
+
export const PERIPHERAL_RULES = [
|
|
21
|
+
{
|
|
22
|
+
id: "gpio",
|
|
23
|
+
label: "GPIO(LED / 按键 / 继电器)",
|
|
24
|
+
family: "gpio",
|
|
25
|
+
rank: 1,
|
|
26
|
+
keywords: ["gpio", "led", "灯", "按键", "按钮", "继电器", "蜂鸣器", "beep", "开关量", "io 口", "输出高低电平"],
|
|
27
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 里点成 GPIO_Output/Input,代码里 HAL_GPIO_WritePin / HAL_GPIO_ReadPin" },
|
|
28
|
+
reg: { effort: 1, risk: 1, setup: "RCC->APB2ENR 开时钟;GPIOx->CRL/CRH 配模式;写 BSRR/BRR 输出" },
|
|
29
|
+
regGap: "没有(寄存器版 GPIO 比 HAL 还短)",
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
id: "usart-poll",
|
|
33
|
+
label: "USART 轮询(串口打印 / printf 重定向)",
|
|
34
|
+
family: "usart",
|
|
35
|
+
rank: 1,
|
|
36
|
+
keywords: ["usart", "uart", "串口", "printf", "串口打印"],
|
|
37
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 配 USART 异步 + 引脚;HAL_UART_Transmit;printf 重定向写 __io_putchar/fputc" },
|
|
38
|
+
reg: { effort: 2, risk: 2, setup: "USARTx->BRR 按 PCLK 算波特率;CR1 使能 TE/UE;轮询 SR 的 TXE/TC 后写 DR" },
|
|
39
|
+
regGap: "波特率要自己按当前 PCLK 算(改时钟树就得重算);错误标志(ORE/FE/NE)要自己清",
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
id: "usart-irq",
|
|
43
|
+
label: "串口中断 / DMA 接收",
|
|
44
|
+
family: "usart",
|
|
45
|
+
rank: 2,
|
|
46
|
+
keywords: ["串口中断", "串口接收中断", "串口 dma", "串口空闲中断", "uart irq", "usart irq", "idle 中断", "不定长接收"],
|
|
47
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 勾 NVIC + DMA;HAL_UART_Receive_IT / ReceiveToIdle_DMA + 回调里搬缓冲" },
|
|
48
|
+
reg: { effort: 3, risk: 4, setup: "CR1 开 RXNEIE;USARTx_IRQHandler 里读 DR 清标志;DMA 要配通道映射与环形缓冲" },
|
|
49
|
+
regGap: "中断优先级、DMA 通道映射、溢出/错误恢复、环形缓冲全得自己写;漏清 ORE 会静默丢字节",
|
|
50
|
+
},
|
|
51
|
+
{
|
|
52
|
+
id: "tim-base",
|
|
53
|
+
label: "定时器(定时中断 / 精确计时)",
|
|
54
|
+
family: "tim",
|
|
55
|
+
rank: 1,
|
|
56
|
+
keywords: ["定时器", "定时中断", "timer", "基准计时", "计时器"],
|
|
57
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 配 TIM 内部时钟;HAL_TIM_Base_Start_IT + HAL_TIM_PeriodElapsedCallback" },
|
|
58
|
+
reg: { effort: 2, risk: 2, setup: "RCC->APB1ENR 开时钟;TIMx->PSC/ARR 定时;DIER 开 UIE;SR 里清 UIF" },
|
|
59
|
+
regGap: "预分频/重装值与 PCLK 的换算要自己算,溢出顺序(先清 SR 再算)错了会丢节拍",
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
id: "tim-pwm",
|
|
63
|
+
label: "PWM / 舵机 / 电机调速",
|
|
64
|
+
family: "tim",
|
|
65
|
+
rank: 2,
|
|
66
|
+
keywords: ["pwm", "呼吸灯", "舵机", "电机调速", "占空比", "输出比较", "调光"],
|
|
67
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 把通道配成 PWM Generation;HAL_TIM_PWM_Start;__HAL_TIM_SET_COMPARE 调占空比" },
|
|
68
|
+
reg: { effort: 3, risk: 3, setup: "CCMRx 设 PWM 模式 1 + 预装载;CCER 开输出;CCRx 写占空比;引脚要配成复用推挽" },
|
|
69
|
+
regGap: "复用功能映射(AFIO/GPIOx_AFR)、预装载与更新事件时序、死区(高级定时器)都得自己处理",
|
|
70
|
+
},
|
|
71
|
+
{
|
|
72
|
+
id: "systick",
|
|
73
|
+
label: "SysTick / 毫秒延时",
|
|
74
|
+
family: "systick",
|
|
75
|
+
rank: 1,
|
|
76
|
+
keywords: ["systick", "毫秒延时", "延时", "hal_delay", "微秒延时"],
|
|
77
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 默认就配好 SysTick;HAL_Delay / HAL_GetTick" },
|
|
78
|
+
reg: { effort: 1, risk: 1, setup: "SysTick->LOAD = 节拍-1;CTRL 开时钟与中断;计数变量在 SysTick_Handler 里自增" },
|
|
79
|
+
regGap: "没有(十几行就能写完,且不依赖 HAL 的 uwTick)",
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
id: "exti",
|
|
83
|
+
label: "外部中断(按键 / 脉冲计数)",
|
|
84
|
+
family: "exti",
|
|
85
|
+
rank: 1,
|
|
86
|
+
keywords: ["exti", "外部中断", "按键中断", "中断唤醒", "脉冲计数"],
|
|
87
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 把引脚配成 GPIO_EXTI + 勾 NVIC;HAL_GPIO_EXTI_Callback 里处理" },
|
|
88
|
+
reg: { effort: 2, risk: 3, setup: "AFIO->EXTICR 选端口;EXTI->IMR/RTSR/FTSR;NVIC 使能;中断里清 EXTI->PR" },
|
|
89
|
+
regGap: "忘了清 PR 会反复进中断;AFIO 时钟(RCC->APB2ENR 的 AFIOEN)漏开是最常见的坑",
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
id: "adc-single",
|
|
93
|
+
label: "ADC 单通道轮询",
|
|
94
|
+
family: "adc",
|
|
95
|
+
rank: 1,
|
|
96
|
+
keywords: ["adc", "采样", "模拟量", "电压检测", "电池电压", "电位器", "热敏"],
|
|
97
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 配 ADC 通道 + 采样时间;HAL_ADC_Start/PollForConversion/GetValue" },
|
|
98
|
+
reg: { effort: 3, risk: 3, setup: "RCC 配 ADCCLK 分频;ADC1->SMPR2 采样时间;SQR1/2/3 排序列;CR2 开 ADON + 校准;等 EOC 读 DR" },
|
|
99
|
+
regGap: "上电校准(RSTCAL/CAL)、采样时间与源阻抗匹配、EOC 顺序与 DMA 请求,错了读数是「看着有值但不准」",
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
id: "adc-dma",
|
|
103
|
+
label: "ADC 多通道 / 连续 / DMA",
|
|
104
|
+
family: "adc",
|
|
105
|
+
rank: 2,
|
|
106
|
+
keywords: ["多通道 adc", "adc dma", "连续采样", "双通道 adc", "adc 扫描"],
|
|
107
|
+
hal: { effort: 2, risk: 3, setup: "CubeMX 勾 Scan + Continuous + DMA;HAL_ADC_Start_DMA + 回调里换算" },
|
|
108
|
+
reg: { effort: 4, risk: 4, setup: "SQR 排多通道 + CR2 连续 + DMA 通道映射 + 循环模式;DMA 半传输/传输完成回调自己写" },
|
|
109
|
+
regGap: "通道顺序、DMA 通道与 ADC 的固定映射、循环缓冲的读写指针同步 —— 寄存器版这里最容易出脏数据",
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
id: "dac",
|
|
113
|
+
label: "DAC 模拟输出 / 波形",
|
|
114
|
+
family: "dac",
|
|
115
|
+
rank: 1,
|
|
116
|
+
keywords: ["dac", "模拟输出", "波形输出", "正弦波"],
|
|
117
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 开 DAC 通道;HAL_DAC_Start + HAL_DAC_SetValue;波形用定时器触发 + DMA" },
|
|
118
|
+
reg: { effort: 3, risk: 3, setup: "RCC->APB1ENR 开 DAC;DHR12R 写值;CR 使能通道 + 触发源;配 DMA 做波形表" },
|
|
119
|
+
regGap: "触发源选择、DMA 请求映射与双通道同步要自己配",
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
id: "spi",
|
|
123
|
+
label: "SPI 主机(传感器 / SPI Flash)",
|
|
124
|
+
family: "spi",
|
|
125
|
+
rank: 1,
|
|
126
|
+
keywords: ["spi", "w25q", "spi flash", "spi 传感器", "屏幕 spi"],
|
|
127
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 配 SPI 模式/CPOL/CPHA/分频;HAL_SPI_TransmitReceive;NSS 用软件 GPIO" },
|
|
128
|
+
reg: { effort: 3, risk: 3, setup: "CR1 配 MSTR/BR/CPOL/CPHA/DFF;SPE 使能;轮询 SR 的 TXE/RXNE/BSY 收发" },
|
|
129
|
+
regGap: "CPOL/CPHA 与从机器件手册对不上会「能发不能收」;NSS 时序与 BSY 等待要自己保证",
|
|
130
|
+
},
|
|
131
|
+
{
|
|
132
|
+
id: "i2c",
|
|
133
|
+
label: "I2C(OLED / EEPROM / 传感器)",
|
|
134
|
+
family: "i2c",
|
|
135
|
+
rank: 1,
|
|
136
|
+
keywords: ["i2c", "iic", "oled", "eeprom", "mpu6050", "sht30", "bmp280", "aht20"],
|
|
137
|
+
hal: { effort: 2, risk: 3, setup: "CubeMX 配 I2C 速度;HAL_I2C_Master_Transmit / Mem_Read;出错看 HAL 返回码" },
|
|
138
|
+
reg: { effort: 4, risk: 5, setup: "CR2 产生 START;DR 写地址/数据;SR1/SR2 状态机逐位判 ADDR/TXE/RXNE/BTF/STOPF" },
|
|
139
|
+
regGap: "这是寄存器版最容易卡死的外设:状态机顺序、时钟拉伸、总线忙时恢复(9 个时钟 + STOP)都得自己写",
|
|
140
|
+
},
|
|
141
|
+
{
|
|
142
|
+
id: "can",
|
|
143
|
+
label: "CAN / FDCAN 总线",
|
|
144
|
+
family: "can",
|
|
145
|
+
rank: 1,
|
|
146
|
+
keywords: ["can", "fdcan", "can 总线", "canopen"],
|
|
147
|
+
hal: { effort: 2, risk: 3, setup: "CubeMX 配位定时(波特率)+ 验收滤波器;HAL_FDCAN_Start + 收发回调" },
|
|
148
|
+
reg: null,
|
|
149
|
+
regGap: "位定时/采样点、验收滤波器寄存器布局、错误状态机(bus-off 恢复)差异极大",
|
|
150
|
+
halOnlyReason: "位定时与验收滤波器寄存器在 F1/F4/G4/H7 上布局完全不同,错误状态机(bus-off 恢复)写错会整条总线掉线;" + HAL_ONLY_CORE,
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
id: "usb",
|
|
154
|
+
label: "USB(虚拟串口 / HID / U 盘)",
|
|
155
|
+
family: "usb",
|
|
156
|
+
rank: 1,
|
|
157
|
+
keywords: ["usb", "cdc", "hid", "虚拟串口", "u 盘", "msc"],
|
|
158
|
+
hal: { effort: 3, risk: 3, setup: "CubeMX 开 USB_DEVICE 中间件(CDC/HID);只用生成的收发接口,别改中间件" },
|
|
159
|
+
reg: null,
|
|
160
|
+
regGap: "USB 协议栈 + 端点缓冲 + 枚举状态机,手写等于重写中间件",
|
|
161
|
+
halOnlyReason: "USB 是协议栈级外设(枚举、端点、类驱动),寄存器版要重写整套中间件;" + HAL_ONLY_CORE,
|
|
162
|
+
},
|
|
163
|
+
{
|
|
164
|
+
id: "eth",
|
|
165
|
+
label: "以太网 / TCP-IP",
|
|
166
|
+
family: "eth",
|
|
167
|
+
rank: 1,
|
|
168
|
+
keywords: ["以太网", "ethernet", "lwip", "网口", "tcp", "udp", "http"],
|
|
169
|
+
hal: { effort: 4, risk: 4, setup: "CubeMX 开 ETH + LwIP 中间件;PHY 地址与 RMII/MII 引脚按板子配" },
|
|
170
|
+
reg: null,
|
|
171
|
+
regGap: "MAC/DMA 描述符环 + PHY 管理 + 协议栈",
|
|
172
|
+
halOnlyReason: "要同时写 MAC/DMA 描述符环、PHY 管理与协议栈;" + HAL_ONLY_CORE,
|
|
173
|
+
},
|
|
174
|
+
{
|
|
175
|
+
id: "sd",
|
|
176
|
+
label: "SD 卡 / FatFs 文件系统",
|
|
177
|
+
family: "sd",
|
|
178
|
+
rank: 1,
|
|
179
|
+
keywords: ["sd 卡", "sd卡", "sdmmc", "sdio", "fatfs", "文件系统"],
|
|
180
|
+
hal: { effort: 3, risk: 3, setup: "CubeMX 开 SDIO/SDMMC + FATFS 中间件;用 f_mount/f_open 接口" },
|
|
181
|
+
reg: null,
|
|
182
|
+
regGap: "SD 协议命令序列 + 文件系统",
|
|
183
|
+
halOnlyReason: "SD 命令序列(CMD0/CMD8/ACMD41…)+ 卡状态机 + 文件系统;" + HAL_ONLY_CORE,
|
|
184
|
+
},
|
|
185
|
+
{
|
|
186
|
+
id: "fsmc",
|
|
187
|
+
label: "FSMC/FMC 外部存储 / 并口屏",
|
|
188
|
+
family: "fsmc",
|
|
189
|
+
rank: 1,
|
|
190
|
+
keywords: ["fsmc", "fmc", "外部 ram", "sram", "lcd 并口", "并口屏"],
|
|
191
|
+
hal: { effort: 3, risk: 3, setup: "CubeMX 配 FSMC 时序(地址/数据建立保持);用指针直接读写映射地址" },
|
|
192
|
+
reg: null,
|
|
193
|
+
regGap: "时序寄存器组合与芯片手册的 tAS/tDS/tWR 换算",
|
|
194
|
+
halOnlyReason: "时序参数组合多且与具体器件手册绑定,写错表现为「偶尔读到错数据」;" + HAL_ONLY_CORE,
|
|
195
|
+
},
|
|
196
|
+
{
|
|
197
|
+
id: "dma",
|
|
198
|
+
label: "DMA 搬运",
|
|
199
|
+
family: "dma",
|
|
200
|
+
rank: 1,
|
|
201
|
+
keywords: ["dma", "搬运", "内存到内存"],
|
|
202
|
+
hal: { effort: 2, risk: 3, setup: "CubeMX 配 DMA 请求(外设固定通道);HAL_DMA_Start_IT + 回调" },
|
|
203
|
+
reg: { effort: 4, risk: 4, setup: "DMA_CPAR/CMAR/CNDTR/CCR 逐寄存器配;通道与外设的固定映射查参考手册表;中断标志按通道清" },
|
|
204
|
+
regGap: "通道-外设映射是芯片固定表、多通道优先级与中断标志(IFCR)按位清,配错就是「数据只搬一半」",
|
|
205
|
+
},
|
|
206
|
+
{
|
|
207
|
+
id: "rtc",
|
|
208
|
+
label: "RTC 实时时钟 / 日历",
|
|
209
|
+
family: "rtc",
|
|
210
|
+
rank: 1,
|
|
211
|
+
keywords: ["rtc", "实时时钟", "日历", "闹钟", "时间戳"],
|
|
212
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 开 RTC(LSE 或 LSI)+ 备份域;HAL_RTC_SetTime/GetTime" },
|
|
213
|
+
reg: { effort: 3, risk: 3, setup: "PWR->CR 开备份域访问;RCC->BDCR 选时钟源;RTC->PRLH/PRLL 分频;CNT/ALR 与进入初始化序列" },
|
|
214
|
+
regGap: "备份域解锁顺序(PWR_CR 的 DBP)、进入/退出初始化模式、BCD 与二进制换算,错一步就写不进",
|
|
215
|
+
},
|
|
216
|
+
{
|
|
217
|
+
id: "watchdog",
|
|
218
|
+
label: "看门狗(IWDG / WWDG)",
|
|
219
|
+
family: "wdg",
|
|
220
|
+
rank: 1,
|
|
221
|
+
keywords: ["看门狗", "iwdg", "wwdg", "watchdog", "喂狗"],
|
|
222
|
+
hal: { effort: 1, risk: 1, setup: "CubeMX 开 IWDG(LSI 分频 + 重装值);主循环里 HAL_IWDG_Refresh" },
|
|
223
|
+
reg: { effort: 1, risk: 1, setup: "IWDG->KR 写 0xCCCC 启动;PR/RLR 前先写 0x5555 解锁;喂狗写 0xAAAA" },
|
|
224
|
+
regGap: "没有(就四条写 KR 的魔数,但魔数写错会静默不生效)",
|
|
225
|
+
},
|
|
226
|
+
{
|
|
227
|
+
id: "flash-param",
|
|
228
|
+
label: "参数掉电保存(内部 Flash / EEPROM 模拟)",
|
|
229
|
+
family: "flash",
|
|
230
|
+
rank: 1,
|
|
231
|
+
keywords: ["内部 flash", "参数保存", "掉电保存", "eeprom 模拟", "flash 读写", "配置保存"],
|
|
232
|
+
hal: { effort: 2, risk: 3, setup: "HAL_FLASH_Unlock/Erase/Program;按页规划布局,写完回读校验" },
|
|
233
|
+
reg: { effort: 3, risk: 3, setup: "FLASH->KEYR 写两个 key 解锁;CR 置 PER 擦页;SR 等 BSY;半字编程 + 回读" },
|
|
234
|
+
regGap: "页地址/大小按型号变(F1 是 1 KB 页)、擦除期间的取指停顿、掉电中断会写坏整页 —— 需要双备份策略",
|
|
235
|
+
},
|
|
236
|
+
{
|
|
237
|
+
id: "lowpower",
|
|
238
|
+
label: "低功耗(Sleep/Stop/Standby + 唤醒)",
|
|
239
|
+
family: "lowpower",
|
|
240
|
+
rank: 1,
|
|
241
|
+
keywords: ["低功耗", "待机", "休眠", "stop 模式", "standby", "睡眠模式", "电池供电"],
|
|
242
|
+
hal: { effort: 3, risk: 3, setup: "HAL_PWR_EnterSTOPMode / EnterSTANDBYMode;唤醒后要重配时钟(Stop 会关 PLL)" },
|
|
243
|
+
reg: null,
|
|
244
|
+
regGap: "时钟恢复、唤醒源屏蔽、备份域与 IO 状态",
|
|
245
|
+
halOnlyReason: "进入低功耗后时钟树/外设状态要成体系地恢复,写错表现为「睡下去就再也醒不来」或「电流没降」;" + HAL_ONLY_CORE,
|
|
246
|
+
},
|
|
247
|
+
{
|
|
248
|
+
id: "rtos",
|
|
249
|
+
label: "RTOS(FreeRTOS 任务)",
|
|
250
|
+
family: "rtos",
|
|
251
|
+
rank: 1,
|
|
252
|
+
keywords: ["freertos", "rtos", "任务", "多线程", "信号量", "队列"],
|
|
253
|
+
hal: { effort: 3, risk: 3, setup: "CubeMX 开 FREERTOS 中间件(CMSIS_V2);中断里只用 FromISR 接口" },
|
|
254
|
+
reg: null,
|
|
255
|
+
regGap: "内核移植 + 上下文切换 + 中断优先级约束",
|
|
256
|
+
halOnlyReason: "RTOS 不是外设而是内核(SysTick/PendSV 接管、优先级分组约束),没有「寄存器版」可言;" + HAL_ONLY_CORE,
|
|
257
|
+
},
|
|
258
|
+
{
|
|
259
|
+
id: "clock",
|
|
260
|
+
label: "时钟树(PLL / 外部晶振 / 变频)",
|
|
261
|
+
family: "clock",
|
|
262
|
+
rank: 1,
|
|
263
|
+
keywords: ["时钟树", "pll", "超频", "外部晶振", "hse", "lse", "主频"],
|
|
264
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 时钟树页面直接配;SystemClock_Config 由生成器写,别手改" },
|
|
265
|
+
reg: { effort: 3, risk: 4, setup: "RCC->CR 开 HSE 等 HSERDY;CFGR 配 PLLMUL/PLLSRC + 总线分频;FLASH->ACR 配等待周期;切 SW 后确认 SWS" },
|
|
266
|
+
regGap: "Flash 等待周期必须跟着主频走(跟不上会随机跑飞)、切换顺序错了会短暂无时钟",
|
|
267
|
+
},
|
|
268
|
+
{
|
|
269
|
+
id: "qei",
|
|
270
|
+
label: "编码器接口(正交解码)",
|
|
271
|
+
family: "qei",
|
|
272
|
+
rank: 1,
|
|
273
|
+
keywords: ["编码器", "qei", "正交解码", "霍尔"],
|
|
274
|
+
hal: { effort: 2, risk: 2, setup: "CubeMX 把 TIM 配成 Encoder Mode;读 CNT 即计数" },
|
|
275
|
+
reg: { effort: 3, risk: 3, setup: "SMCR 配 SMS=001/010/011;CCMR 配输入滤波;CNT 直接读" },
|
|
276
|
+
regGap: "输入滤波(ICF)与极性配置影响高速时丢脉冲",
|
|
277
|
+
},
|
|
278
|
+
{
|
|
279
|
+
id: "boot",
|
|
280
|
+
label: "Bootloader / IAP 在线升级",
|
|
281
|
+
family: "boot",
|
|
282
|
+
rank: 1,
|
|
283
|
+
keywords: ["bootloader", "iap", "在线升级", "固件升级", "ota"],
|
|
284
|
+
hal: { effort: 3, risk: 4, setup: "两份工程:boot 跳转到 app(改 SCB->VTOR)+ 校验;app 里写升级标志" },
|
|
285
|
+
reg: { effort: 3, risk: 4, setup: "跳转 = 取 app 向量表首字当 SP、第二字当入口,__set_MSP + 函数指针跳转;Flash 写入同 flash-param" },
|
|
286
|
+
regGap: "跳转本身寄存器版更直接,但 Flash 写入与向量表重定位的坑一样多;建议先 HAL 跑通再考虑换",
|
|
287
|
+
},
|
|
288
|
+
];
|
|
289
|
+
function ruleById(id) {
|
|
290
|
+
return PERIPHERAL_RULES.find((rule) => rule.id === id);
|
|
291
|
+
}
|
|
292
|
+
/** 一段文本 → 命中的规则(同族只留 rank 最高的那条在最后算)。source 记录命中来源。 */
|
|
293
|
+
function matchText(text, into, source) {
|
|
294
|
+
const hay = text.toLowerCase();
|
|
295
|
+
if (hay.trim() === "")
|
|
296
|
+
return;
|
|
297
|
+
for (const rule of PERIPHERAL_RULES) {
|
|
298
|
+
if (!rule.keywords.some((keyword) => hay.includes(keyword)))
|
|
299
|
+
continue;
|
|
300
|
+
const sources = into.get(rule.id) ?? new Set();
|
|
301
|
+
sources.add(source);
|
|
302
|
+
into.set(rule.id, sources);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
/** 显式列出的外设(id / 标签 / 关键词都能对上)。对不上的进 unknown。 */
|
|
306
|
+
function matchExplicit(tokens, into, unknown) {
|
|
307
|
+
for (const raw of tokens) {
|
|
308
|
+
const token = raw.trim().toLowerCase();
|
|
309
|
+
if (token === "")
|
|
310
|
+
continue;
|
|
311
|
+
const rule = PERIPHERAL_RULES.find((item) => item.id === token
|
|
312
|
+
|| item.label.toLowerCase().includes(token)
|
|
313
|
+
|| item.keywords.some((keyword) => keyword === token || token.includes(keyword)));
|
|
314
|
+
if (rule === undefined) {
|
|
315
|
+
unknown.push(raw.trim());
|
|
316
|
+
continue;
|
|
317
|
+
}
|
|
318
|
+
const sources = into.get(rule.id) ?? new Set();
|
|
319
|
+
sources.add("explicit");
|
|
320
|
+
into.set(rule.id, sources);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
export const VERDICT_LABEL = {
|
|
324
|
+
"hal-only": "只能走 HAL(.ioc + CubeMX 生成)",
|
|
325
|
+
"both-viable": "两条都能走,HAL 更稳",
|
|
326
|
+
"register-ok": "寄存器版够用(小而定型的外设)",
|
|
327
|
+
unclear: "还没看出要做什么外设",
|
|
328
|
+
};
|
|
329
|
+
/** 判定单个外设走哪条路:寄存器只有在 effort<=2 且 risk<=2 时才被推荐。 */
|
|
330
|
+
function adviceFor(rule) {
|
|
331
|
+
if (rule.reg === null)
|
|
332
|
+
return "hal-required";
|
|
333
|
+
if (rule.reg.effort <= 2 && rule.reg.risk <= 2)
|
|
334
|
+
return "register";
|
|
335
|
+
return "hal";
|
|
336
|
+
}
|
|
337
|
+
function reasonFor(rule, advice) {
|
|
338
|
+
if (advice === "hal-required")
|
|
339
|
+
return rule.halOnlyReason ?? (HAL_ONLY_CORE + "。");
|
|
340
|
+
if (advice === "register") {
|
|
341
|
+
return "寄存器版代价 " + String(rule.reg?.effort ?? 0) + "/5、风险 " + String(rule.reg?.risk ?? 0) + "/5(越低越省):"
|
|
342
|
+
+ (rule.regGap === "" ? "可以直接写。" : rule.regGap);
|
|
343
|
+
}
|
|
344
|
+
return "寄存器版风险 " + String(rule.reg?.risk ?? 0) + "/5 偏高,HAL 更省事:" + rule.regGap;
|
|
345
|
+
}
|
|
346
|
+
/** 逐个外设评估。纯函数。 */
|
|
347
|
+
export function assessRoute(input) {
|
|
348
|
+
const matched = new Map();
|
|
349
|
+
const unknown = [];
|
|
350
|
+
matchText(input.requirement, matched, "requirement");
|
|
351
|
+
matchExplicit(input.peripherals ?? [], matched, unknown);
|
|
352
|
+
for (const name of input.iocPeripherals ?? [])
|
|
353
|
+
matchText(name, matched, "ioc");
|
|
354
|
+
const byFamily = new Map();
|
|
355
|
+
for (const id of matched.keys()) {
|
|
356
|
+
const rule = ruleById(id);
|
|
357
|
+
if (rule === undefined)
|
|
358
|
+
continue;
|
|
359
|
+
const current = byFamily.get(rule.family);
|
|
360
|
+
if (current === undefined || rule.rank > current.rank)
|
|
361
|
+
byFamily.set(rule.family, rule);
|
|
362
|
+
}
|
|
363
|
+
const chosen = [...byFamily.values()].sort((left, right) => left.id.localeCompare(right.id));
|
|
364
|
+
const devices = chosen.map((rule) => {
|
|
365
|
+
const advice = adviceFor(rule);
|
|
366
|
+
const sources = [...(matched.get(rule.id) ?? new Set())].sort();
|
|
367
|
+
return {
|
|
368
|
+
id: rule.id,
|
|
369
|
+
label: rule.label,
|
|
370
|
+
matchedBy: sources,
|
|
371
|
+
hal: rule.hal,
|
|
372
|
+
reg: rule.reg,
|
|
373
|
+
advice,
|
|
374
|
+
reason: reasonFor(rule, advice),
|
|
375
|
+
};
|
|
376
|
+
});
|
|
377
|
+
let verdict;
|
|
378
|
+
if (devices.length === 0)
|
|
379
|
+
verdict = "unclear";
|
|
380
|
+
else if (devices.some((device) => device.advice === "hal-required"))
|
|
381
|
+
verdict = "hal-only";
|
|
382
|
+
else if (devices.every((device) => device.advice === "register"))
|
|
383
|
+
verdict = "register-ok";
|
|
384
|
+
else
|
|
385
|
+
verdict = "both-viable";
|
|
386
|
+
const halEffort = devices.reduce((sum, device) => sum + device.hal.effort, 0);
|
|
387
|
+
const regEffort = devices.reduce((sum, device) => sum + (device.reg?.effort ?? 0), 0);
|
|
388
|
+
const regRisk = devices.reduce((max, device) => Math.max(max, device.reg?.risk ?? 0), 0);
|
|
389
|
+
const delta = [];
|
|
390
|
+
if (verdict === "both-viable" || verdict === "register-ok") {
|
|
391
|
+
delta.push("开发效率:HAL 合计代价 " + String(halEffort) + "/" + String(devices.length * 5)
|
|
392
|
+
+ ",寄存器 " + String(regEffort) + "/" + String(devices.length * 5)
|
|
393
|
+
+ "(要手配的寄存器少,但每个都得按参考手册算对)。");
|
|
394
|
+
delta.push("可读性:HAL 版是「初始化结构体 + 语义化函数」,别人接手能看懂;寄存器版是「位赋值 + 魔数」"
|
|
395
|
+
+ "(配合头部注释与宏能缓解,但没有 HAL 那样的现成文档)。");
|
|
396
|
+
delta.push("工程形态:HAL 版必须有 .ioc + CubeMX(生成代码占几百 KB Flash);寄存器版是一个 main.c + 启动文件,"
|
|
397
|
+
+ "不依赖 CubeMX,Flash 占用小一个量级。");
|
|
398
|
+
delta.push("排错:HAL 出错会有 HAL 返回码与状态机(能定位到具体函数);寄存器版出错只能读寄存器 + 看波形,"
|
|
399
|
+
+ "但反过来也没有 HAL 的版本兼容问题。");
|
|
400
|
+
if (regRisk >= 3)
|
|
401
|
+
delta.push("⚠ 寄存器路线里风险最高的一项到 " + String(regRisk) + "/5:这一项建议单独用 HAL 或先用 stm32_regs_read 把寄存器读通再写逻辑。");
|
|
402
|
+
}
|
|
403
|
+
if (verdict === "hal-only") {
|
|
404
|
+
delta.push("没法给「两版都写」的承诺:上面标 hal-required 的外设在寄存器版里等于重写协议栈/内核,风险不可控。");
|
|
405
|
+
}
|
|
406
|
+
const halSteps = [
|
|
407
|
+
"先 stm32_ioc_plan 把外设配进 .ioc(CubeMX 会拒绝不认识的外设组合,等于替你校验一遍配置)。",
|
|
408
|
+
"stm32_generate 用 CubeMX 无头生成 MX_*_Init / HAL_MspInit / 时钟树(生成区不要手改)。",
|
|
409
|
+
"业务只写 USER CODE 段:改参数改 HAL_xxx_Init 的结构体,主循环放业务;中断里只置标志。",
|
|
410
|
+
"用 stm32_build → stm32_flash → stm32_debug_run 验证(能停在断点看变量,是 HAL 路线最大的便利)。",
|
|
411
|
+
];
|
|
412
|
+
const regSteps = [
|
|
413
|
+
"不建 .ioc:寄存器版只有 main.c + CMakeLists.txt + 链接脚本;启动文件/设备头从缓存目录取(首次从网上下载,之后复用)。",
|
|
414
|
+
"时钟与引脚在 main 里逐位配:RCC->APB2ENR 开时钟、GPIOx->CRL/CRH 配模式、AFIO->MAPR 配重映射。",
|
|
415
|
+
"每个外设写完立刻用 stm32_regs_read 读回寄存器自证(例如 ODR 位在翻、BRR 与波特率对得上、CNT 在涨)。",
|
|
416
|
+
"烧录后先看串口有没有输出:寄存器版没有 HAL 的返回值,串口打印是最便宜的观测手段。",
|
|
417
|
+
];
|
|
418
|
+
const recommendations = [];
|
|
419
|
+
if (verdict === "unclear") {
|
|
420
|
+
recommendations.push("需求里没认出外设。把要做的事说具体些(例如「按键控制 LED,串口每秒打印一次状态」),或直接列 peripherals。");
|
|
421
|
+
}
|
|
422
|
+
if (verdict === "hal-only") {
|
|
423
|
+
recommendations.push("走 HAL:需要 STM32CubeMX + 本芯片的固件包(工具链检查里会分开提示怎么装)。");
|
|
424
|
+
}
|
|
425
|
+
if (verdict === "register-ok") {
|
|
426
|
+
recommendations.push("寄存器版够用:不需要 CubeMX,也不需要固件包,只要 gcc/cmake/ninja 与烧录工具。");
|
|
427
|
+
}
|
|
428
|
+
if (verdict === "both-viable") {
|
|
429
|
+
const registerFriendly = devices.filter((device) => device.advice === "register").map((device) => device.label);
|
|
430
|
+
const halNeeded = devices.filter((device) => device.advice === "hal").map((device) => device.label);
|
|
431
|
+
recommendations.push("整体建议走 HAL;寄存器版只在这几项上划算 —— " + (registerFriendly.length === 0 ? "(没有)" : registerFriendly.join("、")) + "。");
|
|
432
|
+
recommendations.push("这几项用 HAL 才有把握:" + (halNeeded.length === 0 ? "(没有)" : halNeeded.join("、")) + "。");
|
|
433
|
+
}
|
|
434
|
+
if (unknown.length > 0) {
|
|
435
|
+
recommendations.push("这几个词我没认出对应的外设:" + unknown.join("、") + ";如果它们是别的东西,请换一种说法或直接给 peripherals。");
|
|
436
|
+
}
|
|
437
|
+
const notes = [];
|
|
438
|
+
notes.push("代价/风险都是 1(最省)到 5(最费),按这台芯片的参考手册估的,不是通用评分。");
|
|
439
|
+
if (input.iocPeripherals !== undefined && input.iocPeripherals.length > 0) {
|
|
440
|
+
notes.push("已把 .ioc 里使能的 " + String(input.iocPeripherals.length) + " 个外设算作证据:" + input.iocPeripherals.join("、"));
|
|
441
|
+
}
|
|
442
|
+
return {
|
|
443
|
+
verdict,
|
|
444
|
+
verdictLabel: VERDICT_LABEL[verdict],
|
|
445
|
+
devices,
|
|
446
|
+
unknown,
|
|
447
|
+
delta,
|
|
448
|
+
halSteps,
|
|
449
|
+
regSteps,
|
|
450
|
+
recommendations,
|
|
451
|
+
notes,
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
// ── 固件包(要读盘)────────────────────────────────────────────────────────
|
|
455
|
+
/** 型号 → 芯片族:STM32F103C8T6 → F1,STM32G431 → G4,STM32H743 → H7;认不出返回空串。 */
|
|
456
|
+
export function familyOf(mcu) {
|
|
457
|
+
const match = /^STM32([A-Za-z])(\d)/u.exec(mcu.trim().toUpperCase());
|
|
458
|
+
if (match === null)
|
|
459
|
+
return "";
|
|
460
|
+
return String(match[1]).toUpperCase() + String(match[2]);
|
|
461
|
+
}
|
|
462
|
+
/** 目录里是不是一个能编译的固件包(与 scaffold.resolveFirmwareRoot 的三条判据一致)。 */
|
|
463
|
+
function isCompletePackage(dir, family) {
|
|
464
|
+
if (family === "")
|
|
465
|
+
return false;
|
|
466
|
+
const prefix = "STM32" + family + "xx";
|
|
467
|
+
return (existsSync(join(dir, "Drivers", prefix + "_HAL_Driver"))
|
|
468
|
+
&& existsSync(join(dir, "Drivers", "CMSIS", "Include"))
|
|
469
|
+
&& existsSync(join(dir, "Drivers", "CMSIS", "Device", "ST", prefix)));
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* 在 CubeMX 的 Repository 里找这台芯片的固件包。
|
|
473
|
+
*
|
|
474
|
+
* 判据与 scaffold 保持一致(HAL 驱动 + CMSIS 头 + 设备目录),并且允许同族多个版本:
|
|
475
|
+
* 取目录名(含版本)字典序最大的那个 —— ST 的版本号补零不一致,但同族里逐位比较足够用。
|
|
476
|
+
*/
|
|
477
|
+
export function findFirmwarePackage(cubeMxRoots, mcuOrFamily) {
|
|
478
|
+
const direct = /^([A-Za-z]\d)$/u.exec(mcuOrFamily.trim().toUpperCase());
|
|
479
|
+
const family = direct !== null ? String(direct[1]).toUpperCase() : familyOf(mcuOrFamily);
|
|
480
|
+
const empty = {
|
|
481
|
+
found: false,
|
|
482
|
+
family,
|
|
483
|
+
packageName: "",
|
|
484
|
+
path: "",
|
|
485
|
+
repositoryDir: "",
|
|
486
|
+
incomplete: false,
|
|
487
|
+
message: family === ""
|
|
488
|
+
? "不知道芯片族(没给 MCU 型号),没法判断固件包。"
|
|
489
|
+
: "没找到 STM32Cube_FW_" + family + "_V* 固件包。",
|
|
490
|
+
};
|
|
491
|
+
if (family === "")
|
|
492
|
+
return empty;
|
|
493
|
+
const prefix = "STM32Cube_FW_" + family + "_";
|
|
494
|
+
let bestComplete = null;
|
|
495
|
+
let partial = null;
|
|
496
|
+
for (const root of cubeMxRoots) {
|
|
497
|
+
const repositoryDir = join(root, "Repository");
|
|
498
|
+
let entries;
|
|
499
|
+
try {
|
|
500
|
+
entries = readdirSync(repositoryDir, { withFileTypes: true })
|
|
501
|
+
.filter((entry) => entry.isDirectory() && entry.name.startsWith(prefix))
|
|
502
|
+
.map((entry) => entry.name);
|
|
503
|
+
}
|
|
504
|
+
catch {
|
|
505
|
+
continue;
|
|
506
|
+
}
|
|
507
|
+
for (const name of entries) {
|
|
508
|
+
const dir = join(repositoryDir, name);
|
|
509
|
+
if (isCompletePackage(dir, family)) {
|
|
510
|
+
if (bestComplete === null || name.localeCompare(bestComplete.name) > 0)
|
|
511
|
+
bestComplete = { name, dir, root };
|
|
512
|
+
}
|
|
513
|
+
else if (partial === null || name.localeCompare(partial.name) > 0) {
|
|
514
|
+
partial = { name, dir, root };
|
|
515
|
+
}
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
if (bestComplete !== null) {
|
|
519
|
+
return {
|
|
520
|
+
found: true,
|
|
521
|
+
family,
|
|
522
|
+
packageName: bestComplete.name,
|
|
523
|
+
path: bestComplete.dir,
|
|
524
|
+
repositoryDir: join(bestComplete.root, "Repository"),
|
|
525
|
+
incomplete: false,
|
|
526
|
+
message: "固件包 " + bestComplete.name + " 在 " + bestComplete.dir + "(HAL + CMSIS + 设备头齐全)。",
|
|
527
|
+
};
|
|
528
|
+
}
|
|
529
|
+
if (partial !== null) {
|
|
530
|
+
return {
|
|
531
|
+
found: false,
|
|
532
|
+
family,
|
|
533
|
+
packageName: partial.name,
|
|
534
|
+
path: partial.dir,
|
|
535
|
+
repositoryDir: join(partial.root, "Repository"),
|
|
536
|
+
incomplete: true,
|
|
537
|
+
message: "找到 " + partial.name + " 但它是半成品(缺 Drivers/STM32" + family + "xx_HAL_Driver 或 CMSIS 设备头),"
|
|
538
|
+
+ "编译会挂 —— 多半是只解压了 GitHub 源码包(子模块是空目录)。用 CubeMX 包管理器重装这一个包。",
|
|
539
|
+
};
|
|
540
|
+
}
|
|
541
|
+
return {
|
|
542
|
+
found: false,
|
|
543
|
+
family,
|
|
544
|
+
packageName: "",
|
|
545
|
+
path: "",
|
|
546
|
+
repositoryDir: cubeMxRoots.length === 0 ? "" : join(cubeMxRoots[0] ?? "", "Repository"),
|
|
547
|
+
incomplete: false,
|
|
548
|
+
message: "没找到 STM32Cube_FW_" + family + "_V* 固件包(找过 " + cubeMxRoots.join("、") + ")。"
|
|
549
|
+
+ (family in FIRMWARE_FAMILIES
|
|
550
|
+
? "这一代插件能自动下(stm32_firmware_install,约 2 MB)。"
|
|
551
|
+
: "这一代插件还不会自动下,用 CubeMX 包管理器装(见 guides)。"),
|
|
552
|
+
};
|
|
553
|
+
}
|