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
@@ -125,16 +125,16 @@ int main(void)
125
125
  程序名取 `fcdev.json` 的 `name`,要符合 DOS 8.3 规则,且不要与 DOS 内部命令重名(如 `COPY`、`TYPE`、`DIR`),重名时先被当成内部命令。
126
126
 
127
127
  ```bash
128
- fcdev build src # 生成 build/sb2000/<NAME>.EXE
129
- fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
130
- fcdev run src # 构建,挂载镜像,在模拟器里运行
128
+ npx fcdev build src # 生成 build/sb2000/<NAME>.EXE
129
+ npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
130
+ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
131
131
  ```
132
132
 
133
- `fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
133
+ `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
134
134
 
135
135
  ## 6. 头文件与函数
136
136
 
137
- `sb2000.h` 包含 `sb2000-symbols.h` 与下面 13 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 184 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
137
+ `sb2000.h` 包含 `sb2000-symbols.h` 与下面 16 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 204 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
138
138
 
139
139
  | 头文件 | 模块 | 内容 |
140
140
  | --- | --- | --- |
@@ -151,17 +151,21 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
151
151
  | `sb2000-sound.h` | sound | 曲子与音效、WAV、语音 |
152
152
  | `sb2000-printer.h` | printer | 24 针点阵打印机 |
153
153
  | `sb2000-ime.h` | ime | 中文输入法 |
154
+ | `sb2000-dma.h` | dma | 通用 DMA:把扩展 RAM 里的数据复制到 ERAM 或显存,源地址换算 |
155
+ | `sb2000-ppu.h` | ppu | 直接操作图形端口:显存读写、调色板、精灵 RAM、等垂直消隐、打开显示 |
156
+ | `sb2000-timer.h` | timer | 硬件定时器:启动、停止、读当前值与下溢标志、屏蔽与允许 |
154
157
 
155
158
  约定:
156
159
 
157
160
  - 命名 `sb_<模块>_<动作>`;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
161
+ - dma、ppu、timer 三个模块直接读写硬件寄存器,不经系统调用,没有 `@syscall`;寄存器地址与位的符号是 `sb2000-symbols.h` 里以 `SB_HW_` 开头的常量,程序不要再自己定义。行为以真机实测为准,见 [硬件说明](03-硬件说明.md)。
158
162
  - 字符串、缓冲区、结构体指针必须在程序窗口 `$8000` 到 `$BFFF` 里(读写目标不能在窗口 3);系统服务换页后程序窗口不可见的情况,函数内部已经处理好。
159
163
  - 一个函数一个源文件,放在 `src/lib/<模块>/sb-<函数名>.c`(或 `.s`);库内部用的辅助函数以 `sbi_` 开头,声明在 `src/lib/sb-internal.h`,不对外。
160
164
  - 运行库由 `tools/build-libs.mjs` 编译:`lib-build.json` 里以 `/` 结尾的项展开成目录下全部 `.c` 与 `.s`;`.c` 用 `cc65 -t none --cpu 6502 -Oirs` 编译再汇编,同名文件报错。链接只带入程序用到的函数。
161
165
 
162
166
  随时查询接口:
163
167
 
164
- - `fcdev api` 列出全部模块;`fcdev api <函数名>` 看完整文档;`fcdev api <模块名>` 看函数列表;`fcdev api '$7B'` 或 `fcdev api '$7B/$09'` 看用到某个系统调用的函数;`fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
168
+ - `npx fcdev api` 列出全部模块;`npx fcdev api <函数名>` 看完整文档;`npx fcdev api <模块名>` 看函数列表;`npx fcdev api '$7B'` 或 `npx fcdev api '$7B/$09'` 看用到某个系统调用的函数;`npx fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
165
169
  - [api-reference.md](../../targets/sb2000/api-reference.md) 是同一份文档的整本 Markdown,由 `node tools/gen-sb2000-api-doc.mjs` 从头文件生成,末尾有“系统调用覆盖表”。改头文件注释后重新生成,测试会核对。
166
170
  - [api-unwrapped.json](../../targets/sb2000/api-unwrapped.json) 登记没有封装的功能号与子功能及原因(`functions` 是整个功能号不封装,`partial` 是封装了一部分)。`node tools/check-sb2000-api.mjs` 检查:头文件里每个函数有说明、`@param`、`@return`,有且只有一处实现,库里没有头文件之外的公开函数,BIOS 里有处理例程的每个功能号(`KNOWN_FUNCTIONS`)要么被某个函数的 `@syscall` 涉及、要么在 `functions` 里写明原因。
167
171
 
@@ -171,7 +175,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
171
175
 
172
176
  ## 7. 符号定义
173
177
 
174
- - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
178
+ - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、硬件寄存器与位(`HW_` 开头)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
175
179
  - [include/sb2000-symbols.h](../../targets/sb2000/include/sb2000-symbols.h) 是 C 用的同一份符号,每个符号对应一个 `SB_` 前缀的数值宏。它由 `node tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 生成,不要手工修改;改 `sb2000.inc` 后重新运行,测试会检查入库的头文件与生成结果一致。`sb2000.inc` 里符号的行尾注释,会变成宏上方的 `/** */` 文档注释,编辑器悬停时显示;分组标题变成普通的 `/* */` 注释。各模块头文件里的函数也用 `/** */` 与 `@param`、`@return`、`@syscall` 写文档。新增的服务先在 `sb2000.inc` 里加符号(功能号、子功能号、参数与结果单元、出错码),再重新生成。
176
180
 
177
181
  ## 8. 常用做法
@@ -194,6 +198,9 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
194
198
  | 读鼠标 | `$14` 复位并检查 `MOUSE_PRESENT`(`$0633`)非 0 → `$13/$81` 允许鼠标中断 → `$6C/$00` 设范围(`$0646-$0649`,`$0652` 不要是 1-4)→ `$6C/$04` 设初始坐标(`$0652`、`$0653`)→ 随时 `$6C/$02` 取坐标(`$0646`、`$0647`);`$6C/$03` 取按键状态(`$0360-$0367`,按住为 1,点击事件读走即清) | `mouse` |
195
199
  | 播放 WAV | 功能 `$65`、子功能 `$0C`(`SUB_SOUND_WAV`,C 里是 `sb_sound_play_wav`),见 [系统调用手册](02-系统调用手册.md) 5.5(只读过代码,没有示例) | — |
196
200
  | 把 NES 游戏当程序运行 | 读入 `.nes`、复制启动桩到 ERAM、写 `$4301` 后跳转 | `play` |
201
+ | 用 DMA 复制扩展 RAM 的数据 | `sb_dma_to_cpu`(目的只能是 ERAM `$6000-$7FFF`)、`sb_dma_to_vram`;源用 `sb_dma_page_address(页号, 偏移)` 换算;长度寄存器写“字节数 − 1”、`$404B` 位 7 置 1 都由函数处理;复制到显存要先关显示;要把数据放进窗口(`$8000` 以上)时,先 DMA 到 ERAM 缓冲,再用 `memcpy` 搬 | `apps/sb2000/bbk-loader` |
202
+ | 直接写显存、调色板、精灵 | `sb_display_off()` 关显示,用 `sb_ppu_*` 读写显存、调色板与精灵 RAM,`sb_ppu_render` 打开显示,用完再用 `sb_display_on()` 恢复 DOS 的显示 | `apps/sb2000/hwtest` |
203
+ | 用定时器计时 | `sb_timer_start(控制, 预置值)` 启动,`sb_timer_pending()` 看下溢标志,`sb_timer_mask()` 清标志;DOS 用它做系统时钟,用完要用 `$EF`、`$3C` 恢复 | `apps/sb2000/hwtest` |
197
204
 
198
205
  ## 9. 要避开的坑
199
206
 
@@ -245,7 +252,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
245
252
 
246
253
  ## 12. 运行库的测试
247
254
 
248
- 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
255
+ 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
249
256
 
250
257
  停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
251
258
 
@@ -29,15 +29,15 @@
29
29
 
30
30
  | 地址 | 内容 |
31
31
  | --- | --- |
32
- | `$0000-$1FFF` | 内部 RAM,8K,不镜像;零页 `$0000-$00FF` 供系统与程序共用,程序要避开 DOS 用到的单元 |
33
- | `$2000-$3FFF` | PPU 寄存器(`$2000-$2007` 及其镜像) |
34
- | `$4000-$4017` | 标准 APU 与手柄寄存器 |
35
- | `$4020-$4036` | 键盘、鼠标、中断、定时器等扩展寄存器(键盘经 `$4020-$4022` 串行收发) |
32
+ | `$0000-$1FFF` | 内部 RAM:只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像(真机实测,模拟器已对齐,见 [硬件说明](03-硬件说明.md));零页 `$0000-$00FF` 供系统与程序共用,程序要避开 DOS 用到的单元 |
33
+ | `$2000-$3FFF` | 图形端口:寄存器 `$2000-$2008`(`$2008` 是 6576 的扩展控制寄存器)与调色板 `$2040-$207F`;芯片手册只定义这两段,`$2080` 以上有没有镜像没有实测 |
34
+ | `$4000-$4017` | 声音(4 通道 PSG:方波 2 路、三角波、噪声,寄存器 `$4000-$400F`、`$4015`;芯片手册没有定义 NES 的 DMC 通道寄存器 `$4010-$4013`)、精灵 DMA(`$4014`)、手柄(`$4016`、`$4017`) |
35
+ | `$4020-$4036` | 键盘(`$4020-$4022`,串行收发)、手柄与鼠标选择(`$4023`)、鼠标(`$4024`)、并口打印机(`$4025`)、扩展 I/O(`$4026`)、DAC(`$4027`)、初始设置(`$4031`)、中断(`$4032`、`$4033`)、定时器(`$4034-$4036`) |
36
36
  | `$4040-$4047` | 8 个窗口的页选择:每个选一个 4K 页,对应 `$8000-$FFFF`;值小于 `$80` 是 BIOS ROM 页,不小于 `$80` 是扩展 RAM 页 |
37
37
  | `$4048-$404F` | DMA(见 [硬件说明](03-硬件说明.md)) |
38
38
  | `$4200-$4207` | 软驱控制器 |
39
39
  | `$4300` | 显存 bank 选择(32K 一个 bank) |
40
- | `$5000-$5FFF` | 2K 工作 RAM |
40
+ | `$4400-$5FFF` | 不是 RAM:读出都是 `$68`,写不进去(真机实测,模拟器已对齐);芯片手册里的 `$5000-$57FF` 2K 工作 RAM 在真机上没有,程序不能使用 |
41
41
  | `$6000-$7FFF` | 8K 扩展 RAM(ERAM),任何窗口映射下都可见;`$6200-$65FF` 一带是 DOS 的状态变量 |
42
42
  | `$8000-$BFFF` | 程序窗口:4 个 4K 窗口,由系统调用 `$29`、`$25` 映射 |
43
43
  | `$C000-$FFFF` | 固定内核:ROM 第 4-7 页 |
@@ -338,7 +338,7 @@
338
338
 
339
339
  音乐驱动的内部例程:`SOUND_PLAY_SONG`(`$F43A`,按 `$049A` 播放:0 复位,`$FB-$FF` 为控制命令,其余为曲号,曲表指针在 `$D31B` 起)、`SOUND_START_TRACKS`(`$F4C9`)、`SOUND_RESET`(`$F5C4`)、`SOUND_UPDATE_ON`/`SOUND_UPDATE_OFF`(`$F5E9`、`$F5F2`);发声在 NMI 中断里更新。
340
340
 
341
- 曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU 寄存器 `$4000-$4013`、`$4015` 的序列):
341
+ 曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU 寄存器的序列(验证时记录 `$4000-$4013`、`$4015` 的写入;芯片手册只定义 `$4000-$400F` 与 `$4015`)):
342
342
 
343
343
  - 曲子有两种头。**音乐格式**:首字节不小于 `$80`,后面是声道项 `[声道号, 音轨偏移低, 偏移高]`(声道号小于 `$80`),以不小于 `$80` 的字节结束;首字节后紧跟一个不小于 `$80` 的字节时,声道项从第 4 字节起。**音效格式**:首字节小于 `$80`,是优先级,后面同样是声道项;第 2 字节不小于 `$80` 时还有 3 字节头(第 3 字节放 `$03BD`,曲号放 `$03BE`,`$0499` 置位 5,用于播完自动接下一首)。声道项里声道号不小于 4 的,优先级写进 `$03BB+声道号`,优先级小于当前 `$03BB+声道号` 时整首不起播;音乐格式的曲子曲号与 `$03BB` 相同时也不起播(`$65/$0A`、`$0B` 的曲号恒为 0,所以音乐格式的曲子用它们起不了播,要用 `$00`、`$01`、`$09`)。
344
344
  - 音轨偏移相对曲首(`$039B/$039C`,音效格式是 `$039D/$039E`);声道 0-3 是音乐声道,4-7 是音效声道,音效声道与同号后四位的音乐声道共用一个硬件声道,音效声道播放时(`$03CF+声道号` 非 0)音乐声道不写 APU。音乐声道读曲子的页放 `$04A1`(`$00`、`$01`、`$09` 设置),音效声道的页放 `$04A3`(`$0A`、`$0B` 设置)。
@@ -437,7 +437,7 @@ BIOS 自己带了一段 WAV:ROM 第 `$64` 页起,单声道、8 位、22050 H
437
437
 
438
438
  ### 5.7.2 DMA 与显存服务 `$30-$34`(已验证)
439
439
 
440
- DMA 寄存器:`$4048` 控制、`$4049` 源高、`$404A` 源低、`$404B` 源中、`$404C` 目的低、`$404D` 目的高、`$404E` 长度低、`$404F` 长度高;长度寄存器写“长度 − 1”。屏幕缓冲在扩展 RAM 页 `$FA`(名称表 4、5,偏移 `$000`、`$800`)与页 `$FB`(名称表 6、7),每张 2KB、每个单元 2 字节;区域填充的中转缓冲在页 `$F8` 起。
440
+ DMA 寄存器:`$4048` 控制、`$4049` 源 bank、`$404A` 源低、`$404B` 源高(位 7 是 A15,要求为 1,为 0 时 DMA 失败)、`$404C` 目的低、`$404D` 目的高、`$404E` 长度低、`$404F` 长度高(各位的含义见 [硬件说明](03-硬件说明.md);BIOS 源码里的符号 `DMA_SRC_BANK`、`DMA_SRC_LOW`、`DMA_SRC_HIGH` 依次对应 `$4049`、`$404A`、`$404B`);长度寄存器写“长度 − 1”。屏幕缓冲在扩展 RAM 页 `$FA`(名称表 4、5,偏移 `$000`、`$800`)与页 `$FB`(名称表 6、7),每张 2KB、每个单元 2 字节;区域填充的中转缓冲在页 `$F8` 起。
441
441
 
442
442
  | 功能 | 作用 |
443
443
  | --- | --- |
@@ -1,22 +1,31 @@
1
1
  # SB2000 硬件说明
2
2
 
3
- 本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源是模拟器源码(`virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)和实际运行观察。“已确认”指来自模拟器源码或实际运行,真机均未测试;程序接口见 [系统调用手册](02-系统调用手册.md)。
3
+ 本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源有三类:芯片手册(SH6578 官方手册,下称“芯片手册”)、模拟器源码(`virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)与实际运行观察、真机实测(`apps/sb2000/memtest`,2026-11-12;`apps/sb2000/hwtest`,2026-11-13,真机为 PAL 制式)。SB2000 的真机芯片是 UM6576,芯片手册是 SH6578,两颗芯片有差别,两者不一致时以真机实测为准。“已确认”指来自模拟器源码或实际运行;没有写“真机”的结论都没有在真机上测过。模拟器已按真机实测修改内部 RAM、`$4400-$5FFF`、DMA、定时器与图形端口(见对应行),memtest、hwtest 在模拟器里的结果与真机一致(仍有差异的项见“真机与模拟器仍有差异的行为”一行);模拟器与芯片手册不一致、也没有真机数据的地方,在对应行里写明。程序接口见 [系统调用手册](02-系统调用手册.md)。
4
4
 
5
5
  | 项目 | 结论 | 状态 |
6
6
  | --- | --- | --- |
7
- | CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是映射器 ASIC 的工作模式 | 已确认 |
8
- | 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成 | 已确认 |
7
+ | CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是向 `$4031` 依次写入 `$65`、`$76`(芯片手册称这一步为初始设置)之后的工作模式 | 已确认 |
8
+ | 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成。芯片手册要求两次写入在两个指令周期内连续完成(`LDA #$65 / LDX #$76 / STA $4031 / STX $4031`),模拟器只按顺序识别,不检查间隔 | 已确认(芯片手册、模拟器源码) |
9
9
  | 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真 | 已确认 |
10
10
  | 程序窗口 | `$4040-$4047` 各选一个 4K 页,对应 `$8000-$FFFF` 的 8 个窗口;值小于 `$80` 是 BIOS ROM 页(512KB,共 128 页),不小于 `$80` 是扩展 RAM 页(512KB) | 已确认 |
11
11
  | 启动后的窗口 | `$C000-$FFFF` 固定为 ROM 第 4-7 页,`$8000-$BFFF` 由 BIOS 换页 | 已确认 |
12
12
  | 向量 | NMI `$C084`,RESET `$C000`,IRQ `$C12B`(ROM 偏移 `$7FFA` 起) | 已确认 |
13
- | 内部 RAM | 6576 模式下 `$0000-$1FFF` 为 8K 且不镜像;`$5000-$5FFF` 为 2K 工作 RAM,`$6000-$7FFF` 为 8K 扩展 RAM | 已确认 |
14
- | DMA | `$4048-$404F`;写 `$4048` 的最高位启动;源为 ROM 或扩展 RAM,目的为工作 RAM 或显存 | 已确认 |
13
+ | 内部 RAM | 芯片手册:工作 RAM 共 10KB,在 `$0000-$1FFF`(8KB)与 `$5000-$57FF`(2KB)。模拟器(6576 模式)已按真机实测修改,行为与下面的真机实测相同;模拟器在 FC 兼容模式下仍保留 `$5000-$5FFF` 的 2K RAM(镜像两次),这个模式没有在真机上测过。真机实测:内部 RAM 只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像;`$4400-$5FFF` 读出的都是 `$68`,写 `$55`、`$AA` 后读回仍是 `$68`,既不是 RAM 也不是会应答的寄存器(`$5006` 的写入仍有效果);`$6000-$7FFF` 是 8K,各 1K 互相独立 | 已确认(真机实测;模拟器已在 SB-DOS 下用真实 CPU 指令读写核对);内存大小与芯片手册不一致,以真机为准 |
14
+ | DMA | `$4048-$404F`,把主存储器的数据复制到显存或工作 RAM;写 `$4048` 的最高位启动(模拟器瞬时完成)。`$4048`:位 7 使能;位 6 传输速率(0 为 890KB/s,1 为 1.78MB/s);位 5 目的(0 为显存,1 为工作 RAM),其余位为 0。芯片手册要求先把 `$4020` 位 7 置 1,位 6、5 才起作用(模拟器不检查;BIOS 在系统初始化时写 `$4020=$80`)。`$4049`:源 bank,低 5 位对应 XA20-XA16,位 4 为 1 取扩展 RAM,否则取 ROM;`$404A`、`$404B`:源地址的低、高字节,`$404B` 的低 7 位是 A14-A8,位 7 是 A15(真机要求为 1,模拟器已按真机处理:为 0 时不传输);`$404C`、`$404D`:目的地址低、高字节,目的是显存时位 15 为 1 表示扩展显存;`$404E`、`$404F`:长度寄存器的值是字节数减 1,真机实际搬“长度 + 1”个字节(BIOS 也传“字节数 − 1”),最大 32KB(`$8000` 不屏蔽,写 `$8010` 会搬 `$8011` 个字节)。每搬一个字节,源地址与目的地址各加 1。芯片手册:目的是显存时只在垂直消隐期间或显示关闭时运行,没搬完的数据留到下一次垂直消隐再继续;目的是工作 RAM 时没有这个限制。BIOS 把 `$C0` 用于复制到显存,`$A0`、`$E0` 用于复制到 CPU 地址。真机实测:只有目标是 ERAM 且 `$404B` 位 7 为 1 时成功,模式 `$A0`、`$E0` 都行;`$4020` 位 7 为 0 时,模式位 5 不起作用,目的总是显存,位 7 为 1 时才由模式位 5 选择工作 RAM 或显存(与芯片手册的说法一致);模拟器已对齐:`$404B` 位 7 为 0 时不传输,目的在程序窗口(`$8000` 以上)时写不进去,长度按“长度 + 1”,`$4020` 位 7 为 0 时目的总是显存,memtest、hwtest 在模拟器里的结果与真机相同 | 已确认(芯片手册、模拟器源码;位的作用已在模拟器里逐项核对);真机实测 |
15
15
  | 软驱控制器 | `$4200-$4207`;1.44MB(每道 18 扇区、2 面、80 道),LBA = 磁道×36 + 磁头×18 + 扇区 − 1 | 已确认 |
16
- | 键盘 | 经 `$4020-$4022` 串行收发,扫描码与 DirectInput 的 DIK 值一致 | 已确认 |
16
+ | 键盘 | 经 `$4020-$4022` 串行收发。芯片手册:键盘口收发 AT 键盘的 11 位串行帧(起始位、8 位扫描码、奇偶位、停止位),收完整帧后产生键盘中断,要在下一位到来前读走 `$4020` 里的扫描码;`$4022` 位 7 是键盘时钟 CLK(接收时必须保持 1,BIOS 处理完一个码后写 `$80`),位 2 允许“发送命令完成”中断,位 0 是方向(0 为键盘到系统,1 为系统到键盘);发送时先把数据写入 `$4021`,再置位 0 为 1、CLK 拉低大于 60ms 后拉高,硬件自动发出。模拟器直接给出与 DirectInput 的 DIK 值一致的扫描码(即 IBM 码集 1 的按下码),在 CLK 上升沿且位 0 为 1 时把 `$4021` 发给键盘;真机键盘实际是否按此工作没有测过;BIOS 初始化键盘时(功能 `$17`)会发 `$F0`、`$01` 选择扫描码集 1 | 已确认(芯片手册、模拟器源码) |
17
17
  | 显存 | 512KB,经 `$4300` 选 32KB 的 bank | 已确认 |
18
- | 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 3 软驱,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断 | 已确认(模拟器源码) |
19
- | 并口打印机 | 模拟器实现了 Epson ESC/P 虪拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
18
+ | 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 4 INT4(芯片手册:实时时钟)、位 3 软驱、位 2 INT2(芯片手册:打印机的 IRQ2)、位 1 INT1(芯片手册:φ 使能的 IRQ1),位 0 未用,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断。BIOS 为位 4、2、1 各留了钩子,模拟器里没有设备置位它们 | 已确认(芯片手册、模拟器源码) |
19
+ | 鼠标 | `$4023` 位 0 选手柄 2 或鼠标(1 为鼠标);真机实测(`hwprobe`):读回是 `$80 | 位 0`,位 7 是输入线(闲置为 1),位 6-1 读 0;鼠标数据经 `$4024` 读,是微软串口鼠标的 3 字节包。复位信号:BIOS(功能 `$14`)与模拟器都用 `$4026` 的位 1(EIO1),拉低再拉高,模拟器在上升沿发 RTS。芯片手册在鼠标一节把复位信号写作 `$4026` 的 D2,在扩展 I/O 一节又写 EIO1 产生鼠标复位,两处说法不一致,这里按 BIOS 与模拟器的用法,真机没有核实;手册要求复位时间大于 30ms,并可写 `$4024` 设置波特率(NTSC 为 `$A3`、PAL/B 为 `$A9`),BIOS 没有写它 | 已确认(芯片手册、模拟器源码、BIOS 代码);复位位的说法见左 |
20
+ | 定时器 | `$4034` 控制:位 7 允许,位 6 连续重载(0 只计一次),位 5 基准时钟(0 为 CPU 时钟,1 为行消隐时钟 15625Hz),位 3-0 为预分频 PS;`$4035` 写预置值 TP,同时装入当前值;`$4036` 读当前值(递减)。周期 = 基准周期 × (PS + 1) × (TP + 1),下溢时置 `$4033` 位 7(`$4032` 位 7 为 0 才产生中断)。真机实测:`$4035` 可读(读回写入的预置值);一次计时(位 6 为 0)下溢一次后,当前值保持预置值,不再计时,也不再置中断标志,模拟器已对齐(旧版把当前值置 0);真机一帧是 PAL 的 50Hz,120 帧内的下溢次数:BIOS 的设置与行消隐时钟两组模拟器与真机相同(38、147),CPU 时钟那组真机 1040 次、模拟器 1038 次。BIOS 开机设 `$4034=$EF`、`$4035=$3C`(连续、行消隐时钟、PS=15、TP=60,周期 64µs × 16 × 61 约 62.5ms,即约 16Hz),用作软件时钟的节拍;播放 WAV 时用 `$4034=$C0`(CPU 时钟、PS=0),`$4035` 取 `$28`、`$51`、`$A2` 作采样节拍 | 已确认(芯片手册、模拟器源码;开机后的寄存器值已在模拟器里读出);`$4035` 可读与一次计时的行为为真机实测 |
21
+ | 声音 | 芯片手册:4 通道 PSG,通道 1、2 方波,通道 3 三角波,通道 4 噪声,寄存器为 `$4000-$4003`、`$4004-$4007`、`$4008`、`$400A`、`$400B`、`$400C`、`$400E`、`$400F`,`$4015` 低 4 位依次使能通道 1-4;没有定义 NES 的 DMC 寄存器 `$4010-$4013`,语音改用 `$4027` 的 DAC 输出。BIOS 的声音引擎在 RAM 里维护这些寄存器的影子,再写到芯片(见 [系统调用手册](02-系统调用手册.md) 5.5 节) | 芯片手册 |
22
+ | DAC | `$4027` 是 8 位 DAC,输出语音(PCM)。芯片手册:实际输出发生在定时器溢出时,所以使用 DAC 必须同时设置定时器;输出带约 1/2 Vcc 的直流偏置,输出语音前要把电平从 0 缓慢升到偏置值,否则开始时有“噗”声。BIOS 播放 WAV 时写它(`$65/$0C`) | 芯片手册;BIOS 的用法已验证 |
23
+ | 实时时钟 | 芯片手册:`$4080` 写 RTC 地址,`$4081` 读写 RTC 数据,使用前先设地址。SB2000 的 BIOS 不访问它们,系统时钟由定时器中断软件计时;模拟器的 `$4026` 位 0(EIO0)没有接 RTC | 芯片手册;BIOS 没有使用 |
24
+ | 图形端口 | 寄存器 `$2000-$2008` 与调色板 `$2040-$207F`。`$2000`:位 7 允许 NMI,位 5 精灵 8×16,位 2 地址增量(0 加 1,1 加 32),位 1-0 背景页;`$2001`:位 0 黑白,位 1、2 屏蔽背景、精灵最左 8 个像素,位 3、4 背景、精灵显示,位 7-5 红绿蓝增强;`$2002` 读:位 7 垂直消隐,位 6 精灵与背景碰撞,位 5 一行超过 8 个精灵;`$2008`:位 7 背景 4 色(0)或 16 色(1),位 3-2 精灵图案表起始,位 0 名称表起始(为 1 时名称表在显存 `$2000-$27FF`,只能显示一页)。名称表项 2 字节,高 4 位是调色板组,低 12 位是图案号;调色板 64 项,每项低 4 位颜色、位 5-4 亮度。显存、调色板、精灵 RAM 只能在垂直消隐期间或显示关闭时更新,精灵用 `$4014` 的 DMA 更新。BIOS 功能 `$10` 修改的就是这些位(见 [系统调用手册](02-系统调用手册.md) 5.7 节)。真机实测(`hwtest`,与芯片手册不一致的地方以真机为准):① `$2001` 位 1、2 的极性与 NES 相同,为 1 表示显示最左 8 个像素,为 0 表示屏蔽(芯片手册写反,BIOS 影子初值 `$0E` 即两位都显示);位 0 为 1 时黑白,背景底色也变灰;位 5 增强绿、位 6 增强红、位 7 增强蓝(PAL 顺序,芯片手册写位 5 蓝、位 6 绿、位 7 红)。② 精灵属性位 6 为水平镜像,位 7 为垂直翻转,位 5 为 1 表示在背景之后(只被不透明的背景像素盖住);读回 OAM 时属性字节的位 4-2 恒为 1(写 `FF` 读 `FF`,写 `00` 读 `1C`),不跟地址、也不跟最后写的 PPU 端口走;早先的两次 `hwtest` 曾读到 `E3`、`F3`,用现在的程序复现不了,原因不明。③ `$2000` 位 1-0 选 4 个互相独立的名称表;`$2008` 位 0 为 1 时名称表从 `$2000` 起;8×16 精灵的图案号最低位被忽略(相邻的偶数号、奇数号显示同一对图块),上半取偶数号。④ 调色板每项低 4 位是色相、位 5-4 是亮度,与芯片手册相同,16 色模式可用;读调色板得到 `(值 & $3F) | $40`。⑤ `$2002` 位 6(精灵 0 碰撞)、位 5(一行超过 8 个精灵)有效,低 5 位是最后一次写 PPU 总线的值。模拟器的 UM6576 PPU(`PPU_UM6576.cpp`)已按以上实测实现;颜色的亮度与饱和度渲染与真机电视的差别没有对齐,不影响程序行为 | 芯片手册;位的作用为真机实测(`hwtest`),模拟器已对齐 |
25
+ | 空读(没有器件驱动的位) | 真机实测:读到 CPU 数据总线上最近的一个值,读指令里的地址高字节就是总线最近的值,所以 `$203F`、`$2080` 读 `$20`,`$4018`、`$4019`、`$401F` 读 `$40`;`$4016`、`$4017` 的位 6 也是这个原因;`$2009` 读 `$00`。模拟器(UM6576 模式)记录总线最近的值,空读时返回它,零页间接寻址(`(zp),Y`)读到的是指针高字节,堆栈不记录;`$200A-$203F`、`$2080-$3FFE`、`$4018-$401F` 按这个规则处理,其中只有 `$203F`、`$2080`、`$4018`、`$4019`、`$401F` 在真机上测过 | 真机实测(`hwtest`);模拟器已对齐 |
26
+ | 实时时钟 | 真机实测:`$4081` 不论有没有设地址,读出的都是 `$60`;模拟器读出 `$60` | 真机实测(`hwtest`);模拟器已对齐 |
27
+ | 真机与模拟器仍有差异的行为 | `hwtest` 在真机上测到、模拟器没有对齐的项目(程序不应依赖这些值)。真机读数:`$3FFF` 为 `$68`(模拟器读 `$00`,原因不明),`$4037` 两次实测分别为 `$A0`、`$E0`(不固定);`$4015` 写 `$FF` 后读出位 4 为 1、写 `$1F` 后读出位 4 为 0(模拟器反过来);`$4022` 开机值 `$C0`(模拟器为 `$80`;写入后的读回还没有真机数据);`$4026` 读出 `$3F`(位 4 为 1,模拟器按虚拟打印机固定为 `$2F`);`$4016` 读出 `$44`、`$4017` 读出 `$40`(模拟器为 `$40`、`$48`);`$4033` 位 6 在清除后仍为 1(鼠标待处理,没接鼠标时的真机状态,模拟器为 0)。`$4036` 运行中的当前值取决于读取时刻,通用 DMA 在 `$8010` 起的采样取决于源 RAM 里原来的内容,`$4015` 位 4 取决于读取时刻(同一个写入值两遍读回不同,像 DMC 的活动状态位),模拟器用的是同类逻辑,无法逐值比对;`$4023` 位 7 在 `hwprobe` 里一直为 1(`hwtest` 报告里“写 1、写 0 后读到 `01`、`00`”是编译器省掉了写后的回读,不是真机值,`$4022` 写后的“读回”也一样,只有测前的值是真读),模拟器按 1 处理 | 真机实测(`hwtest`);模拟器没有对齐 |
28
+ | 并口打印机 | 模拟器实现了 Epson ESC/P 虚拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。芯片手册只定义了 `$4016` 的位 1、0(OUT1、OUT0)、`$4017` 的位 0、`$4025`(数据寄存器,写入时产生选通)与 `$4026`(EIO7-EIO0);这里 `$4016` 位 2、`$4017` 位 2、3 的用法来自模拟器源码的注释,芯片手册没有定义,真机没有核实。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
20
29
  | 语音端口 `$4302` | 读:位 7 为 1 表示可以接收下一个字节(缓冲未满),语音播完时低 4 位为 `$F`。写:把一个语音数据字节送进环形缓冲,由模拟器的 LPC 语音线程解码播放。`$4026` 位 6 的上升沿复位语音(清缓冲)。BIOS 的 `$74`、`$75`(`API_74_PORT4302_CONTROL`、`API_75_PORT4302_SEND`)就是操作它 | 已确认(模拟器源码);`$74`、`$75` 的发送序列与“播完”结束都已实测(见 [系统调用手册](02-系统调用手册.md) 5.13 节);模拟器曾缺 `case 0x4302:`,已修复 |
21
30
 
22
31
  ## 软件环境
@@ -25,6 +25,8 @@
25
25
  | 事项 | 说明 |
26
26
  | --- | --- |
27
27
  | 内核集成进 VS Code 面板 | 只要调试服务协议不变,`fcdev` 不用改 |
28
+ | 外设读数与真机对齐 | `hwtest` 在真机与模拟器上仍有差异的读数(`$4015` 位 4、`$4022` 开机值、`$4026`、`$4016`、`$4017`、`$4033` 位 6、`$3FFF`),具体数值见 [03-硬件说明](sb2000/03-硬件说明.md) 的“真机与模拟器仍有差异的行为”;程序不应依赖这些值,是否对齐由用户决定。|
29
+ | `runnes` 与 `play` 的 DMA 写法 | 两个程序借用程序窗口 2(`$A000`)做 DMA 目的,真机上失败,模拟器对齐真机后也失败(`runnes` 现在用库函数 `sb_dma_to_cpu`,目的在窗口时函数直接返回出错、不复制);改成先 DMA 到 ERAM 缓冲再用 CPU 搬(参考 `apps/sb2000/bbk-loader`) |
28
30
 
29
31
  ## 4. 目标
30
32
 
@@ -40,6 +42,6 @@
40
42
  | 事项 | 说明 |
41
43
  | --- | --- |
42
44
  | 其他映射器 | 现在只支持 NROM 与平铺二进制;其他映射器需要目标提供地址映射 |
43
- | 跳转表识别 | 例程内联的跳转表(如 `RTS` 跳转表)追踪不到,这部分按数据输出 |
45
+ | 跳转表识别 | 已识别 `LDA 表,X` 加间接 `JMP`、`PHA`/`RTS` 的表和 `JMP (地址)` 指向的表;例程内联的跳转表(`JSR` 之后紧跟地址表)、立即数拼出的分发指针还追不到,这部分按数据输出;补全覆盖靠运行记录:模拟器 `trace ... unique` 在步步高机型上可用,CDL 只对 SB2K 映射器有效,对步步高 RAM 里的程序没用。立即数拼出的指针可以让 `fcdev` 列出“可能的入口”供人工确认,还没做 |
44
46
  | 地址表与字符串识别 | 现在没追到的字节都是 `ByteTable` |
45
47
  | SB2000 固件页的 CDL 验证 | 没有做;模拟器自带 CDL 只对 SB2K 映射器有效 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fcdev",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
4
4
  "description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
5
5
  "license": "Apache-2.0",
6
6
  "author": "sungbin <sungbin@3578.cn>",
@@ -25,12 +25,12 @@
25
25
  },
26
26
  "files": [
27
27
  "bin",
28
+ "CHANGELOG.md",
28
29
  "docs",
29
30
  "src",
30
31
  "targets"
31
32
  ],
32
33
  "optionalDependencies": {
33
- "@rujianjs/fcdev-cc65": "0.4.0",
34
- "@rujianjs/fcdev-emulator": "0.4.0"
34
+ "fcdev-cc65": "0.6.0"
35
35
  }
36
36
  }
@@ -38,14 +38,14 @@ export async function runApiCommand({ positionals, options, context }) {
38
38
  }
39
39
  const lines = [`${target.title} 的 C 接口:${functions.length} 个函数,${groups.size} 个模块`, ''];
40
40
  for (const [name, items] of groups) lines.push(` ${name.padEnd(10)} ${String(items.length).padStart(3)} 个函数 ${items[0].header}`);
41
- lines.push('', '查询:fcdev api <函数名>(完整文档)、fcdev api <模块名>(函数列表)、fcdev api <$功能号>(用到该系统调用的函数)、fcdev api <词>(按名称与说明搜索)');
41
+ lines.push('', '查询:npx fcdev api <函数名>(完整文档)、npx fcdev api <模块名>(函数列表)、npx fcdev api <$功能号>(用到该系统调用的函数)、npx fcdev api <词>(按名称与说明搜索)');
42
42
  context.stdout.write(`${lines.join('\n')}\n`);
43
43
  return 0;
44
44
  }
45
45
 
46
46
  const { kind, matches } = queryApi(functions, query);
47
47
  if (matches.length === 0) {
48
- throw new FcdevError(`没有找到“${query}”`, { code: 'API_NOT_FOUND', hint: '不带查询词运行 fcdev api 可以看到全部模块' });
48
+ throw new FcdevError(`没有找到“${query}”`, { code: 'API_NOT_FOUND', hint: '不带查询词运行 npx fcdev api 可以看到全部模块' });
49
49
  }
50
50
  if (options.json) {
51
51
  context.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
@@ -18,7 +18,7 @@ import { FcdevError } from '../../shared/index.mjs';
18
18
  */
19
19
  export async function runBuildCommand({ positionals, options, context }) {
20
20
  if (positionals.length > 1) {
21
- throw new FcdevError('build 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev build [目录或文件]' });
21
+ throw new FcdevError('build 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev build [目录或文件]' });
22
22
  }
23
23
  const reporter = {
24
24
  log: (message) => context.stdout.write(`${message}\n`),
@@ -4,7 +4,7 @@
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
7
+ // 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace、tape 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
8
8
  // ------------------------------------------------------------------------
9
9
  import path from 'node:path';
10
10
  import { DEFAULT_DEBUG_PORT, DebugClient } from '../../emulator/index.mjs';
@@ -39,6 +39,9 @@ export function resolveCommandPaths(tokens, cwd) {
39
39
  if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
40
40
  return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
41
41
  }
42
+ if (name === 'tape' && (rest[0] === 'play' || rest[0] === 'rec') && rest[1]) {
43
+ return [name, rest[0], path.resolve(cwd, rest.slice(1).join(' '))];
44
+ }
42
45
  const position = PATH_POSITIONS[name];
43
46
  if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
44
47
  if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
@@ -55,7 +58,7 @@ export function resolveCommandPaths(tokens, cwd) {
55
58
  */
56
59
  export async function runDebugCommand({ positionals, context }) {
57
60
  if (positionals.length === 0) {
58
- throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:fcdev debug status、fcdev debug run 60、fcdev debug shot out.png' });
61
+ throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug status、npx fcdev debug run 60、npx fcdev debug shot out.png' });
59
62
  }
60
63
  const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
61
64
  const tokens = resolveCommandPaths(positionals, context.cwd);
@@ -37,7 +37,7 @@ export function parseAddress(text, option) {
37
37
  */
38
38
  export async function runDisasmCommand({ positionals, options, context }) {
39
39
  if (positionals.length !== 1) {
40
- throw new FcdevError('disasm 需要一个输入文件', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--symbols 文件] [--out 目录]' });
40
+ throw new FcdevError('disasm 需要一个输入文件', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--symbols 文件] [--out 目录]' });
41
41
  }
42
42
  const inputFile = path.resolve(context.cwd, positionals[0]);
43
43
  const config = loadProjectConfig(context.cwd, context.cwd);
@@ -18,7 +18,7 @@ import { FcdevError } from '../../shared/index.mjs';
18
18
  */
19
19
  export async function runDiskCommand({ positionals, options, context }) {
20
20
  if (positionals.length > 1) {
21
- throw new FcdevError('disk 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disk [目录或文件]' });
21
+ throw new FcdevError('disk 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev disk [目录或文件]' });
22
22
  }
23
23
  const reporter = {
24
24
  log: (message) => context.stdout.write(`${message}\n`),
@@ -31,14 +31,14 @@ export async function runDocsCommand({ positionals, options, context }) {
31
31
  const width = Math.max(...docs.map((doc) => doc.topic.length));
32
32
  const lines = [`fcdev 开发文档:${docs.length} 份`, `本机目录:${directory}`, ''];
33
33
  for (const doc of docs) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
34
- lines.push('', '查询:fcdev docs <主题>(本机路径)、fcdev docs <词>(按主题、文件名、标题与说明搜索)');
34
+ lines.push('', '查询:npx fcdev docs <主题>(本机路径)、npx fcdev docs <词>(按主题、文件名、标题与说明搜索)');
35
35
  context.stdout.write(`${lines.join('\n')}\n`);
36
36
  return 0;
37
37
  }
38
38
 
39
39
  const { kind, matches } = queryDocs(query);
40
40
  if (matches.length === 0) {
41
- throw new FcdevError(`没有找到“${query}”`, { code: 'DOCS_NOT_FOUND', hint: '不带查询词运行 fcdev docs 可以看到全部主题' });
41
+ throw new FcdevError(`没有找到“${query}”`, { code: 'DOCS_NOT_FOUND', hint: '不带查询词运行 npx fcdev docs 可以看到全部主题' });
42
42
  }
43
43
  if (options.json) {
44
44
  context.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
@@ -52,7 +52,7 @@ export async function runDocsCommand({ positionals, options, context }) {
52
52
  const width = Math.max(...matches.map((doc) => doc.topic.length));
53
53
  const lines = [`包含“${query}”的文档:${matches.length} 份(${kind === 'file' ? '按文件名' : '按关键词'})`];
54
54
  for (const doc of matches) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
55
- lines.push('', '用 fcdev docs <主题> 查看某份文档的本机路径');
55
+ lines.push('', '用 npx fcdev docs <主题> 查看某份文档的本机路径');
56
56
  context.stdout.write(`${lines.join('\n')}\n`);
57
57
  return 0;
58
58
  }
@@ -20,7 +20,7 @@ import { FcdevError } from '../../shared/index.mjs';
20
20
  */
21
21
  export async function runRunCommand({ positionals, options, context }) {
22
22
  if (positionals.length > 1) {
23
- throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev run [目录或文件]' });
23
+ throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev run [目录或文件]' });
24
24
  }
25
25
  const reporter = {
26
26
  log: (message) => context.stdout.write(`${message}\n`),
@@ -62,7 +62,7 @@ export async function runRunCommand({ positionals, options, context }) {
62
62
  context.stdout.write(`等 DOS 启动后,在提示符下输入 ${path.basename(result.outputFile, path.extname(result.outputFile))} 运行程序\n`);
63
63
  }
64
64
  if (options.debug) {
65
- context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 fcdev debug run 60\n`);
65
+ context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 npx fcdev debug run 60\n`);
66
66
  }
67
67
  return 0;
68
68
  }
@@ -0,0 +1,161 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:address-tables.mjs
3
+ // 说明:在已追踪的代码里找经地址表分发的跳转:从表里读出目标地址,供静态追踪继续追下去。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-13
7
+ // 备注:识别的写法(窗口为紧随加载指令之后的 10 条顺序指令):
8
+ // 1. LDA 表,X/Y 与 LDA 表+1,X/Y 成对,窗口内有间接 JMP:字表,目标就是表里的值;
9
+ // 2. 一对加载指令,窗口内有两条 PHA 与一条 RTS:目标是表里的值加 1;表是字表(两个加载地址相差 1)或低、高字节分开的两张表;
10
+ // 3. 间接 JMP 的地址指向映像内未识别的字节:表项是目标。
11
+ // 表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束;单张表最多 128 项。
12
+ // ------------------------------------------------------------------------
13
+ import { KIND_ADDRESS, KIND_OPCODE, KIND_UNKNOWN } from './byte-kinds.mjs';
14
+ import { OPCODES } from './opcode-table.mjs';
15
+
16
+ const LDA_ABS_Y = 0xb9;
17
+ const LDA_ABS_X = 0xbd;
18
+ const PHA = 0x48;
19
+ const RTS = 0x60;
20
+ const JMP_INDIRECT = 0x6c;
21
+
22
+ /** 加载指令之后检查的顺序指令条数 */
23
+ const WINDOW = 10;
24
+
25
+ /** 单张表的最大项数 */
26
+ const MAX_ENTRIES = 128;
27
+
28
+ /**
29
+ * @typedef {object} AddressTable
30
+ * @property {string} key 表的标识,同一张表只返回一次
31
+ * @property {number|null} wordOffset 字表在映像里的偏移;分开的两张表为 null
32
+ * @property {number[]} targets 表里读出的目标地址
33
+ */
34
+
35
+ /**
36
+ * 判断一个目标地址能不能作为代码入口。
37
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
38
+ * @param {number} target 目标地址
39
+ * @returns {boolean} 在映像内、是官方操作码、不在已识别指令中间
40
+ */
41
+ function isCodeTarget({ bytes, base, kinds }, target) {
42
+ const offset = target - base;
43
+ if (offset < 0 || offset >= bytes.length) return false;
44
+ if (OPCODES[bytes[offset]] === null) return false;
45
+ return kinds[offset] === KIND_UNKNOWN || kinds[offset] === KIND_OPCODE;
46
+ }
47
+
48
+ /**
49
+ * 从字表的偏移处读出连续的目标,遇到不能当入口的值或已识别的字节就停止。
50
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
51
+ * @param {number} start 表在映像里的偏移
52
+ * @param {number} adjust 加到每个值上的偏移,RTS 表为 1
53
+ * @returns {number[]} 目标地址
54
+ */
55
+ function readWordTable(image, start, adjust) {
56
+ const { bytes, kinds } = image;
57
+ const targets = [];
58
+ for (let offset = start; offset + 1 < bytes.length && targets.length < MAX_ENTRIES; offset += 2) {
59
+ if (kinds[offset] !== KIND_UNKNOWN || kinds[offset + 1] !== KIND_UNKNOWN) break;
60
+ const target = (bytes.readUInt16LE(offset) + adjust) & 0xffff;
61
+ if (!isCodeTarget(image, target)) break;
62
+ targets.push(target);
63
+ }
64
+ return targets;
65
+ }
66
+
67
+ /**
68
+ * 读出低、高字节分开的两张表。
69
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
70
+ * @param {number} lowOffset 低字节表的偏移
71
+ * @param {number} highOffset 高字节表的偏移
72
+ * @returns {number[]} 目标地址(已加 1)
73
+ */
74
+ function readSplitTable(image, lowOffset, highOffset) {
75
+ const { bytes, kinds } = image;
76
+ const targets = [];
77
+ while (targets.length < MAX_ENTRIES) {
78
+ const low = lowOffset + targets.length;
79
+ const high = highOffset + targets.length;
80
+ if (low >= bytes.length || high >= bytes.length || kinds[low] !== KIND_UNKNOWN || kinds[high] !== KIND_UNKNOWN) break;
81
+ const target = ((bytes[high] << 8) | bytes[low]) + 1;
82
+ if (!isCodeTarget(image, target & 0xffff)) break;
83
+ targets.push(target & 0xffff);
84
+ }
85
+ return targets;
86
+ }
87
+
88
+ /**
89
+ * 取出某条指令之后的顺序指令的偏移,遇到未识别的字节就停止。
90
+ * @param {{bytes: Buffer, kinds: Uint8Array}} image 映像与分类
91
+ * @param {number} offset 起点指令的偏移
92
+ * @returns {number[]} 起点之后最多 WINDOW 条指令的偏移
93
+ */
94
+ function followingInstructions({ bytes, kinds }, offset) {
95
+ const result = [];
96
+ let current = offset + OPCODES[bytes[offset]][1];
97
+ while (result.length < WINDOW && current < bytes.length && kinds[current] === KIND_OPCODE) {
98
+ result.push(current);
99
+ current += OPCODES[bytes[current]][1];
100
+ }
101
+ return result;
102
+ }
103
+
104
+ /**
105
+ * 查找经地址表分发的跳转,只返回还没有返回过的表。
106
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array, seen: Set<string>}} input 映像、分类与已返回过的表的标识
107
+ * @returns {AddressTable[]} 新找到的表
108
+ */
109
+ export function findAddressTables({ bytes, base, kinds, seen }) {
110
+ const image = { bytes, base, kinds };
111
+ const found = [];
112
+ const add = (key, wordOffset, targets) => {
113
+ if (seen.has(key) || targets.length === 0) return;
114
+ seen.add(key);
115
+ found.push({ key, wordOffset, targets });
116
+ };
117
+
118
+ for (let offset = 0; offset < bytes.length; offset += 1) {
119
+ if (kinds[offset] !== KIND_OPCODE) continue;
120
+ const opcode = bytes[offset];
121
+
122
+ if (opcode === JMP_INDIRECT) {
123
+ const tableOffset = bytes.readUInt16LE(offset + 1) - base;
124
+ if (tableOffset >= 0 && tableOffset < bytes.length) add(`w:${tableOffset}:0`, tableOffset, readWordTable(image, tableOffset, 0));
125
+ continue;
126
+ }
127
+ if (opcode !== LDA_ABS_X && opcode !== LDA_ABS_Y) continue;
128
+
129
+ const window = followingInstructions(image, offset);
130
+ const loads = [offset, ...window.filter((index) => bytes[index] === LDA_ABS_X || bytes[index] === LDA_ABS_Y)];
131
+ if (loads.length < 2) continue;
132
+ const addresses = loads.map((index) => bytes.readUInt16LE(index + 1) - base);
133
+ const pushes = window.filter((index) => bytes[index] === PHA).length;
134
+ const returns = window.some((index) => bytes[index] === RTS);
135
+ const indirect = window.some((index) => bytes[index] === JMP_INDIRECT);
136
+
137
+ if (indirect) {
138
+ // 两条加载的地址相差 1:字表在较小的地址上
139
+ const low = Math.min(addresses[0], addresses[1]);
140
+ if (Math.abs(addresses[0] - addresses[1]) === 1 && low >= 0 && low < bytes.length) add(`w:${low}:0`, low, readWordTable(image, low, 0));
141
+ } else if (pushes >= 2 && returns) {
142
+ // 先压入高字节再压入低字节,RTS 返回到“表里的值加 1”
143
+ const high = addresses[0];
144
+ const low = addresses[1];
145
+ if (high < 0 || low < 0 || high >= bytes.length || low >= bytes.length) continue;
146
+ if (Math.abs(high - low) === 1 && low < high) add(`w:${low}:1`, low, readWordTable(image, low, 1));
147
+ else if (Math.abs(high - low) > 1) add(`s:${low}:${high}`, null, readSplitTable(image, low, high));
148
+ }
149
+ }
150
+ return found;
151
+ }
152
+
153
+ /**
154
+ * 把字表占的字节标成地址。
155
+ * @param {Uint8Array} kinds 每个字节的分类
156
+ * @param {AddressTable} table 字表
157
+ */
158
+ export function markWordTable(kinds, table) {
159
+ if (table.wordOffset === null) return;
160
+ for (let index = 0; index < table.targets.length * 2; index += 1) kinds[table.wordOffset + index] = KIND_ADDRESS;
161
+ }
@@ -1,23 +1,19 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:analysis.mjs
3
- // 说明:静态追踪:从入口出发沿控制流标出哪些字节是指令的操作码、哪些是操作数;CDL 里的代码段起点也当作入口。
3
+ // 说明:静态追踪:从入口出发沿控制流标出哪些字节是指令的操作码、哪些是操作数;CDL 里的代码段起点也当作入口;追完后再从地址表里找新入口。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
- // 日期:2026-11-10
6
+ // 日期:2026-11-13
7
7
  // 备注:处理规则:顺序执行继续,条件分支两路都追,JMP 只追目标,JSR 追目标并假定会返回,RTS、RTI、BRK、间接 JMP 结束这一路;
8
8
  // 遇到非法操作码、越界或与已识别指令重叠时放弃这一路并记入警告。没被追到的字节都算数据,这不影响回读校验(da65 对非法操作码输出 .byte)。
9
+ // 待办的入口追完后,查找经地址表分发的跳转(见 address-tables.mjs),表里的目标成为新入口,直到没有新表。
9
10
  // ------------------------------------------------------------------------
11
+ import { findAddressTables, markWordTable } from './address-tables.mjs';
12
+ import { KIND_OPCODE, KIND_OPERAND, KIND_UNKNOWN } from './byte-kinds.mjs';
10
13
  import { CDL_CODE } from './cdl.mjs';
11
14
  import { OPCODES } from './opcode-table.mjs';
12
15
 
13
- /** 字节分类:没有被标成指令 */
14
- export const KIND_UNKNOWN = 0;
15
-
16
- /** 字节分类:指令的第一个字节 */
17
- export const KIND_OPCODE = 1;
18
-
19
- /** 字节分类:指令的操作数 */
20
- export const KIND_OPERAND = 2;
16
+ export { KIND_ADDRESS, KIND_OPCODE, KIND_OPERAND, KIND_UNKNOWN } from './byte-kinds.mjs';
21
17
 
22
18
  /**
23
19
  * @typedef {object} Analysis
@@ -53,7 +49,17 @@ export function analyzeCode({ bytes, base, entries, cdl = null }) {
53
49
  }
54
50
  }
55
51
 
56
- while (pending.length > 0) {
52
+ const seenTables = new Set();
53
+ const discoverTables = () => {
54
+ const tables = findAddressTables({ bytes, base, kinds, seen: seenTables });
55
+ for (const table of tables) {
56
+ markWordTable(kinds, table);
57
+ pending.push(...table.targets);
58
+ }
59
+ return tables.length > 0;
60
+ };
61
+
62
+ while (pending.length > 0 || discoverTables()) {
57
63
  let address = pending.pop();
58
64
  // 沿着顺序执行一路走下去,遇到分支目标或调用目标就放进待办
59
65
  for (;;) {
@@ -0,0 +1,20 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:byte-kinds.mjs
3
+ // 说明:反汇编分析里每个字节的分类常量。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-13
7
+ // 备注:无
8
+ // ------------------------------------------------------------------------
9
+
10
+ /** 字节分类:没有被标成指令或地址表 */
11
+ export const KIND_UNKNOWN = 0;
12
+
13
+ /** 字节分类:指令的第一个字节 */
14
+ export const KIND_OPCODE = 1;
15
+
16
+ /** 字节分类:指令的操作数 */
17
+ export const KIND_OPERAND = 2;
18
+
19
+ /** 字节分类:地址表里的字节,两个字节一个地址 */
20
+ export const KIND_ADDRESS = 3;
@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
10
10
  import path from 'node:path';
11
11
  import { FcdevError } from '../shared/index.mjs';
12
12
  import { runTool } from '../toolchain/index.mjs';
13
- import { KIND_UNKNOWN, analyzeCode } from './analysis.mjs';
13
+ import { analyzeCode } from './analysis.mjs';
14
+ import { KIND_OPCODE, KIND_OPERAND } from './byte-kinds.mjs';
14
15
  import { parseCdl } from './cdl.mjs';
15
16
  import { buildRanges, renderInfo } from './info-writer.mjs';
16
17
  import { loadBinary, loadInes } from './loaders.mjs';
@@ -99,7 +100,7 @@ export async function disassemble({ inputFile, format, base, entries = [], cdlFi
99
100
  });
100
101
  }
101
102
 
102
- const codeBytes = analysis.kinds.reduce((count, value) => count + (value === KIND_UNKNOWN ? 0 : 1), 0);
103
+ const codeBytes = analysis.kinds.reduce((count, value) => count + (value === KIND_OPCODE || value === KIND_OPERAND ? 1 : 0), 0);
103
104
  return {
104
105
  sourceFile,
105
106
  infoFile,