fcdev 0.2.0 → 0.3.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 (27) hide show
  1. package/README.md +18 -0
  2. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +164 -0
  3. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +157 -0
  4. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +123 -0
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +51 -0
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +100 -0
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +103 -0
  8. package/docs/07-/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +74 -0
  9. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +72 -0
  10. package/docs/09-/345/217/221/345/270/203.md +67 -0
  11. package/docs/10-VS Code/346/211/251/345/261/225.md" +131 -0
  12. package/docs/nes/01-NES/347/233/256/346/240/207.md +52 -0
  13. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +252 -0
  14. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +797 -0
  15. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +27 -0
  16. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +46 -0
  17. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +10 -0
  18. package/package.json +4 -3
  19. package/src/cli/commands/docs-command.mjs +58 -0
  20. package/src/cli/index.mjs +3 -0
  21. package/src/docs/doc-index.mjs +101 -0
  22. package/src/docs/doc-topics.mjs +38 -0
  23. package/src/docs/index.mjs +10 -0
  24. package/targets/nes/lib/fcnes.lib +0 -0
  25. package/targets/nes/lib/nes-font.o +0 -0
  26. package/targets/sb2000/lib/crt0.o +0 -0
  27. package/targets/sb2000/lib/sb2000.lib +0 -0
@@ -0,0 +1,252 @@
1
+ # SB2000 开发指南
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 节列出。
4
+
5
+ ## 1. 目标定义
6
+
7
+ | 项 | 值 |
8
+ | --- | --- |
9
+ | 目标名 | `sb2000` |
10
+ | `cc65Target` | `none`,用 `none.lib` 提供乘除法、移位、`memcpy` 等,不使用它的启动代码 |
11
+ | 链接配置 | `link.cfg`;`targetOptions.banks` 大于 0 时用 `link-banked.cfg` 展开的多页配置,见第 3.1 节 |
12
+ | 启动代码 | `lib/crt0.o` |
13
+ | 库 | `lib/sb2000.lib`、`toolchain:lib/none.lib` |
14
+ | 预定义宏 | `__SB2000__` |
15
+ | 打包器 | `flat-exe`,文件头必须匹配 `4C????AA55`,大小不超过 16384 字节(多页程序不检查大小上限) |
16
+ | 目标专用选项 | `banks`:数字,库页个数,默认 0(普通程序),最大 113 |
17
+ | 产物 | 大写主名的 `.EXE` |
18
+ | 程序名规则 | `dos-8.3` |
19
+ | 磁盘镜像 | `fat-floppy`,1.44MB |
20
+ | 运行方案 | `firmware-disk`,需要固件 |
21
+
22
+ ## 2. 程序格式
23
+
24
+ SB2000 的程序格式:
25
+
26
+ - 程序映像从 `$8000` 起,最大 16K(`$8000` 到 `$BFFF`);超过 16K 的程序用多页(换页),见第 3.1 节。
27
+ - 文件头 5 个字节:`4C lo hi AA 55`(`JMP` 到入口,再加魔数),其后 3 个字节:偏移 5、6 由 DOS 装入时改写(偏移 5 是起始页号,`sb_puts` 要用),偏移 7 保留;`crt0.s` 全部写 `00`。
28
+ - 程序以 `RTS` 返回 DOS;返回后 DOS 清屏,所以显示完要先等键。
29
+ - 系统调用:写 `SYS_FUNCTION`、`SYS_SUBFUNCTION`,再 `JSR SYSCALL`;A、X、Y 与进位不带回结果,结果由调用者读各服务规定的变量。
30
+ - 显示文字借用 ROM 页组 0 的运行库,经功能 `$25` 调用 `LIB_PRINT_STRING`。
31
+
32
+ ## 3. 内存布局
33
+
34
+ 由 `link.cfg` 决定:
35
+
36
+ | 区域 | 位置 | 说明 |
37
+ | --- | --- | --- |
38
+ | 零页 `ZP` | `$0060` 起 `$20` 字节 | C 运行库使用 |
39
+ | `MAIN` | `$8000` 到 `$BBFF`,共 15K | `HEADER`、`STARTUP`、`LOWCODE`、`ONCE`、`CODE`、`RODATA`、`DATA` 依次放在这里;`BSS` 紧随其后,不占文件空间,但占这块地址 |
40
+ | C 软件栈 | 1K,`$C000` 向下 | 在窗口顶端;`__STACKSTART__`、`__STACKSIZE__`、`__ZPSTART__` 是弱符号,可以覆盖 |
41
+ | 硬件栈 | `$0100` 到 `$01FF` | `main` 入口时 `S` 为 `$EA`,可用约 235 字节 |
42
+
43
+ 程序(含 `BSS`)超过 `MAIN` 的 15K 时,`ld65` 链接失败。打包器的 16384 字节上限是对映像大小的再一层检查。超过 16K 的程序用多页(换页),见第 3.1 节。
44
+
45
+ DOS 只按文件大小给程序分配扩展 RAM 页,而 `BSS` 与软件栈在 `$8000` 到 `$BFFF` 的 4 个窗口里,文件之外的页没有人占用,会被页分配服务分给别人。所以 `crt0.s` 启动时把窗口里不足 4 页的部分紧接着程序的页再申请下来(见第 4 节),返回 DOS 前释放。
46
+
47
+ ### 3.1 大程序(多页)
48
+
49
+ 程序超过 16K 时,在 `fcdev.json` 里设置库页个数:`"targetOptions": { "banks": N }`,N 为 0 到 113,默认 0 即普通程序。DOS 按文件大小一次装入整个文件,程序用功能 `$29`(`sb_window_map`)把后面的页换进窗口 2;换页由编译器与运行库配合自动完成(方案的验证见 [系统调用手册](02-系统调用手册.md) 第 9 节 V04)。
50
+
51
+ 文件按页(每页 4K)排列:
52
+
53
+ | 文件页 | 内容 | 地址 |
54
+ | --- | --- | --- |
55
+ | 0、1 | 常驻部分 `MAIN`:`main`、运行库、没放进库页的全部代码与数据、`BSS`,共 8K | `$8000` |
56
+ | 2 | 库页 1,程序启动时就在窗口 2 里 | `$A000` |
57
+ | 3 | 栈页:窗口 3,C 软件栈在它的顶端 1K,不放程序内容,不能当库页 | `$B000` |
58
+ | 4 起 | 库页 2 到 N | `$A000` |
59
+
60
+ 链接配置由 [link-banked.cfg](../../targets/sb2000/link-banked.cfg) 按库页个数展开成中间文件目录里的 `<程序名>.cfg`(规则见 [03-目标规范](../03-目标规范.md) 第 2.3 节);库页 n 的段名是 `BANKn`,一页放不下时 `ld65` 链接失败;程序里用到的库页号超过 `banks` 时,链接失败并提示加大 `banks`。
61
+
62
+ 写法(头文件 [sb2000-bank.h](../../targets/sb2000/include/sb2000-bank.h),`sb2000.h` 已包含):
63
+
64
+ ```c
65
+ /* parser.h:声明放在 SB_BANK_CALLS_BEGIN 里,调用时由编译器经蹦床换页 */
66
+ SB_BANK_CALLS_BEGIN(2)
67
+ unsigned int parse(unsigned int value, unsigned char mode);
68
+ SB_BANK_CALLS_END()
69
+
70
+ /* parser.c:定义放在 SB_BANK_BEGIN 里,进库页 2 */
71
+ SB_BANK_BEGIN(2)
72
+ unsigned int parse(unsigned int value, unsigned char mode) { return value + mode; }
73
+ SB_BANK_END()
74
+ ```
75
+
76
+ 原理:`SB_BANK_BEGIN(n)` 用 `#pragma code-name` 与 `rodata-name` 把后面的代码与只读数据放进段 `BANKn`;`SB_BANK_CALLS_BEGIN(n)` 用 cc65 的 `#pragma wrapped-call`,让编译器把对这些函数的每次直接调用改成 `JSR` 到库内部的蹦床 `sbi_bank_trampoline`(库页号在 `tmp4`,函数地址在 `ptr4`)。蹦床先暂存 A、X,把原来的库页压进硬件栈,调用 `sb_bank_select` 换入目标库页,A、X 与 C 栈上的参数原样交给函数;函数返回后暂存返回值,换回原来的库页再带回,所以库页函数之间可以嵌套调用。`sb_bank_select(n)` 与 `sb_bank_current()` 也可以自己调用,用来直接读库页里的数据。库页号 n 对应的程序页:1 是第 2 页,n 不小于 2 时是第 n+2 页(第 3 页是栈页)。
77
+
78
+ 限制:
79
+
80
+ - 库页里只放代码与只读数据(`const`);可写的变量与 `BSS` 在常驻部分,常驻部分连同运行库共 8K。
81
+ - 只有按函数名的直接调用经过蹦床;用函数指针调用库页函数、变参函数都不行。
82
+ - 库页函数返回指向库页数据的指针时,调用者拿到指针时窗口 2 已换回原来的库页,指向的内容可能已被换走;库页里的代码把窗口 2 里的地址传给系统服务时,指的是当时换入的库页。
83
+ - 最多 113 个库页,程序文件 116 页(约 468K);DOS 一次把整个文件装入内存,连续的空闲页不够时程序不能启动(实测 116 页能装入,160 页不能)。
84
+
85
+ ## 4. 启动代码
86
+
87
+ [crt0.s](../../targets/sb2000/src/crt0.s) 依次:
88
+
89
+ 1. 在 `HEADER` 段写文件头。
90
+ 2. 占页(`claim_pages`):文件占的页数不足 4 页时,用 `$7E/$00` 每次申请 1 页,申请到的页必须正好是紧接着程序的页,否则释放已申请的并以 `SB_ERR_NO_MEMORY` 返回 DOS(出错码放在 `$6308`)。
91
+ 3. 设置 C 软件栈指针为 `$C000`。
92
+ 4. 清 `BSS`(`zerobss`)。
93
+ 5. 调用构造函数(`initlib`)、`_main`、析构函数(`donelib`)。
94
+ 6. 释放启动时申请的页,`CLC`、`RTS` 返回 DOS。
95
+
96
+ `DATA` 随文件原位装入,不复制;返回 DOS 时不保存也不恢复零页,原因见 [系统调用手册](02-系统调用手册.md) 第 9 节。`main` 的返回值被忽略。运行子程序(`sb_exec`)时,子程序的启动代码会重设软件栈指针并改写零页,所以 `sb_exec` 在运行前后保存、恢复零页 `$60` 到 `$7F`(见 [系统调用手册](02-系统调用手册.md) 第 9 节 V07)。
97
+
98
+ ## 5. 最小程序、构建与运行
99
+
100
+ 创建项目(目标 `sb2000`,语言 `c` 或 `asm`)并构建:
101
+
102
+ ```bash
103
+ npm create fcdev@latest hello -- --target sb2000 --template c
104
+ cd hello
105
+ npm run build # 生成 build/sb2000/HELLO.EXE
106
+ ```
107
+
108
+ C 的最小程序(模板里的 `src/hello.c`):
109
+
110
+ ```c
111
+ #include <sb2000.h>
112
+
113
+ int main(void)
114
+ {
115
+ sb_puts("Hello, SB2000!");
116
+ /* GB2312:你好,小霸王! */
117
+ sb_puts("\xC4\xE3\xBA\xC3\xA3\xAC\xD0\xA1\xB0\xD4\xCD\xF5\xA3\xA1");
118
+ sb_getkey(); /* DOS 在程序返回后会清屏,不等待就看不到输出 */
119
+ return 0;
120
+ }
121
+ ```
122
+
123
+ 汇编程序导出 `_main`,由启动代码调用;`_sb_puts`、`_sb_getkey` 来自目标自带的库,参数用 cc65 的 fastcall:指针在 A(低)与 X(高),见模板 `sb2000-asm`。
124
+
125
+ 程序名取 `fcdev.json` 的 `name`,要符合 DOS 8.3 规则,且不要与 DOS 内部命令重名(如 `COPY`、`TYPE`、`DIR`),重名时先被当成内部命令。
126
+
127
+ ```bash
128
+ fcdev build src # 生成 build/sb2000/<NAME>.EXE
129
+ fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
130
+ fcdev run src # 构建,挂载镜像,在模拟器里运行
131
+ ```
132
+
133
+ `fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
134
+
135
+ ## 6. 头文件与函数
136
+
137
+ `sb2000.h` 包含 `sb2000-symbols.h` 与下面 13 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 184 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
138
+
139
+ | 头文件 | 模块 | 内容 |
140
+ | --- | --- | --- |
141
+ | `sb2000-system.h` | system | 等帧、NMI 与 IRQ 的开关与钩子、显示开关、系统初始化、跨页调用与跳转、上下文保存恢复、运行子程序 `sb_exec` |
142
+ | `sb2000-memory.h` | memory | 页的申请与释放、远读写、窗口映射、窗口地址换算 |
143
+ | `sb2000-bank.h` | bank | 大程序的库页:换页的宏 `SB_BANK_BEGIN` 等、`sb_bank_select`、`sb_bank_current`,见第 3.1 节 |
144
+ | `sb2000-text.h` | text | `sb_puts`、`sb_newline`、字符与数字输出、光标 |
145
+ | `sb2000-input.h` | input | 键盘、手柄、鼠标 |
146
+ | `sb2000-clock.h` | clock | 系统日期与时间 |
147
+ | `sb2000-file.h` | file | 文件与目录:打开、读写、整个加载与保存、删除、改名、属性、遍历 |
148
+ | `sb2000-disk.h` | disk | 软驱:按扇区读写、成批读写、扫描、格式化磁道、空闲字节数 |
149
+ | `sb2000-display.h` | display | 屏幕单元、文字、字模、窗口保存还原、调色板、显存 DMA、图片解压与显示 |
150
+ | `sb2000-math.h` | math | 伪随机数、除法、浮点与 40 位整数的文字转换、直线步进、3 字节整数运算 |
151
+ | `sb2000-sound.h` | sound | 曲子与音效、WAV、语音 |
152
+ | `sb2000-printer.h` | printer | 24 针点阵打印机 |
153
+ | `sb2000-ime.h` | ime | 中文输入法 |
154
+
155
+ 约定:
156
+
157
+ - 命名 `sb_<模块>_<动作>`;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
158
+ - 字符串、缓冲区、结构体指针必须在程序窗口 `$8000` 到 `$BFFF` 里(读写目标不能在窗口 3);系统服务换页后程序窗口不可见的情况,函数内部已经处理好。
159
+ - 一个函数一个源文件,放在 `src/lib/<模块>/sb-<函数名>.c`(或 `.s`);库内部用的辅助函数以 `sbi_` 开头,声明在 `src/lib/sb-internal.h`,不对外。
160
+ - 运行库由 `tools/build-libs.mjs` 编译:`lib-build.json` 里以 `/` 结尾的项展开成目录下全部 `.c` 与 `.s`;`.c` 用 `cc65 -t none --cpu 6502 -Oirs` 编译再汇编,同名文件报错。链接只带入程序用到的函数。
161
+
162
+ 随时查询接口:
163
+
164
+ - `fcdev api` 列出全部模块;`fcdev api <函数名>` 看完整文档;`fcdev api <模块名>` 看函数列表;`fcdev api '$7B'` 或 `fcdev api '$7B/$09'` 看用到某个系统调用的函数;`fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
165
+ - [api-reference.md](../../targets/sb2000/api-reference.md) 是同一份文档的整本 Markdown,由 `node tools/gen-sb2000-api-doc.mjs` 从头文件生成,末尾有“系统调用覆盖表”。改头文件注释后重新生成,测试会核对。
166
+ - [api-unwrapped.json](../../targets/sb2000/api-unwrapped.json) 登记没有封装的功能号与子功能及原因(`functions` 是整个功能号不封装,`partial` 是封装了一部分)。`node tools/check-sb2000-api.mjs` 检查:头文件里每个函数有说明、`@param`、`@return`,有且只有一处实现,库里没有头文件之外的公开函数,BIOS 里有处理例程的每个功能号(`KNOWN_FUNCTIONS`)要么被某个函数的 `@syscall` 涉及、要么在 `functions` 里写明原因。
167
+
168
+ 不封装的内容(详见覆盖表):文件系统内部步骤(FAT、簇链、扇区定位)、`$41` 到 `$44` 带步长的屏幕单元写入、`$31` 与 `$34` 的显存填充与 DMA 变体、`$66` 卡拉 OK、`$65` 与 `$6D` 的部分子功能、`$74` 与 `$75` 的 NMI 发送与播放列表等,需要时用 `sb_syscall` 加 `sb2000-symbols.h` 里的常量自行调用。
169
+
170
+ `sb_puts` 的实现要点:`LIB_PRINT_STRING` 在光标当前列显示字符串且不移动光标,所以先把光标列置 1(行首)再显示,显示后换行;字符串在程序所在的页组里,页组首页号取自文件头偏移 5。
171
+
172
+ ## 7. 符号定义
173
+
174
+ - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
175
+ - [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
+
177
+ ## 8. 常用做法
178
+
179
+ 下面每一项都有可参考的示例程序(第 10 节)。表里的符号名(`SYS_FUNCTION`、`FN_INPUT` 等)是汇编用的 `sb2000.inc` 里的名字,C 里加 `SB_` 前缀(第 7 节);C 程序一般直接用第 6 节的函数。
180
+
181
+ | 要做的事 | 做法 | 示例 |
182
+ | --- | --- | --- |
183
+ | 调用系统服务 | 写 `SYS_FUNCTION`(功能号)、`SYS_SUBFUNCTION`,`JSR SYSCALL`;A、X、Y、进位都不会带回,结果只在内存变量里 | 全部 |
184
+ | 显示文字 | 借用运行库:经功能 `FN_CALL_BANKED`(`SYS_GROUP=0`,入口写 `PROG_ENTRY_LO/HI`)调用 `LIB_PRINT_STRING`;字符串在程序里时 `LIB_GROUP` 写 `$80`,在 ERAM 里写 0;字符码不小于 `$A1` 按 GB2312 显示汉字;用 `LIB_NEWLINE` 换行(先把 `CURSOR_COL` 置 1) | `hello` |
185
+ | 等待按键 | `FN_INPUT` 的 `SUB_KEY_GET_WAIT`,结果在 `KEY_ASCII`、`KEY_SCAN` | `hello` |
186
+ | 取命令行参数 | `CMD_TAIL`(`$6364`):第 1 个字节是分隔空格,已转大写,以 0 结尾;`$6364` 为 0 表示没有参数 | `say`、`copy` |
187
+ | 读整个文件 | 打开(`$7B/$09`,方式 0)→ 取大小(`$7C/$0D`)→ 按页分配(`$7E/$00`)→ 读入(`$7C/$0F`)→ 关闭(`$7B/$0A`)→ 释放(`$7E/$01`)→ 软驱停转(`$80/$07`) | `show` |
188
+ | 读文件的一段 | 打开后写 `FILE_OFFSET_0-2`、`FILE_SIZE_0-2`(长度)、`FILE_START_PAGE`,调用 `$7C/$05`;越界出错码 `$14` | `peek` |
189
+ | 写文件 | 方式 1 打开(不存在则建立,已存在则覆盖)→ 写 `FILE_SIZE_0-2`、`FILE_START_PAGE` → `$7C/$10` → 关闭;关闭前文件不会写回目录项;空文件不能用 `$7C/$10` 写,打开后直接关闭即可 | `copy` |
190
+ | 改文件的一段 | 方式 2 打开已有文件 → 写 `FILE_OFFSET_0-2`、`FILE_SIZE_0-2`、`FILE_START_PAGE` → `$7C/$06` → 关闭;文件大小不变,可以跨扇区 | `poke` |
191
+ | 访问读入的数据 | 用功能 `FN_MAP_WINDOW`(`$29`)把页映射到窗口(`SYS_PAGE` 页号、`SYS_WINDOW` 窗口号),窗口 3 在 `$B000`;程序自己在窗口 0 里,不要映射窗口 0 | `show` |
192
+ | 处理出错 | 每次文件或页服务调用后读 `DOS_ERROR`(`$6300`),0 为成功;出错码含义见 系统调用手册第 6 节;出错时按已做的步骤倒序清理(关闭文件、释放页、软驱停转) | `copy` |
193
+ | 读手柄 | 先 `$12/$85` 打开 NMI 里的手柄读取,再 `$6A/$00` 初始化;`$6A/$01` 不等待取键码、`$6A/$02` 等到有键,键码在 `PAD_KEY`(A 为 `$0F`,右为 `$08`,无键 `$FF`),原始状态在 `PAD1_BITS`、`PAD2_BITS`(位 7 为 A,位 0 为右) | `pad` |
194
+ | 读鼠标 | `$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
+ | 播放 WAV | 功能 `$65`、子功能 `$0C`(`SUB_SOUND_WAV`,C 里是 `sb_sound_play_wav`),见 [系统调用手册](02-系统调用手册.md) 5.5(只读过代码,没有示例) | — |
196
+ | 把 NES 游戏当程序运行 | 读入 `.nes`、复制启动桩到 ERAM、写 `$4301` 后跳转 | `play` |
197
+
198
+ ## 9. 要避开的坑
199
+
200
+ - **程序返回后 DOS 会清屏。** 显示完先等待按键再返回,否则看不到输出。
201
+ - **运行库例程拿不到寄存器参数。** 经功能 `$25` 调用时分发器用页组值覆盖了 A,所以 `LIB_PRINT_HEX` 这类要 A 传参的例程不能用;要显示十六进制就自己转换(见示例 `show`)。
202
+ - **`LIB_PRINT_STRING` 在光标当前列开始显示,且不会移动光标。** 分两次显示同一行会互相覆盖;要整行显示就先拼好再一次显示,换行前把 `CURSOR_COL` 置 1。
203
+ - **服务的结果不要从进位标志取。** 要读 `DOS_ERROR`(文件、页服务)或各服务规定的变量。
204
+ - **`FILE_SIZE_0-2`、`FILE_START_PAGE` 等单元会被后续调用改写。** 写文件时在 `$7C/$10` 之前才写这些单元;需要的值先存到程序自己的变量里(程序在 ERAM 里,变量可以直接放在代码后面)。
205
+ - **页分配的 `ALLOC_COUNT`、`ALLOC_START` 要在释放前写回。** 它们也会被别的调用改写,所以自己保存起始页号与页数。
206
+ - **示例里的页数换算只适用于不大于 64K 的文件。** 文件大小的第 3 字节非 0 时,示例按“内存不足”处理。
207
+ - **从键盘启动程序时,模拟器把回车键当成手柄的选择加开始键。** 读手柄的程序要先等几十帧再初始化(示例 `pad` 等 120 帧),否则会马上读到这两个键。
208
+ - **鼠标中断要用 `$13/$81` 允许。** `$13` 的位是“屏蔽”位,`$13/$01` 是屏蔽、`$13/$81` 才是允许;屏蔽时一直收不到鼠标数据。
209
+ - **手柄服务 `$6A` 要先用 `$12/$85` 打开。** 否则 NMI 里不读手柄,`$6A/$02` 会一直等下去。
210
+ - **不要直接 `JSR` 到别的页组的地址。** 跨页调用要经 `$25`、`$26`。
211
+
212
+ ## 10. 示例程序
213
+
214
+ 示例在仓库的 `examples/sb2000/` 下,每个是一个 fcdev 项目;在仓库根目录用 `node packages/fcdev/bin/fcdev.mjs build examples/sb2000/<名>` 构建。
215
+
216
+ | 目录 | 作用 | 用法(在 DOS 提示符下) |
217
+ | --- | --- | --- |
218
+ | `hello` | 显示英文与中文各一行 | `hello` |
219
+ | `say` | 显示命令行参数 | `say 文字` |
220
+ | `show` | 读文件并显示开头 90 字节 | `show 文件名` |
221
+ | `copy` | 复制文件(文件不超过 64K) | `cp 源 目标` |
222
+ | `peek` | 按十六进制偏移读文件 30 字节 | `peek 文件名 偏移` |
223
+ | `poke` | 按十六进制偏移把文字写进已有文件(最长 60 个字符,大写) | `poke 文件名 偏移 文字` |
224
+ | `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试命令 `pad 0 掩码` 按键) |
225
+ | `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试命令 `mouse move dx dy` 移动) |
226
+ | `play` | 把 NES 游戏装入并运行(mapper 0 与 4,PRG、CHR 各不超过 128K) | `play 文件名.nes`(放进软盘镜像的文件名要符合 8.3) |
227
+ | `newcall` | 调用 BIOS 里新增的系统调用 $35,显示扩展版本号;原始 BIOS 不支持时显示 NOT SUPPORTED(演示给自己修改的 BIOS 做功能检测) | `newcall` |
228
+ | `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试命令 `write cpu` 写请求块,格式见源码文件头) |
229
+
230
+ ## 11. 限制与没做过的事
231
+
232
+ - `main` 的返回值不实现为退出码:`$6308` 是运行库显示消息用的 `LIB_GROUP`,DOS 外壳运行程序后只记录装入与运行状态,不读取程序返回时的它,系统里没有退出码这个约定。
233
+ - 程序最大 16K 的窗口,其中顶端 1K 是 C 栈,程序(含 `BSS`)实际最大 15K,窗口里的 4 页由 `crt0.s` 占住。
234
+ - 运行需要用户自己提供 BIOS 文件,不随包发布。DOS 启动后要按两次回车跳过日期与时间提示,才能输入程序名。
235
+ - 大程序(超过 16K)用多页(第 3.1 节):库页里只放代码与只读数据;函数指针与变参函数不能经蹦床调用库页函数;指向库页数据的指针只在该库页换入窗口 2 时有效;最多 113 个库页,DOS 里连续空闲页不够时程序不能启动。
236
+ - 英文输入法(序号 9)下按键不设结果标志,`sb_ime_key_wait` 会一直等;用全拼等需要选字的输入法。外挂输入法模块与联想方式没有验证。
237
+ - 没有封装的功能见 `api-reference.md` 末尾的覆盖表。
238
+
239
+ 没做过的事:
240
+
241
+ - 屏幕绘图与精灵等直接操作 PPU 的程序;显示服务 `$3B-$61` 的参数只实测了 `$40` 子功能 0 的整屏填充和 `$3C` 的图块号,其余只读过代码(见 [系统调用手册](02-系统调用手册.md) 5.12 节)。
242
+ - 声音服务 `$65` 的音乐数据格式。
243
+
244
+ 这些见 [系统调用手册](02-系统调用手册.md) 第 8 节,读懂并验证后补进来。
245
+
246
+ ## 12. 运行库的测试
247
+
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,没有时整组跳过。
249
+
250
+ 停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
251
+
252
+ 接口检查与参考文档的测试在 `test/sb2000-api.test.mjs`,`fcdev api` 命令的测试在 `packages/fcdev/test/api-command.test.mjs`。