fcdev 0.6.0 → 0.7.0

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 (33) hide show
  1. package/CHANGELOG.md +46 -32
  2. package/README.md +8 -8
  3. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +9 -8
  4. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +5 -5
  5. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +3 -3
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +69 -62
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +3 -3
  8. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +13 -10
  9. package/docs/09-/345/217/221/345/270/203.md +16 -11
  10. package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
  11. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +7 -7
  12. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +4 -1
  13. package/package.json +5 -2
  14. package/src/cli/args-parser.mjs +1 -1
  15. package/src/cli/commands/debug-command.mjs +20 -58
  16. package/src/cli/commands/run-command.mjs +36 -39
  17. package/src/cli/index.mjs +4 -4
  18. package/src/config/config-loader.mjs +1 -1
  19. package/src/disasm/disassembler.mjs +1 -1
  20. package/src/disasm/trace.mjs +4 -3
  21. package/src/docs/doc-topics.mjs +38 -38
  22. package/src/emulator/debug-cli.mjs +48 -0
  23. package/src/emulator/emulator-launcher.mjs +107 -29
  24. package/src/emulator/emulator-locator.mjs +7 -7
  25. package/src/emulator/index.mjs +4 -3
  26. package/src/emulator/sb2000-session.mjs +101 -0
  27. package/targets/nes/lib/fcnes.lib +0 -0
  28. package/targets/nes/lib/nes-font.o +0 -0
  29. package/targets/nes/target.json +1 -1
  30. package/targets/sb2000/lib/crt0.o +0 -0
  31. package/targets/sb2000/lib/sb2000.lib +0 -0
  32. package/targets/sb2000/target.json +1 -1
  33. package/src/emulator/debug-client.mjs +0 -125
package/CHANGELOG.md CHANGED
@@ -1,32 +1,46 @@
1
- # 更新记录
2
-
3
- 适用于 `fcdev`、`create-fcdev`、`fcdev-cc65` 三个包,它们的版本号相同。
4
-
5
- ## 0.6.0(2026-11-15)
6
-
7
- ### 安装
8
-
9
- - cc65 工具链包改名为 `fcdev-cc65`,不再放在 `@rujianjs` 作用域下;`fcdev` 会自动安装它,使用者无须任何操作。
10
-
11
- ### 模拟器与调试
12
-
13
- - 不再提供模拟器包 `@rujianjs/fcdev-emulator`:`fcdev run` 与 `fcdev debug` 需要自备模拟器,用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定。
14
-
15
- ## 0.5.0(2026-11-13)
16
-
17
- ### 小霸王学习机 SB2000
18
-
19
- - 新增直接操作硬件的函数:通用 DMA、图形端口(显存、调色板、精灵)和硬件定时器,程序不用再自己写寄存器。
20
- - 新增硬件寄存器与位的符号,C 里以 `SB_HW_` 开头,汇编里以 `HW_` 开头。
21
- - C 接口参考扩充到 204 个函数,用 `npx fcdev api dma`、`npx fcdev api ppu`、`npx fcdev api timer` 查询新增的三个模块。
22
- - 硬件说明按真机实测更新:图形端口、DMA 和定时器的行为,并列出真机与模拟器仍有差异的读数。
23
-
24
- ### 反汇编
25
-
26
- - 识别地址表:`LDA 表,X` 加间接跳转、`PHA`/`RTS`、`JMP (地址)` 指向的表,表里的地址作为新入口继续追踪。
27
-
28
- ### 模拟器与调试
29
-
30
- - `fcdev debug` 的 `tape play`、`tape rec` 命令里的文件路径按终端当前目录解析。
31
- - 模拟器包带上新版模拟器,改动见模拟器的更新记录。
32
- - 命令的提示、错误说明和文档里的示例统一写成 `npx fcdev …`,终端里直接输入 `fcdev` 会找不到命令的原因也写进了使用说明。
1
+ # 更新记录
2
+
3
+ 适用于 `fcdev`、`create-fcdev`、`fcdev-cc65` 三个包,它们的版本号相同。
4
+
5
+ ## 0.7.0(2026-11-15)
6
+
7
+ ### 模拟器与调试
8
+
9
+ - `fcdev run` 与 `fcdev debug` 改用新模拟器 Ember:用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指向 Ember 的可执行文件,不再支持旧模拟器。
10
+ - `fcdev debug` 的参数改为调试终端客户端 `ember-debug` 的命令,如 `debug call runtime.status`、`debug screenshot out.png`,不再支持旧模拟器的单行命令。
11
+ - `fcdev run --debug` 用独立的用户数据目录启动 Ember,可以和平时在用的 Ember 同时运行,程序载入后停在开机状态,等待 `debug` 命令。
12
+ - `fcdev` 依赖调试 SDK `ember-debug-sdk`,安装时自动带上。
13
+ - 学习机目标(SB2000)的程序可以用 `fcdev run` 在 Ember 里运行:在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,程序会放进软盘镜像、开机后自动在 SB-DOS 里输入程序名运行;加 `--debug` 则停在开机状态,由 `debug` 命令继续。
14
+
15
+ ### 反汇编
16
+
17
+ - `fcdev disasm --trace` 改为读 Ember 记录的指令轨迹,不再读旧模拟器的轨迹。
18
+
19
+ ## 0.6.0(2026-11-15)
20
+
21
+ ### 安装
22
+
23
+ - cc65 工具链包改名为 `fcdev-cc65`,不再放在 `@rujianjs` 作用域下;`fcdev` 会自动安装它,使用者无须任何操作。
24
+
25
+ ### 模拟器与调试
26
+
27
+ - 不再提供模拟器包 `@rujianjs/fcdev-emulator`:`fcdev run` 与 `fcdev debug` 需要自备模拟器,用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定。
28
+
29
+ ## 0.5.0(2026-11-13)
30
+
31
+ ### 小霸王学习机 SB2000
32
+
33
+ - 新增直接操作硬件的函数:通用 DMA、图形端口(显存、调色板、精灵)和硬件定时器,程序不用再自己写寄存器。
34
+ - 新增硬件寄存器与位的符号,C 里以 `SB_HW_` 开头,汇编里以 `HW_` 开头。
35
+ - C 接口参考扩充到 204 个函数,用 `npx fcdev api dma`、`npx fcdev api ppu`、`npx fcdev api timer` 查询新增的三个模块。
36
+ - 硬件说明按真机实测更新:图形端口、DMA 和定时器的行为,并列出真机与模拟器仍有差异的读数。
37
+
38
+ ### 反汇编
39
+
40
+ - 识别地址表:`LDA 表,X` 加间接跳转、`PHA`/`RTS`、`JMP (地址)` 指向的表,表里的地址作为新入口继续追踪。
41
+
42
+ ### 模拟器与调试
43
+
44
+ - `fcdev debug` 的 `tape play`、`tape rec` 命令里的文件路径按终端当前目录解析。
45
+ - 模拟器包带上新版模拟器,改动见模拟器的更新记录。
46
+ - 命令的提示、错误说明和文档里的示例统一写成 `npx fcdev …`,终端里直接输入 `fcdev` 会找不到命令的原因也写进了使用说明。
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  npm install --save-dev fcdev
11
11
  ```
12
12
 
13
- 要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指定,调试命令要求该模拟器支持同样的调试服务。
13
+ 要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器 Ember 不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指向 Ember 的可执行文件。调试 SDK `ember-debug-sdk` 是 `fcdev` 的依赖,会自动安装。
14
14
 
15
15
  ## 使用
16
16
 
@@ -20,7 +20,7 @@ npm install --save-dev fcdev
20
20
  npx fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
21
21
  npx fcdev build src # 构建目录 src
22
22
  npx fcdev build src/a.c # 只构建这个文件,它自己是一个程序
23
- npx fcdev run src # 构建后在模拟器里运行
23
+ npx fcdev run src # 构建后在 Ember 里运行
24
24
  npx fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
25
25
  npx fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
26
26
  npx fcdev sync # 生成 IDE 的 C/C++ 配置
@@ -34,12 +34,12 @@ npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键
34
34
  ### 调试
35
35
 
36
36
  ```bash
37
- npx fcdev run --debug --port 5688 src # 以调试模式启动模拟器,只在收到 run 命令时运行
38
- FCDEV_DEBUG_PORT=5688 npx fcdev debug run 60
39
- FCDEV_DEBUG_PORT=5688 npx fcdev debug shot screen.png
37
+ npx fcdev run --debug --port 5688 src # 以调试模式启动 Ember,程序载入后停在开机状态
38
+ FCDEV_DEBUG_PORT=5688 npx fcdev debug call runtime.run frames=60 wait=true
39
+ FCDEV_DEBUG_PORT=5688 npx fcdev debug screenshot screen.png
40
40
  ```
41
41
 
42
- `debug` 把命令原样转发给模拟器的调试服务,命令表见模拟器的说明文档。调试端口默认 5699。
42
+ `debug` 把参数原样交给 Ember 调试 SDK 的终端客户端 `ember-debug`,`npx fcdev debug --help` 查看命令,`npx fcdev debug methods` 列出全部请求。调试端口默认 5699。学习机目标需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,`run` 会把程序放进软盘镜像、开机并在 SB-DOS 里输入程序名运行(加 `--debug` 停在开机状态)。
43
43
 
44
44
  ### 反汇编
45
45
 
@@ -49,7 +49,7 @@ npx fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:
49
49
  npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
50
50
  ```
51
51
 
52
- 用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(模拟器 `trace` 命令的日志)补充运行时才执行到的代码。
52
+ 用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(Ember 记录的指令轨迹)补充运行时才执行到的代码。
53
53
 
54
54
  ## 配置
55
55
 
@@ -65,7 +65,7 @@ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号
65
65
  | `include` | 空 | 额外的头文件目录 |
66
66
  | `toolchain` | 空 | 自备 cc65 的根目录,优先于工具链包 |
67
67
  | `firmware` | 无 | 固件(BIOS)文件;SB2000 运行时必填,fcdev 不提供任何 BIOS 或 ROM |
68
- | `emulator` | 空 | 模拟器的路径,不设时读环境变量 `FCDEV_EMULATOR` |
68
+ | `emulator` | 空 | Ember 的路径,不设时读环境变量 `FCDEV_EMULATOR` |
69
69
  | `targetOptions` | 空 | 目标专用选项,如 NES 的 `font`(是否链接 ASCII 字库,默认 `true`)、SB2000 的 `banks`(大程序的库页个数,默认 0) |
70
70
 
71
71
  ## 目标
@@ -1,6 +1,6 @@
1
1
  # 软件架构设计
2
2
 
3
- fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器需要自备。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
3
+ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器(Ember)需要自备。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
4
4
 
5
5
  本文说明包的划分、目录、分层规则和设计决策。各部分的细节见第 9 节列出的文档。
6
6
 
@@ -28,14 +28,14 @@ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境
28
28
  | D01 | 用 npm 包发布命令行、目标、模板与编译器 | 项目锁定版本;终端、CI 与 Copilot 都能构建,不依赖 VS Code |
29
29
  | D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包 `fcdev-cc65`;三个包都不带作用域,目录名与包名相同 | `npm create fcdev` 会自动运行 `create-fcdev`;工具链包只被主包依赖,使用者不直接输入名字 |
30
30
  | D03 | 命令行与库用 Node 22 的 ESM(`.mjs`)加 JSDoc,运行时无依赖,不需要构建步骤 | 发布内容就是源码,便于核对 |
31
- | D04 | 用 npm workspaces 管理多个包,发布的三个包同一个版本号,同步发布;主包对工具链包写精确版本;工作区里的 `ember-debug-sdk` 是 Ember 调试服务的客户端,版本独立,不属于这三个包 | 命令行、目标与编译器必须配套 |
31
+ | D04 | 用 npm workspaces 管理多个包,发布的四个包同一个版本号,同步发布;主包对工具链包与 `ember-debug-sdk` 都写精确版本,被依赖的包先发布;`ember-debug-sdk` 是 Ember 调试服务的客户端,`fcdev` 的 `debug` 与 `run --debug` 经它连接 Ember | 命令行、目标与编译器必须配套;使用者只需记一个版本号 |
32
32
  | D05 | 一种机型是一个“目标”,是主包内 `targets/<名>/` 一个目录;新增机型只加目录,不改构建流程 | 多机型扩展 |
33
33
  | D06 | 目标声明可选能力:磁盘镜像、模拟器运行;没有该能力的目标,对应命令明确报错 | NES 没有磁盘,学习机有 |
34
34
  | D07 | 构建由 `fcdev` 自己判断增量,不用 `make` | Windows 上不必另装 `make` |
35
35
  | D08 | 目标运行库在发布前用 `cc65`、`ca65`、`ar65` 编译成 `.lib` 随包发布(C 与汇编源码都可以,一个函数一个目标文件) | 目标文件格式与平台无关,使用者不必再编译库 |
36
36
  | D09 | 工具链是体积较大的二进制,放在独立的包里,主包用 `optionalDependencies` 引用 | 不适用的环境可以跳过安装,也不拖慢主包 |
37
37
  | D10 | 许可证分区,见第 7 节 | 各自保留原许可证,作为独立程序互不影响 |
38
- | D11 | cc65 与模拟器的源码放在仓库根目录的 `cc65/` 与 `virtuanes/`,由本仓库维护 | 以后在本仓库里直接修改与升级,来源仍可核对 |
38
+ | D11 | cc65 与模拟器 Ember 的源码放在仓库根目录的 `cc65/` 与 `ember/`,由本仓库维护;`virtuanes/` 是 `fcdev` 不再使用的旧模拟器,保留作学习机阶段的参考 | 以后在本仓库里直接修改与升级,来源仍可核对 |
39
39
  | D12 | 反汇编不改 `da65` 的 C 代码,用前端脚本生成它的信息文件 | 只有实测发现信息文件无法表达时才改,见 [06-反汇编](06-反汇编.md) |
40
40
 
41
41
  ## 3. 包与依赖
@@ -74,15 +74,16 @@ famiclone/
74
74
  create-fcdev/ 创建包
75
75
  bin/ src/ templates/ test/
76
76
  fcdev-cc65/ 工具链包
77
- ember-debug-sdk/ Ember 调试服务的 SDK(独立包,不随 fcdev 发布,说明见它的 README)
77
+ ember-debug-sdk/ Ember 调试服务的 SDK(fcdev 依赖它,随主包一同发布,说明见它的 README)
78
78
  cc65/ cc65 源码(删减版,本仓库维护)
79
- virtuanes/ 模拟器源码(VirtuaNES 调试版,本仓库维护)
79
+ ember/ 模拟器 Ember 的源码(本仓库维护,设计与调试服务见 ember/docs)
80
+ virtuanes/ 旧模拟器源码(VirtuaNES 调试版,fcdev 不再使用,保留作参考)
80
81
  vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
81
82
  tools/ 维护脚本,见第 8 节
82
83
  apps/ 应用程序与示例(apps/sb2000:SB-DOS 的 asm、edit、runnes、disk 与 examples 示例),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
83
84
  test/ 仓库级测试:目录结构、cc65 工具链包、SB2000 头文件
84
85
  machines/ 各机型的资料与工程(不属于 fcdev 包,不随包发布),一个机型一个目录,如 machines/sb2000
85
- build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是模拟器的编译输出
86
+ build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是旧模拟器的编译输出
86
87
  ```
87
88
 
88
89
  ## 5. 主包分层
@@ -98,7 +99,7 @@ famiclone/
98
99
  | `targets` | 目标注册表、程序名规则 | `shared` |
99
100
  | `toolchain` | 定位与调用 cc65 工具链 | `shared` |
100
101
  | `packagers` | 打包器:平铺映像、iNES、FAT12 软盘镜像 | `shared` |
101
- | `emulator` | 定位与启动模拟器、调试客户端 | `shared` |
102
+ | `emulator` | 定位与启动 Ember、定位调试 SDK 的终端客户端 | `shared` |
102
103
  | `disasm` | 反汇编前端 | `shared`、`toolchain` |
103
104
  | `build` | 构建计划、增量、调用工具链、打包 | `shared`、`config`、`targets`、`toolchain`、`packagers` |
104
105
  | `cli` | 参数解析与各命令 | `shared`、`config`、`targets`、`toolchain`、`build`、`emulator`、`disasm`、`api`、`docs` |
@@ -148,7 +149,7 @@ famiclone/
148
149
  | `build` | [02-命令行与构建](02-命令行与构建.md) | 命令、构建规则、配置文件、构建流程 |
149
150
  | `targets` | [03-目标规范](03-目标规范.md) | 目标定义、打包器、新增机型的步骤 |
150
151
  | `toolchain` | [04-cc65工具链](04-cc65工具链.md) | cc65 源码、构建与工具链包 |
151
- | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、模拟器定位、调试服务与命令表 |
152
+ | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、Ember 定位、调试服务与 debug 命令 |
152
153
  | `disasm` | [06-反汇编](06-反汇编.md) | 反汇编前端的流程与限制 |
153
154
  | `create` | [07-创建包与模板](07-创建包与模板.md) | 创建命令、模板与生成内容 |
154
155
  | `testing` | [08-测试与验证](08-测试与验证.md) | 测试分层、环境变量与运行方法 |
@@ -12,8 +12,8 @@
12
12
  | --- | --- |
13
13
  | `fcdev build [路径]` | 构建,规则见第 2 节 |
14
14
  | `fcdev disk [路径]` | 构建并把产物放进磁盘镜像;只有声明了磁盘能力的目标可用,镜像放在产物旁边,文件名与程序名相同,扩展名为 `.img`,卷标为 `FCDEV` |
15
- | `fcdev run [路径]` | 构建后在模拟器里运行 |
16
- | `fcdev debug <调试命令…>` | 把命令原样转发给模拟器的调试服务 |
15
+ | `fcdev run [路径]` | 构建后在 Ember 里运行 |
16
+ | `fcdev debug <参数…>` | 把参数原样交给 Ember 调试 SDK 的终端客户端 `ember-debug`(`call`、`screenshot`、`watch` 等) |
17
17
  | `fcdev disasm <文件>` | 反汇编,并回读校验 |
18
18
  | `fcdev sync` | 生成 IDE 配置,见第 6 节 |
19
19
  | `fcdev info [--json]` | 显示目标、工具链与头文件目录 |
@@ -25,13 +25,13 @@
25
25
  | 选项 | 说明 |
26
26
  | --- | --- |
27
27
  | `--target <名>` | 指定目标,覆盖 `fcdev.json` 里的 `target` |
28
- | `--debug` | `run` 以调试模式启动模拟器 |
28
+ | `--debug` | `run` 以调试模式启动 Ember |
29
29
  | `--port <端口>` | `run` 的调试端口,1 到 65535,默认 5699 |
30
30
  | `--json` | `info` 输出机器可读格式 |
31
31
  | `-h`、`--help` | 显示帮助 |
32
32
  | `-v`、`--version` | 显示版本 |
33
33
 
34
- `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [06-反汇编](06-反汇编.md)。`debug` 把命令名之后的全部参数原样交给调试服务,不再解析选项;它的端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
34
+ `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [06-反汇编](06-反汇编.md)。`debug` 把命令名之后的全部参数原样交给 `ember-debug`,不再解析选项;它按环境变量 `FCDEV_DEBUG_PORT`(默认 5699)找到 `run --debug` 启动的 Ember,细节见 [05-模拟器与调试](05-模拟器与调试.md)。
35
35
 
36
36
  ## 2. 构建单位
37
37
 
@@ -62,7 +62,7 @@
62
62
  | `include` | 字符串数组 | 空 | 额外头文件目录,相对项目根 |
63
63
  | `toolchain` | 字符串 | 空 | 自备 cc65 的根目录,优先于工具链包 |
64
64
  | `firmware` | 字符串 | 无 | 固件(BIOS、ROM)文件路径;目标的运行方案要求固件时必填 |
65
- | `emulator` | 字符串 | 空 | 模拟器可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
65
+ | `emulator` | 字符串 | 空 | Ember 可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
66
66
  | `targetOptions` | 对象 | 空 | 目标专用选项,由各目标定义并校验 |
67
67
 
68
68
  - 配置里出现未知项、类型不对、`define` 的值不是字符串或数字时,报错并列出可用的项。
@@ -57,10 +57,10 @@ targets/<名>/
57
57
 
58
58
  | 值 | 含义 |
59
59
  | --- | --- |
60
- | `rom` | 模拟器直接加载产物 |
61
- | `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,挂载磁盘镜像后复位 |
60
+ | `rom` | Ember 直接加载产物 |
61
+ | `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,把程序做成磁盘镜像挂到软驱并开机,再在 SB-DOS 里输入程序名运行(经 Ember 的调试服务,见 [05-模拟器与调试](05-模拟器与调试.md) 第 3 节);没有设置 `firmware` 时 `fcdev run` 报错 |
62
62
 
63
- `run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是按 `virtuanes` 的调试服务控制模拟器(模拟器程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
63
+ `run.emulator` 必须是字符串,标识要用的模拟器,目前写 `ember`,主包总是用 Ember 运行(Ember 程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。
64
64
 
65
65
  ### 2.3 多页(换页)程序
66
66
 
@@ -1,92 +1,99 @@
1
1
  # 模拟器与调试
2
2
 
3
- `fcdev` 的 `run`、`debug` 命令经调试服务控制模拟器。模拟器不随 npm 包提供,需要自备,并且要支持第 5 节的调试服务。本仓库的 `virtuanes/` 是实现了这套服务的 VirtuaNES 调试版源码,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序,由本仓库维护。模拟器的改动清单见 `virtuanes/README.md`,调试服务的命令表见第 5.1 节。
3
+ `fcdev` 的 `run`、`debug` 命令使用本仓库的模拟器 Ember。Ember 不随 npm 包提供,需要自备(见第 1 节);调试服务由 Ember 提供,`fcdev` 用调试 SDK(npm 包 `ember-debug-sdk`,是 `fcdev` 的依赖,随 `fcdev` 一起安装)与它通信。Ember 的设计与调试协议见仓库的 `ember/docs/`(第 04 篇是调试服务),SDK 的用法与全部请求见 `packages/ember-debug-sdk/README.md` 与它生成的协议参考。
4
4
 
5
- ## 1. 模拟器的获得
5
+ Ember 运行 NES 程序,也运行学习机整机(SB2000);学习机的启动方式见第 3 节与第 7 节。
6
6
 
7
- - `virtuanes/` 基于 Win32 与 DirectX,许可证 GPL-3.0-only,是 32 位程序,运行需要 32 位的 VC++ 运行库。
8
- - 编译需要 Visual Studio(含“使用 C++ 的桌面开发”),运行 `virtuanes/build.ps1 -Configuration Release`,输出在仓库根目录的 `build/virtuanes/Release/bin/VirtuaNES.exe`。编译前只结束调试实例(调试服务监听 `127.0.0.1` 端口的 `VirtuaNES.exe`);用户自己打开的模拟器不会被结束,它们占用输出文件时编译报错,需先自行关闭。
9
- - 模拟器运行时会在程序所在目录里写 `VirtuaNES.ini` 与 `save/`。
7
+ ## 1. Ember 的获得
10
8
 
11
- ## 2. 定位模拟器
9
+ - 在仓库的 `ember/` 目录运行 `npm run package`(Windows 用 `npm run package:win`),输出在 `ember/out/Ember-win32-x64/ember.exe`(构建与打包步骤见 `ember/docs/06-构建与模块登记.md`)。
10
+ - 把这个文件的路径交给 `fcdev`,见第 2 节。
11
+
12
+ ## 2. 定位 Ember
12
13
 
13
14
  按顺序查找,找到即停:
14
15
 
15
16
  1. 配置项 `emulator`。
16
17
  2. 环境变量 `FCDEV_EMULATOR`。
17
18
 
18
- 都没有设置时报“找不到模拟器”,指定的路径不存在时报“找不到模拟器:路径”。模拟器需要支持同样的调试服务才能用调试命令。
19
+ 都没有设置时报“找不到 Ember”,指定的路径不存在时报“找不到 Ember:路径”。`fcdev` 不去 `PATH` 里猜。
19
20
 
20
21
  ## 3. `fcdev run`
21
22
 
22
- 先构建,再按目标的运行方案启动模拟器。目标没有运行方案时报错。
23
+ 先确认目标能运行、能找到 Ember,再构建并启动 Ember。目标没有运行方案时报错。
23
24
 
24
25
  | 运行方案 | 做法 |
25
26
  | --- | --- |
26
- | `rom` | 模拟器直接加载产物,不需要固件;没有 `--debug` 时启动后立即返回 |
27
- | `firmware-disk` | 要求 `fcdev.json` 配置 `firmware`;构建并生成磁盘镜像,以调试模式启动模拟器,依次发 `disk <镜像>`、`reset`、`live`;等 DOS 启动后在提示符下输入程序名 |
27
+ | `rom` | Ember 直接加载产物(`.nes`),不需要固件 |
28
+ | `firmware-disk` | 学习机方案:加载 `fcdev.json` 里 `firmware` 指定的 BIOS,把程序放进磁盘镜像挂到软驱 0 并开机;没有设置 `firmware` 时在构建之前报“需要固件”,见下面与第 7 节 |
29
+
30
+ - 学习机(`firmware-disk`)没有命令行入口,不论是否带 `--debug` 都经调试服务启动(独立的用户数据目录与调试端口,同下一条):依次 `machines.setBios`(Ember 把 BIOS 复制进自己的 BIOS 目录)、`machines.boot`(上电、不运行)、`media.floppyInsert`(放入 `fcdev disk` 生成的镜像,程序名取镜像里的程序)。没有 `--debug` 时,再让机器运行到 SB-DOS 询问日期,回车跳过日期与时间,输入程序名并回车,随后 `runtime.resume`,命令行断开调试连接并返回,Ember 留在运行状态;有 `--debug` 时停在开机状态,程序还没有被运行,要在 SB-DOS 里输入程序名才运行。程序名只能用字母与数字,不合适时用 `fcdev.json` 的 `name` 改名。
28
31
 
29
- - `--debug` 时不发 `live`,模拟器停在调试服务,只在收到 `run` 命令时运行;`firmware-disk` 方案总是以调试模式启动,因为要用调试服务挂载镜像。
30
- - `--port` 指定调试端口,默认 5699。
31
- - 调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的模拟器;启动后最多等 30 秒,等到调试服务回应 `running=1`,超时则结束模拟器进程并报错。
32
- - 模拟器进程与命令行脱离,命令行退出后窗口保持打开,工作目录是模拟器所在目录(语言包按相对文件名加载)。
33
- - 非调试模式下沿用模拟器的单实例规则:已有普通模拟器窗口时,会把程序交给它打开。
32
+ - 没有 `--debug`:用 `--cartridge=<产物>` 启动 Ember,窗口打开并开始运行,命令行立即返回。用的是 Ember 平时的用户数据目录(首选项、键位映射等设置照常生效),遵守 Ember 的单实例规则,见第 6 节。
33
+ - 有 `--debug`:用独立的用户数据目录(系统临时目录下的 `fcdev-ember/<端口>`)、`--debug-port=<端口>` 与随机生成的令牌启动 Ember,不带 `--cartridge`;连上调试服务后用 `cartridges.load` 载入产物,上电但不运行(`powerOn` 为真、`resume` 为假);之后用 `fcdev debug` 继续。独立的用户数据目录让调试用的 Ember 能和平时在用的 Ember 同时运行,互不影响设置。
34
+ - `--port` 指定调试端口,默认 5699。调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的 Ember;启动后最多等 30 秒,等到调试服务可连接并成功载入程序,超时则结束 Ember 进程并报错;Ember 在就绪前退出时立即报错。
35
+ - Ember 进程与命令行脱离,命令行退出后窗口保持打开;工作目录是 Ember 所在目录。
36
+ - Ember 没有“退出”请求,调试结束后关闭它的窗口,或按 `run` 打印的进程号结束进程。
34
37
 
35
38
  ## 4. `fcdev debug`
36
39
 
37
40
  ```bash
38
- npx fcdev debug run 60
39
- npx fcdev debug shot screen.png
41
+ npx fcdev debug call runtime.status
42
+ npx fcdev debug call runtime.run frames=60 wait=true
43
+ npx fcdev debug screenshot screen.png
44
+ npx fcdev debug methods
40
45
  ```
41
46
 
42
- - 把命令原样转发给调试服务,打印应答;应答首行以 `OK` 开头时退出码为 0,否则为 1。
43
- - 端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
44
- - 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀、`tape play`、`tape rec` 的文件;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
45
- - `run`、`step` 的应答超时是 10 分钟,其余命令 30 秒。
47
+ - `debug` 之后的全部参数原样交给调试 SDK 的终端客户端 `ember-debug`(命令有 `endpoint`、`methods`、`describe`、`call`、`screenshot`、`watch`,选项见 `npx fcdev debug --help`),它的输出与退出码就是 `fcdev` 的输出与退出码(0 成功,1 失败,2 用法错误);`fcdev` 自己不解析调试命令。
48
+ - 找到 Ember:没有显式指定位置时,用环境变量 `FCDEV_DEBUG_PORT`(默认 5699)推出 `fcdev run --debug` 用的用户数据目录,读那里的端点文件取得地址与令牌。设置了环境变量 `EMBER_DEBUG_URL`、`EMBER_DEBUG_TOKEN`、`EMBER_DEBUG_ENDPOINT`、`EMBER_USER_DATA` 之一,或在命令里给了 `--url`、`--token`、`--endpoint-file`、`--user-data-dir`,就按显式指定的位置找,可以连到平时在用的 Ember。
49
+ - 命令的工作目录就是终端当前目录,`screenshot` 的相对路径相对终端当前目录;`call` 里的 `file` 参数(如 `inspector.traceStart` 的文件名)由 Ember 写进它的调试输出目录,调试模式下是用户数据目录里的 `debug-output`,结果里的 `file` 给出完整路径。
50
+ - 请求默认最多等 60 秒;`runtime.run` 带 `wait=true` 运行很多帧时用 `--timeout <毫秒>` 加长。
51
+ - 需要调试 SDK 已构建:本仓库里先运行 `npm run build -w packages/ember-debug-sdk`(需要 Ember 的 Schema 生成物,见 SDK 的说明);用 npm 安装的 `fcdev` 已自带构建好的 SDK。
52
+
53
+ ### 4.1 常用操作
54
+
55
+ | 要做的事 | 命令 |
56
+ | --- | --- |
57
+ | 看运行状态与卡带 | `call runtime.status` |
58
+ | 运行 N 帧并等运行结束 | `call runtime.run frames=N wait=true` |
59
+ | 单步 | `call runtime.step unit=instruction count=N`(`unit` 还有 `cycle`、`scanline`、`frame`) |
60
+ | 继续运行、暂停 | `call runtime.resume`、`call runtime.pause` |
61
+ | 复位 | `call runtime.reset kind=soft`(或 `hard`) |
62
+ | 看寄存器与芯片状态 | `call inspector.getState`、`call inspector.snapshot` |
63
+ | 读内存 | `call inspector.readMemory space=cpu address=0x8000 length=16 --out 文件`(数据是二进制,用 `--out` 保存;`call inspector.listSpaces` 列出全部空间) |
64
+ | 断点 | `call inspector.addBreakpoint kind=execute address=0x8000` |
65
+ | 截图 | `screenshot 文件.png` |
66
+ | 记录指令轨迹 | `call inspector.traceStart kind=instruction file=trace.txt`,运行后 `call inspector.traceStop id=<编号>`;文件用于 `fcdev disasm --trace` |
67
+ | 记录代码与数据标记 | `call inspector.cdlStart`,运行后 `call inspector.cdlSave file=prg.cdl` |
68
+ | 注入按键 | `call input.key code=KeyW down=true`(`code` 是 `KeyboardEvent.code`,由卡带的 mapper 脚本翻译)、`call input.pad port=0 buttons=1` |
69
+ | 订阅事件 | `watch runtime.* --timeout 5000` |
70
+
71
+ 全部请求、参数与错误码用 `fcdev debug methods` 与 `fcdev debug describe <请求>` 查看。
72
+
73
+ ## 5. 与旧模拟器的差异
74
+
75
+ `fcdev` 不再支持 VirtuaNES 调试版与它的文本命令协议(`run 60`、`shot`、`bp x`、`trace`、`cdl` 等),以下是行为上的变化:
46
76
 
47
- ## 5. 调试服务协议
77
+ - `fcdev debug` 的参数是 `ember-debug` 的命令,不再是旧的单行命令;旧命令里相对路径要换成绝对路径的处理也不再需要。
78
+ - `fcdev disasm --trace` 读 Ember 的指令轨迹(`kind=instruction`,每行是 nestest 日志的写法,行首是四位十六进制的指令地址),不再读旧模拟器行首为 `T` 的轨迹;`--cdl` 的格式不变(Mesen 的位定义)。
79
+ - 旧命令里 Ember 没有对应请求的:存档(`savestate`、`loadstate`,已登记在 Ember 的待办里)、磁带相关命令(磁带机还没有做);软驱的放入、取出、保存对应 `media.floppyInsert`、`media.floppyEject`、`media.floppySave`。
80
+ - 仓库里的 `virtuanes/` 保留作参考,`fcdev` 不再使用它;其中的调试服务协议见 `virtuanes/README.md`。
48
81
 
49
- - 模拟器只在设置了环境变量 `FCDEV_DEBUG_PORT` 时启动调试服务,只监听 `127.0.0.1`。
50
- - 一行一个命令;应答若干行文本,以单独的 `.` 行结束;应答首行以 `OK` 或 `ERR` 开头。一次只处理一条命令。
51
- - 客户端在 [src/emulator/debug-client.mjs](../src/emulator/debug-client.mjs):`DebugClient.connect` 连接(5 秒超时),`send` 发命令并等应答。
52
- - `fcdev` 只经这套协议与模拟器通信,协议保持稳定;以后把内核集成进 VS Code 时,只要协议不变,`fcdev` 不用改。
53
- - 命令表见下面的第 5.1 节。`live` 命令由 `fcdev` 新增:把模拟器切换为自由运行,供 `fcdev run` 把窗口交给用户操作。
82
+ ## 6. 限制
54
83
 
55
- ### 5.1 命令表
84
+ - 学习机的运行方式是自动在 SB-DOS 里输入程序名,靠固定的帧数等待 DOS 启动(约 2600 帧,调试服务里不限速、几秒完成);换了别的 BIOS 或磁盘时提示的出现时间不同,就会输错位置,这时用 `--debug` 启动,自己用 `fcdev debug` 操作。
85
+ - 不带 `--debug` 的 `fcdev run` 遵守 Ember 的单实例规则:平时用的 Ember 已经在运行时,新启动的进程只会把已有窗口提到前面,不会载入新程序;这时先关闭 Ember,或改用 `--debug`(独立的用户数据目录,不受影响)。学习机目标不受影响,它总是用独立的用户数据目录。
86
+ - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供(学习机目标必填;仓库里有一份 SB2000 的 BIOS:`reference/rom/SB2K_BIOS.NES`)。
56
87
 
57
- 直接发给服务的路径必须是绝对路径;数字默认按十六进制解析(地址、扫描码、寄存器),帧数、长度、次数按十进制。
88
+ ## 7. 学习机在 Ember 里的调试
58
89
 
59
- | 命令 | 说明 |
90
+ 学习机用 `--debug` 启动后,机器已开机、磁盘在软驱 0 里、没有运行,操作与 NES 相同,另有:
91
+
92
+ | 要做的事 | 命令 |
60
93
  | --- | --- |
61
- | `status` | 运行状态、寄存器与 bank 寄存器 |
62
- | `run <帧数>` | 运行指定帧数,遇到断点提前停止 |
63
- | `step <条数>` | 单步指定条数的指令 |
64
- | `bp x\|r\|w <地址> [结束地址]` | 添加执行、读、写断点;`bp list`、`bp del <编号\|all>` |
65
- | `regs [pc=.. a=.. x=.. y=.. s=.. p=..]` | 读取或修改寄存器 |
66
- | `read <空间> <地址> <长度>` | 读内存;空间为 `cpu`、`rom`、`pram`、`vram`、`cram`、`eram`、`wram`、`ram` |
67
- | `write <空间> <地址> <十六进制字节>` | 写内存 |
68
- | `resolve <地址>` | 把 CPU 地址解析为物理空间与偏移 |
69
- | `key <扫描码> <0\|1>`、`key clear` | 按下或松开键盘键(DirectInput 扫描码) |
70
- | `mouse move <dx> <dy>`、`mouse btn <掩码>` | 鼠标移动与按键 |
71
- | `shot <文件.png>` | 截图 |
72
- | `trace <文件> [最大行数] [unique]`、`trace off` | 记录每条指令与中断;加 `unique` 时每个 CPU 地址的指令、每个中断入口只记第一次,最大行数按实际写出的行数算(适合长时间运行后给 `fcdev disasm --trace` 用;只按 CPU 地址去重,换页后同一地址的其他代码会漏记) |
73
- | `io <文件> [最大行数] [w]`、`io off` | 记录 `$2000-$4FFF` 的读写;加 `w` 只记录写 |
74
- | `pad <0-3> <十六进制掩码>`、`pad <0-3> clear` | 注入手柄按键(A=01、B=02、Select=04、Start=08、上=10、下=20、左=40、右=80),与真实输入合并 |
75
- | `disklog <文件> [最大行数]`、`disklog off` | 记录软驱控制器读写的 LBA |
76
- | `calllog <文件> <pc> <地址:长度[,...]> [最大次数] [skip=地址=值[,...]]`、`calllog off` | 每次执行到 `pc` 就记录寄存器、栈顶与内存段;`skip` 表示该地址字节等于值(十六进制)时不记录;可添加多条,`off` 全部关闭 |
77
- | `cdl on\|off\|clear\|save <前缀>` | 代码数据标记,保存为 `<前缀>-rom.cdl`、`<前缀>-pram.cdl` |
78
- | `dialogs [clear]` | 列出调试期间被自动关闭的对话框(标题、文字、按下的按钮),`clear` 同时清空记录。调试服务启动后,模拟器自己弹出的消息框、文件框会被自动按下“确定”“取消”“否”“忽略”“关闭”中第一个存在的按钮,不会停在模态对话框上;文件对话框(打开、另存为,如虚拟打印机输出 PNG 时的“Save to...”)直接按“取消”,因为没有文件名时“确定”不起作用 |
79
- | `tape play <文件>`、`tape rec <文件>`、`tape stop`、`tape status` | 数据录音机(`.vtp`)的播放与录制;`rec` 的文件在 `stop` 后才完整(命令已实现,还没有用实际程序验证) |
80
- | `disk <镜像>`、`savedisk` | 挂载或保存软盘镜像 |
81
- | `fdc eject\|insert\|wp <0\|1>\|noindex <0\|1>\|seekfail <0\|1>\|dead <0\|1>\|bad <逻辑扇区...>\|clear\|status` | 软驱故障注入。`eject`、`insert` 取出、放回盘片(取出后控制器对 READ ID 报找不到地址标志);`wp` 写保护;`noindex` 没有索引脉冲(READ ID、读写、格式化命令一直不结束);`seekfail` 磁头卡住(SEEK、RECALIBRATE 不移动,已在 0 磁道时回 0 磁道仍成功);`dead` 控制器收到命令字节后不再处理;`bad` 指定的逻辑扇区(十进制)读时报数据校验错,写不受影响;`clear` 关闭全部故障、放回盘片并取消写保护;`status` 显示当前状态。`disk` 挂载新镜像时也会清掉全部故障 |
82
- | `audio fast\|real` | 声音播放速度:`fast` 时语音与 DAC(开机音乐、WAV)不再等声卡按真实时间播放,采样直接丢弃,模拟器内部时序不变;`real` 为默认的真实时间。开关是全局状态,复位后保持;验证工具只在开机阶段打开,开机完成后恢复 |
83
- | `reset`、`softreset`、`savestate <文件>`、`loadstate <文件>` | `reset` 是硬复位(回到 BIOS),`softreset` 只复位 CPU、手柄与 APU、保留映射器状态(游戏中的软复位);另有状态存取 |
84
- | `live` | 切换为自由运行:模拟器按正常速度连续运行,不再由 `run` 授权帧数;此后只建议使用 `key`、`pad`、`mouse`、`shot`、`quit`,读写内存与断点类命令与模拟线程并行,结果不可靠。`fcdev run` 用它把窗口交给用户操作 |
85
- | `quit` | 关闭模拟器 |
86
-
87
- ## 6. 对 `virtuanes/` 的约定
88
-
89
- - 改动处按文件头约定标明,改动清单写在 `virtuanes/README.md` 的“相对上游的改动”。
90
- - 调试模式(设置了 `FCDEV_DEBUG_PORT`)下,`WinMain.cpp` 不把命令行转交给已运行的实例,调试模式的模拟器可以与用户平时用的普通实例同时运行。
91
- - `WinMain.cpp` 含 Shift-JIS 编码的内容,不要用编辑工具整体改写。
92
- - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供。
94
+ | 在 SB-DOS 里敲键 | `call input.key code=KeyA down=true`,运行几帧后 `down=false`;回车是 `Enter`,不要连续几帧不运行就松开,BIOS 来不及读到 |
95
+ | 手柄、鼠标 | `call input.pad port=0 buttons=1`、`call input.mouse kind=move dx=10 dy=5`、`call input.mouse kind=down buttons=1` |
96
+ | 把软驱里被程序改写的盘片存回镜像文件 | `call media.floppySave drive=0` |
97
+ | 取出、重新放入盘片 | `call media.floppyEject drive=0`、`call media.floppyInsert drive=0 path=<镜像>` |
98
+
99
+ 运行库的测试(`test/sb2000-library.test.mjs`)就是这样用的,机制见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
@@ -27,7 +27,7 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
27
27
  | `--base <地址>` | 平铺二进制的加载地址,十六进制,可带 `$` 或 `0x`;平铺二进制必须给 |
28
28
  | `--entry <地址>` | 追踪代码的入口,可重复;iNES 自动使用中断向量 |
29
29
  | `--cdl <文件>` | CDL 文件,其中代码段的起点也当作入口 |
30
- | `--trace <文件>` | 模拟器 `trace` 命令记录的指令轨迹,执行过的指令地址都当作入口 |
30
+ | `--trace <文件>` | Ember 的 `inspector.traceStart`(`kind=instruction`)记录的指令轨迹,执行过的指令地址都当作入口 |
31
31
  | `--symbols <文件>` | 符号文件,给地址起名字 |
32
32
  | `--out <目录>` | 输出目录,默认 `build/disasm/<输入文件名>` |
33
33
 
@@ -57,7 +57,7 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
57
57
 
58
58
  ### 3.3 指令轨迹
59
59
 
60
- 模拟器 `trace` 命令的日志,每行以 `T` 开头,第二列是指令地址。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。
60
+ Ember 的 `inspector.traceStart`(`kind=instruction`)记录的日志:每行是 nestest 日志的写法,行首是四位大写十六进制的指令地址,后面跟指令字节(如 `C000 4C F5 C5 JMP $C5F5 ...`)。`io`、`irq` 与调用记录的行不是指令行,一律忽略;旧模拟器行首为 `T` 的轨迹不再识别。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。生成方法:`npx fcdev debug call inspector.traceStart kind=instruction file=trace.txt`,运行一段时间后 `npx fcdev debug call inspector.traceStop id=<编号>`,结果里的 `file` 是完整路径(文件写在 Ember 的调试输出目录)。
61
61
 
62
62
  ### 3.4 符号文件
63
63
 
@@ -101,7 +101,7 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
101
101
 
102
102
  - iNES 只支持 NROM。
103
103
  - 只识别上述几种写法的地址表;用立即数拼出地址再存进指针的跳转、调用方自己写进工作区的分发、直接访问表项的对象表都追不到,也不把数据识别成字符串,未追到的字节都是 `ByteTable`。
104
- - 模拟器自带的 CDL 只对 SB2K 映射器有效。
104
+ - 旧模拟器(VirtuaNES)自带的 CDL 只对 SB2K 映射器有效。
105
105
  - SB2000 固件页的 CDL 验证没有做。
106
106
  - `da65` 输出的源码是 CRLF 换行。
107
107
 
@@ -23,10 +23,10 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
23
23
  | 变量 | 作用 |
24
24
  | --- | --- |
25
25
  | `FCDEV_CC65_HOME` | 指向自备的 cc65 目录;没有工具链包时用它跑集成测试 |
26
- | `FCDEV_EMULATOR` | 指向自备的模拟器 |
27
- | `FCDEV_TEST_FIRMWARE` | 指向 SB2000 的 BIOS 文件(仓库里有一份:`machines/sb2000/reference/rom/SB2K_BIOS.NES`);设置后额外运行“SB2000 程序在模拟器里运行”的用例 |
26
+ | `FCDEV_EMULATOR` | 指向 Ember 的可执行文件(如 `ember/out/Ember-win32-x64/ember.exe`);设置后额外运行“真实 Ember”的用例(还需要 cc65 与已构建的调试 SDK) |
27
+ | `FCDEV_TEST_FIRMWARE` | 指向 SB2000 的 BIOS 文件,用于“SB2000 程序在 Ember 里运行”的用例;没有设置时用仓库里的 `reference/rom/SB2K_BIOS.NES` |
28
28
  | `FCDEV_TEST_NES_ROM` | 指向一个 NROM 的 `.nes` 文件;设置后额外对它做完整反汇编与回读 |
29
- | `FCDEV_SKIP_GUI_TESTS` | 设为 `1` 时跳过会打开模拟器窗口的用例 |
29
+ | `FCDEV_SKIP_GUI_TESTS` | 设为 `1` 时跳过会打开 Ember 窗口的用例 |
30
30
 
31
31
  ## 3. 测试分层
32
32
 
@@ -35,7 +35,7 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
35
35
  | 单元测试 | `args-parser`、`config`、`build-helpers`、`targets-packagers`、`fat12-image` | 参数解析、配置查找与未知项报错、源文件收集、依赖文件解析、工具参数、目标字段校验、程序名规则、各打包器、FAT12 镜像 |
36
36
  | 命令行与构建 | `cli`、`build`、`toolchain` | 帮助、版本、错误输出与退出码、`build`、`info`、`sync`;构建计划的路径规则;增量与错误提示;工具链定位的优先级与不完整报错 |
37
37
  | 目标 | `sb2000`(主包) | 构建 C 与汇编程序,文件头、大小与内存布局,运行库一个函数一个目标文件、链接只带用到的函数,多页程序的文件页序、库页不够与超过上限的提示,`disk` 命令,缺少固件的提示 |
38
- | 模拟器 | `emulator`、`sb2000`、`sb2000-library` | 调试客户端的应答解析与超时、模拟器定位、端口检查、`debug` 命令的路径换算;真实模拟器里运行 NES 程序并截图;设置固件后运行 SB2000 程序,以及运行库每个模块的测试程序(约 15 个用例,共数百项检查,文件与磁盘类用例把镜像读回核对;换页的用例覆盖 9 个库页与上限 113 个库页),见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节 |
38
+ | 模拟器 | `emulator`、`sb2000`、`sb2000-library` | Ember 定位、端口检查、调试用户数据目录与环境变量、学习机程序名的按键、`run` 对学习机目标没有固件时报错、找不到 Ember 时报错、`debug` 把参数交给 `ember-debug`(需要调试 SDK 已构建);真实 Ember 里调试模式载入 NES 程序、运行 60 帧、截图,并用 `debug` 命令连到同一个 Ember。SB2000 运行库的测试程序(约 15 个用例,共数百项检查)在 `sb2000-library`,经 Ember 的调试服务运行整机(需要 Ember、cc65、已构建的调试 SDK 与 BIOS,缺一就整组跳过),见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节 |
39
39
  | 反汇编 | `disasm` | 映像读取、CDL 与轨迹解析、静态追踪、信息文件、回读校验;对 `fcdev` 自己构建的 NES 与 SB2000 程序做完整反汇编;设置 `FCDEV_TEST_NES_ROM` 时对真实游戏做反汇编 |
40
40
  | 创建包 | `create`(`create-fcdev`) | 参数解析、模板列表、项目生成、目录检查、交互选择、安装流程;四个模板都能用 `fcdev` 构建 |
41
41
  | 接口文档 | `api-command`(主包)、`sb2000-api`(仓库) | `fcdev api` 命令的各种查询与错误提示、头文件文档注释的解析、系统调用标签的匹配;SB2000 接口检查(函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因);入库的 `api-reference.md` 与头文件生成的结果一致 |
@@ -46,10 +46,12 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
46
46
 
47
47
  ## 4. 模拟器验证
48
48
 
49
- - NES hello 与 SB2000 的 C、汇编 hello 在模拟器里运行,用调试服务的 `shot` 命令截图,核对屏幕文字:NES 显示 `HELLO, NES!`,SB2000 显示 `Hello, SB2000!` 与“你好,小霸王!”并能返回 DOS。
49
+ - NES hello 在 Ember 里运行:`emulator` 测试的真实 Ember 用例把程序载入调试模式的 Ember,运行 60 帧后用 `output.screenshot` 与 `fcdev debug screenshot` 截图并核对 PNG 文件头。
50
+ - SB2000 的 C、汇编 hello 曾在旧模拟器里运行并截图核对屏幕文字(显示 `Hello, SB2000!` 与“你好,小霸王!”并能返回 DOS),这部分用例已删除;现在由 `sb2000-library` 的文字输出、显示等用例在 Ember 里覆盖运行与屏幕显示,没有单独核对 hello 的屏幕文字。
51
+ - `fcdev run` 在 Ember 里运行学习机程序的完整流程(构建、打包镜像、添加固件、开机、输入程序名、运行)已用 `apps/sb2000/hwtest` 实际运行并截图核对,没有做成自动测试用例。
50
52
  - SB2000 的程序运行环境验证(V01 到 V10)的结论见 [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) 第 9 节。
51
53
  - 运行库测试程序的停靠点用写断点实现(对全局变量 `sb_test_stop` 设断点),不对函数入口设执行断点,原因见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
52
- - 用调试服务验证时一律显式指定端口,避免连到别的模拟器;只结束本仓库启动的模拟器进程。
54
+ - 用调试服务验证时一律显式指定端口,避免连到别的 Ember;只结束本仓库启动的 Ember 进程。
53
55
 
54
56
  ## 5. 反汇编验证
55
57
 
@@ -59,14 +61,15 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
59
61
 
60
62
  `npm run release:verify`(`tools/verify-install.mjs`):
61
63
 
62
- 1. 把三个包用 `npm pack` 打成 `.tgz`。
64
+ 1. 把四个包用 `npm pack` 打成 `.tgz`。
63
65
  2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
64
- 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与工具链包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
65
- 4. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
66
+ 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev`、工具链包与调试 SDK(`fcdev` 依赖它们,不访问 npm 仓库时要一并给出),运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
67
+ 4. 调试 SDK 单独装进临时目录,确认 `ember-debug-sdk` 与 `ember-debug-sdk/node` 两个入口能加载,`dist/cli.js`、`dist/mcp.js` 在。
68
+ 5. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
66
69
 
67
70
  只验证构建,不启动模拟器。
68
71
 
69
72
  ## 7. 注意事项
70
73
 
71
- - 带真实模拟器的用例运行后会在模拟器所在目录里生成 `VirtuaNES.ini` 与 `save/`,不用删。
74
+ - 真实 Ember 的用例用系统临时目录下的 `fcdev-ember/<端口>` 做用户数据目录,结束时按进程号结束自己启动的 Ember 并删除该目录,不碰平时在用的 Ember。
72
75
  - 没有目测的界面输出,汇报时写明。
@@ -1,16 +1,18 @@
1
1
  # 发布
2
2
 
3
- 本文说明三个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
3
+ 本文说明四个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
4
4
 
5
5
  ## 1. 包与版本
6
6
 
7
7
  | 包 | 说明 |
8
8
  | --- | --- |
9
9
  | `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
- | `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies` |
10
+ | `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies`,对 `ember-debug-sdk` 写精确版本的 `dependencies` |
11
11
  | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
12
+ | `ember-debug-sdk` | Ember 调试服务的客户端 SDK(含终端客户端与 MCP 服务),目录 `packages/ember-debug-sdk`;`fcdev` 的 `debug` 命令与 `run --debug` 经它连接 Ember,所以 `fcdev` 依赖它 |
12
13
 
13
- - 三个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包的依赖版本必须与之相同。工作区里的 `packages/ember-debug-sdk`(`ember-debug-sdk`)不在这三个包之列,版本独立,不由本文的发布脚本发布。
14
+ - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包与 `ember-debug-sdk` 的依赖版本必须与之相同(`node tools/release.mjs prepare` 会一并改)。
15
+ - `ember-debug-sdk` 的 `dist` 不入库,`npm pack` 与 `npm publish` 前会由它的 `prepack` 自动构建;发布脚本还会先运行它的 `check`(生成接口类型、类型检查、oxlint、构建、测试)。
14
16
  - `release-check` 会检查工具链包的包名是否在 `fcdev` 的 `optionalDependencies` 里。
15
17
  - 工具链包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs`。
16
18
  - 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
@@ -20,28 +22,30 @@
20
22
  1. 所有改动已提交。
21
23
  2. 工具链包已构建:`node tools/build-cc65.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
22
24
  3. `npm run release:check` 通过。
23
- 4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(三个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
25
+ 4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(`fcdev`、`create-fcdev`、`fcdev-cc65` 共用一份,SDK 没有单独的更新记录,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展有自己的 `CHANGELOG.md`(`vscode/`),版本号独立,有改动才升;Ember 没有随这些包发布。
24
26
 
25
27
  ## 3. 检查
26
28
 
27
29
  `npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
28
30
 
29
- - 三个包的版本一致,都写了 `license`,`fcdev` 对工具链包的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里,作用域包声明了公开发布。
31
+ - 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与 `ember-debug-sdk` 的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里。
30
32
  - `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
31
33
  - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
32
34
  - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
33
35
  - 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
36
+ - `ember-debug-sdk` 已构建(`dist` 存在),发布内容含两个入口、命令行入口与类型声明。
34
37
  - 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
35
38
 
36
39
  `npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
37
40
 
38
41
  ## 4. 发布顺序
39
42
 
40
- 先发工具链包,再发 `fcdev`,最后发 `create-fcdev`:
43
+ 先发被依赖的工具链包与调试 SDK,再发 `fcdev`,最后发 `create-fcdev`:
41
44
 
42
45
  1. `fcdev-cc65`
43
- 2. `fcdev`
44
- 3. `create-fcdev`
46
+ 2. `ember-debug-sdk`
47
+ 3. `fcdev`
48
+ 4. `create-fcdev`
45
49
 
46
50
  `npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
47
51
 
@@ -54,6 +58,7 @@
54
58
  | `fcdev` | 71 | 64 kB |
55
59
  | `create-fcdev` | 23 | 15 kB |
56
60
  | `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
61
+ | `ember-debug-sdk` | 30 | 88 kB |
57
62
 
58
63
  体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
59
64
 
@@ -63,8 +68,8 @@
63
68
 
64
69
  | 命令 | 作用 |
65
70
  | --- | --- |
66
- | `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version`、主包对工具链包的精确依赖,重新构建工具链包并生成它的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
67
- | `npm run release:publish -- --dry-run` | 演练:跑全部测试、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
68
- | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、三个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,发布后不再用 `npm view` 核对(新发布的包要等 npm 审核,马上查不到)。验证码由 npm 在终端里询问 |
71
+ | `npm run release:prepare -- <版本号>` | 升版本号:改主包、创建包与 SDK 的 `version`、主包对工具链包的精确依赖,重新构建工具链包并生成它的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
72
+ | `npm run release:publish -- --dry-run` | 演练:跑全部测试、SDK 的 `check`、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
73
+ | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、四个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,发布后不再用 `npm view` 核对(新发布的包要等 npm 审核,马上查不到)。验证码由 npm 在终端里询问 |
69
74
 
70
75
  两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。