fcdev 0.4.0 → 0.6.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 (66) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +26 -24
  3. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +14 -17
  4. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +4 -2
  5. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +1 -1
  6. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +2 -2
  7. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +12 -20
  8. package/docs/06-/345/217/215/346/261/207/347/274/226.md +9 -4
  9. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +3 -3
  10. package/docs/09-/345/217/221/345/270/203.md +20 -25
  11. package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
  12. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +15 -8
  13. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +7 -7
  14. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +17 -8
  15. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +3 -1
  16. package/package.json +3 -3
  17. package/src/cli/commands/api-command.mjs +2 -2
  18. package/src/cli/commands/build-command.mjs +1 -1
  19. package/src/cli/commands/debug-command.mjs +5 -2
  20. package/src/cli/commands/disasm-command.mjs +1 -1
  21. package/src/cli/commands/disk-command.mjs +1 -1
  22. package/src/cli/commands/docs-command.mjs +3 -3
  23. package/src/cli/commands/run-command.mjs +2 -2
  24. package/src/disasm/address-tables.mjs +161 -0
  25. package/src/disasm/analysis.mjs +17 -11
  26. package/src/disasm/byte-kinds.mjs +20 -0
  27. package/src/disasm/disassembler.mjs +3 -2
  28. package/src/disasm/info-writer.mjs +3 -3
  29. package/src/docs/doc-topics.mjs +2 -2
  30. package/src/emulator/debug-client.mjs +1 -1
  31. package/src/emulator/emulator-locator.mjs +4 -18
  32. package/src/emulator/index.mjs +1 -1
  33. package/src/toolchain/toolchain-locator.mjs +2 -2
  34. package/targets/nes/lib/fcnes.lib +0 -0
  35. package/targets/nes/lib/nes-font.o +0 -0
  36. package/targets/sb2000/api-reference.md +310 -1
  37. package/targets/sb2000/asminc/sb2000.inc +90 -1
  38. package/targets/sb2000/include/sb2000-dma.h +46 -0
  39. package/targets/sb2000/include/sb2000-ppu.h +106 -0
  40. package/targets/sb2000/include/sb2000-symbols.h +170 -0
  41. package/targets/sb2000/include/sb2000-timer.h +54 -0
  42. package/targets/sb2000/include/sb2000.h +3 -0
  43. package/targets/sb2000/lib/crt0.o +0 -0
  44. package/targets/sb2000/lib/sb2000.lib +0 -0
  45. package/targets/sb2000/src/lib/dma/sb-dma-page-address.c +16 -0
  46. package/targets/sb2000/src/lib/dma/sb-dma-to-cpu.c +19 -0
  47. package/targets/sb2000/src/lib/dma/sb-dma-to-vram.c +16 -0
  48. package/targets/sb2000/src/lib/dma/sbi-dma-run.c +34 -0
  49. package/targets/sb2000/src/lib/ppu/sb-ppu-address.c +20 -0
  50. package/targets/sb2000/src/lib/ppu/sb-ppu-fill.c +19 -0
  51. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-clear.c +21 -0
  52. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-put.c +20 -0
  53. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-get.c +16 -0
  54. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-set.c +16 -0
  55. package/targets/sb2000/src/lib/ppu/sb-ppu-peek.c +22 -0
  56. package/targets/sb2000/src/lib/ppu/sb-ppu-read.c +20 -0
  57. package/targets/sb2000/src/lib/ppu/sb-ppu-render.c +20 -0
  58. package/targets/sb2000/src/lib/ppu/sb-ppu-wait-vblank.c +25 -0
  59. package/targets/sb2000/src/lib/ppu/sb-ppu-write.c +21 -0
  60. package/targets/sb2000/src/lib/sb-internal.h +3 -0
  61. package/targets/sb2000/src/lib/timer/sb-timer-current.c +16 -0
  62. package/targets/sb2000/src/lib/timer/sb-timer-mask.c +16 -0
  63. package/targets/sb2000/src/lib/timer/sb-timer-pending.c +16 -0
  64. package/targets/sb2000/src/lib/timer/sb-timer-start.c +17 -0
  65. package/targets/sb2000/src/lib/timer/sb-timer-stop.c +16 -0
  66. package/targets/sb2000/src/lib/timer/sb-timer-unmask.c +16 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,32 @@
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` 会找不到命令的原因也写进了使用说明。
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # fcdev
2
2
 
3
- 6502 兼容机(NES、小霸王学习机等)的开发工具:用 cc65 把 C 或 ca65 汇编构建成机型对应的程序,带调试用模拟器,并能把已有程序反汇编回 ca65 源码。首批支持 NES 与小霸王学习机 SB2000,更多机型按“目标”扩展。
3
+ 6502 兼容机(NES、小霸王学习机等)的开发工具:用 cc65 把 C 或 ca65 汇编构建成机型对应的程序,可在模拟器里运行与调试,并能把已有程序反汇编回 ca65 源码。首批支持 NES 与小霸王学习机 SB2000,更多机型按“目标”扩展。
4
4
 
5
5
  通常不需要手动安装:用 `npm create fcdev@latest` 创建项目时会自动装好。
6
6
 
@@ -10,21 +10,23 @@
10
10
  npm install --save-dev fcdev
11
11
  ```
12
12
 
13
- 要求 Node.js 22 及以上。cc65 编译器与模拟器分别在 `@rujianjs/fcdev-cc65`、`@rujianjs/fcdev-emulator` 两个依赖包里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录,用 `FCDEV_EMULATOR` 指向自备的模拟器,但调试命令需要该模拟器支持同样的调试服务。
13
+ 要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指定,调试命令要求该模拟器支持同样的调试服务。
14
14
 
15
15
  ## 使用
16
16
 
17
+ `fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里直接输入 `fcdev` 会提示找不到命令,要写成 `npx fcdev …`。`package.json` 的 `scripts` 里可以直接写 `fcdev …`,用 `npm run <脚本>` 运行。想直接输入 `fcdev`,可以全局安装:`npm install -g fcdev`。
18
+
17
19
  ```bash
18
- fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
19
- fcdev build src # 构建目录 src
20
- fcdev build src/a.c # 只构建这个文件,它自己是一个程序
21
- fcdev run src # 构建后在模拟器里运行
22
- fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
23
- fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
24
- fcdev sync # 生成 IDE 的 C/C++ 配置
25
- fcdev info --json # 显示目标、工具链与头文件目录
26
- fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
27
- fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
20
+ npx fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
21
+ npx fcdev build src # 构建目录 src
22
+ npx fcdev build src/a.c # 只构建这个文件,它自己是一个程序
23
+ npx fcdev run src # 构建后在模拟器里运行
24
+ npx fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
25
+ npx fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
26
+ npx fcdev sync # 生成 IDE 的 C/C++ 配置
27
+ npx fcdev info --json # 显示目标、工具链与头文件目录
28
+ npx fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
29
+ npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
28
30
  ```
29
31
 
30
32
  入口是 `main`(汇编程序写 `.export _main`)。产物放在项目根的 `build/<目标>/`,中间文件在 `build/obj/`。
@@ -32,9 +34,9 @@ fcdev docs syscall # 查开发文档的本机路径(主题名或关键词
32
34
  ### 调试
33
35
 
34
36
  ```bash
35
- fcdev run --debug --port 5688 src # 以调试模式启动模拟器,只在收到 run 命令时运行
36
- FCDEV_DEBUG_PORT=5688 fcdev debug run 60
37
- FCDEV_DEBUG_PORT=5688 fcdev debug shot screen.png
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
38
40
  ```
39
41
 
40
42
  `debug` 把命令原样转发给模拟器的调试服务,命令表见模拟器的说明文档。调试端口默认 5699。
@@ -42,9 +44,9 @@ FCDEV_DEBUG_PORT=5688 fcdev debug shot screen.png
42
44
  ### 反汇编
43
45
 
44
46
  ```bash
45
- fcdev disasm game.nes # NES(NROM),入口取自中断向量
46
- fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:加载地址与入口
47
- fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
47
+ npx fcdev disasm game.nes # NES(NROM),入口取自中断向量
48
+ npx fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:加载地址与入口
49
+ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
48
50
  ```
49
51
 
50
52
  用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(模拟器 `trace` 命令的日志)补充运行时才执行到的代码。
@@ -63,7 +65,7 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
63
65
  | `include` | 空 | 额外的头文件目录 |
64
66
  | `toolchain` | 空 | 自备 cc65 的根目录,优先于工具链包 |
65
67
  | `firmware` | 无 | 固件(BIOS)文件;SB2000 运行时必填,fcdev 不提供任何 BIOS 或 ROM |
66
- | `emulator` | 空 | 自备模拟器的路径,优先于模拟器包 |
68
+ | `emulator` | 空 | 模拟器的路径,不设时读环境变量 `FCDEV_EMULATOR` |
67
69
  | `targetOptions` | 空 | 目标专用选项,如 NES 的 `font`(是否链接 ASCII 字库,默认 `true`)、SB2000 的 `banks`(大程序的库页个数,默认 0) |
68
70
 
69
71
  ## 目标
@@ -71,11 +73,11 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
71
73
  | 目标 | 产物 | 头文件 | 说明 |
72
74
  | --- | --- | --- | --- |
73
75
  | `nes` | `.nes` | `nes.h`(cc65)、`fcnes.h` | NROM,16K PRG 加 8K CHR;`fcnes.h` 提供调色板、文字显示与等待垂直消隐 |
74
- | `sb2000` | `.EXE` | `sb2000.h` | 程序从 `$8000` 起装入,默认最大 16K,设 `targetOptions.banks` 后可换页做到约 468K;C 栈在窗口顶端;运行库把 DOS 的系统调用封装成 180 多个 C 函数(文字、键盘手柄鼠标、文件目录、软驱、显示、声音、数学、打印机、输入法等),用 `fcdev api` 查询,整本文档见 `targets/sb2000/api-reference.md` |
76
+ | `sb2000` | `.EXE` | `sb2000.h` | 程序从 `$8000` 起装入,默认最大 16K,设 `targetOptions.banks` 后可换页做到约 468K;C 栈在窗口顶端;运行库把 DOS 的系统调用和硬件寄存器封装成 200 多个 C 函数(文字、键盘手柄鼠标、文件目录、软驱、显示、声音、数学、打印机、输入法,以及 DMA、图形端口、定时器等硬件操作),用 `fcdev api` 查询,整本文档见 `targets/sb2000/api-reference.md` |
75
77
 
76
78
  ## 文档
77
79
 
78
- 完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `fcdev docs` 列出全部主题,`fcdev docs <主题>` 给出该文档的本机路径。
80
+ 完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
79
81
 
80
82
  | 想做什么 | 主题 | 文档 |
81
83
  | --- | --- | --- |
@@ -84,7 +86,7 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
84
86
  | 开发 SB2000(SB-DOS)程序 | `sb2000` | `docs/sb2000/01-开发指南.md` |
85
87
  | 查 SB-DOS 系统调用与出错码 | `syscall` | `docs/sb2000/02-系统调用手册.md` |
86
88
  | 查 SB2000 的硬件行为 | `hardware` | `docs/sb2000/03-硬件说明.md` |
87
- | 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `fcdev api` 查询) |
89
+ | 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `npx fcdev api` 查询) |
88
90
  | 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/05-模拟器与调试.md` |
89
91
  | 反汇编已有程序 | `disasm` | `docs/06-反汇编.md` |
90
92
  | 创建项目与模板 | `create` | `docs/07-创建包与模板.md` |
@@ -92,10 +94,10 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
92
94
 
93
95
  ## 限制
94
96
 
95
- - 反汇编目前只支持 NROM 与平铺二进制;静态追踪追不到 RTS 跳转表等间接调用的代码,这部分按数据输出,回读仍然一致。
97
+ - 反汇编目前只支持 NROM 与平铺二进制;静态追踪只追到经地址表分发的间接跳转,其他间接调用的代码按数据输出,回读仍然一致。
96
98
  - SB2000 程序的退出码被忽略,`main` 返回后总是回到 DOS。
97
99
  - `run` 在非调试模式下沿用模拟器的单实例规则:已有普通的模拟器窗口时,会把程序交给它打开。
98
100
 
99
101
  ## 许可证
100
102
 
101
- Apache-2.0。cc65 部分为 zlib 许可,模拟器为 GPL-3.0,各自随工具链包与模拟器包附带许可文件。
103
+ Apache-2.0。cc65 部分为 zlib 许可,随工具链包附带许可文件。
@@ -1,6 +1,6 @@
1
1
  # 软件架构设计
2
2
 
3
- fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板、调试用模拟器和反汇编前端。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
3
+ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器需要自备。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
4
4
 
5
5
  本文说明包的划分、目录、分层规则和设计决策。各部分的细节见第 9 节列出的文档。
6
6
 
@@ -8,7 +8,7 @@ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境
8
8
 
9
9
  范围内:
10
10
 
11
- - 命令行构建工具、目标定义、cc65 工具链包、调试模拟器包、创建包与模板、反汇编前端。
11
+ - 命令行构建工具、目标定义、cc65 工具链包、创建包与模板、反汇编前端。
12
12
  - 首批目标:NES、SB2000;其他机型按 [03-目标规范](03-目标规范.md) 加入。
13
13
  - VS Code 扩展的智能感知与语法高亮:见 [10-VS Code扩展](10-VS%20Code扩展.md)。
14
14
 
@@ -25,15 +25,15 @@ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境
25
25
 
26
26
  | 编号 | 决策 | 原因 |
27
27
  | --- | --- | --- |
28
- | D01 | 用 npm 包发布命令行、目标、模板、编译器与模拟器 | 项目锁定版本;终端、CI 与 Copilot 都能构建,不依赖 VS Code |
29
- | D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包 `@rujianjs/fcdev-cc65`,模拟器包 `@rujianjs/fcdev-emulator`;主包与创建包不带作用域,工具链包与模拟器包放进 `@rujianjs` 作用域,目录名是 `fcdev-cc65`、`fcdev-emulator` | `npm create fcdev` 会自动运行 `create-fcdev`;不带作用域的包名发布时被 npm 的垃圾包名检测拦截(403);这两个包只被主包依赖,使用者不直接输入名字,带作用域没有影响;作用域包要在 `package.json` 里写 `publishConfig.access` 为 `public` |
28
+ | D01 | 用 npm 包发布命令行、目标、模板与编译器 | 项目锁定版本;终端、CI 与 Copilot 都能构建,不依赖 VS Code |
29
+ | D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包 `fcdev-cc65`;三个包都不带作用域,目录名与包名相同 | `npm create fcdev` 会自动运行 `create-fcdev`;工具链包只被主包依赖,使用者不直接输入名字 |
30
30
  | D03 | 命令行与库用 Node 22 的 ESM(`.mjs`)加 JSDoc,运行时无依赖,不需要构建步骤 | 发布内容就是源码,便于核对 |
31
- | D04 | 用 npm workspaces 管理多个包,所有包同一个版本号,同步发布;主包对工具链包与模拟器包写精确版本 | 命令行、目标、编译器与模拟器必须配套 |
31
+ | D04 | 用 npm workspaces 管理多个包,发布的三个包同一个版本号,同步发布;主包对工具链包写精确版本;工作区里的 `ember-debug-sdk` 是 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
- | D09 | 工具链与模拟器是体积较大的二进制,各放在独立的包里,主包用 `optionalDependencies` 引用 | 不适用的环境可以跳过安装,也不拖慢主包 |
36
+ | D09 | 工具链是体积较大的二进制,放在独立的包里,主包用 `optionalDependencies` 引用 | 不适用的环境可以跳过安装,也不拖慢主包 |
37
37
  | D10 | 许可证分区,见第 7 节 | 各自保留原许可证,作为独立程序互不影响 |
38
38
  | D11 | cc65 与模拟器的源码放在仓库根目录的 `cc65/` 与 `virtuanes/`,由本仓库维护 | 以后在本仓库里直接修改与升级,来源仍可核对 |
39
39
  | D12 | 反汇编不改 `da65` 的 C 代码,用前端脚本生成它的信息文件 | 只有实测发现信息文件无法表达时才改,见 [06-反汇编](06-反汇编.md) |
@@ -45,7 +45,6 @@ flowchart LR
45
45
  CREATE[create-fcdev] -->|生成的项目依赖| CLI[fcdev 主包]
46
46
  CLI --> TG[内置目标: nes、sb2000]
47
47
  CLI -->|optionalDependencies| TC[fcdev-cc65 工具链包]
48
- CLI -->|optionalDependencies| EM[fcdev-emulator 模拟器包]
49
48
  EXT[VS Code 扩展] -.->|调用命令行| CLI
50
49
  ```
51
50
 
@@ -53,8 +52,7 @@ flowchart LR
53
52
  | --- | --- | --- |
54
53
  | `fcdev` | 命令行、构建核心、内置目标、反汇编前端 | 是 |
55
54
  | `create-fcdev` | 创建项目的命令与四个模板 | 是 |
56
- | `@rujianjs/fcdev-cc65` | cc65、ca65、ld65、ar65、da65,头文件、库与链接配置 | 只入库 `package.json`,其余由脚本生成 |
57
- | `@rujianjs/fcdev-emulator` | 调试用模拟器可执行文件 | 只入库 `package.json`,其余由脚本生成 |
55
+ | `fcdev-cc65` | cc65、ca65、ld65、ar65、da65,头文件、库与链接配置 | 只入库 `package.json`,其余由脚本生成 |
58
56
 
59
57
  - 主包不引用具体机型的代码,只读取 `targets/` 下的目标定义。
60
58
  - 主包找不到工具链或模拟器时,不去 `PATH` 里猜,报错并说明可选的解决办法。
@@ -76,7 +74,7 @@ famiclone/
76
74
  create-fcdev/ 创建包
77
75
  bin/ src/ templates/ test/
78
76
  fcdev-cc65/ 工具链包
79
- fcdev-emulator/ 模拟器包
77
+ ember-debug-sdk/ Ember 调试服务的 SDK(独立包,不随 fcdev 发布,说明见它的 README)
80
78
  cc65/ cc65 源码(删减版,本仓库维护)
81
79
  virtuanes/ 模拟器源码(VirtuaNES 调试版,本仓库维护)
82
80
  vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
@@ -84,7 +82,7 @@ famiclone/
84
82
  apps/ 应用程序与示例(apps/sb2000:SB-DOS 的 asm、edit、runnes、disk 与 examples 示例),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
85
83
  test/ 仓库级测试:目录结构、cc65 工具链包、SB2000 头文件
86
84
  machines/ 各机型的资料与工程(不属于 fcdev 包,不随包发布),一个机型一个目录,如 machines/sb2000
87
- build/ 构建中间目录(不入库)
85
+ build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是模拟器的编译输出
88
86
  ```
89
87
 
90
88
  ## 5. 主包分层
@@ -122,7 +120,7 @@ famiclone/
122
120
  | --- | --- |
123
121
  | 仓库与 `fcdev`、`create-fcdev` 自己的代码 | Apache-2.0,见根目录 `LICENSE` |
124
122
  | `cc65/` 及工具链包 | zlib,见 `cc65/LICENSE` |
125
- | `virtuanes/` 及模拟器包 | GPL-3.0-only,见 `virtuanes/LICENSE` |
123
+ | `virtuanes/` | GPL-3.0-only,见 `virtuanes/LICENSE` |
126
124
 
127
125
  模拟器源码里只有 `interp.h`、`nx_hq2x.h`、`nx_Scale2x.h` 三个文件头写“版本 2 或以后”,合并后按 GPLv3 发布。两个包都是独立程序,许可证互不影响。
128
126
 
@@ -130,8 +128,7 @@ famiclone/
130
128
 
131
129
  | 脚本 | 作用 |
132
130
  | --- | --- |
133
- | `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装 `@rujianjs/fcdev-cc65`,见 [04-cc65工具链](04-cc65工具链.md) |
134
- | `tools/build-emulator.mjs` | 构建模拟器,组装 `@rujianjs/fcdev-emulator`,见 [05-模拟器与调试](05-模拟器与调试.md) |
131
+ | `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装 `fcdev-cc65`,见 [04-cc65工具链](04-cc65工具链.md) |
135
132
  | `tools/build-libs.mjs` | 按各目标的 `lib-build.json` 用 `cc65`、`ca65`、`ar65` 编出 `lib/` 下的运行库(`.c` 与 `.s` 源码,目录项递归展开);`fcdev` 的 `prepack` 与 `npm test` 前自动运行 |
136
133
  | `tools/gen-sb2000-header.mjs` | 由 `sb2000.inc` 生成 `sb2000-symbols.h` |
137
134
  | `tools/check-sb2000-api.mjs` | 检查 SB2000 的 C 接口:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节 |
@@ -143,7 +140,7 @@ famiclone/
143
140
 
144
141
  ## 9. 文档清单
145
142
 
146
- 文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
143
+ 文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`npx fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
147
144
 
148
145
  | 主题 | 文档 | 内容 |
149
146
  | --- | --- | --- |
@@ -151,7 +148,7 @@ famiclone/
151
148
  | `build` | [02-命令行与构建](02-命令行与构建.md) | 命令、构建规则、配置文件、构建流程 |
152
149
  | `targets` | [03-目标规范](03-目标规范.md) | 目标定义、打包器、新增机型的步骤 |
153
150
  | `toolchain` | [04-cc65工具链](04-cc65工具链.md) | cc65 源码、构建与工具链包 |
154
- | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、调试服务与命令表、模拟器包 |
151
+ | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、模拟器定位、调试服务与命令表 |
155
152
  | `disasm` | [06-反汇编](06-反汇编.md) | 反汇编前端的流程与限制 |
156
153
  | `create` | [07-创建包与模板](07-创建包与模板.md) | 创建命令、模板与生成内容 |
157
154
  | `testing` | [08-测试与验证](08-测试与验证.md) | 测试分层、环境变量与运行方法 |
@@ -161,6 +158,6 @@ famiclone/
161
158
  | `sb2000` | [sb2000/01-开发指南](sb2000/01-开发指南.md) | SB2000 目标的程序格式、内存布局、运行库、常用做法与示例 |
162
159
  | `syscall` | [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) | SB-DOS 的系统调用:参数、结果、出错码与可靠程度 |
163
160
  | `hardware` | [sb2000/03-硬件说明](sb2000/03-硬件说明.md) | SB2000 的硬件行为 |
164
- | `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `fcdev api`) |
161
+ | `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `npx fcdev api`) |
165
162
  | `todo` | [待办备忘](待办备忘.md) | 已确定以后再做的事项 |
166
163
  | `bugs` | [缺陷记录](缺陷记录.md) | 发现的缺陷及修复情况 |
@@ -6,6 +6,8 @@
6
6
 
7
7
  入口是 [packages/fcdev/bin/fcdev.mjs](../bin/fcdev.mjs),由 `cli/index.mjs` 的 `runCli` 分发。命令正常结束返回 0;出现 `FcdevError` 时向标准错误写“错误:”加说明与建议,返回 1。
8
8
 
9
+ `fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里要写成 `npx fcdev <命令>`(全局安装 `npm install -g fcdev` 后可以直接写 `fcdev <命令>`);`package.json` 的 `scripts` 里直接写 `fcdev <命令>`。下面的表格和本文其余地方都省略 `npx`。
10
+
9
11
  | 命令 | 作用 |
10
12
  | --- | --- |
11
13
  | `fcdev build [路径]` | 构建,规则见第 2 节 |
@@ -60,7 +62,7 @@
60
62
  | `include` | 字符串数组 | 空 | 额外头文件目录,相对项目根 |
61
63
  | `toolchain` | 字符串 | 空 | 自备 cc65 的根目录,优先于工具链包 |
62
64
  | `firmware` | 字符串 | 无 | 固件(BIOS、ROM)文件路径;目标的运行方案要求固件时必填 |
63
- | `emulator` | 字符串 | 空 | 自备模拟器可执行文件路径,优先于模拟器包 |
65
+ | `emulator` | 字符串 | 空 | 模拟器可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
64
66
  | `targetOptions` | 对象 | 空 | 目标专用选项,由各目标定义并校验 |
65
67
 
66
68
  - 配置里出现未知项、类型不对、`define` 的值不是字符串或数字时,报错并列出可用的项。
@@ -110,7 +112,7 @@
110
112
 
111
113
  1. 配置项 `toolchain`。
112
114
  2. 环境变量 `FCDEV_CC65_HOME`。
113
- 3. 工具链包 `@rujianjs/fcdev-cc65`。
115
+ 3. 工具链包 `fcdev-cc65`。
114
116
 
115
117
  目录里必须有 `bin` 下的 `cc65`、`ca65`、`ld65`,否则报“不是完整的 cc65 目录”。都找不到时报错并写明三种解决办法。不使用 `PATH` 里的 cc65,避免版本不一致。
116
118
 
@@ -60,7 +60,7 @@ targets/<名>/
60
60
  | `rom` | 模拟器直接加载产物 |
61
61
  | `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,挂载磁盘镜像后复位 |
62
62
 
63
- `run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是使用 `virtuanes` 的模拟器包,该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
63
+ `run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是按 `virtuanes` 的调试服务控制模拟器(模拟器程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
64
64
 
65
65
  ### 2.3 多页(换页)程序
66
66
 
@@ -1,6 +1,6 @@
1
1
  # cc65 工具链
2
2
 
3
- `fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成工具链包 `@rujianjs/fcdev-cc65` 随 npm 发布。工具链怎么被主包找到,见 [02-命令行与构建](02-命令行与构建.md) 第 4.4 节。
3
+ `fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成工具链包 `fcdev-cc65` 随 npm 发布。工具链怎么被主包找到,见 [02-命令行与构建](02-命令行与构建.md) 第 4.4 节。
4
4
 
5
5
  ## 1. 源码目录 `cc65/`
6
6
 
@@ -38,7 +38,7 @@ node tools/build-cc65.mjs
38
38
 
39
39
  ## 3. 工具链包
40
40
 
41
- - 包名 `@rujianjs/fcdev-cc65`(目录名不含作用域,是 `fcdev-cc65`),主包把它列为 `optionalDependencies`,版本精确一致。
41
+ - 包名 `fcdev-cc65`(与目录名相同),主包把它列为 `optionalDependencies`,版本精确一致。
42
42
  - 入库的只有 `package.json`;`bin/`、`include/`、`asminc/`、`lib/`、`cfg/`、`LICENSE`、`manifest.json` 都是生成物,由 `.gitignore` 排除。
43
43
  - 主包找不到工具链包时,提示可用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。
44
44
  - `npm run release:check` 校验工具链包里的文件与清单一致,且没有清单之外的文件;源码目录里的路径和清单由 `test/cc65-tools.test.mjs` 检查,见 [08-测试与验证](08-测试与验证.md)。
@@ -1,21 +1,12 @@
1
1
  # 模拟器与调试
2
2
 
3
- `fcdev` 自带一个调试用模拟器:VirtuaNES 调试版,带调试服务,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序。它的源码在本仓库的 `virtuanes/` 目录,由本仓库维护;构建脚本把它编成模拟器包 `@rujianjs/fcdev-emulator` 随 npm 发布。模拟器的改动清单见 `virtuanes/README.md`,调试服务的命令表见第 5.1 节。
3
+ `fcdev` 的 `run`、`debug` 命令经调试服务控制模拟器。模拟器不随 npm 包提供,需要自备,并且要支持第 5 节的调试服务。本仓库的 `virtuanes/` 是实现了这套服务的 VirtuaNES 调试版源码,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序,由本仓库维护。模拟器的改动清单见 `virtuanes/README.md`,调试服务的命令表见第 5.1 节。
4
4
 
5
- ## 1. 模拟器包
5
+ ## 1. 模拟器的获得
6
6
 
7
- - 基于 Win32 与 DirectX。许可证 GPL-3.0-only,包里附许可文件。
8
- - 模拟器是 32 位程序,`bin/` 里随带 `vcruntime140.dll`、`msvcp140.dll`(应用本地部署)。
9
- - 包内容:`bin/VirtuaNES.exe`、`bin/Chinese.vlp`、两个运行库、`LICENSE`、`manifest.json`、`package.json`。入库的只有 `package.json`,其余是生成物。
10
- - 模拟器运行时会在 `bin/` 里写 `VirtuaNES.ini` 与 `save/`,发布前要删除;`release-check` 会把它们当作清单之外的文件报错。
11
-
12
- 构建:
13
-
14
- ```bash
15
- node tools/build-emulator.mjs
16
- ```
17
-
18
- `tools/build-emulator.mjs` 需要 Visual Studio(含“使用 C++ 的桌面开发”)。它调用 `virtuanes/build.ps1 -Configuration Release`,把 `VirtuaNES.exe` 与 `Chinese.vlp` 复制进 `bin/`,再用 `vswhere` 找到 Visual Studio 里 32 位的 VC++ 运行库一并放入,最后写 `LICENSE`、`manifest.json`(当前提交、`virtuanes/` 有无未提交改动 `sourceDirty`、各文件的 SHA-256)与 `package.json`。编译前先关闭正在运行的模拟器。
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/`。
19
10
 
20
11
  ## 2. 定位模拟器
21
12
 
@@ -23,9 +14,8 @@ node tools/build-emulator.mjs
23
14
 
24
15
  1. 配置项 `emulator`。
25
16
  2. 环境变量 `FCDEV_EMULATOR`。
26
- 3. 模拟器包 `@rujianjs/fcdev-emulator` 里的 `bin/VirtuaNES.exe`。
27
17
 
28
- 指定的路径不存在时报“找不到模拟器”。自备的模拟器需要支持同样的调试服务才能用调试命令。
18
+ 都没有设置时报“找不到模拟器”,指定的路径不存在时报“找不到模拟器:路径”。模拟器需要支持同样的调试服务才能用调试命令。
29
19
 
30
20
  ## 3. `fcdev run`
31
21
 
@@ -45,13 +35,13 @@ node tools/build-emulator.mjs
45
35
  ## 4. `fcdev debug`
46
36
 
47
37
  ```bash
48
- fcdev debug run 60
49
- fcdev debug shot screen.png
38
+ npx fcdev debug run 60
39
+ npx fcdev debug shot screen.png
50
40
  ```
51
41
 
52
42
  - 把命令原样转发给调试服务,打印应答;应答首行以 `OK` 开头时退出码为 0,否则为 1。
53
43
  - 端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
54
- - 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
44
+ - 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀、`tape play`、`tape rec` 的文件;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
55
45
  - `run`、`step` 的应答超时是 10 分钟,其余命令 30 秒。
56
46
 
57
47
  ## 5. 调试服务协议
@@ -79,12 +69,14 @@ fcdev debug shot screen.png
79
69
  | `key <扫描码> <0\|1>`、`key clear` | 按下或松开键盘键(DirectInput 扫描码) |
80
70
  | `mouse move <dx> <dy>`、`mouse btn <掩码>` | 鼠标移动与按键 |
81
71
  | `shot <文件.png>` | 截图 |
82
- | `trace <文件> [最大行数]`、`trace off` | 记录每条指令与中断 |
72
+ | `trace <文件> [最大行数] [unique]`、`trace off` | 记录每条指令与中断;加 `unique` 时每个 CPU 地址的指令、每个中断入口只记第一次,最大行数按实际写出的行数算(适合长时间运行后给 `fcdev disasm --trace` 用;只按 CPU 地址去重,换页后同一地址的其他代码会漏记) |
83
73
  | `io <文件> [最大行数] [w]`、`io off` | 记录 `$2000-$4FFF` 的读写;加 `w` 只记录写 |
84
74
  | `pad <0-3> <十六进制掩码>`、`pad <0-3> clear` | 注入手柄按键(A=01、B=02、Select=04、Start=08、上=10、下=20、左=40、右=80),与真实输入合并 |
85
75
  | `disklog <文件> [最大行数]`、`disklog off` | 记录软驱控制器读写的 LBA |
86
76
  | `calllog <文件> <pc> <地址:长度[,...]> [最大次数] [skip=地址=值[,...]]`、`calllog off` | 每次执行到 `pc` 就记录寄存器、栈顶与内存段;`skip` 表示该地址字节等于值(十六进制)时不记录;可添加多条,`off` 全部关闭 |
87
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` 后才完整(命令已实现,还没有用实际程序验证) |
88
80
  | `disk <镜像>`、`savedisk` | 挂载或保存软盘镜像 |
89
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` 挂载新镜像时也会清掉全部故障 |
90
82
  | `audio fast\|real` | 声音播放速度:`fast` 时语音与 DAC(开机音乐、WAV)不再等声卡按真实时间播放,采样直接丢弃,模拟器内部时序不变;`real` 为默认的真实时间。开关是全局状态,复位后保持;验证工具只在开机阶段打开,开机完成后恢复 |
@@ -18,7 +18,7 @@
18
18
  ## 2. 命令
19
19
 
20
20
  ```bash
21
- fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
21
+ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
22
22
  ```
23
23
 
24
24
  | 选项 | 说明 |
@@ -73,6 +73,11 @@ fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [-
73
73
  - `RTS`、`RTI`、`BRK` 与间接 `JMP` 结束这一路。
74
74
  - 遇到非法操作码、超出映像末尾或与已识别的指令重叠时,放弃这一路并记入警告。
75
75
  - 没被追到的字节都按数据输出,这不影响回读校验。
76
+ - 入口都追完后,查找经地址表分发的跳转(`address-tables.mjs`),表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
77
+ - `LDA 表,X/Y` 与 `LDA 表+1,X/Y` 成对,窗口里有间接 `JMP`:字表,目标就是表里的值;
78
+ - 一对加载指令、两条 `PHA` 与一条 `RTS`:目标是表里的值加 1,表可以是字表,也可以是低、高字节分开的两张表;
79
+ - 间接 `JMP (地址)` 的地址在映像内、那里还是未识别的字节:那里是字表。
80
+ 表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束,单张表最多 128 项;字表占的字节按 `AddrTable` 输出,分开的两张表保持为数据。
76
81
 
77
82
  指令表在 `opcode-table.mjs`,共 151 条官方指令,数据取自 `da65` 的 `cc65/src/da65/opc6502.c`;非官方(非法)操作码不在表里。
78
83
 
@@ -84,18 +89,18 @@ fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [-
84
89
  | --- | --- |
85
90
  | `Code` | 追踪到的指令 |
86
91
  | `ByteTable` | 没被追到的字节 |
87
- | `AddrTable` | iNES 末尾 6 字节的中断向量表 |
92
+ | `AddrTable` | iNES 末尾 6 字节的中断向量表,以及识别出的字表 |
88
93
 
89
94
  另有 `GLOBAL`(输入输出文件名、起始地址、CPU)、`ASMINC`(符号定义文件)与 `LABEL`(用户符号与中断向量名)。
90
95
 
91
96
  ## 6. 验证与限制
92
97
 
93
- 验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM` 提供)回读都与原文件逐字节一致。静态追踪追不到 `RTS` 跳转表与间接调用,所以马里奥只追到约 2320 字节代码,其余按数据输出,回读仍一致;补充 CDL 或 `trace` 能扩大覆盖。
98
+ 验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM` 提供)回读都与原文件逐字节一致。静态追踪追不到表驱动之外的间接调用,所以马里奥只追到约 2320 字节代码,其余按数据输出,回读仍一致;补充 CDL 或 `trace` 能扩大覆盖。步步高 DOS 下的 GBASIC(`.CMD`,26896 字节,平铺二进制加载地址 `$7B00`)加入地址表识别后,代码从 6905 字节增到 8980 字节,再加一个经人工确认的入口 `$880F` 增到 10361 字节;再用模拟器的 `trace ... unique` 记录下运行 BASIC 语句、图形编辑与退回 DOS 时执行过的地址,并补三个经单独追踪确认的入口,增到 14843 字节(剩余约 12000 字节主要是图形数据与关键字表),回读一致。
94
99
 
95
100
  限制:
96
101
 
97
102
  - iNES 只支持 NROM。
98
- - 不识别例程内联的跳转表,也不把数据识别成地址表或字符串,未追到的字节都是 `ByteTable`。
103
+ - 只识别上述几种写法的地址表;用立即数拼出地址再存进指针的跳转、调用方自己写进工作区的分发、直接访问表项的对象表都追不到,也不把数据识别成字符串,未追到的字节都是 `ByteTable`。
99
104
  - 模拟器自带的 CDL 只对 SB2K 映射器有效。
100
105
  - SB2000 固件页的 CDL 验证没有做。
101
106
  - `da65` 输出的源码是 CRLF 换行。
@@ -59,14 +59,14 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
59
59
 
60
60
  `npm run release:verify`(`tools/verify-install.mjs`):
61
61
 
62
- 1. 把四个包用 `npm pack` 打成 `.tgz`。
62
+ 1. 把三个包用 `npm pack` 打成 `.tgz`。
63
63
  2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
64
- 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与两个工具链、模拟器包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
64
+ 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与工具链包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
65
65
  4. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
66
66
 
67
67
  只验证构建,不启动模拟器。
68
68
 
69
69
  ## 7. 注意事项
70
70
 
71
- - 带真实模拟器的用例运行后会在模拟器包的 `bin/` 里生成 `VirtuaNES.ini` 与 `save/`;发布前必须删除,`release:check` 会把它们当作清单之外的文件报错。
71
+ - 带真实模拟器的用例运行后会在模拟器所在目录里生成 `VirtuaNES.ini` 与 `save/`,不用删。
72
72
  - 没有目测的界面输出,汇报时写明。
@@ -1,51 +1,47 @@
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
- | `@rujianjs/fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
- | `@rujianjs/fcdev-emulator` | 模拟器包,目录 `packages/fcdev-emulator` |
11
- | `fcdev` | 主包,对两个包写精确版本的 `optionalDependencies` |
9
+ | `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
+ | `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies` |
12
11
  | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
13
12
 
14
- - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包与模拟器包的依赖版本必须与之相同。
15
- - 工具链包与模拟器包的包名带 `@rujianjs` 作用域,目录名不带。作用域包默认不能公开发布,所以它们的 `package.json` 写了 `publishConfig.access` 为 `public`,`release-check` 会检查这一项,以及这两个包的包名是否都在 `fcdev` 的 `optionalDependencies` 里。
16
- - 不带作用域的名字发布时被 npm 的垃圾包名检测拦截(403),所以改用作用域,见 [01-软件架构设计](01-软件架构设计.md) 的 D02。
17
- - 工具链包与模拟器包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs` 与 `node tools/build-emulator.mjs`。
13
+ - 三个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包的依赖版本必须与之相同。工作区里的 `packages/ember-debug-sdk`(`ember-debug-sdk`)不在这三个包之列,版本独立,不由本文的发布脚本发布。
14
+ - `release-check` 会检查工具链包的包名是否在 `fcdev` 的 `optionalDependencies` 里。
15
+ - 工具链包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs`。
18
16
  - 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
19
17
 
20
18
  ## 2. 发布前提
21
19
 
22
20
  1. 所有改动已提交。
23
- 2. 在已提交的状态下重新运行 `node tools/build-emulator.mjs`,使模拟器包清单里的 `sourceDirty` 为 `false`。`sourceDirty` 只看 `virtuanes/` 目录有没有未提交的改动。
24
- 3. 工具链包与模拟器包都已构建:`node tools/build-cc65.mjs`、`node tools/build-emulator.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
25
- 4. 模拟器包的 `bin/` 里没有 `VirtuaNES.ini` 与 `save/`,见 [08-测试与验证](08-测试与验证.md) 第 7 节。
26
- 5. `npm run release:check` 不带 `--allow-dirty` 通过。
21
+ 2. 工具链包已构建:`node tools/build-cc65.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
22
+ 3. `npm run release:check` 通过。
23
+ 4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(三个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
27
24
 
28
25
  ## 3. 检查
29
26
 
30
27
  `npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
31
28
 
32
- - 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与模拟器包的依赖版本一致;这两个包的包名都在 `fcdev` 的依赖里,作用域包声明了公开发布。
29
+ - 三个包的版本一致,都写了 `license`,`fcdev` 对工具链包的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里,作用域包声明了公开发布。
30
+ - `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
33
31
  - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
34
32
  - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
35
- - 两个包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
36
- - 模拟器清单的 `sourceDirty` 为 `true` 时报错;加 `--allow-dirty` 降为警告,只用于发布前的演练。
33
+ - 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
37
34
  - 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
38
35
 
39
36
  `npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
40
37
 
41
38
  ## 4. 发布顺序
42
39
 
43
- 先发工具链包与模拟器包,再发 `fcdev`,最后发 `create-fcdev`:
40
+ 先发工具链包,再发 `fcdev`,最后发 `create-fcdev`:
44
41
 
45
- 1. `@rujianjs/fcdev-cc65`
46
- 2. `@rujianjs/fcdev-emulator`
47
- 3. `fcdev`
48
- 4. `create-fcdev`
42
+ 1. `fcdev-cc65`
43
+ 2. `fcdev`
44
+ 3. `create-fcdev`
49
45
 
50
46
  `npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
51
47
 
@@ -57,8 +53,7 @@
57
53
  | --- | --- | --- |
58
54
  | `fcdev` | 71 | 64 kB |
59
55
  | `create-fcdev` | 23 | 15 kB |
60
- | `@rujianjs/fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
61
- | `@rujianjs/fcdev-emulator` | 7 | 0.7 MB(解压 1.8 MB) |
56
+ | `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
62
57
 
63
58
  体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
64
59
 
@@ -68,8 +63,8 @@
68
63
 
69
64
  | 命令 | 作用 |
70
65
  | --- | --- |
71
- | `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version`、主包对两个包的精确依赖,重新构建两个包并生成它们的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
72
- | `npm run release:publish -- --dry-run` | 演练:跑全部测试、重建模拟器包、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
73
- | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、四个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,最后用 `npm view` 核对。验证码由 npm 在终端里询问 |
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 在终端里询问 |
74
69
 
75
70
  两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。
@@ -49,4 +49,4 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
49
49
 
50
50
  ## 6. 运行
51
51
 
52
- `fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。
52
+ `npx fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。