fcdev 0.4.0 → 0.5.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.
- package/CHANGELOG.md +22 -0
- package/README.md +22 -20
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +3 -3
- package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +2 -0
- package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +8 -6
- package/docs/06-/345/217/215/346/261/207/347/274/226.md +9 -4
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +1 -1
- package/docs/09-/345/217/221/345/270/203.md +4 -3
- package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
- package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +15 -8
- package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +7 -7
- package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +17 -8
- package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +3 -1
- package/package.json +4 -3
- package/src/cli/commands/api-command.mjs +2 -2
- package/src/cli/commands/build-command.mjs +1 -1
- package/src/cli/commands/debug-command.mjs +5 -2
- package/src/cli/commands/disasm-command.mjs +1 -1
- package/src/cli/commands/disk-command.mjs +1 -1
- package/src/cli/commands/docs-command.mjs +3 -3
- package/src/cli/commands/run-command.mjs +2 -2
- package/src/disasm/address-tables.mjs +161 -0
- package/src/disasm/analysis.mjs +17 -11
- package/src/disasm/byte-kinds.mjs +20 -0
- package/src/disasm/disassembler.mjs +3 -2
- package/src/disasm/info-writer.mjs +3 -3
- package/src/docs/doc-topics.mjs +1 -1
- package/src/emulator/debug-client.mjs +1 -1
- package/targets/nes/lib/fcnes.lib +0 -0
- package/targets/nes/lib/nes-font.o +0 -0
- package/targets/sb2000/api-reference.md +310 -1
- package/targets/sb2000/asminc/sb2000.inc +90 -1
- package/targets/sb2000/include/sb2000-dma.h +46 -0
- package/targets/sb2000/include/sb2000-ppu.h +106 -0
- package/targets/sb2000/include/sb2000-symbols.h +170 -0
- package/targets/sb2000/include/sb2000-timer.h +54 -0
- package/targets/sb2000/include/sb2000.h +3 -0
- package/targets/sb2000/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
- package/targets/sb2000/src/lib/dma/sb-dma-page-address.c +16 -0
- package/targets/sb2000/src/lib/dma/sb-dma-to-cpu.c +19 -0
- package/targets/sb2000/src/lib/dma/sb-dma-to-vram.c +16 -0
- package/targets/sb2000/src/lib/dma/sbi-dma-run.c +34 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-address.c +20 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-fill.c +19 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-oam-clear.c +21 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-oam-put.c +20 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-palette-get.c +16 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-palette-set.c +16 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-peek.c +22 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-read.c +20 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-render.c +20 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-wait-vblank.c +25 -0
- package/targets/sb2000/src/lib/ppu/sb-ppu-write.c +21 -0
- package/targets/sb2000/src/lib/sb-internal.h +3 -0
- package/targets/sb2000/src/lib/timer/sb-timer-current.c +16 -0
- package/targets/sb2000/src/lib/timer/sb-timer-mask.c +16 -0
- package/targets/sb2000/src/lib/timer/sb-timer-pending.c +16 -0
- package/targets/sb2000/src/lib/timer/sb-timer-start.c +17 -0
- package/targets/sb2000/src/lib/timer/sb-timer-stop.c +16 -0
- package/targets/sb2000/src/lib/timer/sb-timer-unmask.c +16 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# 更新记录
|
|
2
|
+
|
|
3
|
+
适用于 `fcdev`、`create-fcdev`、`@rujianjs/fcdev-cc65`、`@rujianjs/fcdev-emulator` 四个包,它们的版本号相同。
|
|
4
|
+
|
|
5
|
+
## 0.5.0(2026-11-13)
|
|
6
|
+
|
|
7
|
+
### 小霸王学习机 SB2000
|
|
8
|
+
|
|
9
|
+
- 新增直接操作硬件的函数:通用 DMA、图形端口(显存、调色板、精灵)和硬件定时器,程序不用再自己写寄存器。
|
|
10
|
+
- 新增硬件寄存器与位的符号,C 里以 `SB_HW_` 开头,汇编里以 `HW_` 开头。
|
|
11
|
+
- C 接口参考扩充到 204 个函数,用 `npx fcdev api dma`、`npx fcdev api ppu`、`npx fcdev api timer` 查询新增的三个模块。
|
|
12
|
+
- 硬件说明按真机实测更新:图形端口、DMA 和定时器的行为,并列出真机与模拟器仍有差异的读数。
|
|
13
|
+
|
|
14
|
+
### 反汇编
|
|
15
|
+
|
|
16
|
+
- 识别地址表:`LDA 表,X` 加间接跳转、`PHA`/`RTS`、`JMP (地址)` 指向的表,表里的地址作为新入口继续追踪。
|
|
17
|
+
|
|
18
|
+
### 模拟器与调试
|
|
19
|
+
|
|
20
|
+
- `fcdev debug` 的 `tape play`、`tape rec` 命令里的文件路径按终端当前目录解析。
|
|
21
|
+
- 模拟器包带上新版模拟器,改动见模拟器的更新记录。
|
|
22
|
+
- 命令的提示、错误说明和文档里的示例统一写成 `npx fcdev …`,终端里直接输入 `fcdev` 会找不到命令的原因也写进了使用说明。
|
package/README.md
CHANGED
|
@@ -14,17 +14,19 @@ npm install --save-dev fcdev
|
|
|
14
14
|
|
|
15
15
|
## 使用
|
|
16
16
|
|
|
17
|
+
`fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里直接输入 `fcdev` 会提示找不到命令,要写成 `npx fcdev …`。`package.json` 的 `scripts` 里可以直接写 `fcdev …`,用 `npm run <脚本>` 运行。想直接输入 `fcdev`,可以全局安装:`npm install -g fcdev`。
|
|
18
|
+
|
|
17
19
|
```bash
|
|
18
|
-
fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
|
|
19
|
-
fcdev build src # 构建目录 src
|
|
20
|
-
fcdev build src/a.c # 只构建这个文件,它自己是一个程序
|
|
21
|
-
fcdev run src # 构建后在模拟器里运行
|
|
22
|
-
fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
|
|
23
|
-
fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
|
|
24
|
-
fcdev sync # 生成 IDE 的 C/C++ 配置
|
|
25
|
-
fcdev info --json # 显示目标、工具链与头文件目录
|
|
26
|
-
fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
|
|
27
|
-
fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
|
|
20
|
+
npx fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
|
|
21
|
+
npx fcdev build src # 构建目录 src
|
|
22
|
+
npx fcdev build src/a.c # 只构建这个文件,它自己是一个程序
|
|
23
|
+
npx fcdev run src # 构建后在模拟器里运行
|
|
24
|
+
npx fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
|
|
25
|
+
npx fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
|
|
26
|
+
npx fcdev sync # 生成 IDE 的 C/C++ 配置
|
|
27
|
+
npx fcdev info --json # 显示目标、工具链与头文件目录
|
|
28
|
+
npx fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
|
|
29
|
+
npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
|
|
28
30
|
```
|
|
29
31
|
|
|
30
32
|
入口是 `main`(汇编程序写 `.export _main`)。产物放在项目根的 `build/<目标>/`,中间文件在 `build/obj/`。
|
|
@@ -32,9 +34,9 @@ fcdev docs syscall # 查开发文档的本机路径(主题名或关键词
|
|
|
32
34
|
### 调试
|
|
33
35
|
|
|
34
36
|
```bash
|
|
35
|
-
fcdev run --debug --port 5688 src # 以调试模式启动模拟器,只在收到 run 命令时运行
|
|
36
|
-
FCDEV_DEBUG_PORT=5688 fcdev debug run 60
|
|
37
|
-
FCDEV_DEBUG_PORT=5688 fcdev debug shot screen.png
|
|
37
|
+
npx fcdev run --debug --port 5688 src # 以调试模式启动模拟器,只在收到 run 命令时运行
|
|
38
|
+
FCDEV_DEBUG_PORT=5688 npx fcdev debug run 60
|
|
39
|
+
FCDEV_DEBUG_PORT=5688 npx fcdev debug shot screen.png
|
|
38
40
|
```
|
|
39
41
|
|
|
40
42
|
`debug` 把命令原样转发给模拟器的调试服务,命令表见模拟器的说明文档。调试端口默认 5699。
|
|
@@ -42,9 +44,9 @@ FCDEV_DEBUG_PORT=5688 fcdev debug shot screen.png
|
|
|
42
44
|
### 反汇编
|
|
43
45
|
|
|
44
46
|
```bash
|
|
45
|
-
fcdev disasm game.nes # NES(NROM),入口取自中断向量
|
|
46
|
-
fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:加载地址与入口
|
|
47
|
-
fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
|
|
47
|
+
npx fcdev disasm game.nes # NES(NROM),入口取自中断向量
|
|
48
|
+
npx fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:加载地址与入口
|
|
49
|
+
npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
|
|
48
50
|
```
|
|
49
51
|
|
|
50
52
|
用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(模拟器 `trace` 命令的日志)补充运行时才执行到的代码。
|
|
@@ -71,11 +73,11 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
|
|
|
71
73
|
| 目标 | 产物 | 头文件 | 说明 |
|
|
72
74
|
| --- | --- | --- | --- |
|
|
73
75
|
| `nes` | `.nes` | `nes.h`(cc65)、`fcnes.h` | NROM,16K PRG 加 8K CHR;`fcnes.h` 提供调色板、文字显示与等待垂直消隐 |
|
|
74
|
-
| `sb2000` | `.EXE` | `sb2000.h` | 程序从 `$8000` 起装入,默认最大 16K,设 `targetOptions.banks` 后可换页做到约 468K;C 栈在窗口顶端;运行库把 DOS
|
|
76
|
+
| `sb2000` | `.EXE` | `sb2000.h` | 程序从 `$8000` 起装入,默认最大 16K,设 `targetOptions.banks` 后可换页做到约 468K;C 栈在窗口顶端;运行库把 DOS 的系统调用和硬件寄存器封装成 200 多个 C 函数(文字、键盘手柄鼠标、文件目录、软驱、显示、声音、数学、打印机、输入法,以及 DMA、图形端口、定时器等硬件操作),用 `fcdev api` 查询,整本文档见 `targets/sb2000/api-reference.md` |
|
|
75
77
|
|
|
76
78
|
## 文档
|
|
77
79
|
|
|
78
|
-
完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `fcdev docs` 列出全部主题,`fcdev docs <主题>`
|
|
80
|
+
完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
|
|
79
81
|
|
|
80
82
|
| 想做什么 | 主题 | 文档 |
|
|
81
83
|
| --- | --- | --- |
|
|
@@ -84,7 +86,7 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
|
|
|
84
86
|
| 开发 SB2000(SB-DOS)程序 | `sb2000` | `docs/sb2000/01-开发指南.md` |
|
|
85
87
|
| 查 SB-DOS 系统调用与出错码 | `syscall` | `docs/sb2000/02-系统调用手册.md` |
|
|
86
88
|
| 查 SB2000 的硬件行为 | `hardware` | `docs/sb2000/03-硬件说明.md` |
|
|
87
|
-
| 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `fcdev api` 查询) |
|
|
89
|
+
| 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `npx fcdev api` 查询) |
|
|
88
90
|
| 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/05-模拟器与调试.md` |
|
|
89
91
|
| 反汇编已有程序 | `disasm` | `docs/06-反汇编.md` |
|
|
90
92
|
| 创建项目与模板 | `create` | `docs/07-创建包与模板.md` |
|
|
@@ -92,7 +94,7 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
|
|
|
92
94
|
|
|
93
95
|
## 限制
|
|
94
96
|
|
|
95
|
-
- 反汇编目前只支持 NROM
|
|
97
|
+
- 反汇编目前只支持 NROM 与平铺二进制;静态追踪只追到经地址表分发的间接跳转,其他间接调用的代码按数据输出,回读仍然一致。
|
|
96
98
|
- SB2000 程序的退出码被忽略,`main` 返回后总是回到 DOS。
|
|
97
99
|
- `run` 在非调试模式下沿用模拟器的单实例规则:已有普通的模拟器窗口时,会把程序交给它打开。
|
|
98
100
|
|
|
@@ -84,7 +84,7 @@ famiclone/
|
|
|
84
84
|
apps/ 应用程序与示例(apps/sb2000:SB-DOS 的 asm、edit、runnes、disk 与 examples 示例),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
|
|
85
85
|
test/ 仓库级测试:目录结构、cc65 工具链包、SB2000 头文件
|
|
86
86
|
machines/ 各机型的资料与工程(不属于 fcdev 包,不随包发布),一个机型一个目录,如 machines/sb2000
|
|
87
|
-
build/
|
|
87
|
+
build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是模拟器的编译输出
|
|
88
88
|
```
|
|
89
89
|
|
|
90
90
|
## 5. 主包分层
|
|
@@ -143,7 +143,7 @@ famiclone/
|
|
|
143
143
|
|
|
144
144
|
## 9. 文档清单
|
|
145
145
|
|
|
146
|
-
文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
|
|
146
|
+
文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`npx fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
|
|
147
147
|
|
|
148
148
|
| 主题 | 文档 | 内容 |
|
|
149
149
|
| --- | --- | --- |
|
|
@@ -161,6 +161,6 @@ famiclone/
|
|
|
161
161
|
| `sb2000` | [sb2000/01-开发指南](sb2000/01-开发指南.md) | SB2000 目标的程序格式、内存布局、运行库、常用做法与示例 |
|
|
162
162
|
| `syscall` | [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) | SB-DOS 的系统调用:参数、结果、出错码与可靠程度 |
|
|
163
163
|
| `hardware` | [sb2000/03-硬件说明](sb2000/03-硬件说明.md) | SB2000 的硬件行为 |
|
|
164
|
-
| `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `fcdev api`) |
|
|
164
|
+
| `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `npx fcdev api`) |
|
|
165
165
|
| `todo` | [待办备忘](待办备忘.md) | 已确定以后再做的事项 |
|
|
166
166
|
| `bugs` | [缺陷记录](缺陷记录.md) | 发现的缺陷及修复情况 |
|
|
@@ -6,6 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
入口是 [packages/fcdev/bin/fcdev.mjs](../bin/fcdev.mjs),由 `cli/index.mjs` 的 `runCli` 分发。命令正常结束返回 0;出现 `FcdevError` 时向标准错误写“错误:”加说明与建议,返回 1。
|
|
8
8
|
|
|
9
|
+
`fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里要写成 `npx fcdev <命令>`(全局安装 `npm install -g fcdev` 后可以直接写 `fcdev <命令>`);`package.json` 的 `scripts` 里直接写 `fcdev <命令>`。下面的表格和本文其余地方都省略 `npx`。
|
|
10
|
+
|
|
9
11
|
| 命令 | 作用 |
|
|
10
12
|
| --- | --- |
|
|
11
13
|
| `fcdev build [路径]` | 构建,规则见第 2 节 |
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
- 基于 Win32 与 DirectX。许可证 GPL-3.0-only,包里附许可文件。
|
|
8
8
|
- 模拟器是 32 位程序,`bin/` 里随带 `vcruntime140.dll`、`msvcp140.dll`(应用本地部署)。
|
|
9
9
|
- 包内容:`bin/VirtuaNES.exe`、`bin/Chinese.vlp`、两个运行库、`LICENSE`、`manifest.json`、`package.json`。入库的只有 `package.json`,其余是生成物。
|
|
10
|
-
- 模拟器运行时会在 `bin/` 里写 `VirtuaNES.ini` 与 `save
|
|
10
|
+
- 模拟器运行时会在 `bin/` 里写 `VirtuaNES.ini` 与 `save/`;模拟器包的 `files` 只列出 `manifest.json` 里的文件,所以这些文件不会发布,不用删。
|
|
11
11
|
|
|
12
12
|
构建:
|
|
13
13
|
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
node tools/build-emulator.mjs
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
`tools/build-emulator.mjs` 需要 Visual Studio(含“使用 C++ 的桌面开发”)。它调用 `virtuanes/build.ps1 -Configuration Release
|
|
18
|
+
`tools/build-emulator.mjs` 需要 Visual Studio(含“使用 C++ 的桌面开发”)。它调用 `virtuanes/build.ps1 -Configuration Release`(编译输出在仓库根目录的 `build/virtuanes/Release/bin/`),把 `VirtuaNES.exe` 与 `Chinese.vlp` 复制进 `bin/`,再用 `vswhere` 找到 Visual Studio 里 32 位的 VC++ 运行库一并放入,最后写 `LICENSE`、`manifest.json`(当前提交、`virtuanes/` 有无未提交改动 `sourceDirty`、各文件的 SHA-256)与 `package.json`。编译前只结束调试实例(调试服务监听 `127.0.0.1` 端口的 `VirtuaNES.exe`);用户自己打开的模拟器不会被结束,它们占用输出文件时编译报错,需先自行关闭。
|
|
19
19
|
|
|
20
20
|
## 2. 定位模拟器
|
|
21
21
|
|
|
@@ -45,13 +45,13 @@ node tools/build-emulator.mjs
|
|
|
45
45
|
## 4. `fcdev debug`
|
|
46
46
|
|
|
47
47
|
```bash
|
|
48
|
-
fcdev debug run 60
|
|
49
|
-
fcdev debug shot screen.png
|
|
48
|
+
npx fcdev debug run 60
|
|
49
|
+
npx fcdev debug shot screen.png
|
|
50
50
|
```
|
|
51
51
|
|
|
52
52
|
- 把命令原样转发给调试服务,打印应答;应答首行以 `OK` 开头时退出码为 0,否则为 1。
|
|
53
53
|
- 端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
|
|
54
|
-
- 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save`
|
|
54
|
+
- 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀、`tape play`、`tape rec` 的文件;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
|
|
55
55
|
- `run`、`step` 的应答超时是 10 分钟,其余命令 30 秒。
|
|
56
56
|
|
|
57
57
|
## 5. 调试服务协议
|
|
@@ -79,12 +79,14 @@ fcdev debug shot screen.png
|
|
|
79
79
|
| `key <扫描码> <0\|1>`、`key clear` | 按下或松开键盘键(DirectInput 扫描码) |
|
|
80
80
|
| `mouse move <dx> <dy>`、`mouse btn <掩码>` | 鼠标移动与按键 |
|
|
81
81
|
| `shot <文件.png>` | 截图 |
|
|
82
|
-
| `trace <文件> [最大行数]`、`trace off` |
|
|
82
|
+
| `trace <文件> [最大行数] [unique]`、`trace off` | 记录每条指令与中断;加 `unique` 时每个 CPU 地址的指令、每个中断入口只记第一次,最大行数按实际写出的行数算(适合长时间运行后给 `fcdev disasm --trace` 用;只按 CPU 地址去重,换页后同一地址的其他代码会漏记) |
|
|
83
83
|
| `io <文件> [最大行数] [w]`、`io off` | 记录 `$2000-$4FFF` 的读写;加 `w` 只记录写 |
|
|
84
84
|
| `pad <0-3> <十六进制掩码>`、`pad <0-3> clear` | 注入手柄按键(A=01、B=02、Select=04、Start=08、上=10、下=20、左=40、右=80),与真实输入合并 |
|
|
85
85
|
| `disklog <文件> [最大行数]`、`disklog off` | 记录软驱控制器读写的 LBA |
|
|
86
86
|
| `calllog <文件> <pc> <地址:长度[,...]> [最大次数] [skip=地址=值[,...]]`、`calllog off` | 每次执行到 `pc` 就记录寄存器、栈顶与内存段;`skip` 表示该地址字节等于值(十六进制)时不记录;可添加多条,`off` 全部关闭 |
|
|
87
87
|
| `cdl on\|off\|clear\|save <前缀>` | 代码数据标记,保存为 `<前缀>-rom.cdl`、`<前缀>-pram.cdl` |
|
|
88
|
+
| `dialogs [clear]` | 列出调试期间被自动关闭的对话框(标题、文字、按下的按钮),`clear` 同时清空记录。调试服务启动后,模拟器自己弹出的消息框、文件框会被自动按下“确定”“取消”“否”“忽略”“关闭”中第一个存在的按钮,不会停在模态对话框上;文件对话框(打开、另存为,如虚拟打印机输出 PNG 时的“Save to...”)直接按“取消”,因为没有文件名时“确定”不起作用 |
|
|
89
|
+
| `tape play <文件>`、`tape rec <文件>`、`tape stop`、`tape status` | 数据录音机(`.vtp`)的播放与录制;`rec` 的文件在 `stop` 后才完整(命令已实现,还没有用实际程序验证) |
|
|
88
90
|
| `disk <镜像>`、`savedisk` | 挂载或保存软盘镜像 |
|
|
89
91
|
| `fdc eject\|insert\|wp <0\|1>\|noindex <0\|1>\|seekfail <0\|1>\|dead <0\|1>\|bad <逻辑扇区...>\|clear\|status` | 软驱故障注入。`eject`、`insert` 取出、放回盘片(取出后控制器对 READ ID 报找不到地址标志);`wp` 写保护;`noindex` 没有索引脉冲(READ ID、读写、格式化命令一直不结束);`seekfail` 磁头卡住(SEEK、RECALIBRATE 不移动,已在 0 磁道时回 0 磁道仍成功);`dead` 控制器收到命令字节后不再处理;`bad` 指定的逻辑扇区(十进制)读时报数据校验错,写不受影响;`clear` 关闭全部故障、放回盘片并取消写保护;`status` 显示当前状态。`disk` 挂载新镜像时也会清掉全部故障 |
|
|
90
92
|
| `audio fast\|real` | 声音播放速度:`fast` 时语音与 DAC(开机音乐、WAV)不再等声卡按真实时间播放,采样直接丢弃,模拟器内部时序不变;`real` 为默认的真实时间。开关是全局状态,复位后保持;验证工具只在开机阶段打开,开机完成后恢复 |
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
## 2. 命令
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
|
-
fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
|
|
21
|
+
npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
|
|
22
22
|
```
|
|
23
23
|
|
|
24
24
|
| 选项 | 说明 |
|
|
@@ -73,6 +73,11 @@ fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [-
|
|
|
73
73
|
- `RTS`、`RTI`、`BRK` 与间接 `JMP` 结束这一路。
|
|
74
74
|
- 遇到非法操作码、超出映像末尾或与已识别的指令重叠时,放弃这一路并记入警告。
|
|
75
75
|
- 没被追到的字节都按数据输出,这不影响回读校验。
|
|
76
|
+
- 入口都追完后,查找经地址表分发的跳转(`address-tables.mjs`),表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
|
|
77
|
+
- `LDA 表,X/Y` 与 `LDA 表+1,X/Y` 成对,窗口里有间接 `JMP`:字表,目标就是表里的值;
|
|
78
|
+
- 一对加载指令、两条 `PHA` 与一条 `RTS`:目标是表里的值加 1,表可以是字表,也可以是低、高字节分开的两张表;
|
|
79
|
+
- 间接 `JMP (地址)` 的地址在映像内、那里还是未识别的字节:那里是字表。
|
|
80
|
+
表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束,单张表最多 128 项;字表占的字节按 `AddrTable` 输出,分开的两张表保持为数据。
|
|
76
81
|
|
|
77
82
|
指令表在 `opcode-table.mjs`,共 151 条官方指令,数据取自 `da65` 的 `cc65/src/da65/opc6502.c`;非官方(非法)操作码不在表里。
|
|
78
83
|
|
|
@@ -84,18 +89,18 @@ fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [-
|
|
|
84
89
|
| --- | --- |
|
|
85
90
|
| `Code` | 追踪到的指令 |
|
|
86
91
|
| `ByteTable` | 没被追到的字节 |
|
|
87
|
-
| `AddrTable` | iNES 末尾 6
|
|
92
|
+
| `AddrTable` | iNES 末尾 6 字节的中断向量表,以及识别出的字表 |
|
|
88
93
|
|
|
89
94
|
另有 `GLOBAL`(输入输出文件名、起始地址、CPU)、`ASMINC`(符号定义文件)与 `LABEL`(用户符号与中断向量名)。
|
|
90
95
|
|
|
91
96
|
## 6. 验证与限制
|
|
92
97
|
|
|
93
|
-
验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM`
|
|
98
|
+
验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM` 提供)回读都与原文件逐字节一致。静态追踪追不到表驱动之外的间接调用,所以马里奥只追到约 2320 字节代码,其余按数据输出,回读仍一致;补充 CDL 或 `trace` 能扩大覆盖。步步高 DOS 下的 GBASIC(`.CMD`,26896 字节,平铺二进制加载地址 `$7B00`)加入地址表识别后,代码从 6905 字节增到 8980 字节,再加一个经人工确认的入口 `$880F` 增到 10361 字节;再用模拟器的 `trace ... unique` 记录下运行 BASIC 语句、图形编辑与退回 DOS 时执行过的地址,并补三个经单独追踪确认的入口,增到 14843 字节(剩余约 12000 字节主要是图形数据与关键字表),回读一致。
|
|
94
99
|
|
|
95
100
|
限制:
|
|
96
101
|
|
|
97
102
|
- iNES 只支持 NROM。
|
|
98
|
-
-
|
|
103
|
+
- 只识别上述几种写法的地址表;用立即数拼出地址再存进指针的跳转、调用方自己写进工作区的分发、直接访问表项的对象表都追不到,也不把数据识别成字符串,未追到的字节都是 `ByteTable`。
|
|
99
104
|
- 模拟器自带的 CDL 只对 SB2K 映射器有效。
|
|
100
105
|
- SB2000 固件页的 CDL 验证没有做。
|
|
101
106
|
- `da65` 输出的源码是 CRLF 换行。
|
|
@@ -68,5 +68,5 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
|
|
|
68
68
|
|
|
69
69
|
## 7. 注意事项
|
|
70
70
|
|
|
71
|
-
- 带真实模拟器的用例运行后会在模拟器包的 `bin/` 里生成 `VirtuaNES.ini` 与 `save
|
|
71
|
+
- 带真实模拟器的用例运行后会在模拟器包的 `bin/` 里生成 `VirtuaNES.ini` 与 `save/`;模拟器包只发布清单里的文件,这两个不会被发布,不用删。
|
|
72
72
|
- 没有目测的界面输出,汇报时写明。
|
|
@@ -22,17 +22,18 @@
|
|
|
22
22
|
1. 所有改动已提交。
|
|
23
23
|
2. 在已提交的状态下重新运行 `node tools/build-emulator.mjs`,使模拟器包清单里的 `sourceDirty` 为 `false`。`sourceDirty` 只看 `virtuanes/` 目录有没有未提交的改动。
|
|
24
24
|
3. 工具链包与模拟器包都已构建:`node tools/build-cc65.mjs`、`node tools/build-emulator.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
|
|
25
|
-
4.
|
|
26
|
-
5. `
|
|
25
|
+
4. `npm run release:check` 不带 `--allow-dirty` 通过。
|
|
26
|
+
5. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(四个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
|
|
27
27
|
|
|
28
28
|
## 3. 检查
|
|
29
29
|
|
|
30
30
|
`npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
|
|
31
31
|
|
|
32
32
|
- 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与模拟器包的依赖版本一致;这两个包的包名都在 `fcdev` 的依赖里,作用域包声明了公开发布。
|
|
33
|
+
- `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
|
|
33
34
|
- 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
|
|
34
35
|
- `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
|
|
35
|
-
-
|
|
36
|
+
- 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件;模拟器包里清单中的文件与记录一致,并且发布内容里只有清单中的文件。模拟器包的 `package.json` 的 `files` 逐个列出这些文件,所以调试时模拟器在 `bin/` 里生成的 `VirtuaNES.ini`、`save/` 等文件不会被发布,也不用删除。
|
|
36
37
|
- 模拟器清单的 `sourceDirty` 为 `true` 时报错;加 `--allow-dirty` 降为警告,只用于发布前的演练。
|
|
37
38
|
- 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
|
|
38
39
|
|
|
@@ -49,4 +49,4 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
|
|
|
49
49
|
|
|
50
50
|
## 6. 运行
|
|
51
51
|
|
|
52
|
-
`fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。
|
|
52
|
+
`npx fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。
|
|
@@ -125,16 +125,16 @@ int main(void)
|
|
|
125
125
|
程序名取 `fcdev.json` 的 `name`,要符合 DOS 8.3 规则,且不要与 DOS 内部命令重名(如 `COPY`、`TYPE`、`DIR`),重名时先被当成内部命令。
|
|
126
126
|
|
|
127
127
|
```bash
|
|
128
|
-
fcdev build src # 生成 build/sb2000/<NAME>.EXE
|
|
129
|
-
fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
|
|
130
|
-
fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
128
|
+
npx fcdev build src # 生成 build/sb2000/<NAME>.EXE
|
|
129
|
+
npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
|
|
130
|
+
npx fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
131
131
|
```
|
|
132
132
|
|
|
133
|
-
`fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
|
|
133
|
+
`npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
|
|
134
134
|
|
|
135
135
|
## 6. 头文件与函数
|
|
136
136
|
|
|
137
|
-
`sb2000.h` 包含 `sb2000-symbols.h` 与下面
|
|
137
|
+
`sb2000.h` 包含 `sb2000-symbols.h` 与下面 16 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 204 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
|
|
138
138
|
|
|
139
139
|
| 头文件 | 模块 | 内容 |
|
|
140
140
|
| --- | --- | --- |
|
|
@@ -151,17 +151,21 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
151
151
|
| `sb2000-sound.h` | sound | 曲子与音效、WAV、语音 |
|
|
152
152
|
| `sb2000-printer.h` | printer | 24 针点阵打印机 |
|
|
153
153
|
| `sb2000-ime.h` | ime | 中文输入法 |
|
|
154
|
+
| `sb2000-dma.h` | dma | 通用 DMA:把扩展 RAM 里的数据复制到 ERAM 或显存,源地址换算 |
|
|
155
|
+
| `sb2000-ppu.h` | ppu | 直接操作图形端口:显存读写、调色板、精灵 RAM、等垂直消隐、打开显示 |
|
|
156
|
+
| `sb2000-timer.h` | timer | 硬件定时器:启动、停止、读当前值与下溢标志、屏蔽与允许 |
|
|
154
157
|
|
|
155
158
|
约定:
|
|
156
159
|
|
|
157
160
|
- 命名 `sb_<模块>_<动作>`;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
|
|
161
|
+
- dma、ppu、timer 三个模块直接读写硬件寄存器,不经系统调用,没有 `@syscall`;寄存器地址与位的符号是 `sb2000-symbols.h` 里以 `SB_HW_` 开头的常量,程序不要再自己定义。行为以真机实测为准,见 [硬件说明](03-硬件说明.md)。
|
|
158
162
|
- 字符串、缓冲区、结构体指针必须在程序窗口 `$8000` 到 `$BFFF` 里(读写目标不能在窗口 3);系统服务换页后程序窗口不可见的情况,函数内部已经处理好。
|
|
159
163
|
- 一个函数一个源文件,放在 `src/lib/<模块>/sb-<函数名>.c`(或 `.s`);库内部用的辅助函数以 `sbi_` 开头,声明在 `src/lib/sb-internal.h`,不对外。
|
|
160
164
|
- 运行库由 `tools/build-libs.mjs` 编译:`lib-build.json` 里以 `/` 结尾的项展开成目录下全部 `.c` 与 `.s`;`.c` 用 `cc65 -t none --cpu 6502 -Oirs` 编译再汇编,同名文件报错。链接只带入程序用到的函数。
|
|
161
165
|
|
|
162
166
|
随时查询接口:
|
|
163
167
|
|
|
164
|
-
- `fcdev api` 列出全部模块;`fcdev api <函数名>` 看完整文档;`fcdev api <模块名>` 看函数列表;`fcdev api '$7B'` 或 `fcdev api '$7B/$09'` 看用到某个系统调用的函数;`fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
|
|
168
|
+
- `npx fcdev api` 列出全部模块;`npx fcdev api <函数名>` 看完整文档;`npx fcdev api <模块名>` 看函数列表;`npx fcdev api '$7B'` 或 `npx fcdev api '$7B/$09'` 看用到某个系统调用的函数;`npx fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
|
|
165
169
|
- [api-reference.md](../../targets/sb2000/api-reference.md) 是同一份文档的整本 Markdown,由 `node tools/gen-sb2000-api-doc.mjs` 从头文件生成,末尾有“系统调用覆盖表”。改头文件注释后重新生成,测试会核对。
|
|
166
170
|
- [api-unwrapped.json](../../targets/sb2000/api-unwrapped.json) 登记没有封装的功能号与子功能及原因(`functions` 是整个功能号不封装,`partial` 是封装了一部分)。`node tools/check-sb2000-api.mjs` 检查:头文件里每个函数有说明、`@param`、`@return`,有且只有一处实现,库里没有头文件之外的公开函数,BIOS 里有处理例程的每个功能号(`KNOWN_FUNCTIONS`)要么被某个函数的 `@syscall` 涉及、要么在 `functions` 里写明原因。
|
|
167
171
|
|
|
@@ -171,7 +175,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
171
175
|
|
|
172
176
|
## 7. 符号定义
|
|
173
177
|
|
|
174
|
-
- [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL`
|
|
178
|
+
- [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、硬件寄存器与位(`HW_` 开头)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
|
|
175
179
|
- [include/sb2000-symbols.h](../../targets/sb2000/include/sb2000-symbols.h) 是 C 用的同一份符号,每个符号对应一个 `SB_` 前缀的数值宏。它由 `node tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 生成,不要手工修改;改 `sb2000.inc` 后重新运行,测试会检查入库的头文件与生成结果一致。`sb2000.inc` 里符号的行尾注释,会变成宏上方的 `/** */` 文档注释,编辑器悬停时显示;分组标题变成普通的 `/* */` 注释。各模块头文件里的函数也用 `/** */` 与 `@param`、`@return`、`@syscall` 写文档。新增的服务先在 `sb2000.inc` 里加符号(功能号、子功能号、参数与结果单元、出错码),再重新生成。
|
|
176
180
|
|
|
177
181
|
## 8. 常用做法
|
|
@@ -194,6 +198,9 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
194
198
|
| 读鼠标 | `$14` 复位并检查 `MOUSE_PRESENT`(`$0633`)非 0 → `$13/$81` 允许鼠标中断 → `$6C/$00` 设范围(`$0646-$0649`,`$0652` 不要是 1-4)→ `$6C/$04` 设初始坐标(`$0652`、`$0653`)→ 随时 `$6C/$02` 取坐标(`$0646`、`$0647`);`$6C/$03` 取按键状态(`$0360-$0367`,按住为 1,点击事件读走即清) | `mouse` |
|
|
195
199
|
| 播放 WAV | 功能 `$65`、子功能 `$0C`(`SUB_SOUND_WAV`,C 里是 `sb_sound_play_wav`),见 [系统调用手册](02-系统调用手册.md) 5.5(只读过代码,没有示例) | — |
|
|
196
200
|
| 把 NES 游戏当程序运行 | 读入 `.nes`、复制启动桩到 ERAM、写 `$4301` 后跳转 | `play` |
|
|
201
|
+
| 用 DMA 复制扩展 RAM 的数据 | `sb_dma_to_cpu`(目的只能是 ERAM `$6000-$7FFF`)、`sb_dma_to_vram`;源用 `sb_dma_page_address(页号, 偏移)` 换算;长度寄存器写“字节数 − 1”、`$404B` 位 7 置 1 都由函数处理;复制到显存要先关显示;要把数据放进窗口(`$8000` 以上)时,先 DMA 到 ERAM 缓冲,再用 `memcpy` 搬 | `apps/sb2000/bbk-loader` |
|
|
202
|
+
| 直接写显存、调色板、精灵 | `sb_display_off()` 关显示,用 `sb_ppu_*` 读写显存、调色板与精灵 RAM,`sb_ppu_render` 打开显示,用完再用 `sb_display_on()` 恢复 DOS 的显示 | `apps/sb2000/hwtest` |
|
|
203
|
+
| 用定时器计时 | `sb_timer_start(控制, 预置值)` 启动,`sb_timer_pending()` 看下溢标志,`sb_timer_mask()` 清标志;DOS 用它做系统时钟,用完要用 `$EF`、`$3C` 恢复 | `apps/sb2000/hwtest` |
|
|
197
204
|
|
|
198
205
|
## 9. 要避开的坑
|
|
199
206
|
|
|
@@ -245,7 +252,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
245
252
|
|
|
246
253
|
## 12. 运行库的测试
|
|
247
254
|
|
|
248
|
-
运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
|
|
255
|
+
运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
|
|
249
256
|
|
|
250
257
|
停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
|
|
251
258
|
|
package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md
CHANGED
|
@@ -29,15 +29,15 @@
|
|
|
29
29
|
|
|
30
30
|
| 地址 | 内容 |
|
|
31
31
|
| --- | --- |
|
|
32
|
-
| `$0000-$1FFF` | 内部 RAM
|
|
33
|
-
| `$2000-$3FFF` |
|
|
34
|
-
| `$4000-$4017` |
|
|
35
|
-
| `$4020-$4036` |
|
|
32
|
+
| `$0000-$1FFF` | 内部 RAM:只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像(真机实测,模拟器已对齐,见 [硬件说明](03-硬件说明.md));零页 `$0000-$00FF` 供系统与程序共用,程序要避开 DOS 用到的单元 |
|
|
33
|
+
| `$2000-$3FFF` | 图形端口:寄存器 `$2000-$2008`(`$2008` 是 6576 的扩展控制寄存器)与调色板 `$2040-$207F`;芯片手册只定义这两段,`$2080` 以上有没有镜像没有实测 |
|
|
34
|
+
| `$4000-$4017` | 声音(4 通道 PSG:方波 2 路、三角波、噪声,寄存器 `$4000-$400F`、`$4015`;芯片手册没有定义 NES 的 DMC 通道寄存器 `$4010-$4013`)、精灵 DMA(`$4014`)、手柄(`$4016`、`$4017`) |
|
|
35
|
+
| `$4020-$4036` | 键盘(`$4020-$4022`,串行收发)、手柄与鼠标选择(`$4023`)、鼠标(`$4024`)、并口打印机(`$4025`)、扩展 I/O(`$4026`)、DAC(`$4027`)、初始设置(`$4031`)、中断(`$4032`、`$4033`)、定时器(`$4034-$4036`) |
|
|
36
36
|
| `$4040-$4047` | 8 个窗口的页选择:每个选一个 4K 页,对应 `$8000-$FFFF`;值小于 `$80` 是 BIOS ROM 页,不小于 `$80` 是扩展 RAM 页 |
|
|
37
37
|
| `$4048-$404F` | DMA(见 [硬件说明](03-硬件说明.md)) |
|
|
38
38
|
| `$4200-$4207` | 软驱控制器 |
|
|
39
39
|
| `$4300` | 显存 bank 选择(32K 一个 bank) |
|
|
40
|
-
| `$
|
|
40
|
+
| `$4400-$5FFF` | 不是 RAM:读出都是 `$68`,写不进去(真机实测,模拟器已对齐);芯片手册里的 `$5000-$57FF` 2K 工作 RAM 在真机上没有,程序不能使用 |
|
|
41
41
|
| `$6000-$7FFF` | 8K 扩展 RAM(ERAM),任何窗口映射下都可见;`$6200-$65FF` 一带是 DOS 的状态变量 |
|
|
42
42
|
| `$8000-$BFFF` | 程序窗口:4 个 4K 窗口,由系统调用 `$29`、`$25` 映射 |
|
|
43
43
|
| `$C000-$FFFF` | 固定内核:ROM 第 4-7 页 |
|
|
@@ -338,7 +338,7 @@
|
|
|
338
338
|
|
|
339
339
|
音乐驱动的内部例程:`SOUND_PLAY_SONG`(`$F43A`,按 `$049A` 播放:0 复位,`$FB-$FF` 为控制命令,其余为曲号,曲表指针在 `$D31B` 起)、`SOUND_START_TRACKS`(`$F4C9`)、`SOUND_RESET`(`$F5C4`)、`SOUND_UPDATE_ON`/`SOUND_UPDATE_OFF`(`$F5E9`、`$F5F2`);发声在 NMI 中断里更新。
|
|
340
340
|
|
|
341
|
-
曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU
|
|
341
|
+
曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU 寄存器的序列(验证时记录 `$4000-$4013`、`$4015` 的写入;芯片手册只定义 `$4000-$400F` 与 `$4015`)):
|
|
342
342
|
|
|
343
343
|
- 曲子有两种头。**音乐格式**:首字节不小于 `$80`,后面是声道项 `[声道号, 音轨偏移低, 偏移高]`(声道号小于 `$80`),以不小于 `$80` 的字节结束;首字节后紧跟一个不小于 `$80` 的字节时,声道项从第 4 字节起。**音效格式**:首字节小于 `$80`,是优先级,后面同样是声道项;第 2 字节不小于 `$80` 时还有 3 字节头(第 3 字节放 `$03BD`,曲号放 `$03BE`,`$0499` 置位 5,用于播完自动接下一首)。声道项里声道号不小于 4 的,优先级写进 `$03BB+声道号`,优先级小于当前 `$03BB+声道号` 时整首不起播;音乐格式的曲子曲号与 `$03BB` 相同时也不起播(`$65/$0A`、`$0B` 的曲号恒为 0,所以音乐格式的曲子用它们起不了播,要用 `$00`、`$01`、`$09`)。
|
|
344
344
|
- 音轨偏移相对曲首(`$039B/$039C`,音效格式是 `$039D/$039E`);声道 0-3 是音乐声道,4-7 是音效声道,音效声道与同号后四位的音乐声道共用一个硬件声道,音效声道播放时(`$03CF+声道号` 非 0)音乐声道不写 APU。音乐声道读曲子的页放 `$04A1`(`$00`、`$01`、`$09` 设置),音效声道的页放 `$04A3`(`$0A`、`$0B` 设置)。
|
|
@@ -437,7 +437,7 @@ BIOS 自己带了一段 WAV:ROM 第 `$64` 页起,单声道、8 位、22050 H
|
|
|
437
437
|
|
|
438
438
|
### 5.7.2 DMA 与显存服务 `$30-$34`(已验证)
|
|
439
439
|
|
|
440
|
-
DMA 寄存器:`$4048` 控制、`$4049`
|
|
440
|
+
DMA 寄存器:`$4048` 控制、`$4049` 源 bank、`$404A` 源低、`$404B` 源高(位 7 是 A15,要求为 1,为 0 时 DMA 失败)、`$404C` 目的低、`$404D` 目的高、`$404E` 长度低、`$404F` 长度高(各位的含义见 [硬件说明](03-硬件说明.md);BIOS 源码里的符号 `DMA_SRC_BANK`、`DMA_SRC_LOW`、`DMA_SRC_HIGH` 依次对应 `$4049`、`$404A`、`$404B`);长度寄存器写“长度 − 1”。屏幕缓冲在扩展 RAM 页 `$FA`(名称表 4、5,偏移 `$000`、`$800`)与页 `$FB`(名称表 6、7),每张 2KB、每个单元 2 字节;区域填充的中转缓冲在页 `$F8` 起。
|
|
441
441
|
|
|
442
442
|
| 功能 | 作用 |
|
|
443
443
|
| --- | --- |
|
|
@@ -1,22 +1,31 @@
|
|
|
1
1
|
# SB2000 硬件说明
|
|
2
2
|
|
|
3
|
-
本文是 SB2000
|
|
3
|
+
本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源有三类:芯片手册(SH6578 官方手册,下称“芯片手册”)、模拟器源码(`virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)与实际运行观察、真机实测(`apps/sb2000/memtest`,2026-11-12;`apps/sb2000/hwtest`,2026-11-13,真机为 PAL 制式)。SB2000 的真机芯片是 UM6576,芯片手册是 SH6578,两颗芯片有差别,两者不一致时以真机实测为准。“已确认”指来自模拟器源码或实际运行;没有写“真机”的结论都没有在真机上测过。模拟器已按真机实测修改内部 RAM、`$4400-$5FFF`、DMA、定时器与图形端口(见对应行),memtest、hwtest 在模拟器里的结果与真机一致(仍有差异的项见“真机与模拟器仍有差异的行为”一行);模拟器与芯片手册不一致、也没有真机数据的地方,在对应行里写明。程序接口见 [系统调用手册](02-系统调用手册.md)。
|
|
4
4
|
|
|
5
5
|
| 项目 | 结论 | 状态 |
|
|
6
6
|
| --- | --- | --- |
|
|
7
|
-
| CPU | 标准 6502(含非官方指令),不是新指令集;“6576
|
|
8
|
-
| 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS
|
|
7
|
+
| CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是向 `$4031` 依次写入 `$65`、`$76`(芯片手册称这一步为初始设置)之后的工作模式 | 已确认 |
|
|
8
|
+
| 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成。芯片手册要求两次写入在两个指令周期内连续完成(`LDA #$65 / LDX #$76 / STA $4031 / STX $4031`),模拟器只按顺序识别,不检查间隔 | 已确认(芯片手册、模拟器源码) |
|
|
9
9
|
| 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真 | 已确认 |
|
|
10
10
|
| 程序窗口 | `$4040-$4047` 各选一个 4K 页,对应 `$8000-$FFFF` 的 8 个窗口;值小于 `$80` 是 BIOS ROM 页(512KB,共 128 页),不小于 `$80` 是扩展 RAM 页(512KB) | 已确认 |
|
|
11
11
|
| 启动后的窗口 | `$C000-$FFFF` 固定为 ROM 第 4-7 页,`$8000-$BFFF` 由 BIOS 换页 | 已确认 |
|
|
12
12
|
| 向量 | NMI `$C084`,RESET `$C000`,IRQ `$C12B`(ROM 偏移 `$7FFA` 起) | 已确认 |
|
|
13
|
-
| 内部 RAM |
|
|
14
|
-
| DMA | `$4048-$404F
|
|
13
|
+
| 内部 RAM | 芯片手册:工作 RAM 共 10KB,在 `$0000-$1FFF`(8KB)与 `$5000-$57FF`(2KB)。模拟器(6576 模式)已按真机实测修改,行为与下面的真机实测相同;模拟器在 FC 兼容模式下仍保留 `$5000-$5FFF` 的 2K RAM(镜像两次),这个模式没有在真机上测过。真机实测:内部 RAM 只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像;`$4400-$5FFF` 读出的都是 `$68`,写 `$55`、`$AA` 后读回仍是 `$68`,既不是 RAM 也不是会应答的寄存器(`$5006` 的写入仍有效果);`$6000-$7FFF` 是 8K,各 1K 互相独立 | 已确认(真机实测;模拟器已在 SB-DOS 下用真实 CPU 指令读写核对);内存大小与芯片手册不一致,以真机为准 |
|
|
14
|
+
| DMA | `$4048-$404F`,把主存储器的数据复制到显存或工作 RAM;写 `$4048` 的最高位启动(模拟器瞬时完成)。`$4048`:位 7 使能;位 6 传输速率(0 为 890KB/s,1 为 1.78MB/s);位 5 目的(0 为显存,1 为工作 RAM),其余位为 0。芯片手册要求先把 `$4020` 位 7 置 1,位 6、5 才起作用(模拟器不检查;BIOS 在系统初始化时写 `$4020=$80`)。`$4049`:源 bank,低 5 位对应 XA20-XA16,位 4 为 1 取扩展 RAM,否则取 ROM;`$404A`、`$404B`:源地址的低、高字节,`$404B` 的低 7 位是 A14-A8,位 7 是 A15(真机要求为 1,模拟器已按真机处理:为 0 时不传输);`$404C`、`$404D`:目的地址低、高字节,目的是显存时位 15 为 1 表示扩展显存;`$404E`、`$404F`:长度寄存器的值是字节数减 1,真机实际搬“长度 + 1”个字节(BIOS 也传“字节数 − 1”),最大 32KB(`$8000` 不屏蔽,写 `$8010` 会搬 `$8011` 个字节)。每搬一个字节,源地址与目的地址各加 1。芯片手册:目的是显存时只在垂直消隐期间或显示关闭时运行,没搬完的数据留到下一次垂直消隐再继续;目的是工作 RAM 时没有这个限制。BIOS 把 `$C0` 用于复制到显存,`$A0`、`$E0` 用于复制到 CPU 地址。真机实测:只有目标是 ERAM 且 `$404B` 位 7 为 1 时成功,模式 `$A0`、`$E0` 都行;`$4020` 位 7 为 0 时,模式位 5 不起作用,目的总是显存,位 7 为 1 时才由模式位 5 选择工作 RAM 或显存(与芯片手册的说法一致);模拟器已对齐:`$404B` 位 7 为 0 时不传输,目的在程序窗口(`$8000` 以上)时写不进去,长度按“长度 + 1”,`$4020` 位 7 为 0 时目的总是显存,memtest、hwtest 在模拟器里的结果与真机相同 | 已确认(芯片手册、模拟器源码;位的作用已在模拟器里逐项核对);真机实测 |
|
|
15
15
|
| 软驱控制器 | `$4200-$4207`;1.44MB(每道 18 扇区、2 面、80 道),LBA = 磁道×36 + 磁头×18 + 扇区 − 1 | 已确认 |
|
|
16
|
-
| 键盘 | 经 `$4020-$4022`
|
|
16
|
+
| 键盘 | 经 `$4020-$4022` 串行收发。芯片手册:键盘口收发 AT 键盘的 11 位串行帧(起始位、8 位扫描码、奇偶位、停止位),收完整帧后产生键盘中断,要在下一位到来前读走 `$4020` 里的扫描码;`$4022` 位 7 是键盘时钟 CLK(接收时必须保持 1,BIOS 处理完一个码后写 `$80`),位 2 允许“发送命令完成”中断,位 0 是方向(0 为键盘到系统,1 为系统到键盘);发送时先把数据写入 `$4021`,再置位 0 为 1、CLK 拉低大于 60ms 后拉高,硬件自动发出。模拟器直接给出与 DirectInput 的 DIK 值一致的扫描码(即 IBM 码集 1 的按下码),在 CLK 上升沿且位 0 为 1 时把 `$4021` 发给键盘;真机键盘实际是否按此工作没有测过;BIOS 初始化键盘时(功能 `$17`)会发 `$F0`、`$01` 选择扫描码集 1 | 已确认(芯片手册、模拟器源码) |
|
|
17
17
|
| 显存 | 512KB,经 `$4300` 选 32KB 的 bank | 已确认 |
|
|
18
|
-
| 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 3
|
|
19
|
-
|
|
|
18
|
+
| 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 4 INT4(芯片手册:实时时钟)、位 3 软驱、位 2 INT2(芯片手册:打印机的 IRQ2)、位 1 INT1(芯片手册:φ 使能的 IRQ1),位 0 未用,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断。BIOS 为位 4、2、1 各留了钩子,模拟器里没有设备置位它们 | 已确认(芯片手册、模拟器源码) |
|
|
19
|
+
| 鼠标 | `$4023` 位 0 选手柄 2 或鼠标(1 为鼠标);真机实测(`hwprobe`):读回是 `$80 | 位 0`,位 7 是输入线(闲置为 1),位 6-1 读 0;鼠标数据经 `$4024` 读,是微软串口鼠标的 3 字节包。复位信号:BIOS(功能 `$14`)与模拟器都用 `$4026` 的位 1(EIO1),拉低再拉高,模拟器在上升沿发 RTS。芯片手册在鼠标一节把复位信号写作 `$4026` 的 D2,在扩展 I/O 一节又写 EIO1 产生鼠标复位,两处说法不一致,这里按 BIOS 与模拟器的用法,真机没有核实;手册要求复位时间大于 30ms,并可写 `$4024` 设置波特率(NTSC 为 `$A3`、PAL/B 为 `$A9`),BIOS 没有写它 | 已确认(芯片手册、模拟器源码、BIOS 代码);复位位的说法见左 |
|
|
20
|
+
| 定时器 | `$4034` 控制:位 7 允许,位 6 连续重载(0 只计一次),位 5 基准时钟(0 为 CPU 时钟,1 为行消隐时钟 15625Hz),位 3-0 为预分频 PS;`$4035` 写预置值 TP,同时装入当前值;`$4036` 读当前值(递减)。周期 = 基准周期 × (PS + 1) × (TP + 1),下溢时置 `$4033` 位 7(`$4032` 位 7 为 0 才产生中断)。真机实测:`$4035` 可读(读回写入的预置值);一次计时(位 6 为 0)下溢一次后,当前值保持预置值,不再计时,也不再置中断标志,模拟器已对齐(旧版把当前值置 0);真机一帧是 PAL 的 50Hz,120 帧内的下溢次数:BIOS 的设置与行消隐时钟两组模拟器与真机相同(38、147),CPU 时钟那组真机 1040 次、模拟器 1038 次。BIOS 开机设 `$4034=$EF`、`$4035=$3C`(连续、行消隐时钟、PS=15、TP=60,周期 64µs × 16 × 61 约 62.5ms,即约 16Hz),用作软件时钟的节拍;播放 WAV 时用 `$4034=$C0`(CPU 时钟、PS=0),`$4035` 取 `$28`、`$51`、`$A2` 作采样节拍 | 已确认(芯片手册、模拟器源码;开机后的寄存器值已在模拟器里读出);`$4035` 可读与一次计时的行为为真机实测 |
|
|
21
|
+
| 声音 | 芯片手册:4 通道 PSG,通道 1、2 方波,通道 3 三角波,通道 4 噪声,寄存器为 `$4000-$4003`、`$4004-$4007`、`$4008`、`$400A`、`$400B`、`$400C`、`$400E`、`$400F`,`$4015` 低 4 位依次使能通道 1-4;没有定义 NES 的 DMC 寄存器 `$4010-$4013`,语音改用 `$4027` 的 DAC 输出。BIOS 的声音引擎在 RAM 里维护这些寄存器的影子,再写到芯片(见 [系统调用手册](02-系统调用手册.md) 5.5 节) | 芯片手册 |
|
|
22
|
+
| DAC | `$4027` 是 8 位 DAC,输出语音(PCM)。芯片手册:实际输出发生在定时器溢出时,所以使用 DAC 必须同时设置定时器;输出带约 1/2 Vcc 的直流偏置,输出语音前要把电平从 0 缓慢升到偏置值,否则开始时有“噗”声。BIOS 播放 WAV 时写它(`$65/$0C`) | 芯片手册;BIOS 的用法已验证 |
|
|
23
|
+
| 实时时钟 | 芯片手册:`$4080` 写 RTC 地址,`$4081` 读写 RTC 数据,使用前先设地址。SB2000 的 BIOS 不访问它们,系统时钟由定时器中断软件计时;模拟器的 `$4026` 位 0(EIO0)没有接 RTC | 芯片手册;BIOS 没有使用 |
|
|
24
|
+
| 图形端口 | 寄存器 `$2000-$2008` 与调色板 `$2040-$207F`。`$2000`:位 7 允许 NMI,位 5 精灵 8×16,位 2 地址增量(0 加 1,1 加 32),位 1-0 背景页;`$2001`:位 0 黑白,位 1、2 屏蔽背景、精灵最左 8 个像素,位 3、4 背景、精灵显示,位 7-5 红绿蓝增强;`$2002` 读:位 7 垂直消隐,位 6 精灵与背景碰撞,位 5 一行超过 8 个精灵;`$2008`:位 7 背景 4 色(0)或 16 色(1),位 3-2 精灵图案表起始,位 0 名称表起始(为 1 时名称表在显存 `$2000-$27FF`,只能显示一页)。名称表项 2 字节,高 4 位是调色板组,低 12 位是图案号;调色板 64 项,每项低 4 位颜色、位 5-4 亮度。显存、调色板、精灵 RAM 只能在垂直消隐期间或显示关闭时更新,精灵用 `$4014` 的 DMA 更新。BIOS 功能 `$10` 修改的就是这些位(见 [系统调用手册](02-系统调用手册.md) 5.7 节)。真机实测(`hwtest`,与芯片手册不一致的地方以真机为准):① `$2001` 位 1、2 的极性与 NES 相同,为 1 表示显示最左 8 个像素,为 0 表示屏蔽(芯片手册写反,BIOS 影子初值 `$0E` 即两位都显示);位 0 为 1 时黑白,背景底色也变灰;位 5 增强绿、位 6 增强红、位 7 增强蓝(PAL 顺序,芯片手册写位 5 蓝、位 6 绿、位 7 红)。② 精灵属性位 6 为水平镜像,位 7 为垂直翻转,位 5 为 1 表示在背景之后(只被不透明的背景像素盖住);读回 OAM 时属性字节的位 4-2 恒为 1(写 `FF` 读 `FF`,写 `00` 读 `1C`),不跟地址、也不跟最后写的 PPU 端口走;早先的两次 `hwtest` 曾读到 `E3`、`F3`,用现在的程序复现不了,原因不明。③ `$2000` 位 1-0 选 4 个互相独立的名称表;`$2008` 位 0 为 1 时名称表从 `$2000` 起;8×16 精灵的图案号最低位被忽略(相邻的偶数号、奇数号显示同一对图块),上半取偶数号。④ 调色板每项低 4 位是色相、位 5-4 是亮度,与芯片手册相同,16 色模式可用;读调色板得到 `(值 & $3F) | $40`。⑤ `$2002` 位 6(精灵 0 碰撞)、位 5(一行超过 8 个精灵)有效,低 5 位是最后一次写 PPU 总线的值。模拟器的 UM6576 PPU(`PPU_UM6576.cpp`)已按以上实测实现;颜色的亮度与饱和度渲染与真机电视的差别没有对齐,不影响程序行为 | 芯片手册;位的作用为真机实测(`hwtest`),模拟器已对齐 |
|
|
25
|
+
| 空读(没有器件驱动的位) | 真机实测:读到 CPU 数据总线上最近的一个值,读指令里的地址高字节就是总线最近的值,所以 `$203F`、`$2080` 读 `$20`,`$4018`、`$4019`、`$401F` 读 `$40`;`$4016`、`$4017` 的位 6 也是这个原因;`$2009` 读 `$00`。模拟器(UM6576 模式)记录总线最近的值,空读时返回它,零页间接寻址(`(zp),Y`)读到的是指针高字节,堆栈不记录;`$200A-$203F`、`$2080-$3FFE`、`$4018-$401F` 按这个规则处理,其中只有 `$203F`、`$2080`、`$4018`、`$4019`、`$401F` 在真机上测过 | 真机实测(`hwtest`);模拟器已对齐 |
|
|
26
|
+
| 实时时钟 | 真机实测:`$4081` 不论有没有设地址,读出的都是 `$60`;模拟器读出 `$60` | 真机实测(`hwtest`);模拟器已对齐 |
|
|
27
|
+
| 真机与模拟器仍有差异的行为 | `hwtest` 在真机上测到、模拟器没有对齐的项目(程序不应依赖这些值)。真机读数:`$3FFF` 为 `$68`(模拟器读 `$00`,原因不明),`$4037` 两次实测分别为 `$A0`、`$E0`(不固定);`$4015` 写 `$FF` 后读出位 4 为 1、写 `$1F` 后读出位 4 为 0(模拟器反过来);`$4022` 开机值 `$C0`(模拟器为 `$80`;写入后的读回还没有真机数据);`$4026` 读出 `$3F`(位 4 为 1,模拟器按虚拟打印机固定为 `$2F`);`$4016` 读出 `$44`、`$4017` 读出 `$40`(模拟器为 `$40`、`$48`);`$4033` 位 6 在清除后仍为 1(鼠标待处理,没接鼠标时的真机状态,模拟器为 0)。`$4036` 运行中的当前值取决于读取时刻,通用 DMA 在 `$8010` 起的采样取决于源 RAM 里原来的内容,`$4015` 位 4 取决于读取时刻(同一个写入值两遍读回不同,像 DMC 的活动状态位),模拟器用的是同类逻辑,无法逐值比对;`$4023` 位 7 在 `hwprobe` 里一直为 1(`hwtest` 报告里“写 1、写 0 后读到 `01`、`00`”是编译器省掉了写后的回读,不是真机值,`$4022` 写后的“读回”也一样,只有测前的值是真读),模拟器按 1 处理 | 真机实测(`hwtest`);模拟器没有对齐 |
|
|
28
|
+
| 并口打印机 | 模拟器实现了 Epson ESC/P 虚拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。芯片手册只定义了 `$4016` 的位 1、0(OUT1、OUT0)、`$4017` 的位 0、`$4025`(数据寄存器,写入时产生选通)与 `$4026`(EIO7-EIO0);这里 `$4016` 位 2、`$4017` 位 2、3 的用法来自模拟器源码的注释,芯片手册没有定义,真机没有核实。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
|
|
20
29
|
| 语音端口 `$4302` | 读:位 7 为 1 表示可以接收下一个字节(缓冲未满),语音播完时低 4 位为 `$F`。写:把一个语音数据字节送进环形缓冲,由模拟器的 LPC 语音线程解码播放。`$4026` 位 6 的上升沿复位语音(清缓冲)。BIOS 的 `$74`、`$75`(`API_74_PORT4302_CONTROL`、`API_75_PORT4302_SEND`)就是操作它 | 已确认(模拟器源码);`$74`、`$75` 的发送序列与“播完”结束都已实测(见 [系统调用手册](02-系统调用手册.md) 5.13 节);模拟器曾缺 `case 0x4302:`,已修复 |
|
|
21
30
|
|
|
22
31
|
## 软件环境
|
|
@@ -25,6 +25,8 @@
|
|
|
25
25
|
| 事项 | 说明 |
|
|
26
26
|
| --- | --- |
|
|
27
27
|
| 内核集成进 VS Code 面板 | 只要调试服务协议不变,`fcdev` 不用改 |
|
|
28
|
+
| 外设读数与真机对齐 | `hwtest` 在真机与模拟器上仍有差异的读数(`$4015` 位 4、`$4022` 开机值、`$4026`、`$4016`、`$4017`、`$4033` 位 6、`$3FFF`),具体数值见 [03-硬件说明](sb2000/03-硬件说明.md) 的“真机与模拟器仍有差异的行为”;程序不应依赖这些值,是否对齐由用户决定。|
|
|
29
|
+
| `runnes` 与 `play` 的 DMA 写法 | 两个程序借用程序窗口 2(`$A000`)做 DMA 目的,真机上失败,模拟器对齐真机后也失败(`runnes` 现在用库函数 `sb_dma_to_cpu`,目的在窗口时函数直接返回出错、不复制);改成先 DMA 到 ERAM 缓冲再用 CPU 搬(参考 `apps/sb2000/bbk-loader`) |
|
|
28
30
|
|
|
29
31
|
## 4. 目标
|
|
30
32
|
|
|
@@ -40,6 +42,6 @@
|
|
|
40
42
|
| 事项 | 说明 |
|
|
41
43
|
| --- | --- |
|
|
42
44
|
| 其他映射器 | 现在只支持 NROM 与平铺二进制;其他映射器需要目标提供地址映射 |
|
|
43
|
-
| 跳转表识别 |
|
|
45
|
+
| 跳转表识别 | 已识别 `LDA 表,X` 加间接 `JMP`、`PHA`/`RTS` 的表和 `JMP (地址)` 指向的表;例程内联的跳转表(`JSR` 之后紧跟地址表)、立即数拼出的分发指针还追不到,这部分按数据输出;补全覆盖靠运行记录:模拟器 `trace ... unique` 在步步高机型上可用,CDL 只对 SB2K 映射器有效,对步步高 RAM 里的程序没用。立即数拼出的指针可以让 `fcdev` 列出“可能的入口”供人工确认,还没做 |
|
|
44
46
|
| 地址表与字符串识别 | 现在没追到的字节都是 `ByteTable` |
|
|
45
47
|
| SB2000 固件页的 CDL 验证 | 没有做;模拟器自带 CDL 只对 SB2K 映射器有效 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fcdev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "sungbin <sungbin@3578.cn>",
|
|
@@ -25,12 +25,13 @@
|
|
|
25
25
|
},
|
|
26
26
|
"files": [
|
|
27
27
|
"bin",
|
|
28
|
+
"CHANGELOG.md",
|
|
28
29
|
"docs",
|
|
29
30
|
"src",
|
|
30
31
|
"targets"
|
|
31
32
|
],
|
|
32
33
|
"optionalDependencies": {
|
|
33
|
-
"@rujianjs/fcdev-cc65": "0.
|
|
34
|
-
"@rujianjs/fcdev-emulator": "0.
|
|
34
|
+
"@rujianjs/fcdev-cc65": "0.5.0",
|
|
35
|
+
"@rujianjs/fcdev-emulator": "0.5.0"
|
|
35
36
|
}
|
|
36
37
|
}
|
|
@@ -38,14 +38,14 @@ export async function runApiCommand({ positionals, options, context }) {
|
|
|
38
38
|
}
|
|
39
39
|
const lines = [`${target.title} 的 C 接口:${functions.length} 个函数,${groups.size} 个模块`, ''];
|
|
40
40
|
for (const [name, items] of groups) lines.push(` ${name.padEnd(10)} ${String(items.length).padStart(3)} 个函数 ${items[0].header}`);
|
|
41
|
-
lines.push('', '查询:fcdev api <函数名>(完整文档)、fcdev api <模块名>(函数列表)、fcdev api <$功能号>(用到该系统调用的函数)、fcdev api <词>(按名称与说明搜索)');
|
|
41
|
+
lines.push('', '查询:npx fcdev api <函数名>(完整文档)、npx fcdev api <模块名>(函数列表)、npx fcdev api <$功能号>(用到该系统调用的函数)、npx fcdev api <词>(按名称与说明搜索)');
|
|
42
42
|
context.stdout.write(`${lines.join('\n')}\n`);
|
|
43
43
|
return 0;
|
|
44
44
|
}
|
|
45
45
|
|
|
46
46
|
const { kind, matches } = queryApi(functions, query);
|
|
47
47
|
if (matches.length === 0) {
|
|
48
|
-
throw new FcdevError(`没有找到“${query}”`, { code: 'API_NOT_FOUND', hint: '不带查询词运行 fcdev api 可以看到全部模块' });
|
|
48
|
+
throw new FcdevError(`没有找到“${query}”`, { code: 'API_NOT_FOUND', hint: '不带查询词运行 npx fcdev api 可以看到全部模块' });
|
|
49
49
|
}
|
|
50
50
|
if (options.json) {
|
|
51
51
|
context.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
|
|
@@ -18,7 +18,7 @@ import { FcdevError } from '../../shared/index.mjs';
|
|
|
18
18
|
*/
|
|
19
19
|
export async function runBuildCommand({ positionals, options, context }) {
|
|
20
20
|
if (positionals.length > 1) {
|
|
21
|
-
throw new FcdevError('build 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev build [目录或文件]' });
|
|
21
|
+
throw new FcdevError('build 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev build [目录或文件]' });
|
|
22
22
|
}
|
|
23
23
|
const reporter = {
|
|
24
24
|
log: (message) => context.stdout.write(`${message}\n`),
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
// 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
|
|
7
|
+
// 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace、tape 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
import path from 'node:path';
|
|
10
10
|
import { DEFAULT_DEBUG_PORT, DebugClient } from '../../emulator/index.mjs';
|
|
@@ -39,6 +39,9 @@ export function resolveCommandPaths(tokens, cwd) {
|
|
|
39
39
|
if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
|
|
40
40
|
return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
|
|
41
41
|
}
|
|
42
|
+
if (name === 'tape' && (rest[0] === 'play' || rest[0] === 'rec') && rest[1]) {
|
|
43
|
+
return [name, rest[0], path.resolve(cwd, rest.slice(1).join(' '))];
|
|
44
|
+
}
|
|
42
45
|
const position = PATH_POSITIONS[name];
|
|
43
46
|
if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
|
|
44
47
|
if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
|
|
@@ -55,7 +58,7 @@ export function resolveCommandPaths(tokens, cwd) {
|
|
|
55
58
|
*/
|
|
56
59
|
export async function runDebugCommand({ positionals, context }) {
|
|
57
60
|
if (positionals.length === 0) {
|
|
58
|
-
throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:fcdev debug status、fcdev debug run 60、fcdev debug shot out.png' });
|
|
61
|
+
throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug status、npx fcdev debug run 60、npx fcdev debug shot out.png' });
|
|
59
62
|
}
|
|
60
63
|
const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
|
|
61
64
|
const tokens = resolveCommandPaths(positionals, context.cwd);
|