fcdev 0.7.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 (39) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +9 -8
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +10 -8
  4. package/docs/{05- → 02-}/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +12 -22
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +12 -46
  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 +21 -26
  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 +3 -3
  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/commands/docs-command.mjs +2 -2
  17. package/src/cli/index.mjs +1 -1
  18. package/src/config/config-loader.mjs +1 -1
  19. package/src/docs/doc-index.mjs +1 -1
  20. package/src/docs/doc-topics.mjs +9 -15
  21. package/src/docs/index.mjs +1 -1
  22. package/src/emulator/sb2000-session.mjs +15 -12
  23. package/src/targets/target-registry.mjs +9 -1
  24. package/targets/nes/lib/fcnes.lib +0 -0
  25. package/targets/nes/lib/nes-font.o +0 -0
  26. package/targets/sb2000/api-reference.md +2 -1
  27. package/targets/sb2000/examples-source.md +1330 -0
  28. package/targets/sb2000/lib/crt0.o +0 -0
  29. package/targets/sb2000/lib/sb2000.lib +0 -0
  30. package/targets/sb2000/symbols-reference.md +670 -0
  31. package/targets/sb2000/target.json +1 -0
  32. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -164
  33. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  34. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  35. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -75
  36. package/docs/09-/345/217/221/345/270/203.md +0 -75
  37. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  38. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -50
  39. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
package/CHANGELOG.md CHANGED
@@ -2,6 +2,21 @@
2
2
 
3
3
  适用于 `fcdev`、`create-fcdev`、`fcdev-cc65` 三个包,它们的版本号相同。
4
4
 
5
+ ## 0.8.0(2026-11-18)
6
+
7
+ ### 小霸王学习机 SB2000
8
+
9
+ - 源文件里可以直接写汉字:用 UTF-8 保存,构建时自动转成学习机用的 GB2312,不再需要手写 `\xC4\xE3` 这样的转义。汉字要写在 `.c`、`.s` 文件里,不在 GB2312 里的字符会报错并指出位置。
10
+ - `npm create fcdev` 的 SB2000 模板改成直接写汉字。
11
+
12
+ ### 文档
13
+
14
+ - 新增“SB2000 符号参考”(`npx fcdev docs symbols`):列出功能号、子功能号、系统变量地址、出错码、硬件寄存器与位、运行库入口的汇编名、C 名、值与说明。
15
+ - 新增“SB2000 示例程序源码”(`npx fcdev docs examples`):手册里提到的 11 个示例程序的程序名与完整源码。
16
+ - 手册里指向开发文档的引用去掉了,每篇都能独立读懂。
17
+ - Ember 的帮助文档里新增“fcdev 开发手册”,可以直接阅读这些手册、C 接口参考与符号参考。
18
+ - 随包发布的文档只保留使用手册;架构设计、目标规范、测试、发布等开发文档不再随包发布,`fcdev docs` 的主题相应减少,文件名重新编号。
19
+
5
20
  ## 0.7.0(2026-11-15)
6
21
 
7
22
  ### 模拟器与调试
package/README.md CHANGED
@@ -26,7 +26,7 @@ npx fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
26
26
  npx fcdev sync # 生成 IDE 的 C/C++ 配置
27
27
  npx fcdev info --json # 显示目标、工具链与头文件目录
28
28
  npx fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
29
- npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
29
+ npx fcdev docs syscall # 查使用文档的本机路径(主题名或关键词;不带词列出全部主题)
30
30
  ```
31
31
 
32
32
  入口是 `main`(汇编程序写 `.export _main`)。产物放在项目根的 `build/<目标>/`,中间文件在 `build/obj/`。
@@ -77,20 +77,21 @@ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号
77
77
 
78
78
  ## 文档
79
79
 
80
- 完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
80
+ 完整的使用文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
81
81
 
82
82
  | 想做什么 | 主题 | 文档 |
83
83
  | --- | --- | --- |
84
- | 查命令、`fcdev.json` 配置与构建流程 | `build` | `docs/02-命令行与构建.md` |
85
- | 开发 NES 程序 | `nes` | `docs/nes/01-NES目标.md` |
84
+ | 查命令、`fcdev.json` 配置与构建流程 | `build` | `docs/01-命令行与构建.md` |
85
+ | 开发 NES 程序 | `nes` | `docs/nes/01-开发指南.md` |
86
86
  | 开发 SB2000(SB-DOS)程序 | `sb2000` | `docs/sb2000/01-开发指南.md` |
87
87
  | 查 SB-DOS 系统调用与出错码 | `syscall` | `docs/sb2000/02-系统调用手册.md` |
88
88
  | 查 SB2000 的硬件行为 | `hardware` | `docs/sb2000/03-硬件说明.md` |
89
89
  | 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `npx fcdev api` 查询) |
90
- | 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/05-模拟器与调试.md` |
91
- | 反汇编已有程序 | `disasm` | `docs/06-反汇编.md` |
92
- | 创建项目与模板 | `create` | `docs/07-创建包与模板.md` |
93
- | 新增机型的目标 | `targets` | `docs/03-目标规范.md` |
90
+ | 查 SB2000 的功能号、地址、出错码与寄存器符号(汇编名与 C 名) | `symbols` | `targets/sb2000/symbols-reference.md` |
91
+ | 看 SB2000 示例程序的完整源码 | `examples` | `targets/sb2000/examples-source.md` |
92
+ | 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/02-模拟器与调试.md` |
93
+ | 反汇编已有程序 | `disasm` | `docs/03-反汇编.md` |
94
+ | 创建项目与模板 | `create` | `docs/04-创建包与模板.md` |
94
95
 
95
96
  ## 限制
96
97
 
@@ -1,10 +1,10 @@
1
1
  # 命令行与构建
2
2
 
3
- 本文说明 `fcdev` 的命令、构建规则、配置文件 `fcdev.json` 和构建流程。目标定义见 [03-目标规范](03-目标规范.md),模拟器相关命令的细节见 [05-模拟器与调试](05-模拟器与调试.md),反汇编见 [06-反汇编](06-反汇编.md)。
3
+ 本文说明 `fcdev` 的命令、构建规则、配置文件 `fcdev.json` 和构建流程。模拟器相关命令的细节见 [02-模拟器与调试](02-模拟器与调试.md),反汇编见 [03-反汇编](03-反汇编.md)。
4
4
 
5
5
  ## 1. 命令
6
6
 
7
- 入口是 [packages/fcdev/bin/fcdev.mjs](../bin/fcdev.mjs),由 `cli/index.mjs` 的 `runCli` 分发。命令正常结束返回 0;出现 `FcdevError` 时向标准错误写“错误:”加说明与建议,返回 1。
7
+ 命令正常结束返回 0;出错时向标准错误写“错误:”加说明与建议,返回 1。
8
8
 
9
9
  `fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里要写成 `npx fcdev <命令>`(全局安装 `npm install -g fcdev` 后可以直接写 `fcdev <命令>`);`package.json` 的 `scripts` 里直接写 `fcdev <命令>`。下面的表格和本文其余地方都省略 `npx`。
10
10
 
@@ -18,7 +18,7 @@
18
18
  | `fcdev sync` | 生成 IDE 配置,见第 6 节 |
19
19
  | `fcdev info [--json]` | 显示目标、工具链与头文件目录 |
20
20
  | `fcdev api [词] [--json]` | 查询目标的 C 接口文档,见第 5.1 节 |
21
- | `fcdev docs [词] [--json]` | 查询开发文档的本机路径,见第 5.2 节 |
21
+ | `fcdev docs [词] [--json]` | 查询使用文档的本机路径,见第 5.2 节 |
22
22
 
23
23
  通用选项:
24
24
 
@@ -31,7 +31,7 @@
31
31
  | `-h`、`--help` | 显示帮助 |
32
32
  | `-v`、`--version` | 显示版本 |
33
33
 
34
- `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [06-反汇编](06-反汇编.md)。`debug` 把命令名之后的全部参数原样交给 `ember-debug`,不再解析选项;它按环境变量 `FCDEV_DEBUG_PORT`(默认 5699)找到 `run --debug` 启动的 Ember,细节见 [05-模拟器与调试](05-模拟器与调试.md)。
34
+ `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [03-反汇编](03-反汇编.md)。`debug` 把命令名之后的全部参数原样交给 `ember-debug`,不再解析选项;它按环境变量 `FCDEV_DEBUG_PORT`(默认 5699)找到 `run --debug` 启动的 Ember,细节见 [02-模拟器与调试](02-模拟器与调试.md)。
35
35
 
36
36
  ## 2. 构建单位
37
37
 
@@ -78,13 +78,16 @@
78
78
  | 产物 | `<项目根>/<out>/<目标>/<程序名><扩展名>`,程序名按目标的 `nameRule` 规范化 |
79
79
  | 中间文件 | `<项目根>/<out>/obj/<目标>/<程序名>/` |
80
80
 
81
- 中间文件目录里有每个源文件对应的 `.o`、依赖文件 `.d`,C 文件还有编译出的 `.s` 与汇编依赖文件 `.asm.d`;链接产物 `<程序名>.bin`、`<程序名>.map`、`<程序名>.dbg`;多页程序还有展开后的链接配置 `<程序名>.cfg`;以及指纹文件 `stamp.json`。`.o` 的文件名取源文件相对目录的路径,去掉扩展名,目录分隔符换成 `__`。
81
+ 中间文件目录里有每个源文件对应的 `.o`、依赖文件 `.d`,C 文件还有编译出的 `.s` 与汇编依赖文件 `.asm.d`;目标声明了源文件编码时(如 sb2000),还有每个源文件转码后的副本 `.gb2312.c` 或 `.gb2312.s`;链接产物 `<程序名>.bin`、`<程序名>.map`、`<程序名>.dbg`;多页程序还有展开后的链接配置 `<程序名>.cfg`;以及指纹文件 `stamp.json`。`.o` 的文件名取源文件相对目录的路径,去掉扩展名,目录分隔符换成 `__`。
82
82
 
83
83
  ### 4.2 单个程序
84
84
 
85
85
  1. 对每个 `.c`:`cc65` 输出 `.s` 与依赖文件(`--create-dep`)。
86
86
  2. 对每个 `.s`(含上一步生成的):`ca65` 汇编成 `.o`,同样输出依赖文件。
87
- 3. `ld65`:按目标的链接配置,依次链接启动代码、用户的 `.o`、开启的目标选项所带的目标文件,最后链接目标声明的库;生成 `.bin`、`.map`、`.dbg`。目标声明了 `forceImports` 时,用 `-u` 强制引入这些符号。目标声明了多页(换页)程序(`banked`)且库页个数大于 0 时,链接配置由目标的模板按库页个数展开,写在中间文件目录里,打包器也不再检查映像大小上限,见 [03-目标规范](03-目标规范.md) 第 2.3 节。
87
+
88
+ 目标声明了源文件编码时(sb2000 声明了 GB2312),上面两步编译的是转码后的副本,错误信息仍指向原文件;转换规则见 [sb2000 开发指南](sb2000/01-开发指南.md) 第 5 节。
89
+
90
+ 3. `ld65`:按目标的链接配置,依次链接启动代码、用户的 `.o`、开启的目标选项所带的目标文件,最后链接目标声明的库;生成 `.bin`、`.map`、`.dbg`。目标声明了多页(换页)程序且库页个数大于 0 时,链接配置按库页个数展开,写在中间文件目录里,打包器也不再检查映像大小上限。
88
91
  4. 打包器把 `.bin` 做成最终产物。
89
92
 
90
93
  工具参数:
@@ -138,7 +141,7 @@
138
141
 
139
142
  ### 5.2 文档查询
140
143
 
141
- `fcdev docs` 查询随主包发布的开发文档(主包的 `docs/` 目录),只读、不联网、不需要 `fcdev.json` 和工具链。主题登记在 `src/docs/doc-topics.mjs`,主题名只用小写字母、数字与连字符,清单见 [01-软件架构设计](01-软件架构设计.md) 第 9 节。
144
+ `fcdev docs` 查询随主包发布的使用文档(主包的 `docs/` 目录),只读、不联网、不需要 `fcdev.json` 和工具链。
142
145
 
143
146
  | 用法 | 结果 |
144
147
  | --- | --- |
@@ -147,7 +150,6 @@
147
150
  | `fcdev docs <词>` | 按文件名(去掉序号与扩展名也可)或主题、标题、说明里的关键词查找;只匹配到一份时同上,多份时列出摘要 |
148
151
 
149
152
  - 查询依次按主题名、文件名、关键词匹配,先匹配上的为准;一份都没有匹配上时报“没有找到”。`--json` 输出机器可读的结果:不带查询词时是全部文档,否则是匹配到的文档,每项含 `topic`、`title`、`summary`、`file`、`localPath`。
150
- - 登记项默认是 `docs/` 下的文件;登记项带 `inPackage` 时指向主包根目录下的文件,目前只有 `api` 主题(`targets/sb2000/api-reference.md`)。
151
153
  - 文档目录不存在时报错,提示改读在线文档。
152
154
 
153
155
  ## 6. `fcdev sync`
@@ -1,12 +1,12 @@
1
1
  # 模拟器与调试
2
2
 
3
- `fcdev` 的 `run`、`debug` 命令使用本仓库的模拟器 Ember。Ember 不随 npm 包提供,需要自备(见第 1 节);调试服务由 Ember 提供,`fcdev` 用调试 SDK(npm 包 `ember-debug-sdk`,是 `fcdev` 的依赖,随 `fcdev` 一起安装)与它通信。Ember 的设计与调试协议见仓库的 `ember/docs/`(第 04 篇是调试服务),SDK 的用法与全部请求见 `packages/ember-debug-sdk/README.md` 与它生成的协议参考。
3
+ `fcdev` 的 `run`、`debug` 命令使用模拟器 Ember。Ember 不随 npm 包提供,要在 `fcdev` 里指明它的位置(见第 1、2 节);调试服务由 Ember 提供,`fcdev` 用调试 SDK(npm 包 `ember-debug-sdk`,是 `fcdev` 的依赖,随 `fcdev` 一起安装)与它通信。Ember 的调试协议与全部请求见 Ember 帮助文档里的“调试接口手册”,SDK 的用法见该手册的“客户端工具”页。
4
4
 
5
- Ember 运行 NES 程序,也运行学习机整机(SB2000);学习机的启动方式见第 3 节与第 7 节。
5
+ Ember 运行 NES 程序,也运行学习机整机(SB2000);学习机的启动方式见第 3 节与第 6 节。
6
6
 
7
- ## 1. Ember 的获得
7
+ ## 1. Ember 的位置
8
8
 
9
- - 在仓库的 `ember/` 目录运行 `npm run package`(Windows 用 `npm run package:win`),输出在 `ember/out/Ember-win32-x64/ember.exe`(构建与打包步骤见 `ember/docs/06-构建与模块登记.md`)。
9
+ - Ember 的安装目录里有可执行文件 `ember.exe`。
10
10
  - 把这个文件的路径交给 `fcdev`,见第 2 节。
11
11
 
12
12
  ## 2. 定位 Ember
@@ -25,11 +25,11 @@ Ember 运行 NES 程序,也运行学习机整机(SB2000);学习机的启
25
25
  | 运行方案 | 做法 |
26
26
  | --- | --- |
27
27
  | `rom` | Ember 直接加载产物(`.nes`),不需要固件 |
28
- | `firmware-disk` | 学习机方案:加载 `fcdev.json` 里 `firmware` 指定的 BIOS,把程序放进磁盘镜像挂到软驱 0 并开机;没有设置 `firmware` 时在构建之前报“需要固件”,见下面与第 7 节 |
28
+ | `firmware-disk` | 学习机方案:加载 `fcdev.json` 里 `firmware` 指定的 BIOS,把程序放进磁盘镜像挂到软驱 0 并开机;没有设置 `firmware` 时在构建之前报“需要固件”,见下面与第 6 节 |
29
29
 
30
30
  - 学习机(`firmware-disk`)没有命令行入口,不论是否带 `--debug` 都经调试服务启动(独立的用户数据目录与调试端口,同下一条):依次 `machines.setBios`(Ember 把 BIOS 复制进自己的 BIOS 目录)、`machines.boot`(上电、不运行)、`media.floppyInsert`(放入 `fcdev disk` 生成的镜像,程序名取镜像里的程序)。没有 `--debug` 时,再让机器运行到 SB-DOS 询问日期,回车跳过日期与时间,输入程序名并回车,随后 `runtime.resume`,命令行断开调试连接并返回,Ember 留在运行状态;有 `--debug` 时停在开机状态,程序还没有被运行,要在 SB-DOS 里输入程序名才运行。程序名只能用字母与数字,不合适时用 `fcdev.json` 的 `name` 改名。
31
31
 
32
- - 没有 `--debug`:用 `--cartridge=<产物>` 启动 Ember,窗口打开并开始运行,命令行立即返回。用的是 Ember 平时的用户数据目录(首选项、键位映射等设置照常生效),遵守 Ember 的单实例规则,见第 6 节。
32
+ - 没有 `--debug`:用 `--cartridge=<产物>` 启动 Ember,窗口打开并开始运行,命令行立即返回。用的是 Ember 平时的用户数据目录(首选项、键位映射等设置照常生效),遵守 Ember 的单实例规则,见第 5 节。
33
33
  - 有 `--debug`:用独立的用户数据目录(系统临时目录下的 `fcdev-ember/<端口>`)、`--debug-port=<端口>` 与随机生成的令牌启动 Ember,不带 `--cartridge`;连上调试服务后用 `cartridges.load` 载入产物,上电但不运行(`powerOn` 为真、`resume` 为假);之后用 `fcdev debug` 继续。独立的用户数据目录让调试用的 Ember 能和平时在用的 Ember 同时运行,互不影响设置。
34
34
  - `--port` 指定调试端口,默认 5699。调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的 Ember;启动后最多等 30 秒,等到调试服务可连接并成功载入程序,超时则结束 Ember 进程并报错;Ember 在就绪前退出时立即报错。
35
35
  - Ember 进程与命令行脱离,命令行退出后窗口保持打开;工作目录是 Ember 所在目录。
@@ -48,7 +48,7 @@ npx fcdev debug methods
48
48
  - 找到 Ember:没有显式指定位置时,用环境变量 `FCDEV_DEBUG_PORT`(默认 5699)推出 `fcdev run --debug` 用的用户数据目录,读那里的端点文件取得地址与令牌。设置了环境变量 `EMBER_DEBUG_URL`、`EMBER_DEBUG_TOKEN`、`EMBER_DEBUG_ENDPOINT`、`EMBER_USER_DATA` 之一,或在命令里给了 `--url`、`--token`、`--endpoint-file`、`--user-data-dir`,就按显式指定的位置找,可以连到平时在用的 Ember。
49
49
  - 命令的工作目录就是终端当前目录,`screenshot` 的相对路径相对终端当前目录;`call` 里的 `file` 参数(如 `inspector.traceStart` 的文件名)由 Ember 写进它的调试输出目录,调试模式下是用户数据目录里的 `debug-output`,结果里的 `file` 给出完整路径。
50
50
  - 请求默认最多等 60 秒;`runtime.run` 带 `wait=true` 运行很多帧时用 `--timeout <毫秒>` 加长。
51
- - 需要调试 SDK 已构建:本仓库里先运行 `npm run build -w packages/ember-debug-sdk`(需要 Ember 的 Schema 生成物,见 SDK 的说明);用 npm 安装的 `fcdev` 已自带构建好的 SDK。
51
+ - 调试 SDK 随 `fcdev` 一起安装,已经构建好,不用另外构建。
52
52
 
53
53
  ### 4.1 常用操作
54
54
 
@@ -70,22 +70,13 @@ npx fcdev debug methods
70
70
 
71
71
  全部请求、参数与错误码用 `fcdev debug methods` 与 `fcdev debug describe <请求>` 查看。
72
72
 
73
- ## 5. 与旧模拟器的差异
73
+ ## 5. 限制
74
74
 
75
- `fcdev` 不再支持 VirtuaNES 调试版与它的文本命令协议(`run 60`、`shot`、`bp x`、`trace`、`cdl` 等),以下是行为上的变化:
75
+ - 学习机的运行方式是自动在 SB-DOS 里输入程序名,靠固定的帧数等待 DOS 启动(开机运行 900 帧后直接按两次回车,调试服务里不限速、几秒完成);换了别的 BIOS 或磁盘时提示的出现时间不同,就会输错位置,这时用 `--debug` 启动,自己用 `fcdev debug` 操作。
76
+ - 不带 `--debug` 的 `fcdev run` 遵守 Ember 的单实例规则:平时用的 Ember 已经在运行时,新启动的进程只会把已有窗口提到前面,不会载入新程序(Ember 首选项里开启“允许同时运行多个实例”后不受此限,会打开新窗口);这时先关闭 Ember,或改用 `--debug`(独立的用户数据目录,不受影响)。学习机目标不受影响,它总是用独立的用户数据目录。
77
+ - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供(学习机目标必填)。
76
78
 
77
- - `fcdev debug` 的参数是 `ember-debug` 的命令,不再是旧的单行命令;旧命令里相对路径要换成绝对路径的处理也不再需要。
78
- - `fcdev disasm --trace` 读 Ember 的指令轨迹(`kind=instruction`,每行是 nestest 日志的写法,行首是四位十六进制的指令地址),不再读旧模拟器行首为 `T` 的轨迹;`--cdl` 的格式不变(Mesen 的位定义)。
79
- - 旧命令里 Ember 没有对应请求的:存档(`savestate`、`loadstate`,已登记在 Ember 的待办里)、磁带相关命令(磁带机还没有做);软驱的放入、取出、保存对应 `media.floppyInsert`、`media.floppyEject`、`media.floppySave`。
80
- - 仓库里的 `virtuanes/` 保留作参考,`fcdev` 不再使用它;其中的调试服务协议见 `virtuanes/README.md`。
81
-
82
- ## 6. 限制
83
-
84
- - 学习机的运行方式是自动在 SB-DOS 里输入程序名,靠固定的帧数等待 DOS 启动(约 2600 帧,调试服务里不限速、几秒完成);换了别的 BIOS 或磁盘时提示的出现时间不同,就会输错位置,这时用 `--debug` 启动,自己用 `fcdev debug` 操作。
85
- - 不带 `--debug` 的 `fcdev run` 遵守 Ember 的单实例规则:平时用的 Ember 已经在运行时,新启动的进程只会把已有窗口提到前面,不会载入新程序;这时先关闭 Ember,或改用 `--debug`(独立的用户数据目录,不受影响)。学习机目标不受影响,它总是用独立的用户数据目录。
86
- - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供(学习机目标必填;仓库里有一份 SB2000 的 BIOS:`reference/rom/SB2K_BIOS.NES`)。
87
-
88
- ## 7. 学习机在 Ember 里的调试
79
+ ## 6. 学习机在 Ember 里的调试
89
80
 
90
81
  学习机用 `--debug` 启动后,机器已开机、磁盘在软驱 0 里、没有运行,操作与 NES 相同,另有:
91
82
 
@@ -96,4 +87,3 @@ npx fcdev debug methods
96
87
  | 把软驱里被程序改写的盘片存回镜像文件 | `call media.floppySave drive=0` |
97
88
  | 取出、重新放入盘片 | `call media.floppyEject drive=0`、`call media.floppyInsert drive=0 path=<镜像>` |
98
89
 
99
- 运行库的测试(`test/sb2000-library.test.mjs`)就是这样用的,机制见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
@@ -1,21 +1,8 @@
1
1
  # 反汇编
2
2
 
3
- `fcdev disasm` 把 NES 程序或平铺二进制反汇编成 `ca65` 可直接汇编的源码,并保证汇编回去后与原映像逐字节一致。代码在 `packages/fcdev/src/disasm/`。
3
+ `fcdev disasm` 把 NES 程序或平铺二进制反汇编成 `ca65` 可直接汇编的源码,并保证汇编回去后与原映像逐字节一致。
4
4
 
5
- ## 1. 做法
6
-
7
- 指令解码与源码文本输出交给 cc65 自带的 `da65`,不改 `da65` 的 C 代码;前端脚本负责分析,并把分析结果写成 `da65` 的信息文件。只有实测发现信息文件无法表达时,才修改 `da65` 的 C 源码,并把每处修改写进 `cc65/README-FCDEV.txt`。
8
-
9
- 流程(`disassembler.mjs`):
10
-
11
- 1. 读取输入,判断格式,取出映像(字节、第一个字节的地址、中断向量)。
12
- 2. 收集入口:中断向量、`--entry`、`--trace` 里的地址、CDL 里每段连续代码的起点。没有任何入口时报错。
13
- 3. 静态追踪,标出每个字节是指令的操作码、操作数还是未知。
14
- 4. 生成 `da65` 信息文件。
15
- 5. 运行 `da65 -i <信息文件> --multi-pass`,得到 ca65 源码。
16
- 6. 回读校验:用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较;不一致就报错,指出第一个差异的偏移与地址,不输出“成功”。
17
-
18
- ## 2. 命令
5
+ ## 1. 命令
19
6
 
20
7
  ```bash
21
8
  npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
@@ -44,65 +31,44 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
44
31
 
45
32
  `<名>` 取输入文件名(不含扩展名),非字母、数字、下划线、连字符的字符换成下划线。回读不一致时这些文件仍然保留。命令成功时输出映像大小、指令条数与字节数,以及“回读校验通过”;追踪中放弃某一路的警告最多显示 10 条。
46
33
 
47
- ## 3. 输入
34
+ ## 2. 输入
48
35
 
49
- ### 3.1 映像
36
+ ### 2.1 映像
50
37
 
51
38
  - iNES:只支持映射器 0(NROM),PRG 为 16K 或 32K。32K 映在 `$8000`,16K 映在 `$C000`;跳过 trainer;从 PRG 末尾读出 NMI、复位、IRQ 三个向量。其他映射器报错,可先导出某个 bank,用 `--format binary` 并指定加载地址。
52
39
  - 平铺二进制:按 `--base` 放置,不得超出 `$FFFF`,不能为空。
53
40
 
54
- ### 3.2 CDL
41
+ ### 2.2 CDL
55
42
 
56
43
  每个字节一个标志,位 0 表示被当作代码执行过,位 1 表示被当作数据读取过。支持 FCEUX 与 Mesen 的格式;Mesen CDLv2 开头多出的 9 个字节会自动跳过;只取与 PRG 对应的前 PRG 大小个字节,比 PRG 短时报错。
57
44
 
58
- ### 3.3 指令轨迹
45
+ ### 2.3 指令轨迹
59
46
 
60
- Ember 的 `inspector.traceStart`(`kind=instruction`)记录的日志:每行是 nestest 日志的写法,行首是四位大写十六进制的指令地址,后面跟指令字节(如 `C000 4C F5 C5 JMP $C5F5 ...`)。`io`、`irq` 与调用记录的行不是指令行,一律忽略;旧模拟器行首为 `T` 的轨迹不再识别。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。生成方法:`npx fcdev debug call inspector.traceStart kind=instruction file=trace.txt`,运行一段时间后 `npx fcdev debug call inspector.traceStop id=<编号>`,结果里的 `file` 是完整路径(文件写在 Ember 的调试输出目录)。
47
+ Ember 的 `inspector.traceStart`(`kind=instruction`)记录的日志:每行是 nestest 日志的写法,行首是四位大写十六进制的指令地址,后面跟指令字节(如 `C000 4C F5 C5 JMP $C5F5 ...`)。`io`、`irq` 与调用记录的行不是指令行,一律忽略。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。生成方法:`npx fcdev debug call inspector.traceStart kind=instruction file=trace.txt`,运行一段时间后 `npx fcdev debug call inspector.traceStop id=<编号>`,结果里的 `file` 是完整路径(文件写在 Ember 的调试输出目录)。
61
48
 
62
- ### 3.4 符号文件
49
+ ### 2.4 符号文件
63
50
 
64
51
  每行“名字 = 地址”或“名字 地址”,地址为十六进制,可带 `$` 或 `0x`;以 `;` 或 `#` 开头的行是注释,空行忽略。名字必须是合法的 ca65 标识符。同一地址有多个名字时只用第一个。中断向量对应的地址自动命名为 `reset`、`nmi`、`irq`。
65
52
 
66
53
  信息文件里总是引入 NES 的 `fcnes.inc`,所以 PPU 寄存器地址会显示成符号名;对平铺二进制也一样。
67
54
 
68
- ## 4. 静态追踪
55
+ ## 3. 静态追踪
69
56
 
70
- 规则(`analysis.mjs`):
57
+ 规则:
71
58
 
72
59
  - 顺序执行继续;条件分支两路都追;`JMP` 只追目标;`JSR` 追目标并假定会返回。
73
60
  - `RTS`、`RTI`、`BRK` 与间接 `JMP` 结束这一路。
74
61
  - 遇到非法操作码、超出映像末尾或与已识别的指令重叠时,放弃这一路并记入警告。
75
62
  - 没被追到的字节都按数据输出,这不影响回读校验。
76
- - 入口都追完后,查找经地址表分发的跳转(`address-tables.mjs`),表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
63
+ - 入口都追完后,查找经地址表分发的跳转,表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
77
64
  - `LDA 表,X/Y` 与 `LDA 表+1,X/Y` 成对,窗口里有间接 `JMP`:字表,目标就是表里的值;
78
65
  - 一对加载指令、两条 `PHA` 与一条 `RTS`:目标是表里的值加 1,表可以是字表,也可以是低、高字节分开的两张表;
79
66
  - 间接 `JMP (地址)` 的地址在映像内、那里还是未识别的字节:那里是字表。
80
67
  表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束,单张表最多 128 项;字表占的字节按 `AddrTable` 输出,分开的两张表保持为数据。
81
68
 
82
- 指令表在 `opcode-table.mjs`,共 151 条官方指令,数据取自 `da65` 的 `cc65/src/da65/opc6502.c`;非官方(非法)操作码不在表里。
83
-
84
- ## 5. 信息文件
85
-
86
- `info-writer.mjs` 把整个映像划分成首尾相接、互不重叠的段,没有遗漏,否则 `da65` 会把没说明的字节默认当成代码:
87
-
88
- | 段类型 | 用于 |
89
- | --- | --- |
90
- | `Code` | 追踪到的指令 |
91
- | `ByteTable` | 没被追到的字节 |
92
- | `AddrTable` | iNES 末尾 6 字节的中断向量表,以及识别出的字表 |
93
-
94
- 另有 `GLOBAL`(输入输出文件名、起始地址、CPU)、`ASMINC`(符号定义文件)与 `LABEL`(用户符号与中断向量名)。
95
-
96
- ## 6. 验证与限制
97
-
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 字节主要是图形数据与关键字表),回读一致。
99
-
100
- 限制:
69
+ ## 4. 限制
101
70
 
102
71
  - iNES 只支持 NROM。
103
72
  - 只识别上述几种写法的地址表;用立即数拼出地址再存进指针的跳转、调用方自己写进工作区的分发、直接访问表项的对象表都追不到,也不把数据识别成字符串,未追到的字节都是 `ByteTable`。
104
- - 旧模拟器(VirtuaNES)自带的 CDL 只对 SB2K 映射器有效。
105
73
  - SB2000 固件页的 CDL 验证没有做。
106
74
  - `da65` 输出的源码是 CRLF 换行。
107
-
108
- 以后要做的项目登记在 [待办备忘](待办备忘.md)。
@@ -1,6 +1,6 @@
1
1
  # 创建包与模板
2
2
 
3
- `create-fcdev` 是 `npm create fcdev` 运行的包:在空目录生成开发结构与示例程序,之后用 `npm run build` 构建。代码在 `packages/create-fcdev/`,只依赖 Node,不引入其他依赖。
3
+ `create-fcdev` 是 `npm create fcdev` 运行的包:在空目录生成开发结构与示例程序,之后用 `npm run build` 构建。只依赖 Node,不引入其他依赖。
4
4
 
5
5
  ## 1. 命令
6
6
 
@@ -50,16 +50,6 @@ npm create fcdev@latest [目录] [-- 选项]
50
50
 
51
51
  ## 4. 模板
52
52
 
53
- 每个模板是 `templates/<目标>-<语言>/` 目录,包含:
54
-
55
- | 文件 | 说明 |
56
- | --- | --- |
57
- | `template.json` | `target`、`language`、`title`,可选 `scripts`(额外的 npm 脚本)与 `notes`(创建完成后提示的说明);目录名必须等于 `<target>-<language>` |
58
- | `README.md` | 生成项目的说明,可用 `{{name}}`;末尾有“文档”一节,写明开发文档随 `fcdev` 安装在 `node_modules/fcdev/docs/`,并给出对应目标的 `npx fcdev docs <主题>` |
59
- | `src/hello.c` 或 `src/hello.s` | 示例程序 |
60
-
61
- 目录名以 `_` 开头的是公共文件目录,不是模板,目前只有 `_common/gitignore`。
62
-
63
53
  四个模板:
64
54
 
65
55
  | 模板 | hello world |
@@ -68,7 +58,3 @@ npm create fcdev@latest [目录] [-- 选项]
68
58
  | `nes-asm` | 同样的行为,汇编直接写 PPU 寄存器,`.include "fcnes.inc"`,导出 `_main` |
69
59
  | `sb2000-c` | `sb_puts` 显示英文与中文(GB2312)各一行,`sb_getkey` 等键后返回 |
70
60
  | `sb2000-asm` | 同样的行为,汇编调用 `_sb_puts`、`_sb_getkey`,导出 `_main` |
71
-
72
- ## 5. 新增模板
73
-
74
- 新增机型的目标后,在 `templates/` 下加 `<目标>-c` 与 `<目标>-asm` 两个目录,写 `template.json`、`README.md` 与示例程序;目标需要额外脚本或提示时写进 `template.json`。模板必须能用 `fcdev build` 构建成功,`npm run release:verify` 会逐个验证,见 [09-发布](09-发布.md)。
@@ -1,6 +1,6 @@
1
- # NES 目标
1
+ # NES 开发指南
2
2
 
3
- NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它之上加了一个辅助库 `fcnes` 和 ASCII 字库,使 hello 程序保持单文件。目标目录是 [packages/fcdev/targets/nes](../../targets/nes),字段含义见 [03-目标规范](../03-目标规范.md)。
3
+ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它之上加了一个辅助库 `fcnes` 和 ASCII 字库,使 hello 程序保持单文件。目标的定义与运行库随 `fcdev` 包安装,在包里的 `targets/nes/` 下。
4
4
 
5
5
  ## 1. 目标定义
6
6
 
@@ -39,14 +39,9 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
39
39
 
40
40
  ## 4. 字库
41
41
 
42
- - 字库数据来自公有领域的 `font8x8_basic`(Daniel Hepper,源自 IBM 公共领域 VGA 字体),原文件保留在 `chr/font8x8_basic.h`,已转成 `chr/ascii-8x8.chr`(ASCII `$20` 到 `$7F` 的 8×8 字模,共 1536 字节)。
43
42
  - `src/nes-font.s` 把字库放进 `CHARS` 段:前 `$200` 字节留空(对应 `$20` 之前的 32 个图块),之后是字模。
44
43
  - 目标选项 `font`(布尔,默认 `true`)为 `true` 时链接 `lib/nes-font.o`。在 `fcdev.json` 里写 `"targetOptions": { "font": false }` 可关闭,由程序自己提供 CHR 数据。
45
44
 
46
- ## 5. 运行库
45
+ ## 5. 运行
47
46
 
48
- `lib-build.json` 把 `src/fcnes.s` 编成 `lib/fcnes.lib`,把 `src/nes-font.s` 编成 `lib/nes-font.o`,`.incbin` 的搜索目录是 `chr`。构建方法见 [03-目标规范](../03-目标规范.md) 第 5 节。
49
-
50
- ## 6. 运行
51
-
52
- `npx fcdev run` 启动 Ember 直接加载 `.nes`,不需要固件;`--debug` 启动调试模式,程序载入后停在开机状态,继续用 `npx fcdev debug`,见 [05-模拟器与调试](../05-模拟器与调试.md)。验证记录见 [08-测试与验证](../08-测试与验证.md):NES 程序在 Ember 的调试模式里运行 60 帧并截图。
47
+ `npx fcdev run` 启动 Ember 直接加载 `.nes`,不需要固件;`--debug` 启动调试模式,程序载入后停在开机状态,继续用 `npx fcdev debug`,见 [02-模拟器与调试](../02-模拟器与调试.md)。验证方式:NES 程序在 Ember 的调试模式里运行 60 帧并截图。
@@ -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`),重名时先被当成内部命令。
@@ -130,7 +136,7 @@ npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里
130
136
  npx fcdev run src # 构建后在 Ember 里运行(需要 firmware);加 --debug 停在开机状态
131
137
  ```
132
138
 
133
- `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件(仓库里有一份:`reference/rom/SB2K_BIOS.NES`),没有设置时在构建之前报错。它把程序做成磁盘镜像挂到软驱,开机后自动在 SB-DOS 里跳过日期与时间、输入程序名运行(程序名只能用字母与数字);`--debug` 停在开机状态,由自己用 `fcdev debug` 操作,细节见 [05-模拟器与调试](../05-模拟器与调试.md) 第 3 节与第 7 节。本文下面写到的调试操作用 Ember 调试服务的请求表示。
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 # 构建后在 Ember 里运行(需要 firmware)
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 # 构建后在 Ember 里运行(需要 firmware)
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 # 构建后在 Ember 里运行(需要 firmware)
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 # 构建后在 Ember 里运行(需要 firmware)
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 文字` |
@@ -249,11 +252,3 @@ npx fcdev run src # 构建后在 Ember 里运行(需要 firmware)
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 解析核对。测试经 Ember 的调试服务运行:`sb2000-runner.mjs` 随机取空闲端口启动 Ember,依次添加 BIOS(环境变量 `FCDEV_TEST_FIRMWARE`,没有时用仓库里的 `reference/rom/SB2K_BIOS.NES`)、开机、放入镜像,运行到 SB-DOS 询问日期,回车跳过后输入程序名;按键用 `input.key`,手柄与鼠标用 `input.pad`、`input.mouse`,读内存用 `inspector.readMemory`,存回镜像用 `media.floppySave`,截图用 `output.screenshot`,结束时只结束自己启动的 Ember。需要 Ember(环境变量 `FCDEV_EMULATOR`)、cc65 与已构建的调试 SDK,缺一整组跳过。
256
-
257
- 停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`inspector.addBreakpoint kind=write`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 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 节。)