dsh-stm32 0.1.5 → 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/README.md +2 -2
  2. package/README_EN.md +2 -2
  3. package/client/client.js +24 -24
  4. package/docs/reading-guide.md +32 -0
  5. package/lib/client.js +24 -24
  6. package/lib/commands/register.js +5 -5
  7. package/lib/data/chips.js +4 -4
  8. package/lib/data/clock-db.js +24 -24
  9. package/lib/data/clock-f1.js +2 -2
  10. package/lib/data/cmsis-sources.js +6 -6
  11. package/lib/data/db-presets.js +4 -4
  12. package/lib/data/device-facts.js +6 -6
  13. package/lib/data/family.js +16 -16
  14. package/lib/data/firmware-packages.js +10 -10
  15. package/lib/data/install-guides.js +18 -18
  16. package/lib/data/ioc-presets.js +3 -3
  17. package/lib/data/ioc-schema.js +32 -32
  18. package/lib/data/rm-topics.js +6 -6
  19. package/lib/data/search-roots.js +62 -16
  20. package/lib/data/serial-config.js +7 -7
  21. package/lib/data/stm32f1.js +1 -1
  22. package/lib/data/svd.js +7 -7
  23. package/lib/data/toolchain-config.js +3 -3
  24. package/lib/engine/assets.js +5 -5
  25. package/lib/engine/breakpoints.js +5 -5
  26. package/lib/engine/cache.js +4 -4
  27. package/lib/engine/clock-derived.js +2 -2
  28. package/lib/engine/clock-direct.js +3 -3
  29. package/lib/engine/clock-plan.js +7 -7
  30. package/lib/engine/clock-pllmn.js +6 -6
  31. package/lib/engine/cmake-sources.js +9 -9
  32. package/lib/engine/code-patch.js +5 -5
  33. package/lib/engine/cube-mx-guard.js +3 -3
  34. package/lib/engine/cube-programmer.js +4 -4
  35. package/lib/engine/cubemx-db.js +7 -7
  36. package/lib/engine/debug-session.js +12 -12
  37. package/lib/engine/debug.js +3 -3
  38. package/lib/engine/doctor.js +12 -12
  39. package/lib/engine/download.js +1 -1
  40. package/lib/engine/facts-acquire.js +3 -3
  41. package/lib/engine/fetch.js +2 -2
  42. package/lib/engine/firmware-install.js +16 -16
  43. package/lib/engine/firmware-official.js +8 -8
  44. package/lib/engine/flash.js +22 -22
  45. package/lib/engine/fs-longpath.js +1 -1
  46. package/lib/engine/gdb-mi.js +7 -7
  47. package/lib/engine/generate-script.js +2 -2
  48. package/lib/engine/generate.js +17 -17
  49. package/lib/engine/hal-chip.js +7 -7
  50. package/lib/engine/ioc-plan.js +80 -58
  51. package/lib/engine/ioc-rules.js +9 -9
  52. package/lib/engine/ioc-verify.js +34 -34
  53. package/lib/engine/msys2-install.js +50 -50
  54. package/lib/engine/probe-error.js +8 -8
  55. package/lib/engine/probe-session.js +3 -3
  56. package/lib/engine/probe.js +47 -50
  57. package/lib/engine/project-export.js +1 -1
  58. package/lib/engine/register-clock.js +5 -5
  59. package/lib/engine/register-gpio.js +3 -3
  60. package/lib/engine/register-linker.js +7 -7
  61. package/lib/engine/register-template.js +22 -22
  62. package/lib/engine/regs.js +3 -3
  63. package/lib/engine/rm-extract.js +2 -2
  64. package/lib/engine/rm-sources.js +1 -1
  65. package/lib/engine/route-plan.js +9 -9
  66. package/lib/engine/rtt.js +18 -18
  67. package/lib/engine/scaffold.js +22 -22
  68. package/lib/engine/serial.js +34 -30
  69. package/lib/engine/tar.js +1 -1
  70. package/lib/engine/text-file.js +1 -1
  71. package/lib/engine/thirdparty.js +3 -3
  72. package/lib/engine/tool-env.js +2 -2
  73. package/lib/engine/toolchain-gate.js +8 -8
  74. package/lib/engine/usercode-merge.js +2 -2
  75. package/lib/engine/vscode-config.js +2 -2
  76. package/lib/engine/web-api.js +1 -1
  77. package/lib/engine/xcube-catalog.js +1 -1
  78. package/lib/index.js +5 -5
  79. package/lib/skill/stm32-workflow.js +1 -1
  80. package/lib/tools/assets.js +9 -4
  81. package/lib/tools/build.js +0 -1
  82. package/lib/tools/cache.js +2 -2
  83. package/lib/tools/debug-session.js +5 -5
  84. package/lib/tools/doctor.js +2 -2
  85. package/lib/tools/download.js +1 -1
  86. package/lib/tools/env-install.js +3 -3
  87. package/lib/tools/firmware-install.js +5 -5
  88. package/lib/tools/flash.js +8 -8
  89. package/lib/tools/generate.js +1 -1
  90. package/lib/tools/ioc-apply.js +1 -1
  91. package/lib/tools/ioc-plan.js +18 -8
  92. package/lib/tools/ioc-verify.js +11 -11
  93. package/lib/tools/project-create.js +4 -4
  94. package/lib/tools/project-dir.js +1 -1
  95. package/lib/tools/regs.js +10 -10
  96. package/lib/tools/route-plan.js +9 -9
  97. package/lib/tools/rtt.js +9 -9
  98. package/lib/tools/serial.js +8 -8
  99. package/package.json +1 -1
  100. package/templates/scaffold/RTT.md +26 -34
@@ -2,7 +2,7 @@
2
2
  * L2 数据:`.ioc` 外设预设 —— "启用一个外设"到底要写哪些键。
3
3
  *
4
4
  * 为什么必须做成预设:CubeMX **不是**「读到 USART1.VirtualMode 就建 USART1」。
5
- * 它按「某根脚的 Mode + Signal」推导复用模式,再核对 Mcu.IPn 里有这个实例,才生成
5
+ * CubeMX 按「某根脚的 Mode + Signal」推导复用模式,再核对 Mcu.IPn 中有该实例,才生成
6
6
  * MX_xxx_Init。实测(C8T6 + CubeMX 6.15.0 + STM32Cube_FW_F1_V1.8.7):只写
7
7
  * Mcu.IPn=USART1 + USART1.IPParameters/VirtualMode + PA9.Signal=USART1_TX 时,
8
8
  * CubeMX 静默丢弃整个 USART1(生成结果里没有 MX_USART1_UART_Init,
@@ -16,9 +16,9 @@
16
16
  * 换族时按同样的规则加一份表即可(`family` 字段是唯一的族相关入口)。
17
17
  */
18
18
  /**
19
- * 族相关的引脚别名:**离线兜底表**,只在读不到 CubeMX db 时用。
19
+ * 族相关的引脚别名:**离线回退表**,仅在读不到 CubeMX db 时使用。
20
20
  *
21
- * 正常路径是 src/engine/ioc-plan.ts 的 createPinNameResolver:它按 .ioc 里的 Mcu.Name 去本机
21
+ * 正常路径是 src/engine/ioc-plan.ts 的 createPinNameResolver:该解析器按 .ioc 里的 Mcu.Name 去本机
22
22
  * CubeMX 的 `db/mcu/<Mcu.Name>.xml` 查真实引脚名(R16),db 里叫什么就写什么。
23
23
  * 这张表只收 F1 的 6 根带后缀的脚(PA0→PA0-WKUP、PC13→PC13-TAMPER-RTC、PC14/PC15、PD0/PD1),
24
24
  * 没装 CubeMX 或 db 里没有这颗时才会用到;CubeMX 换版本后 db 名可能变,那时这里就会写错脚,
@@ -13,10 +13,10 @@
13
13
  *
14
14
  * 约定:
15
15
  * - key 用占位符模板,{pin} {index} {ip} {name} {n} {signal} 会被编译成正则分组,{*} 是 catch-all(不取参);
16
- * - writer 为 null 表示「CubeMX 自己写,我们故意不写」,并在 trigger 里写清为什么;
16
+ * - writer 为 null 表示「由 CubeMX 写入,本插件有意不写」,并在 trigger 中说明原因;
17
17
  * - rules 关联 docs 里的规则号(R6/R7/R22/R23…),规则与 schema 互为索引。
18
18
  */
19
- /** 真值表本体(49 条,按匹配优先级排列:先匹配到的生效——具体模板放前面,`{ip}.{name}` 这类兜底模板放最后)。 */
19
+ /** 真值表本体(49 条,按匹配优先级排列:先匹配者生效——具体模板在前,`{ip}.{name}` 这类回退模板在后)。 */
20
20
  export const SPECS = [
21
21
  {
22
22
  "id": "mcu.cpn",
@@ -24,7 +24,7 @@ export const SPECS = [
24
24
  "key": "Mcu.CPN",
25
25
  "valueKind": "text",
26
26
  "valueNote": "芯片订货号(STM32F103C8Tx)。",
27
- "trigger": "恒写(新建工程时由 CubeMX 写,我们只替换模板里已有的值)。",
27
+ "trigger": "恒写(新建工程时由 CubeMX 写入,本插件仅替换模板中已有的值)。",
28
28
  "order": "dictionary",
29
29
  "evidence": [
30
30
  "jar.md:66-70",
@@ -38,7 +38,7 @@ export const SPECS = [
38
38
  "key": "Mcu.Name",
39
39
  "valueKind": "text",
40
40
  "valueNote": "db 里的 Mcu.Name(STM32F103C8Tx)。",
41
- "trigger": "恒写;引脚/信号校验都以它为准。",
41
+ "trigger": "恒写;引脚/信号校验均以此为准。",
42
42
  "order": "dictionary",
43
43
  "evidence": [
44
44
  "jar.md:66-70",
@@ -286,7 +286,7 @@ export const SPECS = [
286
286
  "key": "{pin}.GPIO_ModeDefaultEXTI",
287
287
  "valueKind": "enum",
288
288
  "valueNote": "GPIO_MODE_IT_RISING / GPIO_MODE_IT_FALLING / GPIO_MODE_IT_RISING_FALLING(语料只有这三个 token)。",
289
- "trigger": "配了 EXTI 才写,并同时进 GPIOParameters;缺它 CubeMX 不认这根脚的 EXTI(R23)。",
289
+ "trigger": "配了 EXTI 才写,并同时进 GPIOParameters;缺少该键时 CubeMX 不识别该引脚的 EXTI(R23)。",
290
290
  "order": "dictionary",
291
291
  "evidence": [
292
292
  "语料 GPIO_ModeDefaultEXTI 318 次",
@@ -304,7 +304,7 @@ export const SPECS = [
304
304
  "key": "{pin}.GPIO_ModeDefaultPP",
305
305
  "valueKind": "enum",
306
306
  "valueNote": "多模式引脚的上电默认模式。",
307
- "trigger": "我们不写(CubeMX 需要时自己写);语料 90 次。",
307
+ "trigger": "本插件不写(CubeMX 需要时自行写入);语料 90 次。",
308
308
  "order": "dictionary",
309
309
  "evidence": [
310
310
  "语料 90 次"
@@ -317,7 +317,7 @@ export const SPECS = [
317
317
  "key": "{pin}.GPIO_ModeDefaultOutputPP",
318
318
  "valueKind": "enum",
319
319
  "valueNote": "输出脚的默认模式。",
320
- "trigger": "我们不写;语料 418 次。",
320
+ "trigger": "本插件不写;语料 418 次。",
321
321
  "order": "dictionary",
322
322
  "evidence": [
323
323
  "语料 418 次"
@@ -330,7 +330,7 @@ export const SPECS = [
330
330
  "key": "{pin}.PinAttribute",
331
331
  "valueKind": "text",
332
332
  "valueNote": "引脚属性标记字符串。",
333
- "trigger": "我们不写;语料 4,763 次。",
333
+ "trigger": "本插件不写;语料 4,763 次。",
334
334
  "order": "dictionary",
335
335
  "evidence": [
336
336
  "语料 4,763 次"
@@ -396,7 +396,7 @@ export const SPECS = [
396
396
  "key": "NVIC.PriorityGroup",
397
397
  "valueKind": "enum",
398
398
  "valueNote": "NVIC_PRIORITYGROUP_0..4。",
399
- "trigger": "CubeMX 恒写;我们不写(模板里带)。",
399
+ "trigger": "CubeMX 恒写;本插件不写(模板已含)。",
400
400
  "order": "dictionary",
401
401
  "evidence": [
402
402
  "jar.md:128"
@@ -409,7 +409,7 @@ export const SPECS = [
409
409
  "key": "NVIC.ForceEnableDMAVector",
410
410
  "valueKind": "bool",
411
411
  "valueNote": "true / false。",
412
- "trigger": "CubeMX 恒写;我们不写。",
412
+ "trigger": "CubeMX 恒写;本插件不写。",
413
413
  "order": "dictionary",
414
414
  "evidence": [
415
415
  "jar.md:133"
@@ -422,7 +422,7 @@ export const SPECS = [
422
422
  "key": "NVIC.TimeBase",
423
423
  "valueKind": "text",
424
424
  "valueNote": "时基用的向量名或 None。",
425
- "trigger": "CubeMX 恒写;我们不写。",
425
+ "trigger": "CubeMX 恒写;本插件不写。",
426
426
  "order": "dictionary",
427
427
  "evidence": [
428
428
  "jar.md:129"
@@ -535,7 +535,7 @@ export const SPECS = [
535
535
  "key": "{ip}.IPParametersWithoutCheck",
536
536
  "valueKind": "csv",
537
537
  "valueNote": "不做 db 校验的参数名单。",
538
- "trigger": "我们不写(CubeMX 极少数情况写,非空才写)。",
538
+ "trigger": "本插件不写(CubeMX 极少写入,且仅非空时写)。",
539
539
  "order": "insertion",
540
540
  "evidence": [
541
541
  "jar.md:106"
@@ -595,7 +595,7 @@ export const SPECS = [
595
595
  "key": "RCC.{member}",
596
596
  "valueKind": "text",
597
597
  "valueNote": "时钟树派生键(SYSCLKFreq_VALUE、PLLMUL、APB1Freq_Value…)。成员名是 [A-Za-z0-9_]+,取值由 RCC 树决定。",
598
- "trigger": "由 clock-plan.ts 按 RCC 树逐项重算;这里兜住全部成员名,避免覆盖率检查把它们当未知键。S5 收尾把原来的 {*} 全通配收成 {member}:既能渲染键名(renderIocKey 现在拼得出 RCC.SYSCLKFreq_VALUE),也把「RCC.」这个命名空间本身钉住(RCCF.X 不再命中)。",
598
+ "trigger": "由 clock-plan.ts 按 RCC 树逐项重算;此表覆盖全部成员名,避免覆盖率检查将其视为未知键。S5 收尾将原来的 {*} 全通配改为 {member}:既能渲染键名(renderIocKey 现在拼得出 RCC.SYSCLKFreq_VALUE),也固定住「RCC.」这个命名空间本身(RCCF.X 不再命中)。",
599
599
  "order": "dictionary",
600
600
  "evidence": [
601
601
  "jar.md:118-121(RCCService 自己写)",
@@ -609,7 +609,7 @@ export const SPECS = [
609
609
  "key": "ProjectManager.functionlistsort",
610
610
  "valueKind": "csv",
611
611
  "valueNote": "生成时按序调用的初始化清单:序号-MX_xxx_Init-IP-<bool>-HAL-<bool>。",
612
- "trigger": "我们故意不写:CubeMX 保存时按既有编号自己追加,且每个外设的函数名后缀不统一(USART1→MX_USART1_UART_Init,TIM2→MX_TIM2_Init),猜错会把生成顺序写坏。ioc_verify 把它单独归到 autoAddedFunctions。",
612
+ "trigger": "本插件有意不写:CubeMX 保存时按既有编号自行追加,且每个外设的函数名后缀不统一(USART1→MX_USART1_UART_Init,TIM2→MX_TIM2_Init),猜测错误会破坏生成顺序。ioc_verify 将其单独归到 autoAddedFunctions。",
613
613
  "order": "sequence",
614
614
  "evidence": [
615
615
  "jar.md:212",
@@ -623,7 +623,7 @@ export const SPECS = [
623
623
  "key": "ProjectManager.{name}",
624
624
  "valueKind": "text",
625
625
  "valueNote": "工程管理项:ProjectName、TargetToolchain、KeepUserCode、HeapSize、MainLocation、DeviceId…(成员名就是 CubeMX 的字段名)。",
626
- "trigger": "我们不写(只在 apply 前读 ProjectManager.KeepUserCode 做安全闸);CubeMX 每次保存都会写一整组。以前这些键被 {ip}.{name} 兜成 periph.parameter,等于把工程配置误记成外设参数——分出来之后,{ip}.{name} 命中时才能按「是不是真外设」判拼错。",
626
+ "trigger": "本插件不写(仅在 apply 前读取 ProjectManager.KeepUserCode 作为安全闸);CubeMX 每次保存都会写一整组。此前这些键被 {ip}.{name} 回退为 periph.parameter,等于把工程配置误记成外设参数——分出来之后,{ip}.{name} 命中时才能按「是否为真实外设」判定拼写错误。",
627
627
  "order": "dictionary",
628
628
  "evidence": [
629
629
  "语料 65 行 / 2 份 board 级文件(34 个不同成员)",
@@ -637,7 +637,7 @@ export const SPECS = [
637
637
  "key": "MxCube.Version",
638
638
  "valueKind": "text",
639
639
  "valueNote": "写这份 .ioc 的 CubeMX 版本(6.15.0)。",
640
- "trigger": "我们不改(改了等于伪造版本,会影响 CubeMX 的兼容分支)。",
640
+ "trigger": "本插件不修改(修改等于伪造版本,会影响 CubeMX 的兼容分支)。",
641
641
  "order": "dictionary",
642
642
  "evidence": [
643
643
  "语料 504 份均带(4.5.0 … 4.21.0)"
@@ -650,7 +650,7 @@ export const SPECS = [
650
650
  "key": "KeepUserPlacement",
651
651
  "valueKind": "bool",
652
652
  "valueNote": "生成时是否保留用户代码区(true/false)。",
653
- "trigger": "CubeMX 恒写;我们不写(模板自带)。",
653
+ "trigger": "CubeMX 恒写;本插件不写(模板自带)。",
654
654
  "order": "dictionary",
655
655
  "evidence": [
656
656
  "语料 504/504 均带",
@@ -664,7 +664,7 @@ export const SPECS = [
664
664
  "key": "boardIOC",
665
665
  "valueKind": "bool",
666
666
  "valueNote": "这份 .ioc 是从板级配置导入的(true/false)。",
667
- "trigger": "CubeMX 恒写;我们不写。",
667
+ "trigger": "CubeMX 恒写;本插件不写。",
668
668
  "order": "dictionary",
669
669
  "evidence": [
670
670
  "语料 504/504 均带"
@@ -677,7 +677,7 @@ export const SPECS = [
677
677
  "key": "board",
678
678
  "valueKind": "text",
679
679
  "valueNote": "板名(NUCLEO-F030R8)或 custom。",
680
- "trigger": "CubeMX 恒写;我们不写。",
680
+ "trigger": "CubeMX 恒写;本插件不写。",
681
681
  "order": "dictionary",
682
682
  "evidence": [
683
683
  "语料 501/504"
@@ -690,7 +690,7 @@ export const SPECS = [
690
690
  "key": "BSP_IP_NAME",
691
691
  "valueKind": "text",
692
692
  "valueNote": "BSP 组件名(只有板级配置带)。",
693
- "trigger": "我们不写。",
693
+ "trigger": "本插件不写。",
694
694
  "order": "dictionary",
695
695
  "evidence": [
696
696
  "语料 65/504"
@@ -703,7 +703,7 @@ export const SPECS = [
703
703
  "key": "MMTAppRegionsCount",
704
704
  "valueKind": "count",
705
705
  "valueNote": "内存映射表(MMT)分区数(只有部分高端型号带)。",
706
- "trigger": "我们不写。",
706
+ "trigger": "本插件不写。",
707
707
  "order": "dictionary",
708
708
  "evidence": [
709
709
  "语料 26/504"
@@ -716,7 +716,7 @@ export const SPECS = [
716
716
  "key": "MMTConfigApplied",
717
717
  "valueKind": "bool",
718
718
  "valueNote": "是否应用了 MMT 配置。",
719
- "trigger": "我们不写。",
719
+ "trigger": "本插件不写。",
720
720
  "order": "dictionary",
721
721
  "evidence": [
722
722
  "语料 26/504"
@@ -729,7 +729,7 @@ export const SPECS = [
729
729
  "key": "{pin}.ContextOwner",
730
730
  "valueKind": "text",
731
731
  "valueNote": "引脚上下文归属(只有板级 BSP 配置带,如 PB4(NJRST).ContextOwner)。",
732
- "trigger": "我们不写。",
732
+ "trigger": "本插件不写。",
733
733
  "order": "dictionary",
734
734
  "evidence": [
735
735
  "语料 3 例(PB4(NJRST) / PH3-BOOT0)"
@@ -793,7 +793,7 @@ function literalWeight(template) {
793
793
  * 匹配优先级:三条一起决定谁先匹配,避免宽模板抢走具体键。
794
794
  *
795
795
  * 0. 以字面量开头、没有 catch-all(Mcu.Pin{index} / NVIC.{name}_IRQn / {pin}.Signal 之外的都算)
796
- * 1. 以字面量开头、带 catch-all 的命名空间兜底(RCC.{*})
796
+ * 1. 以字面量开头、带 catch-all 的命名空间回退(RCC.{*})
797
797
  * 2. 以占位符开头的通配模板({ip}.{name} / {pin}.Signal / {ip}.IPParameters)
798
798
  *
799
799
  * 同级再按字面量长度降序:RCC.IPParameters(16) 要压住 {ip}.IPParameters(13),
@@ -883,7 +883,7 @@ export function iocKeyTier(spec) {
883
883
  return tier;
884
884
  }
885
885
  /**
886
- * 已知的「伪命名空间」:它们不是外设实例,但确实会以 `前缀.成员` 的形状出现。
886
+ * 已知的「伪命名空间」:并非外设实例,但确实会以 `前缀.成员` 的形式出现。
887
887
  * 目的是让 auditIocKeys 别把这些报成拼错。计数来自 504 份 board 级语料(键出现行数)。
888
888
  */
889
889
  export const IOC_NAMESPACE_PREFIXES = [
@@ -937,11 +937,11 @@ export function describeIocKey(key) {
937
937
  * 闸门第二道:光命中 {ip}.{name} 不算数,还要看占位符填进来的东西是不是真的存在。
938
938
  * 三个判据都来自现场(.ioc 里的 Mcu.IP<i> 列表、本机 db 的引脚表与参数清单),不是猜:
939
939
  * - ip 是已启用的外设实例 → 成员名必须在 db 给这个 IP 的 RefParameter 清单里(拼错 Baudrate 会被抓);
940
- * - ip 是 db 里的引脚名 → 说明写的是「引脚属性」,但引脚属性必须逐条登记进表(否则 CubeMX 丢掉它);
940
+ * - ip 是 db 里的引脚名 → 说明写的是「引脚属性」,但引脚属性必须逐条登记进表(否则 CubeMX 会丢弃该属性);
941
941
  * - ip 是已知伪命名空间(ProjectManager/CAD/…)→ 放行;
942
- * - 三者都不是 → 「疑似拼错」,这是我们唯一能凭空判错的一类。 */
942
+ * - 三者都不是 → 「疑似拼错」,这是本插件唯一能直接判错的一类。 */
943
943
  /**
944
- * 这些前缀在 db 里是 IP 实例、但 CubeMX 从不把它们登记进 Mcu.IP<i>,键直接挂在伪命名空间下。
944
+ * 这些前缀在 db 里是 IP 实例、但 CubeMX 从不将其登记进 Mcu.IP<i>,键直接归入伪命名空间。
945
945
  * 目前只有 GPIO:504 份板级 .ioc 里 Mcu.IPn=GPIO 出现 0 次,GPIO.groupedBy 实测只有
946
946
  * "Group By Peripherals"(110) / "Show All"(8) 两种值。加新前缀前先给语料计数。
947
947
  */
@@ -988,11 +988,11 @@ export function auditIocKeys(keys, context = {}) {
988
988
  const ip = (hit.params.ip ?? "").trim();
989
989
  const name = hit.params.name ?? "";
990
990
  const upper = ip.toUpperCase();
991
- // GPIO 是"伪实例":db 里确实有 IP InstanceName="GPIO",但 CubeMX 从不把它写进 Mcu.IP<i>
992
- // (504 份板级 .ioc 里 Mcu.IPn=GPIO 出现 0 次),它的 <pin>.GPIO_* 走引脚名、GPIO.groupedBy 走面板设置。
991
+ // GPIO 是"伪实例":db 里确实有 IP InstanceName="GPIO",但 CubeMX 从不将其写入 Mcu.IP<i>
992
+ // (504 份板级 .ioc 里 Mcu.IPn=GPIO 出现 0 次),其 <pin>.GPIO_* 走引脚名、GPIO.groupedBy 走面板设置。
993
993
  // 所以必须先判伪命名空间,否则会被判成"有实例但没启用",把一个合法键报成错误。
994
994
  if (IOC_VIRTUAL_NAMESPACES.has(upper) && !instances.has(upper)) {
995
- findings.push({ ...base, verdict: "ok", detail: ip + " 是面板/全局设置用的伪命名空间(CubeMX 不把它列进 Mcu.IP<i>)" });
995
+ findings.push({ ...base, verdict: "ok", detail: ip + " 是面板/全局设置用的伪命名空间(CubeMX 不将其列入 Mcu.IP<i>)" });
996
996
  continue;
997
997
  }
998
998
  if (instances.has(upper)) {
@@ -1023,7 +1023,7 @@ export function auditIocKeys(keys, context = {}) {
1023
1023
  findings.push({
1024
1024
  ...base,
1025
1025
  verdict: "pin-attribute",
1026
- detail: ip + " 是引脚名," + name + " 是引脚属性;引脚属性必须逐条登记进真值表(否则 CubeMX 会丢掉它)",
1026
+ detail: ip + " 是引脚名," + name + " 是引脚属性;引脚属性必须逐条登记进真值表(否则 CubeMX 会丢弃该属性)",
1027
1027
  });
1028
1028
  continue;
1029
1029
  }
@@ -1,16 +1,16 @@
1
1
  /**
2
2
  * rm-topics(主题/锚点清单)的两层装载。
3
3
  *
4
- * 为什么要有「spec」这层:机器是阅卷人不是出题人——自动抽取必须有人(或踩过坑后的会话)
4
+ * 为什么需要「spec」这一层:机器是阅卷人而非出题人——自动抽取必须有人(或经历过已知问题的会话)
5
5
  * 给出「要采信哪几条结论 + 在 RM 里逐字回查什么」,机器才能核验并落 semantics。
6
6
  *
7
7
  * 装载顺序(两层合并,同 id 用户赢):
8
8
  * 1) 插件自带的族级 spec:lib/data/rm-topics/<族>.json(源在 src/data/rm-topics/,
9
9
  * 随包发布;scripts/copy-data.mjs 负责进 lib)。
10
10
  * 2) 用户芯片级 spec:<factsRoot>/topics/<族>/<线>.json——只覆盖手上这颗。
11
- * 用户踩了坑(比如某条选项字节规则害得板子连不上),把「这条结论 + 回查锚点」
12
- * 写成一份小 JSON 放进这里,这颗芯片下一次烧录前就必须过机检;没写过的其它
13
- * 芯片不受影响(族级判据太粗,坑通常是芯片级的,见 2026-11-07 决定)。
11
+ * 用户遇到已知问题(例如某条选项字节规则导致板子无法连接),将「该结论 + 回查锚点」
12
+ * 写成一份小 JSON 放入此处,该芯片下一次烧录前必须通过机检;未写入的其他
13
+ * 芯片不受影响(族级判据过粗,已知问题通常是芯片级的,见 2026-11-07 决定)。
14
14
  *
15
15
  * 判定「这颗芯片要不要过机检」= 合并后主题数 > 0。
16
16
  */
@@ -47,7 +47,7 @@ function readJson(file) {
47
47
  /**
48
48
  * 插件自带族级 spec 的目录:lib/data/rm-topics/(JSON 不进 tsc,由
49
49
  * scripts/copy-data.mjs 在 build 时复制;仓库里 lib/ 是入库的,装包侧也带)。
50
- * 没有退回 src 的兜底:那条相对路径在插件真实安装位置(node_modules 深处)
50
+ * 未回退到 src:该相对路径在插件真实安装位置(node_modules 深处)
51
51
  * 基本不可能存在,留着只会把「没跑 copy-data」伪装成「清单在但读不到」。
52
52
  */
53
53
  export function bundledTopicsDir() {
@@ -96,7 +96,7 @@ export function loadRmTopics(family, line, factsRoot) {
96
96
  const topics = [...merged.values()];
97
97
  if (topics.length === 0)
98
98
  return EMPTY;
99
- // 用户 spec 没写 lines 时只管自己这颗(fallbackLines 兜底);族级有 lines 尊重族级
99
+ // 用户 spec 未写 lines 时仅针对该芯片(fallbackLines 回退);族级有 lines 时遵循族级
100
100
  if (lines.size === 0)
101
101
  lines.add(ln);
102
102
  return { topics, lines: [...lines].sort(), docId, origins, hasSpec: true };
@@ -7,7 +7,7 @@
7
7
  * 3. 用户配置文件(toolchain-config:stm32_env_install 装好后自己写的,见下)——
8
8
  * 也整份替换默认值,但排在环境变量之后(环境变量是临时/脚本场景的活开关);
9
9
  * 4. 默认候选表(DEFAULT_BIN_DIRS / DEFAULT_CUBEMX_ROOTS,本机常见安装位置)。
10
- * 之后再把**自动发现到的**安装目录追加到尾部:只做兜底,不覆盖上面任何一处,
10
+ * 之后再把**自动发现到的**安装目录追加到尾部:仅作为回退,不覆盖上面任何一处,
11
11
  * 这样别人把 MSYS2 装在 E:\\msys64、CubeMX 装在 F:\\tools 也能直接跑。
12
12
  * 设 STM32_NO_DISCOVER=1 可关掉自动发现(CI / 单测里避免扫盘);
13
13
  * 设 DSH_STM32_NO_CONFIG=1 可让第 3 档失效(单测里保证不读本机配置)。
@@ -21,7 +21,7 @@ import { binDirsFromConfig, configReadingDisabled, cubeMxRootsFromConfig, readTo
21
21
  *
22
22
  * 这里绝不能出现开发机专属路径(D:/app/msys64 之类):插件是给别人下载的,
23
23
  * 那些路径在别人机器上必然搜不到,还会把「查过哪些地方」的文案污染成别人看不懂的样子。
24
- * 装在别处的情况由自动发现兜底(扫盘符 msys64/app/msys64/tools 等常见布局)。
24
+ * 非默认位置由自动发现回退处理(扫描盘符内 msys64/app/msys64/tools 等常见布局)。
25
25
  */
26
26
  export const DEFAULT_BIN_DIRS = [
27
27
  "C:/msys64/ucrt64/bin",
@@ -77,7 +77,7 @@ export function looksLikeCubeMxRoot(dir, exists = existsSync) {
77
77
  return exists(dir + "/jre/bin/java.exe") && exists(dir + "/STM32CubeMX.exe");
78
78
  }
79
79
  /**
80
- * 一个目录是不是能用的工具链 bin(至少有一个我们要的 exe)。
80
+ * 一个目录是不是能用的工具链 bin(至少包含一个本插件需要的 exe)。
81
81
  *
82
82
  * 不能只认 gcc/openocd/cmake:只补了 ninja 或 gdb 的 MSYS2(典型:先装 gcc,再单独补 gdb)
83
83
  * 会被整目录漏掉,doctor 于是说「工具链没找到」。这里把 probe 的五项都算上。
@@ -112,7 +112,7 @@ export function discoverBinDirs(probe) {
112
112
  export const DEFAULT_CUBE_PRG_BINS = [
113
113
  "C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeProgrammer/bin",
114
114
  ];
115
- /** 一个目录是不是 CubeProgrammer 的 bin:认它的 CLI 主程序(32 位子目录不算,本插件只在 64 位路径找)。 */
115
+ /** 一个目录是不是 CubeProgrammer 的 bin:以 CLI 主程序判定(32 位子目录不算,本插件只在 64 位路径找)。 */
116
116
  export function looksLikeCubePrgBin(dir, exists = existsSync) {
117
117
  return exists(dir + "/STM32_Programmer_CLI.exe");
118
118
  }
@@ -145,18 +145,25 @@ function cubeMxBases(probe) {
145
145
  bases.push(dir);
146
146
  return bases;
147
147
  }
148
- /** 在常见安装位置里找 CubeMX 根目录(注册表优先,其次扫目录)。 */
148
+ /**
149
+ * 在常见安装位置里找 CubeMX 根目录:安装器环境变量与注册表优先,其次扫目录。
150
+ *
151
+ * 三种来源缺一不可——2026-11 实测 ST 6.18.1 的官方安装包把路径写在 STM32CubeMX_PATH 里,
152
+ * 注册表只有卸载键(且没有 InstallLocation,路径藏在 DisplayIcon 的 exe 全路径里),
153
+ * 而安装目录本身可以落在任意盘任意层级(例如 D:/app/STMicroelectronics/STM32Cube/STM32CubeMX)。
154
+ */
149
155
  export function discoverCubeMxRoots(probe) {
150
156
  const found = [];
151
- for (const dir of probe.registryInstallDirs()) {
157
+ for (const dir of [...probe.installerDirs(), ...probe.registryInstallDirs()]) {
152
158
  const normalized = normalizePathEntry(dir);
153
159
  if (normalized !== "" && looksLikeCubeMxRoot(normalized, probe.exists))
154
160
  found.push(normalized);
155
161
  }
156
162
  for (const base of cubeMxBases(probe)) {
157
- const direct = base.replace(/\/+$/u, "") + "/STM32CubeMX";
158
- if (looksLikeCubeMxRoot(direct, probe.exists))
159
- found.push(direct);
163
+ for (const direct of cubeMxCandidates(base)) {
164
+ if (looksLikeCubeMxRoot(direct, probe.exists))
165
+ found.push(direct);
166
+ }
160
167
  for (const child of probe.listDirs(base)) {
161
168
  if (looksLikeCubeMxRoot(child, probe.exists))
162
169
  found.push(child);
@@ -164,6 +171,11 @@ export function discoverCubeMxRoots(probe) {
164
171
  }
165
172
  return dedupePaths(found);
166
173
  }
174
+ /** 一个 base 下的两种 ST 落点:直接子目录,以及 ST 安装包默认的 <base>/STMicroelectronics/STM32Cube 层级。 */
175
+ function cubeMxCandidates(base) {
176
+ const trimmed = base.replace(/\/+$/u, "");
177
+ return [trimmed + "/STM32CubeMX", trimmed + "/STMicroelectronics/STM32Cube/STM32CubeMX"];
178
+ }
167
179
  /** 解码失败的痕迹:非法字节被换成 U+FFFD。 */
168
180
  const REPLACEMENT_CHAR = "\u{FFFD}";
169
181
  /**
@@ -180,7 +192,7 @@ const REPLACEMENT_CHAR = "\u{FFFD}";
180
192
  * 两种都解不出来就返回 ok:false —— 宁可让用户手写一条,也不把乱码写进注册表。
181
193
  *
182
194
  * 备选方案(没采用):用 powershell 先把 [Console]::OutputEncoding 设成 UTF8 再调 reg.exe。
183
- * 不用的原因:多一层 PowerShell 启动开销与引号转义,而且字节其实已经拿到了,直接探测更短。
195
+ * 不用的原因:多一层 PowerShell 启动开销与引号转义,且字节内容已经取得,直接探测更短。
184
196
  */
185
197
  export function decodeRegistryText(value, label = "reg.exe 输出") {
186
198
  if (value === null || value === undefined) {
@@ -226,15 +238,45 @@ function regExe() {
226
238
  const root = process.env.SystemRoot || process.env.windir || "C:\\Windows";
227
239
  return join(root, "System32", "reg.exe");
228
240
  }
241
+ /**
242
+ * 安装器写进环境变量的安装根(ST 官方 Windows 安装包写 STM32CubeMX_PATH)。
243
+ *
244
+ * 为什么不并进 STM32_CUBEMX_ROOT:该项是本插件自己的开关,语义是"整份替换默认候选";
245
+ * 这个是系统里客观存在的登记信息,只该参与自动发现(与注册表同级),不能因为用户
246
+ * 装了别的版本把候选表整个换掉。
247
+ */
248
+ export function installerCubeMxDirs(env = process.env) {
249
+ return dedupePaths(splitList(env["STM32CubeMX_PATH"]).concat(splitList(env["STM32CUBEMX_PATH"])));
250
+ }
251
+ /** 注册表值可能带图标序号后缀("D:\x\app.exe",0)。 */
252
+ const ICON_INDEX_SUFFIX = /,\s*-?\d+\s*$/u;
253
+ /**
254
+ * 注册表里的值可能是目录(InstallLocation),也可能是指向 exe/bat 的完整路径
255
+ * (DisplayIcon / UninstallString)。后者取所在目录——ST 6.18.1 只在 DisplayIcon 里
256
+ * 留下...\STM32CubeMX\STM32CubeMX.exe,没有 InstallLocation 可读。
257
+ */
258
+ export function dirFromRegistryValue(value) {
259
+ const normalized = normalizePathEntry(value.replace(ICON_INDEX_SUFFIX, ""));
260
+ if (normalized === "")
261
+ return "";
262
+ if (!/\.(exe|bat|cmd|com)$/iu.test(normalized))
263
+ return normalized;
264
+ const slash = normalized.lastIndexOf("/");
265
+ return slash <= 0 ? "" : normalized.slice(0, slash);
266
+ }
229
267
  /** 读注册表里 ST 记下的安装位置;没有这些键是最常见的情况,不算错误。 */
230
268
  function readRegistryInstallDirs() {
231
269
  if (process.platform !== "win32")
232
270
  return [];
271
+ const uninstall = "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\STM32CubeMX";
233
272
  const keys = [
234
273
  { key: "HKLM\\SOFTWARE\\STMicroelectronics\\STM32CubeMX", value: "InstallDir" },
235
274
  { key: "HKLM\\SOFTWARE\\WOW6432Node\\STMicroelectronics\\STM32CubeMX", value: "InstallDir" },
236
275
  { key: "HKCU\\SOFTWARE\\STMicroelectronics\\STM32CubeMX", value: "InstallDir" },
237
- { key: "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\STM32CubeMX", value: "InstallLocation" },
276
+ { key: uninstall, value: "InstallLocation" },
277
+ // ST 6.18.1 实测:只有 DisplayIcon / UninstallString,没有 InstallLocation
278
+ { key: uninstall, value: "DisplayIcon" },
279
+ { key: uninstall, value: "UninstallString" },
238
280
  ];
239
281
  const out = [];
240
282
  for (const entry of keys) {
@@ -258,15 +300,18 @@ function readRegistryInstallDirs() {
258
300
  continue;
259
301
  const parts = trimmed.split(/\s{2,}/u);
260
302
  const dir = parts[parts.length - 1];
261
- if (dir !== undefined && dir.trim() !== "")
262
- out.push(dir.trim());
303
+ if (dir === undefined || dir.trim() === "")
304
+ continue;
305
+ const normalized = dirFromRegistryValue(dir);
306
+ if (normalized !== "")
307
+ out.push(normalized);
263
308
  }
264
309
  }
265
310
  catch {
266
311
  // 键或值不存在:正常情况
267
312
  }
268
313
  }
269
- return out;
314
+ return dedupePaths(out);
270
315
  }
271
316
  /** 真实系统的探针。 */
272
317
  export function defaultDiscoverProbe() {
@@ -283,6 +328,7 @@ export function defaultDiscoverProbe() {
283
328
  return [];
284
329
  }
285
330
  },
331
+ installerDirs: () => installerCubeMxDirs(),
286
332
  registryInstallDirs: readRegistryInstallDirs,
287
333
  driveRoots: () => {
288
334
  if (process.platform !== "win32")
@@ -374,8 +420,8 @@ export function searchConfigWarnings(env = process.env, exists = existsSync) {
374
420
  * 自动发现的安装只追加在"没给显式参数"的那一档尾部:用参数点名目录时说明调用方
375
421
  * 心里有确切位置,再混进别处的同名工具会让"我明明指定了"变成假的。
376
422
  *
377
- * 用户配置文件在这里读,是因为**这一层是唯一的汇聚点**:所有工具/引擎都经过它,
378
- * 装完工具链后不必改任何调用方就能立即生效(不需要重启 DSH:路径是我们自己读的)。
423
+ * 用户配置文件在这里读,是因为**这一层是唯一的汇聚点**:所有工具与引擎都经过这一层,
424
+ * 装完工具链后不必改任何调用方就能立即生效(不需要重启 DSH:路径由本插件自行读取)。
379
425
  */
380
426
  export function resolveSearchConfig(env = process.env, overrides = {},
381
427
  /** 单测注入用;生产代码不要传。 */
@@ -14,7 +14,7 @@
14
14
  *
15
15
  * 环境变量:
16
16
  * DSH_STM32_SERIAL_CONFIG 整体改指配置文件(单测与多工程隔离用;相对路径按主目录解析)
17
- * DSH_STM32_NO_CONFIG=1 让读配置的地方当它不存在(与 config.json 同一套开关语义)
17
+ * DSH_STM32_NO_CONFIG=1 使读取配置的代码按未配置处理(与 config.json 同一套开关语义)
18
18
  */
19
19
  import { randomBytes } from "node:crypto";
20
20
  import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -52,7 +52,7 @@ function asString(value) {
52
52
  }
53
53
  /**
54
54
  * DTR/RTS 只认真正的布尔值,外加 "true"/"false"/"1"/"0" 这些常见字符串写法。
55
- * 认不出来返回 null(由调用方记一条错误)——悄悄回落到缺省值会让"我明明设了 rts"变成静默无效。
55
+ * 无法识别时返回 null(由调用方记录一条错误)——静默回退到缺省值会使「已设置的 rts」静默失效。
56
56
  */
57
57
  function asOptionalBoolean(value) {
58
58
  if (typeof value === "boolean")
@@ -81,7 +81,7 @@ function oneOf(value, allowed) {
81
81
  }
82
82
  /**
83
83
  * 把任意 JSON / 工具参数归一成合法参数:非法的字段按缺省值处理并记一条 errors。
84
- * 不抛异常——参数写错要能变成 settings-invalid 的一次报告,而不是把调用方打崩。
84
+ * 不抛异常——参数写错要能变成 settings-invalid 的一次报告,而非导致调用方失败。
85
85
  */
86
86
  export function normalizeSerialSettings(raw, errors, base = defaultSerialSettings()) {
87
87
  const out = { ...base };
@@ -171,7 +171,7 @@ function isBusPathId(value) {
171
171
  */
172
172
  export function portIdentity(facts) {
173
173
  // 字段声明成 string,但调用方可能是「手工改过的 serial.json / 老版本记录」,
174
- // 缺字段时按空串处理,别让一个半截配置把整条打开流程打崩。
174
+ // 缺字段时按空串处理,避免不完整配置导致整条打开流程失败。
175
175
  const vid = text(facts.vid).toUpperCase();
176
176
  const pid = text(facts.pid).toUpperCase();
177
177
  const serial = text(facts.serialNumber);
@@ -322,7 +322,7 @@ export function readSerialConfig(env = process.env) {
322
322
  path,
323
323
  exists: true,
324
324
  config: null,
325
- errors: ["串口配置文件不是合法 JSON:" + describeError(error) + ";已按无记忆处理(重新写入会覆盖它)"],
325
+ errors: ["串口配置文件不是合法 JSON:" + describeError(error) + ";已按无记忆处理(重新写入将覆盖该值)"],
326
326
  mtimeMs,
327
327
  };
328
328
  cache = { path, mtimeMs, size, read };
@@ -374,7 +374,7 @@ export function findPortMemory(config, facts) {
374
374
  }
375
375
  /**
376
376
  * 取这块板子的历史参数。
377
- * 记忆只是「基准」:调用方显式给的参数永远覆盖它,缺省的字段才落到历史值上。
377
+ * 记忆仅作「基准」:调用方显式给出的参数始终优先,缺省字段才取历史值。
378
378
  */
379
379
  export function recallPortSettings(facts, env = process.env) {
380
380
  const read = readSerialConfig(env);
@@ -393,7 +393,7 @@ export function recallPortSettings(facts, env = process.env) {
393
393
  };
394
394
  }
395
395
  /**
396
- * 打开成功后记一笔:按身份 upsert,其余条目原样保留(别人的板子不能被我们的打开挤掉)。
396
+ * 打开成功后记一笔:按身份 upsert,其余条目原样保留(其他设备的条目不受本插件打开操作影响)。
397
397
  * 只记「这次真的通了」的参数——失败时调用方不该写,否则下次 recover 会复用一个错参数。
398
398
  */
399
399
  export function rememberPort(facts, settings, env = process.env) {
@@ -2,7 +2,7 @@
2
2
  * L1:STM32F1 型号 → 芯片事实(容量档 / 启动文件 / 设备宏 / 设备头 / Flash / RAM / 引脚数)。
3
3
  *
4
4
  * 这里只剩**解析逻辑**,没有事实:事实全部来自内置资源里的 device/f1/chips.json,
5
- * 经 src/data/device-facts.ts 读入(用户 2026-10-31「内置表删了吧」的决定)。
5
+ * 经 src/data/device-facts.ts 读入(用户 2026-10-31 决定删除内置表)。
6
6
  * 所以本文件不再有 F1_LINES / GROUP_BY_LETTER / FLASH_BY_LETTER / RAM_BY_LINE_LETTER
7
7
  * 这类表——加一款芯片只改 scripts/assets/ 的 scripts/build-assets.mjs,插件一个字都不用动。
8
8
  *
package/lib/data/svd.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * L1:SVD 寄存器表(device/f1/svd/<line>.json)——按名字找寄存器、按值解释位域。
3
3
  *
4
4
  * 为什么要这一层:regs_read 以前只认裸地址(0x4001100C),用户手里拿的是手册里的
5
- * "GPIOC_ODR" / "GPIOC.ODR",读回来的 0x00000004 也没人告诉你那是 ODR2(PC2 输出高)。
5
+ * "GPIOC_ODR" / "GPIOC.ODR",读回的 0x00000004 无法指示其为 ODR2(PC2 输出高)。
6
6
  * SVD 里这些都有:外设 baseAddress + 寄存器 addressOffset + 字段 bitOffset/bitWidth。
7
7
  *
8
8
  * 数据来源只有一个:内置资源 插件内置 assets/ 的 device/f1/svd/<line>.json,装到
@@ -12,7 +12,7 @@
12
12
  * · 直接检出/自定义布局:<root>/device/f1/svd/103.json(开发时把 DSH_STM32_ASSETS 指到资源脚本 scripts/assets/)。
13
13
  *
14
14
  * 关键约定:
15
- * · SVD 只在 profile=full 里。缺了不是"静默降级",而是结构化失败 + 一句能照着敲的
15
+ * · SVD 只在 profile=full 里。缺了不是"静默降级",而是结构化失败 + 可直接照做的提示
16
16
  * "随插件内置(profile=full 也随包安装)"(见 SVD_FULL_PROFILE_HINT);
17
17
  * · 读不到不抛:loadSvd() 返回 { device, failure },loadSvdForLine() 复用前者的便捷版(返回 null);
18
18
  * 只有"明确要一个寄存器/一段地址"的 API(resolveRegisterRef / describeAddress)才抛 SvdError,
@@ -71,7 +71,7 @@ function isDirectory(dir) {
71
71
  }
72
72
  /**
73
73
  * SVD 里的数值:内置资源写的是十六进制字符串("0x40011000" / "0x0C"),
74
- * 也接受数字与纯十进制字符串,别的都算坏数据。
74
+ * 也接受数字与纯十进制字符串,其他形式均视为坏数据。
75
75
  */
76
76
  export function parseSvdNumber(value) {
77
77
  if (typeof value === "number")
@@ -139,7 +139,7 @@ function listNames(names, limit = 24) {
139
139
  }
140
140
  const svdCache = new Map();
141
141
  const svdStats = { reads: 0, hits: 0 };
142
- /** 缓存诊断:单测用它证明"第二次没再读盘"(reads 不涨、hits 涨)。 */
142
+ /** 缓存诊断:单测据此证明「第二次未再读盘」(reads 不增加、hits 增加)。 */
143
143
  export function svdCacheStats() {
144
144
  return { reads: svdStats.reads, hits: svdStats.hits, entries: svdCache.size };
145
145
  }
@@ -194,7 +194,7 @@ function fieldFrom(value, where) {
194
194
  return { field: { name, bitOffset, bitWidth, description: textOf(value["description"]) }, error: "" };
195
195
  }
196
196
  /**
197
- * 解析一份 SVD 文本。纯函数:测试可以直接喂字符串,不走磁盘。
197
+ * 解析一份 SVD 文本。纯函数:测试可直接传入字符串,不访问磁盘。
198
198
  * 任何一条外设/寄存器/字段不合法都返回 error(宁缺勿错,见文件头)。
199
199
  */
200
200
  export function parseSvd(text, filePath = "", version = "", expectedLine = "") {
@@ -465,7 +465,7 @@ function locateAddress(device, address) {
465
465
  const exact = device.byAddress.get(address);
466
466
  if (exact !== undefined)
467
467
  return exact;
468
- // flat 已按地址升序:找到最后一条起点 <= address 的,看它是否覆盖该地址。
468
+ // flat 已按地址升序:找到最后一条起点 <= address 的记录,判断其是否覆盖该地址。
469
469
  let low = 0;
470
470
  let high = device.flat.length - 1;
471
471
  let candidate = null;
@@ -505,7 +505,7 @@ export function resolveRegisterRef(ref, line, env = process.env) {
505
505
  return resolvedOf(entry);
506
506
  const inside = locateAddress(device, address);
507
507
  if (inside !== null) {
508
- throw new SvdError("register-unknown", formatAddress(address) + " 不是寄存器起点:它落在 " + inside.peripheral.name + "." + inside.register.name +
508
+ throw new SvdError("register-unknown", formatAddress(address) + " 不是寄存器起点:该地址落在 " + inside.peripheral.name + "." + inside.register.name +
509
509
  "(起点 " + formatAddress(inside.address) + ",位宽 " + String(inside.register.size) + " 位)内部。", { line: device.line, ref: text });
510
510
  }
511
511
  throw new SvdError("address-unknown", "line=" + device.line + " 的 SVD 里没有寄存器覆盖地址 " + formatAddress(address) + "(按裸地址读仍然可以,只是没有名字/位域)。", { line: device.line, ref: text });