fcdev 0.6.0 → 0.8.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 (51) hide show
  1. package/CHANGELOG.md +61 -32
  2. package/README.md +17 -16
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +14 -12
  4. package/docs/02-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +89 -0
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +13 -47
  6. package/docs/{07- → 04-}/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +1 -15
  7. package/docs/nes/{01-NES/347/233/256/346/240/207.md → 01-/345/274/200/345/217/221/346/214/207/345/215/227.md} +4 -9
  8. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +25 -30
  9. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +4 -4
  10. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +5 -5
  11. package/package.json +5 -2
  12. package/src/build/bank-link-config.mjs +1 -1
  13. package/src/build/build-plan.mjs +1 -1
  14. package/src/build/program-builder.mjs +10 -5
  15. package/src/build/source-charset.mjs +111 -0
  16. package/src/cli/args-parser.mjs +1 -1
  17. package/src/cli/commands/debug-command.mjs +20 -58
  18. package/src/cli/commands/docs-command.mjs +2 -2
  19. package/src/cli/commands/run-command.mjs +36 -39
  20. package/src/cli/index.mjs +5 -5
  21. package/src/config/config-loader.mjs +2 -2
  22. package/src/disasm/disassembler.mjs +1 -1
  23. package/src/disasm/trace.mjs +4 -3
  24. package/src/docs/doc-index.mjs +1 -1
  25. package/src/docs/doc-topics.mjs +32 -38
  26. package/src/docs/index.mjs +1 -1
  27. package/src/emulator/debug-cli.mjs +48 -0
  28. package/src/emulator/emulator-launcher.mjs +107 -29
  29. package/src/emulator/emulator-locator.mjs +7 -7
  30. package/src/emulator/index.mjs +4 -3
  31. package/src/emulator/sb2000-session.mjs +104 -0
  32. package/src/targets/target-registry.mjs +9 -1
  33. package/targets/nes/lib/fcnes.lib +0 -0
  34. package/targets/nes/lib/nes-font.o +0 -0
  35. package/targets/nes/target.json +1 -1
  36. package/targets/sb2000/api-reference.md +2 -1
  37. package/targets/sb2000/examples-source.md +1330 -0
  38. package/targets/sb2000/lib/crt0.o +0 -0
  39. package/targets/sb2000/lib/sb2000.lib +0 -0
  40. package/targets/sb2000/symbols-reference.md +670 -0
  41. package/targets/sb2000/target.json +2 -1
  42. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -163
  43. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  44. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  45. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +0 -92
  46. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -72
  47. package/docs/09-/345/217/221/345/270/203.md +0 -70
  48. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  49. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -47
  50. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
  51. package/src/emulator/debug-client.mjs +0 -125
@@ -1,6 +1,6 @@
1
1
  # SB2000 开发指南
2
2
 
3
- 用 fcdev 为小霸王学习机 SB2000 的 DOS(SB-DOS 2.00)开发程序:构建出能在 DOS 提示符下运行的 `.EXE`。本文说明 SB2000 目标的定义、程序格式、内存布局、运行库与常用做法;全部系统调用的参数与结果见 [系统调用手册](02-系统调用手册.md),硬件行为见 [硬件说明](03-硬件说明.md)。目标目录是 [packages/fcdev/targets/sb2000](../../targets/sb2000),字段含义见 [03-目标规范](../03-目标规范.md)。本文只写已经在模拟器里验证过的用法,没验证的在第 11 节列出。
3
+ 用 fcdev 为小霸王学习机 SB2000 的 DOS(SB-DOS 2.00)开发程序:构建出能在 DOS 提示符下运行的 `.EXE`。本文说明 SB2000 目标的定义、程序格式、内存布局、运行库与常用做法;全部系统调用的参数与结果见 [系统调用手册](02-系统调用手册.md),硬件行为见 [硬件说明](03-硬件说明.md)。目标的定义与运行库随 `fcdev` 包安装,在包里的 `targets/sb2000/` 下。本文只写已经在模拟器里验证过的用法,没验证的在第 11 节列出。
4
4
 
5
5
  ## 1. 目标定义
6
6
 
@@ -16,6 +16,7 @@
16
16
  | 目标专用选项 | `banks`:数字,库页个数,默认 0(普通程序),最大 113 |
17
17
  | 产物 | 大写主名的 `.EXE` |
18
18
  | 程序名规则 | `dos-8.3` |
19
+ | 源文件编码 | UTF-8,构建时转成 GB2312,见第 5 节 |
19
20
  | 磁盘镜像 | `fat-floppy`,1.44MB |
20
21
  | 运行方案 | `firmware-disk`,需要固件 |
21
22
 
@@ -57,7 +58,7 @@ DOS 只按文件大小给程序分配扩展 RAM 页,而 `BSS` 与软件栈在
57
58
  | 3 | 栈页:窗口 3,C 软件栈在它的顶端 1K,不放程序内容,不能当库页 | `$B000` |
58
59
  | 4 起 | 库页 2 到 N | `$A000` |
59
60
 
60
- 链接配置由 [link-banked.cfg](../../targets/sb2000/link-banked.cfg) 按库页个数展开成中间文件目录里的 `<程序名>.cfg`(规则见 [03-目标规范](../03-目标规范.md) 第 2.3 节);库页 n 的段名是 `BANKn`,一页放不下时 `ld65` 链接失败;程序里用到的库页号超过 `banks` 时,链接失败并提示加大 `banks`。
61
+ 链接配置由 [link-banked.cfg](../../targets/sb2000/link-banked.cfg) 按库页个数展开成中间文件目录里的 `<程序名>.cfg`;库页 n 的段名是 `BANKn`,一页放不下时 `ld65` 链接失败;程序里用到的库页号超过 `banks` 时,链接失败并提示加大 `banks`。
61
62
 
62
63
  写法(头文件 [sb2000-bank.h](../../targets/sb2000/include/sb2000-bank.h),`sb2000.h` 已包含):
63
64
 
@@ -113,13 +114,18 @@ C 的最小程序(模板里的 `src/hello.c`):
113
114
  int main(void)
114
115
  {
115
116
  sb_puts("Hello, SB2000!");
116
- /* GB2312:你好,小霸王! */
117
- sb_puts("\xC4\xE3\xBA\xC3\xA3\xAC\xD0\xA1\xB0\xD4\xCD\xF5\xA3\xA1");
117
+ sb_puts("你好,小霸王!");
118
118
  sb_getkey(); /* DOS 在程序返回后会清屏,不等待就看不到输出 */
119
119
  return 0;
120
120
  }
121
121
  ```
122
122
 
123
+ 汉字直接写在源文件里:源文件用 UTF-8 保存,构建时 fcdev 把每个 `.c`、`.s`、`.asm` 整个转成学习机用的 GB2312(一个汉字两个字节),注释里的汉字也一起转,编译器拿到的已经是 GB2312。需要留意:
124
+
125
+ - 只支持 GB2312 的符号区与汉字区,机器的字库就这些;其他字符(表情、生僻字等)构建报错,写出文件、行、列。
126
+ - 头文件不转换,汉字写在 `.c` 文件里;编译错误仍指向你写的源文件与原行号。
127
+ - 源文件如果已经存成 GB2312(不是合法的 UTF-8),就原样使用;也可以继续用 `"\xC4\xE3"` 这样的转义直接写字节。
128
+
123
129
  汇编程序导出 `_main`,由启动代码调用;`_sb_puts`、`_sb_getkey` 来自目标自带的库,参数用 cc65 的 fastcall:指针在 A(低)与 X(高),见模板 `sb2000-asm`。
124
130
 
125
131
  程序名取 `fcdev.json` 的 `name`,要符合 DOS 8.3 规则,且不要与 DOS 内部命令重名(如 `COPY`、`TYPE`、`DIR`),重名时先被当成内部命令。
@@ -127,10 +133,10 @@ int main(void)
127
133
  ```bash
128
134
  npx fcdev build src # 生成 build/sb2000/<NAME>.EXE
129
135
  npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
130
- npx fcdev run src # 构建,挂载镜像,在模拟器里运行
136
+ npx fcdev run src # 构建后在 Ember 里运行(需要 firmware);加 --debug 停在开机状态
131
137
  ```
132
138
 
133
- `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
139
+ `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,没有设置时在构建之前报错。它把程序做成磁盘镜像挂到软驱,开机后自动在 SB-DOS 里跳过日期与时间、输入程序名运行(程序名只能用字母与数字);`--debug` 停在开机状态,由自己用 `fcdev debug` 操作,细节见 [02-模拟器与调试](../02-模拟器与调试.md) 第 3 节与第 6 节。本文下面写到的调试操作用 Ember 调试服务的请求表示。
134
140
 
135
141
  ## 6. 头文件与函数
136
142
 
@@ -160,14 +166,11 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
160
166
  - 命名 `sb_<模块>_<动作>`;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
161
167
  - dma、ppu、timer 三个模块直接读写硬件寄存器,不经系统调用,没有 `@syscall`;寄存器地址与位的符号是 `sb2000-symbols.h` 里以 `SB_HW_` 开头的常量,程序不要再自己定义。行为以真机实测为准,见 [硬件说明](03-硬件说明.md)。
162
168
  - 字符串、缓冲区、结构体指针必须在程序窗口 `$8000` 到 `$BFFF` 里(读写目标不能在窗口 3);系统服务换页后程序窗口不可见的情况,函数内部已经处理好。
163
- - 一个函数一个源文件,放在 `src/lib/<模块>/sb-<函数名>.c`(或 `.s`);库内部用的辅助函数以 `sbi_` 开头,声明在 `src/lib/sb-internal.h`,不对外。
164
- - 运行库由 `tools/build-libs.mjs` 编译:`lib-build.json` 里以 `/` 结尾的项展开成目录下全部 `.c` 与 `.s`;`.c` 用 `cc65 -t none --cpu 6502 -Oirs` 编译再汇编,同名文件报错。链接只带入程序用到的函数。
165
169
 
166
170
  随时查询接口:
167
171
 
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)。
169
- - [api-reference.md](../../targets/sb2000/api-reference.md) 是同一份文档的整本 Markdown,由 `node tools/gen-sb2000-api-doc.mjs` 从头文件生成,末尾有“系统调用覆盖表”。改头文件注释后重新生成,测试会核对。
170
- - [api-unwrapped.json](../../targets/sb2000/api-unwrapped.json) 登记没有封装的功能号与子功能及原因(`functions` 是整个功能号不封装,`partial` 是封装了一部分)。`node tools/check-sb2000-api.mjs` 检查:头文件里每个函数有说明、`@param`、`@return`,有且只有一处实现,库里没有头文件之外的公开函数,BIOS 里有处理例程的每个功能号(`KNOWN_FUNCTIONS`)要么被某个函数的 `@syscall` 涉及、要么在 `functions` 里写明原因。
172
+ - `npx fcdev api` 列出全部模块;`npx fcdev api <函数名>` 看完整文档;`npx fcdev api <模块名>` 看函数列表;`npx fcdev api '$7B'` 或 `npx fcdev api '$7B/$09'` 看用到某个系统调用的函数;`npx fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [01-命令行与构建](../01-命令行与构建.md)。
173
+ - [SB2000 C 接口参考](../../targets/sb2000/api-reference.md)是同一份文档的完整版,末尾有“系统调用覆盖表”,登记了没有封装的功能号与原因。
171
174
 
172
175
  不封装的内容(详见覆盖表):文件系统内部步骤(FAT、簇链、扇区定位)、`$41` 到 `$44` 带步长的屏幕单元写入、`$31` 与 `$34` 的显存填充与 DMA 变体、`$66` 卡拉 OK、`$65` 与 `$6D` 的部分子功能、`$74` 与 `$75` 的 NMI 发送与播放列表等,需要时用 `sb_syscall` 加 `sb2000-symbols.h` 里的常量自行调用。
173
176
 
@@ -175,12 +178,12 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
175
178
 
176
179
  ## 7. 符号定义
177
180
 
178
- - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、硬件寄存器与位(`HW_` 开头)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
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` 里加符号(功能号、子功能号、参数与结果单元、出错码),再重新生成。
181
+ - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、硬件寄存器与位(`HW_` 开头)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义;按分节列出全部符号的汇编名、C 名与值的整本表见 [SB2000 符号参考](../../targets/sb2000/symbols-reference.md)。
182
+ - [include/sb2000-symbols.h](../../targets/sb2000/include/sb2000-symbols.h) 是 C 用的同一份符号,每个符号对应一个 `SB_` 前缀的数值宏,不要手工修改。符号行尾的注释会变成宏上方的 `/** */` 文档注释,编辑器悬停时显示;各模块头文件里的函数也用 `/** */` 与 `@param`、`@return`、`@syscall` 写文档。
180
183
 
181
184
  ## 8. 常用做法
182
185
 
183
- 下面每一项都有可参考的示例程序(第 10 节)。表里的符号名(`SYS_FUNCTION`、`FN_INPUT` 等)是汇编用的 `sb2000.inc` 里的名字,C 里加 `SB_` 前缀(第 7 节);C 程序一般直接用第 6 节的函数。
186
+ 下面大多数项有可参考的示例程序(第 10 节,源码见 [SB2000 示例程序源码](../../targets/sb2000/examples-source.md)),没有示例的写“—”。表里的符号名(`SYS_FUNCTION`、`FN_INPUT` 等)是汇编用的 `sb2000.inc` 里的名字,C 里加 `SB_` 前缀(第 7 节);C 程序一般直接用第 6 节的函数。
184
187
 
185
188
  | 要做的事 | 做法 | 示例 |
186
189
  | --- | --- | --- |
@@ -198,9 +201,9 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
198
201
  | 读鼠标 | `$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` |
199
202
  | 播放 WAV | 功能 `$65`、子功能 `$0C`(`SUB_SOUND_WAV`,C 里是 `sb_sound_play_wav`),见 [系统调用手册](02-系统调用手册.md) 5.5(只读过代码,没有示例) | — |
200
203
  | 把 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` |
204
+ | 用 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` 搬 | — |
205
+ | 直接写显存、调色板、精灵 | `sb_display_off()` 关显示,用 `sb_ppu_*` 读写显存、调色板与精灵 RAM,`sb_ppu_render` 打开显示,用完再用 `sb_display_on()` 恢复 DOS 的显示 | — |
206
+ | 用定时器计时 | `sb_timer_start(控制, 预置值)` 启动,`sb_timer_pending()` 看下溢标志,`sb_timer_mask()` 清标志;DOS 用它做系统时钟,用完要用 `$EF`、`$3C` 恢复 | — |
204
207
 
205
208
  ## 9. 要避开的坑
206
209
 
@@ -218,9 +221,9 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
218
221
 
219
222
  ## 10. 示例程序
220
223
 
221
- 示例在仓库的 `apps/sb2000/examples/` 下,每个是一个 fcdev 项目;在仓库根目录用 `node packages/fcdev/bin/fcdev.mjs build apps/sb2000/examples/<名>` 构建。
224
+ 下面是本手册提到的示例程序,每个都是一个 fcdev 项目,完整源码见 [SB2000 示例程序源码](../../targets/sb2000/examples-source.md)。
222
225
 
223
- | 目录 | 作用 | 用法(在 DOS 提示符下) |
226
+ | 示例 | 作用 | 用法(在 DOS 提示符下) |
224
227
  | --- | --- | --- |
225
228
  | `hello` | 显示英文与中文各一行 | `hello` |
226
229
  | `say` | 显示命令行参数 | `say 文字` |
@@ -228,11 +231,11 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
228
231
  | `copy` | 复制文件(文件不超过 64K) | `cp 源 目标` |
229
232
  | `peek` | 按十六进制偏移读文件 30 字节 | `peek 文件名 偏移` |
230
233
  | `poke` | 按十六进制偏移把文字写进已有文件(最长 60 个字符,大写) | `poke 文件名 偏移 文字` |
231
- | `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试命令 `pad 0 掩码` 按键) |
232
- | `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试命令 `mouse move dx dy` 移动) |
234
+ | `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试请求 `input.pad port=0 buttons=掩码` 按键) |
235
+ | `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试请求 `input.mouse kind=move dx=横向 dy=纵向` 移动) |
233
236
  | `play` | 把 NES 游戏装入并运行(mapper 0 与 4,PRG、CHR 各不超过 128K) | `play 文件名.nes`(放进软盘镜像的文件名要符合 8.3) |
234
237
  | `newcall` | 调用 BIOS 里新增的系统调用 $35,显示扩展版本号;原始 BIOS 不支持时显示 NOT SUPPORTED(演示给自己修改的 BIOS 做功能检测) | `newcall` |
235
- | `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试命令 `write cpu` 写请求块,格式见源码文件头) |
238
+ | `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试请求 `inspector.writeMemory space=cpu address=0x7E00 bytes=[...]` 写请求块,格式见源码文件头) |
236
239
 
237
240
  ## 11. 限制与没做过的事
238
241
 
@@ -249,11 +252,3 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
249
252
  - 声音服务 `$65` 的音乐数据格式。
250
253
 
251
254
  这些见 [系统调用手册](02-系统调用手册.md) 第 8 节,读懂并验证后补进来。
252
-
253
- ## 12. 运行库的测试
254
-
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,没有时整组跳过。
256
-
257
- 停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
258
-
259
- 接口检查与参考文档的测试在 `test/sb2000-api.test.mjs`,`fcdev api` 命令的测试在 `packages/fcdev/test/api-command.test.mjs`。
@@ -62,7 +62,7 @@
62
62
  - **A、X、Y 与进位标志都不会带回调用者**:服务返回的值只能放在内存变量里,处理例程里的 `SEC`/`CLC` 在返回时会被恢复的 P 覆盖,所以必须读出错码,不能看进位。
63
63
  - 每次调用开头把 `$0640`(`SYS_STATUS`)清 0;个别功能在子功能号超出范围时把它置为 `$FF`。
64
64
  - 内联跳转表(已确认):`JSR $EE76` 之后紧跟 2 字节地址表,A 为下标,直接跳到表项,不回到 JSR 的下一条指令;换页页组里也各有一份同样的例程
65
- - 功能号规则:小于 `$10` 查 RAM 中 `$05FA` 起的表(每项 3 字节,运行时登记);`$10-$3A`、`$65`、`$67-$6C`、`$6E-$75` 用 ROM 表 `$E082 + 2×(功能号−$10)`;`$3B-$64`、`$66`、`$6D`、`$76-$81` 按范围换入页组后进入页内入口;`$82` 以上直接返回。完整的功能号与封装情况见 [api-reference.md](../../targets/sb2000/api-reference.md) 末尾的覆盖表。
65
+ - 功能号规则:小于 `$10` 查 RAM 中 `$05FA` 起的表(每项 3 字节,运行时登记);`$10-$3A`、`$65`、`$67-$6C`、`$6E-$75` 用 ROM 表 `$E082 + 2×(功能号−$10)`;`$3B-$64`、`$66`、`$6D`、`$76-$81` 按范围换入页组后进入页内入口;`$82` 以上直接返回。完整的功能号与封装情况见 [C 接口参考](../../targets/sb2000/api-reference.md)末尾的覆盖表。
66
66
 
67
67
  ## 4. 文件与目录服务
68
68
 
@@ -407,7 +407,7 @@ BIOS 自己带了一段 WAV:ROM 第 `$64` 页起,单声道、8 位、22050 H
407
407
 
408
408
  ## 5.7 画面与中断控制(内核,部分)
409
409
 
410
- 下面只写读过代码、确认过的用法,其余子功能见 [api-reference.md](../../targets/sb2000/api-reference.md):
410
+ 下面只写读过代码、确认过的用法,其余子功能见 [C 接口参考](../../targets/sb2000/api-reference.md):
411
411
 
412
412
  - `$12`(`API_12_PPU_CONTROL`):`$12/$00` 把 PPU 控制寄存器影子(`$062A`)的位 7 清零,即关闭 NMI;`$12/$80` 把位 7 置位,重新打开 NMI。磁盘读写前后就是成对使用(已确认)。子功能低 4 位不大于 6 时还能打开、关闭 NMI 中断里的各项服务(`$0630` 的开关):`$12/$81-$86` 依次置位 `$0630` 的位 7、6、5、4、3、1,`$12/$01-$06` 清这些位(代码阅读)。其中位 3 管 NMI 里读手柄,要用 `$6A` 必须先调用 `$12/$85`(已确认,`pad`);`$12/$85` 还把 `$0634` 置 `$FF`。`NMI_FLAGS` 各位:位 7 条带动画、位 6 声音更新(`NMI_SOUND_UPDATE`)、位 5 与位 4 调用登记的钩子、位 3 读手柄、位 2 精灵 DMA、位 1 把缓冲区内容复制到 `$2040` 起的调色板区域(代码阅读 `interrupt-handlers.asm`)。
413
413
  - `$13`(`API_13_IRQ_MASK`):中断屏蔽影子 `$062F`,写入 `$4032`,位为 1 表示屏蔽(禁止)该中断源,写 1 时硬件还会同时清除 `$4033` 里该源的待处理标志(模拟器源码确认,见[硬件说明](03-硬件说明.md))。子功能 0-6 把位 7 到位 1(依次为 `$80、$40、$20、$10、$08、$04、$02`)置 1,即屏蔽;`$80+n` 把对应位清 0,即允许。已确认(`mouse`):鼠标中断是位 6,`$13/$81` 允许鼠标中断,`$13/$01` 屏蔽;屏蔽着鼠标中断时收不到鼠标数据。`$13/$81` 执行后,如果鼠标已接入(`$0633` 非 0)就把 `$0634` 清 0,否则置 `$FF`。另外 `$13/$80` 还设置定时器 `$4034/$4035`,`$13/$02`、`$13/$82` 向 `$4022` 写 `$40`、`$80`;`$13/$88` 登记各中断源的处理例程。
@@ -682,7 +682,7 @@ $5A-$61 的共同特点:这些功能返回后 `$0640` 恒为 0(代码里置
682
682
 
683
683
  ## 5.13 语音端口服务(功能 `$74`、`$75`,内核)
684
684
 
685
- 语音端口 `$4302` 的读写规则与 `$4026` 位 6 见[硬件说明](03-硬件说明.md)。语音数据是 LPC 码流:第 1 个字节 `$0A` 是开头标志,之后每帧先读 4 位能量(`0` 是静音帧,`15` 是结束帧),字节按位反序使用(见模拟器 `LPC_D6_SYNTH.C`)。`$032B` 是语音控制标志(位 0 为 0 同步发送,为 1 交给 NMI 逐字节发送;位 1 为 1 时已有传输就不等待;位 2 为 1 时发送后等传输结束;位 3 选命令字节 `$0A` 或 `$0B`;位 6 为 1 表示语音芯片已使用,调用时要先复位),`$0328` 是待发的命令字节,`$0329` 非 0 表示 NMI 正在发送(`$FF` 为请求发送,发出命令字节后放命令字节本身)。
685
+ 语音端口 `$4302` 的读写规则与 `$4026` 位 6 见[硬件说明](03-硬件说明.md)。语音数据是 LPC 码流:第 1 个字节 `$0A` 是开头标志,之后每帧先读 4 位能量(`0` 是静音帧,`15` 是结束帧),字节按位反序使用。`$032B` 是语音控制标志(位 0 为 0 同步发送,为 1 交给 NMI 逐字节发送;位 1 为 1 时已有传输就不等待;位 2 为 1 时发送后等传输结束;位 3 选命令字节 `$0A` 或 `$0B`;位 6 为 1 表示语音芯片已使用,调用时要先复位),`$0328` 是待发的命令字节,`$0329` 非 0 表示 NMI 正在发送(`$FF` 为请求发送,发出命令字节后放命令字节本身)。
686
686
 
687
687
  | 子功能 | 作用 | 状态 |
688
688
  | --- | --- | --- |
@@ -753,7 +753,7 @@ $5A-$61 的共同特点:这些功能返回后 `$0640` 恒为 0(代码里置
753
753
 
754
754
  ## 7. 其他服务
755
755
 
756
- 下列功能已读过但还没整理出参数,作用见 [api-reference.md](../../targets/sb2000/api-reference.md) 末尾的覆盖表:
756
+ 下列功能已读过但还没整理出参数,作用见 [C 接口参考](../../targets/sb2000/api-reference.md)末尾的覆盖表:
757
757
 
758
758
  - 显示:`$10`(显示选项)、`$11`(显示模式)、`$14`(鼠标复位)、`$19`、`$1A`(关闭、重开显示)、`$30`(DMA 到显存);文字显示与窗口功能 `$3B-$61` 见 5.12 节。
759
759
  - 其余未命名的内核功能:`$15`、`$17`、`$18`、`$1F`、`$27`、`$28`、`$31-$34`。(`$6A`、`$6C` 见 5.8 节。)
@@ -1,12 +1,12 @@
1
1
  # SB2000 硬件说明
2
2
 
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)。
3
+ 本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源有三类:芯片手册(SH6578 官方手册,下称“芯片手册”)、模拟器源码与实际运行观察、真机实测(内存测试程序 `memtest`,2026-11-12;硬件测试程序 `hwtest`,2026-11-13,真机为 PAL 制式)。SB2000 的真机芯片是 UM6576,芯片手册是 SH6578,两颗芯片有差别,两者不一致时以真机实测为准。“已确认”指来自模拟器源码或实际运行;没有写“真机”的结论都没有在真机上测过。模拟器已按真机实测修改内部 RAM、`$4400-$5FFF`、DMA、定时器与图形端口(见对应行),memtest、hwtest 在模拟器里的结果与真机一致(仍有差异的项见“真机与模拟器仍有差异的行为”一行);模拟器与芯片手册不一致、也没有真机数据的地方,在对应行里写明。程序接口见 [系统调用手册](02-系统调用手册.md)。
4
4
 
5
5
  | 项目 | 结论 | 状态 |
6
6
  | --- | --- | --- |
7
7
  | CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是向 `$4031` 依次写入 `$65`、`$76`(芯片手册称这一步为初始设置)之后的工作模式 | 已确认 |
8
8
  | 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成。芯片手册要求两次写入在两个指令周期内连续完成(`LDA #$65 / LDX #$76 / STA $4031 / STX $4031`),模拟器只按顺序识别,不检查间隔 | 已确认(芯片手册、模拟器源码) |
9
- | 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真 | 已确认 |
9
+ | 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真;Ember 已实现,并能用“游戏集锦”软盘进入游戏 | 已确认 |
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` 起) | 已确认 |
@@ -16,17 +16,17 @@
16
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
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 代码);复位位的说法见左 |
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
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
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
22
  | DAC | `$4027` 是 8 位 DAC,输出语音(PCM)。芯片手册:实际输出发生在定时器溢出时,所以使用 DAC 必须同时设置定时器;输出带约 1/2 Vcc 的直流偏置,输出语音前要把电平从 0 缓慢升到偏置值,否则开始时有“噗”声。BIOS 播放 WAV 时写它(`$65/$0C`) | 芯片手册;BIOS 的用法已验证 |
23
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`),模拟器已对齐 |
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
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
26
  | 实时时钟 | 真机实测:`$4081` 不论有没有设地址,读出的都是 `$60`;模拟器读出 `$60` | 真机实测(`hwtest`);模拟器已对齐 |
27
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
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 秒没有数据就结束这一页 | 已确认(模拟器源码) |
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:`,已修复 |
29
+ | 语音端口 `$4302` | 读:位 7 为 1 表示可以接收下一个字节(缓冲未满),语音播完时低 4 位为 `$F`。写:把一个语音数据字节送进环形缓冲,由模拟器的 LPC 语音合成器解码播放(Ember 里是 `speech-lpc` 模块,缓冲 15 字节)。`$4026` 位 6 的上升沿复位语音(清缓冲)。BIOS 的 `$74`、`$75`(`API_74_PORT4302_CONTROL`、`API_75_PORT4302_SEND`)就是操作它 | 已确认(模拟器源码);`$74`、`$75` 的发送序列与“播完”结束都已实测(见 [系统调用手册](02-系统调用手册.md) 5.13 节);模拟器曾缺 `case 0x4302:`,已修复 |
30
30
 
31
31
  ## 软件环境
32
32
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fcdev",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
4
4
  "description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
5
5
  "license": "Apache-2.0",
6
6
  "author": "sungbin <sungbin@3578.cn>",
@@ -30,7 +30,10 @@
30
30
  "src",
31
31
  "targets"
32
32
  ],
33
+ "dependencies": {
34
+ "ember-debug-sdk": "0.8.0"
35
+ },
33
36
  "optionalDependencies": {
34
- "fcdev-cc65": "0.6.0"
37
+ "fcdev-cc65": "0.8.0"
35
38
  }
36
39
  }
@@ -5,7 +5,7 @@
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
7
7
  // 备注:模板里写固定的部分与库页 generatedFrom 之前的库页,%BANK_MEMORY% 与 %BANK_SEGMENTS% 两行分别展开成
8
- // 库页 generatedFrom 到 N 的内存区与段;定义见 docs/03-目标规范.md 第 2 节的 banked。
8
+ // 库页 generatedFrom 到 N 的内存区与段;定义见仓库根目录 docs/02-目标规范.md 第 2 节的 banked。
9
9
  // ------------------------------------------------------------------------
10
10
  import { readFileSync, writeFileSync } from 'node:fs';
11
11
  import path from 'node:path';
@@ -4,7 +4,7 @@
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:规则见 docs/02-命令行与构建.md 第 2 节:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序。
7
+ // 备注:规则见 packages/fcdev/docs/01-命令行与构建.md 第 2 节:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序。
8
8
  // ------------------------------------------------------------------------
9
9
  import { statSync } from 'node:fs';
10
10
  import path from 'node:path';
@@ -16,6 +16,7 @@ import { resolveTargetPath } from '../targets/index.mjs';
16
16
  import { getToolchainVersion, runTool } from '../toolchain/index.mjs';
17
17
  import { resolveLinkSetup } from './bank-link-config.mjs';
18
18
  import { parseDependencyFile } from './dependency-file.mjs';
19
+ import { prepareGb2312Source } from './source-charset.mjs';
19
20
  import { getSourceLanguage } from './source-collector.mjs';
20
21
  import { buildAssemblerArguments, buildCompilerArguments, buildLinkerArguments } from './tool-arguments.mjs';
21
22
 
@@ -130,14 +131,18 @@ function describeToolFailure(output) {
130
131
  * @returns {Promise<void>}
131
132
  */
132
133
  async function compileSource(context, source, objectFile) {
133
- const { toolchain, settings, reporter } = context;
134
+ const { toolchain, settings, sourceCharset } = context;
134
135
  const base = objectFile.slice(0, -'.o'.length);
135
- if (getSourceLanguage(source) === 'c') {
136
+ const language = getSourceLanguage(source);
137
+ // 目标声明了源文件编码时,编译的是转码后的副本,工具输出里的副本路径要换回原文件
138
+ const prepared = sourceCharset ? prepareGb2312Source({ source, base, language }) : { file: source, restoreText: (text) => text };
139
+ const reporter = { ...context.reporter, write: (text) => context.reporter.write(prepared.restoreText(text)) };
140
+ if (language === 'c') {
136
141
  const asmFile = `${base}.s`;
137
- await runChecked(toolchain, 'cc65', buildCompilerArguments(settings, { source, output: asmFile, dependencyFile: `${base}.d` }), reporter, `编译失败:${source}`);
142
+ await runChecked(toolchain, 'cc65', buildCompilerArguments(settings, { source: prepared.file, output: asmFile, dependencyFile: `${base}.d` }), reporter, `编译失败:${source}`);
138
143
  await runChecked(toolchain, 'ca65', buildAssemblerArguments(settings, { source: asmFile, output: objectFile, dependencyFile: `${base}.asm.d` }), reporter, `汇编失败:${asmFile}`);
139
144
  } else {
140
- await runChecked(toolchain, 'ca65', buildAssemblerArguments(settings, { source, output: objectFile, dependencyFile: `${base}.d` }), reporter, `汇编失败:${source}`);
145
+ await runChecked(toolchain, 'ca65', buildAssemblerArguments(settings, { source: prepared.file, output: objectFile, dependencyFile: `${base}.d` }), reporter, `汇编失败:${source}`);
141
146
  }
142
147
  }
143
148
 
@@ -172,7 +177,7 @@ export async function buildProgram(plan, toolchain, reporter = SILENT_REPORTER)
172
177
  ensureDirectory(plan.objectDir);
173
178
  }
174
179
 
175
- const context = { toolchain, settings, reporter };
180
+ const context = { toolchain, settings, reporter, sourceCharset: target.sourceCharset };
176
181
  const objects = [];
177
182
  let compiled = 0;
178
183
  let reused = 0;
@@ -0,0 +1,111 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:source-charset.mjs
3
+ // 说明:源文件转码:目标声明了 sourceCharset 时,编译前把 UTF-8 的 C 与汇编源文件转成目标机器用的编码,写成副本交给编译器。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-18
7
+ // 备注:目前只有 GB2312(学习机的字库按它取字模)。GB2312 的第二个字节不小于 0xA1,不会和 ASCII 的反斜杠、引号冲突,所以注释与字符串里的汉字都能整体转换;
8
+ // 文件不是合法的 UTF-8 时视为已经是目标编码,原样使用;机器字库没有的字符(GB2312 之外)报错,指出文件、行、列;
9
+ // 编码表用 Node 自带的 gb18030 解码器反推,不引入依赖;C 副本开头加 #line 指令,让错误信息与调试信息仍指向原文件,汇编靠替换工具输出里的文件名。
10
+ // ------------------------------------------------------------------------
11
+ import { readFileSync, writeFileSync } from 'node:fs';
12
+ import path from 'node:path';
13
+ import { FcdevError } from '../shared/index.mjs';
14
+
15
+ /** GB2312 的区:1-9 区是符号,16-87 区是汉字,对应第一个字节 */
16
+ const GB2312_LEAD_BYTES = [[0xa1, 0xa9], [0xb0, 0xf7]];
17
+
18
+ /** 反推出的编码表:Unicode 码点到两个字节(高字节在前);第一次用到时才建立 */
19
+ let gb2312Table = null;
20
+
21
+ /**
22
+ * 取得 GB2312 编码表。
23
+ * @returns {Map<number, number>} 码点到内码(高 8 位是第一个字节)
24
+ * @throws {FcdevError} 当前的 Node 没有 GB 系列解码器
25
+ */
26
+ function getGb2312Table() {
27
+ if (gb2312Table !== null) return gb2312Table;
28
+ let decoder;
29
+ try {
30
+ decoder = new TextDecoder('gb18030');
31
+ } catch {
32
+ throw new FcdevError('当前的 Node 不支持 GB2312 解码,无法转换源文件编码', { code: 'CHARSET_UNSUPPORTED', hint: '使用带完整国际化数据的 Node 22 或更高版本,或把源文件另存为 GB2312' });
33
+ }
34
+ const table = new Map();
35
+ for (const [first, last] of GB2312_LEAD_BYTES) {
36
+ for (let lead = first; lead <= last; lead += 1) {
37
+ for (let trail = 0xa1; trail <= 0xfe; trail += 1) {
38
+ if (lead === 0xd7 && trail >= 0xfa) continue; // 87 区只到 0xD7F9,后面是 GBK 扩展
39
+ const text = decoder.decode(Uint8Array.of(lead, trail));
40
+ const [char, ...rest] = text;
41
+ if (char !== undefined && rest.length === 0 && char !== '\uFFFD') table.set(char.codePointAt(0), (lead << 8) | trail);
42
+ }
43
+ }
44
+ }
45
+ gb2312Table = table;
46
+ return table;
47
+ }
48
+
49
+ /**
50
+ * 把 UTF-8 文本转成 GB2312 字节;不是合法 UTF-8 的内容原样返回。
51
+ * @param {Buffer} buffer 源文件内容
52
+ * @param {string} label 出错提示里用的文件名
53
+ * @returns {Buffer} 转换后的内容
54
+ * @throws {FcdevError} 有字符不在 GB2312 里
55
+ */
56
+ export function convertToGb2312(buffer, label) {
57
+ let text;
58
+ try {
59
+ text = new TextDecoder('utf-8', { fatal: true }).decode(buffer);
60
+ } catch {
61
+ return buffer;
62
+ }
63
+ const bytes = [];
64
+ let table = null;
65
+ let line = 1;
66
+ let column = 0;
67
+ for (const char of text) {
68
+ column += char.length;
69
+ const code = char.codePointAt(0);
70
+ if (code < 0x80) {
71
+ bytes.push(code);
72
+ if (code === 0x0a) {
73
+ line += 1;
74
+ column = 0;
75
+ }
76
+ continue;
77
+ }
78
+ table ??= getGb2312Table();
79
+ const mapped = table.get(code);
80
+ if (mapped === undefined) {
81
+ const unicode = `U+${code.toString(16).toUpperCase().padStart(4, '0')}`;
82
+ throw new FcdevError(`${label}:${line}:${column - char.length + 1}:字符“${char}”(${unicode})不在 GB2312 里,学习机的字库显示不了`, {
83
+ code: 'SOURCE_CHAR_UNSUPPORTED',
84
+ hint: '改用 GB2312 里有的字,或用 \\x 转义写字节',
85
+ });
86
+ }
87
+ bytes.push(mapped >> 8, mapped & 0xff);
88
+ }
89
+ return Buffer.from(bytes);
90
+ }
91
+
92
+ /**
93
+ * 为一个源文件准备转码后的副本。
94
+ * @param {object} input 参数
95
+ * @param {string} input.source 源文件绝对路径
96
+ * @param {string} input.base 中间文件的公共前缀(不含扩展名)
97
+ * @param {'c'|'asm'} input.language 源文件语言
98
+ * @returns {{file: string, restoreText: (text: string) => string}} 副本路径,以及把工具输出里的副本路径换回原文件的函数
99
+ * @throws {FcdevError} 有字符不在 GB2312 里
100
+ */
101
+ export function prepareGb2312Source({ source, base, language }) {
102
+ const file = `${base}.gb2312${path.extname(source)}`;
103
+ const converted = convertToGb2312(readFileSync(source), source);
104
+ if (language === 'c') {
105
+ const original = source.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
106
+ writeFileSync(file, Buffer.concat([Buffer.from(`#line 1 "${original}"\n`, 'utf8'), converted]));
107
+ return { file, restoreText: (text) => text };
108
+ }
109
+ writeFileSync(file, converted);
110
+ return { file, restoreText: (text) => text.replaceAll(file, source) };
111
+ }
@@ -4,7 +4,7 @@
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:debug 命令把命令名之后的全部参数原样交给调试服务,不再解析选项。
7
+ // 备注:debug 命令把命令名之后的全部参数原样交给 ember-debug,不再解析选项。
8
8
  // ------------------------------------------------------------------------
9
9
  import { FcdevError } from '../shared/index.mjs';
10
10
 
@@ -1,73 +1,35 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:debug-command.mjs
3
- // 说明:debug 命令:把命令原样转发给模拟器的调试服务并打印应答。
3
+ // 说明:debug 命令:把参数原样交给调试 SDK 的终端客户端 ember-debug,由它连接 Ember 的调试服务。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace、tape 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
7
+ // 备注:fcdev 不解析调试命令;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699,找到 run --debug 启动的 Ember;
8
+ // ember-debug 的退出码原样作为 fcdev 的退出码,输出边读边转,watch 这类长时间运行的命令也能看到实时结果。
8
9
  // ------------------------------------------------------------------------
9
- import path from 'node:path';
10
- import { DEFAULT_DEBUG_PORT, DebugClient } from '../../emulator/index.mjs';
10
+ import { spawn } from 'node:child_process';
11
+ import { debugEnvironment, resolveDebugCli } from '../../emulator/index.mjs';
11
12
  import { FcdevError } from '../../shared/index.mjs';
12
13
 
13
- /** 耗时长的命令使用的应答超时,单位毫秒 */
14
- const LONG_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
15
-
16
- /** 耗时长的命令 */
17
- const LONG_COMMANDS = new Set(['run', 'step']);
18
-
19
- /** 命令里路径参数的位置(命令名之后的第几个词,从 1 起);disk 的路径可含空格,取剩余全部 */
20
- const PATH_POSITIONS = {
21
- shot: 1,
22
- disk: 1,
23
- trace: 1,
24
- io: 1,
25
- disklog: 1,
26
- calllog: 1,
27
- savestate: 1,
28
- loadstate: 1,
29
- };
30
-
31
- /**
32
- * 把命令里的相对路径换成绝对路径。
33
- * @param {string[]} tokens 命令的各个词
34
- * @param {string} cwd 终端当前目录
35
- * @returns {string[]} 处理后的词
36
- */
37
- export function resolveCommandPaths(tokens, cwd) {
38
- const [name, ...rest] = tokens;
39
- if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
40
- return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
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
- }
45
- const position = PATH_POSITIONS[name];
46
- if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
47
- if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
48
- const resolved = [...rest];
49
- resolved[position - 1] = path.resolve(cwd, rest[position - 1]);
50
- return [name, ...resolved];
51
- }
52
-
53
14
  /**
54
15
  * 执行 debug 命令。
55
- * @param {{positionals: string[], context: import('../index.mjs').CliContext}} input 调试命令的各个词与运行环境
56
- * @returns {Promise<number>} 应答为 OK 时 0,否则 1
57
- * @throws {FcdevError} 没有给命令,或无法连接调试服务
16
+ * @param {{positionals: string[], context: import('../index.mjs').CliContext}} input ember-debug 的各个参数与运行环境
17
+ * @returns {Promise<number>} ember-debug 的退出码
18
+ * @throws {FcdevError} 没有给命令,或终端客户端不可用
58
19
  */
59
20
  export async function runDebugCommand({ positionals, context }) {
60
21
  if (positionals.length === 0) {
61
- throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug status、npx fcdev debug run 60、npx fcdev debug shot out.png' });
62
- }
63
- const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
64
- const tokens = resolveCommandPaths(positionals, context.cwd);
65
- const client = await DebugClient.connect({ port });
66
- try {
67
- const reply = await client.send(tokens.join(' '), { timeoutMs: LONG_COMMANDS.has(tokens[0]) ? LONG_COMMAND_TIMEOUT_MS : undefined });
68
- context.stdout.write(`${[reply.head, ...reply.lines].join('\n')}\n`);
69
- return reply.ok ? 0 : 1;
70
- } finally {
71
- client.close();
22
+ throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug call runtime.status、npx fcdev debug screenshot out.png;npx fcdev debug --help 查看全部命令' });
72
23
  }
24
+ const cli = resolveDebugCli();
25
+ const env = debugEnvironment(context.env);
26
+ return new Promise((resolve, reject) => {
27
+ const child = spawn(process.execPath, [cli, ...positionals], { cwd: context.cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
28
+ child.stdout.setEncoding('utf8');
29
+ child.stderr.setEncoding('utf8');
30
+ child.stdout.on('data', (chunk) => context.stdout.write(chunk));
31
+ child.stderr.on('data', (chunk) => context.stderr.write(chunk));
32
+ child.once('error', (error) => reject(new FcdevError('无法运行调试 SDK 的终端客户端', { code: 'DEBUG_CLI_START_FAILED', cause: error })));
33
+ child.once('close', (code) => resolve(code ?? 1));
34
+ });
73
35
  }
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:docs-command.mjs
3
- // 说明:docs 命令:列出开发文档的主题,查询某份文档的本机路径。
3
+ // 说明:docs 命令:列出使用文档的主题,查询某份文档的本机路径。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
@@ -29,7 +29,7 @@ export async function runDocsCommand({ positionals, options, context }) {
29
29
  return 0;
30
30
  }
31
31
  const width = Math.max(...docs.map((doc) => doc.topic.length));
32
- const lines = [`fcdev 开发文档:${docs.length} 份`, `本机目录:${directory}`, ''];
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
34
  lines.push('', '查询:npx fcdev docs <主题>(本机路径)、npx fcdev docs <词>(按主题、文件名、标题与说明搜索)');
35
35
  context.stdout.write(`${lines.join('\n')}\n`);