fcdev 0.3.1 → 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.
Files changed (70) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +35 -33
  3. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +27 -25
  4. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +8 -7
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +9 -10
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +13 -11
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +9 -4
  8. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +6 -6
  9. package/docs/09-/345/217/221/345/270/203.md +31 -22
  10. package/docs/10-VS Code/346/211/251/345/261/225.md" +1 -1
  11. package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
  12. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +16 -9
  13. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +7 -7
  14. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +17 -8
  15. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +3 -2
  16. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +1 -1
  17. package/package.json +4 -8
  18. package/src/cli/commands/api-command.mjs +2 -2
  19. package/src/cli/commands/build-command.mjs +1 -1
  20. package/src/cli/commands/debug-command.mjs +5 -2
  21. package/src/cli/commands/disasm-command.mjs +1 -1
  22. package/src/cli/commands/disk-command.mjs +1 -1
  23. package/src/cli/commands/docs-command.mjs +6 -6
  24. package/src/cli/commands/run-command.mjs +2 -2
  25. package/src/cli/index.mjs +1 -1
  26. package/src/disasm/address-tables.mjs +161 -0
  27. package/src/disasm/analysis.mjs +17 -11
  28. package/src/disasm/byte-kinds.mjs +20 -0
  29. package/src/disasm/disassembler.mjs +3 -2
  30. package/src/disasm/info-writer.mjs +3 -3
  31. package/src/docs/doc-index.mjs +5 -28
  32. package/src/docs/doc-topics.mjs +2 -2
  33. package/src/emulator/debug-client.mjs +1 -1
  34. package/src/emulator/emulator-locator.mjs +13 -27
  35. package/src/emulator/index.mjs +1 -1
  36. package/src/toolchain/index.mjs +1 -1
  37. package/src/toolchain/toolchain-locator.mjs +8 -17
  38. package/targets/nes/lib/fcnes.lib +0 -0
  39. package/targets/nes/lib/nes-font.o +0 -0
  40. package/targets/sb2000/api-reference.md +310 -1
  41. package/targets/sb2000/asminc/sb2000.inc +90 -1
  42. package/targets/sb2000/include/sb2000-dma.h +46 -0
  43. package/targets/sb2000/include/sb2000-ppu.h +106 -0
  44. package/targets/sb2000/include/sb2000-symbols.h +170 -0
  45. package/targets/sb2000/include/sb2000-timer.h +54 -0
  46. package/targets/sb2000/include/sb2000.h +3 -0
  47. package/targets/sb2000/lib/crt0.o +0 -0
  48. package/targets/sb2000/lib/sb2000.lib +0 -0
  49. package/targets/sb2000/src/lib/dma/sb-dma-page-address.c +16 -0
  50. package/targets/sb2000/src/lib/dma/sb-dma-to-cpu.c +19 -0
  51. package/targets/sb2000/src/lib/dma/sb-dma-to-vram.c +16 -0
  52. package/targets/sb2000/src/lib/dma/sbi-dma-run.c +34 -0
  53. package/targets/sb2000/src/lib/ppu/sb-ppu-address.c +20 -0
  54. package/targets/sb2000/src/lib/ppu/sb-ppu-fill.c +19 -0
  55. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-clear.c +21 -0
  56. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-put.c +20 -0
  57. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-get.c +16 -0
  58. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-set.c +16 -0
  59. package/targets/sb2000/src/lib/ppu/sb-ppu-peek.c +22 -0
  60. package/targets/sb2000/src/lib/ppu/sb-ppu-read.c +20 -0
  61. package/targets/sb2000/src/lib/ppu/sb-ppu-render.c +20 -0
  62. package/targets/sb2000/src/lib/ppu/sb-ppu-wait-vblank.c +25 -0
  63. package/targets/sb2000/src/lib/ppu/sb-ppu-write.c +21 -0
  64. package/targets/sb2000/src/lib/sb-internal.h +3 -0
  65. package/targets/sb2000/src/lib/timer/sb-timer-current.c +16 -0
  66. package/targets/sb2000/src/lib/timer/sb-timer-mask.c +16 -0
  67. package/targets/sb2000/src/lib/timer/sb-timer-pending.c +16 -0
  68. package/targets/sb2000/src/lib/timer/sb-timer-start.c +17 -0
  69. package/targets/sb2000/src/lib/timer/sb-timer-stop.c +16 -0
  70. package/targets/sb2000/src/lib/timer/sb-timer-unmask.c +16 -0
@@ -6,33 +6,34 @@
6
6
 
7
7
  | 包 | 说明 |
8
8
  | --- | --- |
9
- | `@rujianjs/fcdev-cc65-win32-x64` | 工具链平台包,目录 `packages/fcdev-cc65-win32-x64` |
10
- | `@rujianjs/fcdev-emulator-win32-x64` | 模拟器平台包,目录 `packages/fcdev-emulator-win32-x64` |
11
- | `fcdev` | 主包,对两个平台包写精确版本的 `optionalDependencies` |
9
+ | `@rujianjs/fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
+ | `@rujianjs/fcdev-emulator` | 模拟器包,目录 `packages/fcdev-emulator` |
11
+ | `fcdev` | 主包,对两个包写精确版本的 `optionalDependencies` |
12
12
  | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
13
13
 
14
- - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对平台包的依赖版本必须与之相同。
15
- - 两个平台包的包名带 `@rujianjs` 作用域,目录名不带。作用域包默认不能公开发布,所以它们的 `package.json` 写了 `publishConfig.access` 为 `public`,`release-check` 会检查这一项,以及平台包的包名是否都在 `fcdev` 的 `optionalDependencies` 里。
16
- - 平台包不带作用域的名字发布时被 npm 的垃圾包名检测拦截(403),所以改用作用域,见 [01-软件架构设计](01-软件架构设计.md) 的 D02。
17
- - 两个平台包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs` 与 `node tools/build-emulator.mjs`。
18
- - 每个包的 `package.json` 写 `license`、`repository`、`engines`(`node >=22`)、`files`。作者与邮箱为 `sungbin`、`sungbin@3578.cn`,仓库地址为 `https://gitee.com/sungbin/fcdev.git`。
14
+ - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包与模拟器包的依赖版本必须与之相同。
15
+ - 工具链包与模拟器包的包名带 `@rujianjs` 作用域,目录名不带。作用域包默认不能公开发布,所以它们的 `package.json` 写了 `publishConfig.access` 为 `public`,`release-check` 会检查这一项,以及这两个包的包名是否都在 `fcdev` 的 `optionalDependencies` 里。
16
+ - 不带作用域的名字发布时被 npm 的垃圾包名检测拦截(403),所以改用作用域,见 [01-软件架构设计](01-软件架构设计.md) 的 D02。
17
+ - 工具链包与模拟器包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs` 与 `node tools/build-emulator.mjs`。
18
+ - 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
19
19
 
20
20
  ## 2. 发布前提
21
21
 
22
22
  1. 所有改动已提交。
23
- 2. 在已提交的状态下重新运行 `node tools/build-emulator.mjs`,使模拟器平台包清单里的 `sourceDirty` 为 `false`。`sourceDirty` 只看 `virtuanes/` 目录有没有未提交的改动,构建脚本重写 `SOURCE.txt`(记录新的提交号)不会让它变成 `true`。
24
- 3. 平台包都已构建:`node tools/build-cc65.mjs`、`node tools/build-emulator.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
25
- 4. 模拟器平台包的 `bin/` 里没有 `VirtuaNES.ini` 与 `save/`,见 [08-测试与验证](08-测试与验证.md) 第 7 节。
26
- 5. `npm run release:check` 不带 `--allow-dirty` 通过。
23
+ 2. 在已提交的状态下重新运行 `node tools/build-emulator.mjs`,使模拟器包清单里的 `sourceDirty` 为 `false`。`sourceDirty` 只看 `virtuanes/` 目录有没有未提交的改动。
24
+ 3. 工具链包与模拟器包都已构建:`node tools/build-cc65.mjs`、`node tools/build-emulator.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
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
- `npm run release:check`([tools/release-check.mjs](https://gitee.com/sungbin/fcdev/blob/master/tools/release-check.mjs))只检查,不修改任何文件,也不执行 `npm publish`:
30
+ `npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
31
31
 
32
- - 四个包的版本一致,都写了 `license`,`fcdev` 对平台包的依赖版本一致;平台包的包名都在 `fcdev` 的依赖里,作用域包声明了公开发布。
32
+ - 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与模拟器包的依赖版本一致;这两个包的包名都在 `fcdev` 的依赖里,作用域包声明了公开发布。
33
+ - `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
33
34
  - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
34
35
  - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
35
- - 两个平台包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
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
 
@@ -40,10 +41,10 @@
40
41
 
41
42
  ## 4. 发布顺序
42
43
 
43
- 先发工具链与模拟器平台包,再发 `fcdev`,最后发 `create-fcdev`:
44
+ 先发工具链包与模拟器包,再发 `fcdev`,最后发 `create-fcdev`:
44
45
 
45
- 1. `@rujianjs/fcdev-cc65-win32-x64`
46
- 2. `@rujianjs/fcdev-emulator-win32-x64`
46
+ 1. `@rujianjs/fcdev-cc65`
47
+ 2. `@rujianjs/fcdev-emulator`
47
48
  3. `fcdev`
48
49
  4. `create-fcdev`
49
50
 
@@ -57,11 +58,19 @@
57
58
  | --- | --- | --- |
58
59
  | `fcdev` | 71 | 64 kB |
59
60
  | `create-fcdev` | 23 | 15 kB |
60
- | `@rujianjs/fcdev-cc65-win32-x64` | 223 | 1.9 MB(解压 6.2 MB) |
61
- | `@rujianjs/fcdev-emulator-win32-x64` | 8 | 0.7 MB(解压 1.8 MB) |
61
+ | `@rujianjs/fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
62
+ | `@rujianjs/fcdev-emulator` | 7 | 0.7 MB(解压 1.8 MB) |
62
63
 
63
64
  体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
64
65
 
65
- ## 6. 其他平台
66
+ ## 6. 发布脚本
66
67
 
67
- 首批只发布 `win32-x64`。`darwin-arm64`、`linux-x64` 的构建脚本相同,但没有在这些系统上运行或验证;验证后再发布,发布前主包不列出它们,见 [待办备忘](待办备忘.md)。
68
+ `tools/release.mjs` 把上面的步骤串起来,不暂存、不提交:
69
+
70
+ | 命令 | 作用 |
71
+ | --- | --- |
72
+ | `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version`、主包对两个包的精确依赖,重新构建两个包并生成它们的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
73
+ | `npm run release:publish -- --dry-run` | 演练:跑全部测试、重建模拟器包、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
74
+ | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、四个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,最后用 `npm view` 核对。验证码由 npm 在终端里询问 |
75
+
76
+ 两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。
@@ -88,7 +88,7 @@ C/C++ 扩展用哪个配置,只保存在它自己的工作区状态里,其
88
88
  - 指令与汇编指令不分大小写。
89
89
  - 标签定义要求冒号紧跟在名字后面,行首 `bne :+` 因此不会被当成标签。
90
90
  - 宏的调用与不在词表里的标识符不着色,因为单行匹配无法区分它们与符号。
91
- - 指令词表与 [指令参考](https://gitee.com/sungbin/fcdev/blob/master/vscode/src/shared/assembly/instruction-reference.ts)、[伪指令参考](https://gitee.com/sungbin/fcdev/blob/master/vscode/src/shared/assembly/directive-reference.ts) 的覆盖,由 `test/syntaxes/ca65-grammar.test.ts` 逐条检查。
91
+ - 指令词表与 `vscode/src/shared/assembly/instruction-reference.ts`、`vscode/src/shared/assembly/directive-reference.ts` 的覆盖,由 `test/syntaxes/ca65-grammar.test.ts` 逐条检查。
92
92
 
93
93
  ## 3. 项目信息的来源
94
94
 
@@ -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` 与下面 13 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 184 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
137
+ `sb2000.h` 包含 `sb2000-symbols.h` 与下面 16 个模块头文件,并提供 `SB_BYTE_AT(地址)`(读写一个固定地址的字节)与底层的 `sb_syscall(功能号, 子功能号)`。全部函数(共 204 个)的文档在头文件的 `/** */` 注释里,是接口文档的唯一来源。
138
138
 
139
139
  | 头文件 | 模块 | 内容 |
140
140
  | --- | --- | --- |
@@ -151,17 +151,21 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
151
151
  | `sb2000-sound.h` | sound | 曲子与音效、WAV、语音 |
152
152
  | `sb2000-printer.h` | printer | 24 针点阵打印机 |
153
153
  | `sb2000-ime.h` | ime | 中文输入法 |
154
+ | `sb2000-dma.h` | dma | 通用 DMA:把扩展 RAM 里的数据复制到 ERAM 或显存,源地址换算 |
155
+ | `sb2000-ppu.h` | ppu | 直接操作图形端口:显存读写、调色板、精灵 RAM、等垂直消隐、打开显示 |
156
+ | `sb2000-timer.h` | timer | 硬件定时器:启动、停止、读当前值与下溢标志、屏蔽与允许 |
154
157
 
155
158
  约定:
156
159
 
157
160
  - 命名 `sb_<模块>_<动作>`;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
161
+ - dma、ppu、timer 三个模块直接读写硬件寄存器,不经系统调用,没有 `@syscall`;寄存器地址与位的符号是 `sb2000-symbols.h` 里以 `SB_HW_` 开头的常量,程序不要再自己定义。行为以真机实测为准,见 [硬件说明](03-硬件说明.md)。
158
162
  - 字符串、缓冲区、结构体指针必须在程序窗口 `$8000` 到 `$BFFF` 里(读写目标不能在窗口 3);系统服务换页后程序窗口不可见的情况,函数内部已经处理好。
159
163
  - 一个函数一个源文件,放在 `src/lib/<模块>/sb-<函数名>.c`(或 `.s`);库内部用的辅助函数以 `sbi_` 开头,声明在 `src/lib/sb-internal.h`,不对外。
160
164
  - 运行库由 `tools/build-libs.mjs` 编译:`lib-build.json` 里以 `/` 结尾的项展开成目录下全部 `.c` 与 `.s`;`.c` 用 `cc65 -t none --cpu 6502 -Oirs` 编译再汇编,同名文件报错。链接只带入程序用到的函数。
161
165
 
162
166
  随时查询接口:
163
167
 
164
- - `fcdev api` 列出全部模块;`fcdev api <函数名>` 看完整文档;`fcdev api <模块名>` 看函数列表;`fcdev api '$7B'` 或 `fcdev api '$7B/$09'` 看用到某个系统调用的函数;`fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
168
+ - `npx fcdev api` 列出全部模块;`npx fcdev api <函数名>` 看完整文档;`npx fcdev api <模块名>` 看函数列表;`npx fcdev api '$7B'` 或 `npx fcdev api '$7B/$09'` 看用到某个系统调用的函数;`npx fcdev api <词>` 按名称与说明搜索;`--json` 输出机器可读格式。见 [02-命令行与构建](../02-命令行与构建.md)。
165
169
  - [api-reference.md](../../targets/sb2000/api-reference.md) 是同一份文档的整本 Markdown,由 `node tools/gen-sb2000-api-doc.mjs` 从头文件生成,末尾有“系统调用覆盖表”。改头文件注释后重新生成,测试会核对。
166
170
  - [api-unwrapped.json](../../targets/sb2000/api-unwrapped.json) 登记没有封装的功能号与子功能及原因(`functions` 是整个功能号不封装,`partial` 是封装了一部分)。`node tools/check-sb2000-api.mjs` 检查:头文件里每个函数有说明、`@param`、`@return`,有且只有一处实现,库里没有头文件之外的公开函数,BIOS 里有处理例程的每个功能号(`KNOWN_FUNCTIONS`)要么被某个函数的 `@syscall` 涉及、要么在 `functions` 里写明原因。
167
171
 
@@ -171,7 +175,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
171
175
 
172
176
  ## 7. 符号定义
173
177
 
174
- - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
178
+ - [asminc/sb2000.inc](../../targets/sb2000/asminc/sb2000.inc) 是汇编用的符号定义,ca65 程序用 `.include "sb2000.inc"` 引入,只含符号,不占空间。分节:系统调用、零页单元、不经 `SYSCALL` 直接调用的内核入口、功能号、子功能号(按功能分组)、变量(出错码与显示、文件与目录、内存页、磁盘、键盘手柄鼠标、参数单元)、硬件寄存器与位(`HW_` 开头)、文件打开方式、出错码、运行库入口。每个符号的行尾都有注释,说明含义。
175
179
  - [include/sb2000-symbols.h](../../targets/sb2000/include/sb2000-symbols.h) 是 C 用的同一份符号,每个符号对应一个 `SB_` 前缀的数值宏。它由 `node tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 生成,不要手工修改;改 `sb2000.inc` 后重新运行,测试会检查入库的头文件与生成结果一致。`sb2000.inc` 里符号的行尾注释,会变成宏上方的 `/** */` 文档注释,编辑器悬停时显示;分组标题变成普通的 `/* */` 注释。各模块头文件里的函数也用 `/** */` 与 `@param`、`@return`、`@syscall` 写文档。新增的服务先在 `sb2000.inc` 里加符号(功能号、子功能号、参数与结果单元、出错码),再重新生成。
176
180
 
177
181
  ## 8. 常用做法
@@ -194,6 +198,9 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
194
198
  | 读鼠标 | `$14` 复位并检查 `MOUSE_PRESENT`(`$0633`)非 0 → `$13/$81` 允许鼠标中断 → `$6C/$00` 设范围(`$0646-$0649`,`$0652` 不要是 1-4)→ `$6C/$04` 设初始坐标(`$0652`、`$0653`)→ 随时 `$6C/$02` 取坐标(`$0646`、`$0647`);`$6C/$03` 取按键状态(`$0360-$0367`,按住为 1,点击事件读走即清) | `mouse` |
195
199
  | 播放 WAV | 功能 `$65`、子功能 `$0C`(`SUB_SOUND_WAV`,C 里是 `sb_sound_play_wav`),见 [系统调用手册](02-系统调用手册.md) 5.5(只读过代码,没有示例) | — |
196
200
  | 把 NES 游戏当程序运行 | 读入 `.nes`、复制启动桩到 ERAM、写 `$4301` 后跳转 | `play` |
201
+ | 用 DMA 复制扩展 RAM 的数据 | `sb_dma_to_cpu`(目的只能是 ERAM `$6000-$7FFF`)、`sb_dma_to_vram`;源用 `sb_dma_page_address(页号, 偏移)` 换算;长度寄存器写“字节数 − 1”、`$404B` 位 7 置 1 都由函数处理;复制到显存要先关显示;要把数据放进窗口(`$8000` 以上)时,先 DMA 到 ERAM 缓冲,再用 `memcpy` 搬 | `apps/sb2000/bbk-loader` |
202
+ | 直接写显存、调色板、精灵 | `sb_display_off()` 关显示,用 `sb_ppu_*` 读写显存、调色板与精灵 RAM,`sb_ppu_render` 打开显示,用完再用 `sb_display_on()` 恢复 DOS 的显示 | `apps/sb2000/hwtest` |
203
+ | 用定时器计时 | `sb_timer_start(控制, 预置值)` 启动,`sb_timer_pending()` 看下溢标志,`sb_timer_mask()` 清标志;DOS 用它做系统时钟,用完要用 `$EF`、`$3C` 恢复 | `apps/sb2000/hwtest` |
197
204
 
198
205
  ## 9. 要避开的坑
199
206
 
@@ -211,7 +218,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
211
218
 
212
219
  ## 10. 示例程序
213
220
 
214
- 示例在仓库的 `examples/sb2000/` 下,每个是一个 fcdev 项目;在仓库根目录用 `node packages/fcdev/bin/fcdev.mjs build examples/sb2000/<名>` 构建。
221
+ 示例在仓库的 `apps/sb2000/examples/` 下,每个是一个 fcdev 项目;在仓库根目录用 `node packages/fcdev/bin/fcdev.mjs build apps/sb2000/examples/<名>` 构建。
215
222
 
216
223
  | 目录 | 作用 | 用法(在 DOS 提示符下) |
217
224
  | --- | --- | --- |
@@ -245,7 +252,7 @@ fcdev run src # 构建,挂载镜像,在模拟器里运行
245
252
 
246
253
  ## 12. 运行库的测试
247
254
 
248
- 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
255
+ 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
249
256
 
250
257
  停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
251
258
 
@@ -29,15 +29,15 @@
29
29
 
30
30
  | 地址 | 内容 |
31
31
  | --- | --- |
32
- | `$0000-$1FFF` | 内部 RAM,8K,不镜像;零页 `$0000-$00FF` 供系统与程序共用,程序要避开 DOS 用到的单元 |
33
- | `$2000-$3FFF` | PPU 寄存器(`$2000-$2007` 及其镜像) |
34
- | `$4000-$4017` | 标准 APU 与手柄寄存器 |
35
- | `$4020-$4036` | 键盘、鼠标、中断、定时器等扩展寄存器(键盘经 `$4020-$4022` 串行收发) |
32
+ | `$0000-$1FFF` | 内部 RAM:只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像(真机实测,模拟器已对齐,见 [硬件说明](03-硬件说明.md));零页 `$0000-$00FF` 供系统与程序共用,程序要避开 DOS 用到的单元 |
33
+ | `$2000-$3FFF` | 图形端口:寄存器 `$2000-$2008`(`$2008` 是 6576 的扩展控制寄存器)与调色板 `$2040-$207F`;芯片手册只定义这两段,`$2080` 以上有没有镜像没有实测 |
34
+ | `$4000-$4017` | 声音(4 通道 PSG:方波 2 路、三角波、噪声,寄存器 `$4000-$400F`、`$4015`;芯片手册没有定义 NES 的 DMC 通道寄存器 `$4010-$4013`)、精灵 DMA(`$4014`)、手柄(`$4016`、`$4017`) |
35
+ | `$4020-$4036` | 键盘(`$4020-$4022`,串行收发)、手柄与鼠标选择(`$4023`)、鼠标(`$4024`)、并口打印机(`$4025`)、扩展 I/O(`$4026`)、DAC(`$4027`)、初始设置(`$4031`)、中断(`$4032`、`$4033`)、定时器(`$4034-$4036`) |
36
36
  | `$4040-$4047` | 8 个窗口的页选择:每个选一个 4K 页,对应 `$8000-$FFFF`;值小于 `$80` 是 BIOS ROM 页,不小于 `$80` 是扩展 RAM 页 |
37
37
  | `$4048-$404F` | DMA(见 [硬件说明](03-硬件说明.md)) |
38
38
  | `$4200-$4207` | 软驱控制器 |
39
39
  | `$4300` | 显存 bank 选择(32K 一个 bank) |
40
- | `$5000-$5FFF` | 2K 工作 RAM |
40
+ | `$4400-$5FFF` | 不是 RAM:读出都是 `$68`,写不进去(真机实测,模拟器已对齐);芯片手册里的 `$5000-$57FF` 2K 工作 RAM 在真机上没有,程序不能使用 |
41
41
  | `$6000-$7FFF` | 8K 扩展 RAM(ERAM),任何窗口映射下都可见;`$6200-$65FF` 一带是 DOS 的状态变量 |
42
42
  | `$8000-$BFFF` | 程序窗口:4 个 4K 窗口,由系统调用 `$29`、`$25` 映射 |
43
43
  | `$C000-$FFFF` | 固定内核:ROM 第 4-7 页 |
@@ -338,7 +338,7 @@
338
338
 
339
339
  音乐驱动的内部例程:`SOUND_PLAY_SONG`(`$F43A`,按 `$049A` 播放:0 复位,`$FB-$FF` 为控制命令,其余为曲号,曲表指针在 `$D31B` 起)、`SOUND_START_TRACKS`(`$F4C9`)、`SOUND_RESET`(`$F5C4`)、`SOUND_UPDATE_ON`/`SOUND_UPDATE_OFF`(`$F5E9`、`$F5F2`);发声在 NMI 中断里更新。
340
340
 
341
- 曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU 寄存器 `$4000-$4013`、`$4015` 的序列):
341
+ 曲子数据与引擎(已验证:实机逐帧与按代码写的模型比对 `$0393-$04A3` 的全部字节、`SOUND_TEMP0-03`,以及写向 APU 寄存器的序列(验证时记录 `$4000-$4013`、`$4015` 的写入;芯片手册只定义 `$4000-$400F` 与 `$4015`)):
342
342
 
343
343
  - 曲子有两种头。**音乐格式**:首字节不小于 `$80`,后面是声道项 `[声道号, 音轨偏移低, 偏移高]`(声道号小于 `$80`),以不小于 `$80` 的字节结束;首字节后紧跟一个不小于 `$80` 的字节时,声道项从第 4 字节起。**音效格式**:首字节小于 `$80`,是优先级,后面同样是声道项;第 2 字节不小于 `$80` 时还有 3 字节头(第 3 字节放 `$03BD`,曲号放 `$03BE`,`$0499` 置位 5,用于播完自动接下一首)。声道项里声道号不小于 4 的,优先级写进 `$03BB+声道号`,优先级小于当前 `$03BB+声道号` 时整首不起播;音乐格式的曲子曲号与 `$03BB` 相同时也不起播(`$65/$0A`、`$0B` 的曲号恒为 0,所以音乐格式的曲子用它们起不了播,要用 `$00`、`$01`、`$09`)。
344
344
  - 音轨偏移相对曲首(`$039B/$039C`,音效格式是 `$039D/$039E`);声道 0-3 是音乐声道,4-7 是音效声道,音效声道与同号后四位的音乐声道共用一个硬件声道,音效声道播放时(`$03CF+声道号` 非 0)音乐声道不写 APU。音乐声道读曲子的页放 `$04A1`(`$00`、`$01`、`$09` 设置),音效声道的页放 `$04A3`(`$0A`、`$0B` 设置)。
@@ -437,7 +437,7 @@ BIOS 自己带了一段 WAV:ROM 第 `$64` 页起,单声道、8 位、22050 H
437
437
 
438
438
  ### 5.7.2 DMA 与显存服务 `$30-$34`(已验证)
439
439
 
440
- DMA 寄存器:`$4048` 控制、`$4049` 源高、`$404A` 源低、`$404B` 源中、`$404C` 目的低、`$404D` 目的高、`$404E` 长度低、`$404F` 长度高;长度寄存器写“长度 − 1”。屏幕缓冲在扩展 RAM 页 `$FA`(名称表 4、5,偏移 `$000`、`$800`)与页 `$FB`(名称表 6、7),每张 2KB、每个单元 2 字节;区域填充的中转缓冲在页 `$F8` 起。
440
+ DMA 寄存器:`$4048` 控制、`$4049` 源 bank、`$404A` 源低、`$404B` 源高(位 7 是 A15,要求为 1,为 0 时 DMA 失败)、`$404C` 目的低、`$404D` 目的高、`$404E` 长度低、`$404F` 长度高(各位的含义见 [硬件说明](03-硬件说明.md);BIOS 源码里的符号 `DMA_SRC_BANK`、`DMA_SRC_LOW`、`DMA_SRC_HIGH` 依次对应 `$4049`、`$404A`、`$404B`);长度寄存器写“长度 − 1”。屏幕缓冲在扩展 RAM 页 `$FA`(名称表 4、5,偏移 `$000`、`$800`)与页 `$FB`(名称表 6、7),每张 2KB、每个单元 2 字节;区域填充的中转缓冲在页 `$F8` 起。
441
441
 
442
442
  | 功能 | 作用 |
443
443
  | --- | --- |
@@ -1,22 +1,31 @@
1
1
  # SB2000 硬件说明
2
2
 
3
- 本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源是模拟器源码(fcdev 仓库 `virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)和实际运行观察。“已确认”指来自模拟器源码或实际运行,真机均未测试;程序接口见 [系统调用手册](02-系统调用手册.md)。
3
+ 本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源有三类:芯片手册(SH6578 官方手册,下称“芯片手册”)、模拟器源码(`virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)与实际运行观察、真机实测(`apps/sb2000/memtest`,2026-11-12;`apps/sb2000/hwtest`,2026-11-13,真机为 PAL 制式)。SB2000 的真机芯片是 UM6576,芯片手册是 SH6578,两颗芯片有差别,两者不一致时以真机实测为准。“已确认”指来自模拟器源码或实际运行;没有写“真机”的结论都没有在真机上测过。模拟器已按真机实测修改内部 RAM、`$4400-$5FFF`、DMA、定时器与图形端口(见对应行),memtest、hwtest 在模拟器里的结果与真机一致(仍有差异的项见“真机与模拟器仍有差异的行为”一行);模拟器与芯片手册不一致、也没有真机数据的地方,在对应行里写明。程序接口见 [系统调用手册](02-系统调用手册.md)。
4
4
 
5
5
  | 项目 | 结论 | 状态 |
6
6
  | --- | --- | --- |
7
- | CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是映射器 ASIC 的工作模式 | 已确认 |
8
- | 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成 | 已确认 |
7
+ | CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是向 `$4031` 依次写入 `$65`、`$76`(芯片手册称这一步为初始设置)之后的工作模式 | 已确认 |
8
+ | 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成。芯片手册要求两次写入在两个指令周期内连续完成(`LDA #$65 / LDX #$76 / STA $4031 / STX $4031`),模拟器只按顺序识别,不检查间隔 | 已确认(芯片手册、模拟器源码) |
9
9
  | 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真 | 已确认 |
10
10
  | 程序窗口 | `$4040-$4047` 各选一个 4K 页,对应 `$8000-$FFFF` 的 8 个窗口;值小于 `$80` 是 BIOS ROM 页(512KB,共 128 页),不小于 `$80` 是扩展 RAM 页(512KB) | 已确认 |
11
11
  | 启动后的窗口 | `$C000-$FFFF` 固定为 ROM 第 4-7 页,`$8000-$BFFF` 由 BIOS 换页 | 已确认 |
12
12
  | 向量 | NMI `$C084`,RESET `$C000`,IRQ `$C12B`(ROM 偏移 `$7FFA` 起) | 已确认 |
13
- | 内部 RAM | 6576 模式下 `$0000-$1FFF` 为 8K 且不镜像;`$5000-$5FFF` 为 2K 工作 RAM,`$6000-$7FFF` 为 8K 扩展 RAM | 已确认 |
14
- | DMA | `$4048-$404F`;写 `$4048` 的最高位启动;源为 ROM 或扩展 RAM,目的为工作 RAM 或显存 | 已确认 |
13
+ | 内部 RAM | 芯片手册:工作 RAM 共 10KB,在 `$0000-$1FFF`(8KB)与 `$5000-$57FF`(2KB)。模拟器(6576 模式)已按真机实测修改,行为与下面的真机实测相同;模拟器在 FC 兼容模式下仍保留 `$5000-$5FFF` 的 2K RAM(镜像两次),这个模式没有在真机上测过。真机实测:内部 RAM 只有 2K,`$0800-$1FFF` 是 `$0000-$07FF` 的镜像;`$4400-$5FFF` 读出的都是 `$68`,写 `$55`、`$AA` 后读回仍是 `$68`,既不是 RAM 也不是会应答的寄存器(`$5006` 的写入仍有效果);`$6000-$7FFF` 是 8K,各 1K 互相独立 | 已确认(真机实测;模拟器已在 SB-DOS 下用真实 CPU 指令读写核对);内存大小与芯片手册不一致,以真机为准 |
14
+ | DMA | `$4048-$404F`,把主存储器的数据复制到显存或工作 RAM;写 `$4048` 的最高位启动(模拟器瞬时完成)。`$4048`:位 7 使能;位 6 传输速率(0 为 890KB/s,1 为 1.78MB/s);位 5 目的(0 为显存,1 为工作 RAM),其余位为 0。芯片手册要求先把 `$4020` 位 7 置 1,位 6、5 才起作用(模拟器不检查;BIOS 在系统初始化时写 `$4020=$80`)。`$4049`:源 bank,低 5 位对应 XA20-XA16,位 4 为 1 取扩展 RAM,否则取 ROM;`$404A`、`$404B`:源地址的低、高字节,`$404B` 的低 7 位是 A14-A8,位 7 是 A15(真机要求为 1,模拟器已按真机处理:为 0 时不传输);`$404C`、`$404D`:目的地址低、高字节,目的是显存时位 15 为 1 表示扩展显存;`$404E`、`$404F`:长度寄存器的值是字节数减 1,真机实际搬“长度 + 1”个字节(BIOS 也传“字节数 − 1”),最大 32KB(`$8000` 不屏蔽,写 `$8010` 会搬 `$8011` 个字节)。每搬一个字节,源地址与目的地址各加 1。芯片手册:目的是显存时只在垂直消隐期间或显示关闭时运行,没搬完的数据留到下一次垂直消隐再继续;目的是工作 RAM 时没有这个限制。BIOS 把 `$C0` 用于复制到显存,`$A0`、`$E0` 用于复制到 CPU 地址。真机实测:只有目标是 ERAM 且 `$404B` 位 7 为 1 时成功,模式 `$A0`、`$E0` 都行;`$4020` 位 7 为 0 时,模式位 5 不起作用,目的总是显存,位 7 为 1 时才由模式位 5 选择工作 RAM 或显存(与芯片手册的说法一致);模拟器已对齐:`$404B` 位 7 为 0 时不传输,目的在程序窗口(`$8000` 以上)时写不进去,长度按“长度 + 1”,`$4020` 位 7 为 0 时目的总是显存,memtest、hwtest 在模拟器里的结果与真机相同 | 已确认(芯片手册、模拟器源码;位的作用已在模拟器里逐项核对);真机实测 |
15
15
  | 软驱控制器 | `$4200-$4207`;1.44MB(每道 18 扇区、2 面、80 道),LBA = 磁道×36 + 磁头×18 + 扇区 − 1 | 已确认 |
16
- | 键盘 | 经 `$4020-$4022` 串行收发,扫描码与 DirectInput 的 DIK 值一致 | 已确认 |
16
+ | 键盘 | 经 `$4020-$4022` 串行收发。芯片手册:键盘口收发 AT 键盘的 11 位串行帧(起始位、8 位扫描码、奇偶位、停止位),收完整帧后产生键盘中断,要在下一位到来前读走 `$4020` 里的扫描码;`$4022` 位 7 是键盘时钟 CLK(接收时必须保持 1,BIOS 处理完一个码后写 `$80`),位 2 允许“发送命令完成”中断,位 0 是方向(0 为键盘到系统,1 为系统到键盘);发送时先把数据写入 `$4021`,再置位 0 为 1、CLK 拉低大于 60ms 后拉高,硬件自动发出。模拟器直接给出与 DirectInput 的 DIK 值一致的扫描码(即 IBM 码集 1 的按下码),在 CLK 上升沿且位 0 为 1 时把 `$4021` 发给键盘;真机键盘实际是否按此工作没有测过;BIOS 初始化键盘时(功能 `$17`)会发 `$F0`、`$01` 选择扫描码集 1 | 已确认(芯片手册、模拟器源码) |
17
17
  | 显存 | 512KB,经 `$4300` 选 32KB 的 bank | 已确认 |
18
- | 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 3 软驱,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断 | 已确认(模拟器源码) |
19
- | 并口打印机 | 模拟器实现了 Epson ESC/P 虪拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
18
+ | 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 4 INT4(芯片手册:实时时钟)、位 3 软驱、位 2 INT2(芯片手册:打印机的 IRQ2)、位 1 INT1(芯片手册:φ 使能的 IRQ1),位 0 未用,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断。BIOS 为位 4、2、1 各留了钩子,模拟器里没有设备置位它们 | 已确认(芯片手册、模拟器源码) |
19
+ | 鼠标 | `$4023` 位 0 选手柄 2 或鼠标(1 为鼠标);真机实测(`hwprobe`):读回是 `$80 | 位 0`,位 7 是输入线(闲置为 1),位 6-1 读 0;鼠标数据经 `$4024` 读,是微软串口鼠标的 3 字节包。复位信号:BIOS(功能 `$14`)与模拟器都用 `$4026` 的位 1(EIO1),拉低再拉高,模拟器在上升沿发 RTS。芯片手册在鼠标一节把复位信号写作 `$4026` 的 D2,在扩展 I/O 一节又写 EIO1 产生鼠标复位,两处说法不一致,这里按 BIOS 与模拟器的用法,真机没有核实;手册要求复位时间大于 30ms,并可写 `$4024` 设置波特率(NTSC 为 `$A3`、PAL/B 为 `$A9`),BIOS 没有写它 | 已确认(芯片手册、模拟器源码、BIOS 代码);复位位的说法见左 |
20
+ | 定时器 | `$4034` 控制:位 7 允许,位 6 连续重载(0 只计一次),位 5 基准时钟(0 为 CPU 时钟,1 为行消隐时钟 15625Hz),位 3-0 为预分频 PS;`$4035` 写预置值 TP,同时装入当前值;`$4036` 读当前值(递减)。周期 = 基准周期 × (PS + 1) × (TP + 1),下溢时置 `$4033` 位 7(`$4032` 位 7 为 0 才产生中断)。真机实测:`$4035` 可读(读回写入的预置值);一次计时(位 6 为 0)下溢一次后,当前值保持预置值,不再计时,也不再置中断标志,模拟器已对齐(旧版把当前值置 0);真机一帧是 PAL 的 50Hz,120 帧内的下溢次数:BIOS 的设置与行消隐时钟两组模拟器与真机相同(38、147),CPU 时钟那组真机 1040 次、模拟器 1038 次。BIOS 开机设 `$4034=$EF`、`$4035=$3C`(连续、行消隐时钟、PS=15、TP=60,周期 64µs × 16 × 61 约 62.5ms,即约 16Hz),用作软件时钟的节拍;播放 WAV 时用 `$4034=$C0`(CPU 时钟、PS=0),`$4035` 取 `$28`、`$51`、`$A2` 作采样节拍 | 已确认(芯片手册、模拟器源码;开机后的寄存器值已在模拟器里读出);`$4035` 可读与一次计时的行为为真机实测 |
21
+ | 声音 | 芯片手册:4 通道 PSG,通道 1、2 方波,通道 3 三角波,通道 4 噪声,寄存器为 `$4000-$4003`、`$4004-$4007`、`$4008`、`$400A`、`$400B`、`$400C`、`$400E`、`$400F`,`$4015` 低 4 位依次使能通道 1-4;没有定义 NES 的 DMC 寄存器 `$4010-$4013`,语音改用 `$4027` 的 DAC 输出。BIOS 的声音引擎在 RAM 里维护这些寄存器的影子,再写到芯片(见 [系统调用手册](02-系统调用手册.md) 5.5 节) | 芯片手册 |
22
+ | DAC | `$4027` 是 8 位 DAC,输出语音(PCM)。芯片手册:实际输出发生在定时器溢出时,所以使用 DAC 必须同时设置定时器;输出带约 1/2 Vcc 的直流偏置,输出语音前要把电平从 0 缓慢升到偏置值,否则开始时有“噗”声。BIOS 播放 WAV 时写它(`$65/$0C`) | 芯片手册;BIOS 的用法已验证 |
23
+ | 实时时钟 | 芯片手册:`$4080` 写 RTC 地址,`$4081` 读写 RTC 数据,使用前先设地址。SB2000 的 BIOS 不访问它们,系统时钟由定时器中断软件计时;模拟器的 `$4026` 位 0(EIO0)没有接 RTC | 芯片手册;BIOS 没有使用 |
24
+ | 图形端口 | 寄存器 `$2000-$2008` 与调色板 `$2040-$207F`。`$2000`:位 7 允许 NMI,位 5 精灵 8×16,位 2 地址增量(0 加 1,1 加 32),位 1-0 背景页;`$2001`:位 0 黑白,位 1、2 屏蔽背景、精灵最左 8 个像素,位 3、4 背景、精灵显示,位 7-5 红绿蓝增强;`$2002` 读:位 7 垂直消隐,位 6 精灵与背景碰撞,位 5 一行超过 8 个精灵;`$2008`:位 7 背景 4 色(0)或 16 色(1),位 3-2 精灵图案表起始,位 0 名称表起始(为 1 时名称表在显存 `$2000-$27FF`,只能显示一页)。名称表项 2 字节,高 4 位是调色板组,低 12 位是图案号;调色板 64 项,每项低 4 位颜色、位 5-4 亮度。显存、调色板、精灵 RAM 只能在垂直消隐期间或显示关闭时更新,精灵用 `$4014` 的 DMA 更新。BIOS 功能 `$10` 修改的就是这些位(见 [系统调用手册](02-系统调用手册.md) 5.7 节)。真机实测(`hwtest`,与芯片手册不一致的地方以真机为准):① `$2001` 位 1、2 的极性与 NES 相同,为 1 表示显示最左 8 个像素,为 0 表示屏蔽(芯片手册写反,BIOS 影子初值 `$0E` 即两位都显示);位 0 为 1 时黑白,背景底色也变灰;位 5 增强绿、位 6 增强红、位 7 增强蓝(PAL 顺序,芯片手册写位 5 蓝、位 6 绿、位 7 红)。② 精灵属性位 6 为水平镜像,位 7 为垂直翻转,位 5 为 1 表示在背景之后(只被不透明的背景像素盖住);读回 OAM 时属性字节的位 4-2 恒为 1(写 `FF` 读 `FF`,写 `00` 读 `1C`),不跟地址、也不跟最后写的 PPU 端口走;早先的两次 `hwtest` 曾读到 `E3`、`F3`,用现在的程序复现不了,原因不明。③ `$2000` 位 1-0 选 4 个互相独立的名称表;`$2008` 位 0 为 1 时名称表从 `$2000` 起;8×16 精灵的图案号最低位被忽略(相邻的偶数号、奇数号显示同一对图块),上半取偶数号。④ 调色板每项低 4 位是色相、位 5-4 是亮度,与芯片手册相同,16 色模式可用;读调色板得到 `(值 & $3F) | $40`。⑤ `$2002` 位 6(精灵 0 碰撞)、位 5(一行超过 8 个精灵)有效,低 5 位是最后一次写 PPU 总线的值。模拟器的 UM6576 PPU(`PPU_UM6576.cpp`)已按以上实测实现;颜色的亮度与饱和度渲染与真机电视的差别没有对齐,不影响程序行为 | 芯片手册;位的作用为真机实测(`hwtest`),模拟器已对齐 |
25
+ | 空读(没有器件驱动的位) | 真机实测:读到 CPU 数据总线上最近的一个值,读指令里的地址高字节就是总线最近的值,所以 `$203F`、`$2080` 读 `$20`,`$4018`、`$4019`、`$401F` 读 `$40`;`$4016`、`$4017` 的位 6 也是这个原因;`$2009` 读 `$00`。模拟器(UM6576 模式)记录总线最近的值,空读时返回它,零页间接寻址(`(zp),Y`)读到的是指针高字节,堆栈不记录;`$200A-$203F`、`$2080-$3FFE`、`$4018-$401F` 按这个规则处理,其中只有 `$203F`、`$2080`、`$4018`、`$4019`、`$401F` 在真机上测过 | 真机实测(`hwtest`);模拟器已对齐 |
26
+ | 实时时钟 | 真机实测:`$4081` 不论有没有设地址,读出的都是 `$60`;模拟器读出 `$60` | 真机实测(`hwtest`);模拟器已对齐 |
27
+ | 真机与模拟器仍有差异的行为 | `hwtest` 在真机上测到、模拟器没有对齐的项目(程序不应依赖这些值)。真机读数:`$3FFF` 为 `$68`(模拟器读 `$00`,原因不明),`$4037` 两次实测分别为 `$A0`、`$E0`(不固定);`$4015` 写 `$FF` 后读出位 4 为 1、写 `$1F` 后读出位 4 为 0(模拟器反过来);`$4022` 开机值 `$C0`(模拟器为 `$80`;写入后的读回还没有真机数据);`$4026` 读出 `$3F`(位 4 为 1,模拟器按虚拟打印机固定为 `$2F`);`$4016` 读出 `$44`、`$4017` 读出 `$40`(模拟器为 `$40`、`$48`);`$4033` 位 6 在清除后仍为 1(鼠标待处理,没接鼠标时的真机状态,模拟器为 0)。`$4036` 运行中的当前值取决于读取时刻,通用 DMA 在 `$8010` 起的采样取决于源 RAM 里原来的内容,`$4015` 位 4 取决于读取时刻(同一个写入值两遍读回不同,像 DMC 的活动状态位),模拟器用的是同类逻辑,无法逐值比对;`$4023` 位 7 在 `hwprobe` 里一直为 1(`hwtest` 报告里“写 1、写 0 后读到 `01`、`00`”是编译器省掉了写后的回读,不是真机值,`$4022` 写后的“读回”也一样,只有测前的值是真读),模拟器按 1 处理 | 真机实测(`hwtest`);模拟器没有对齐 |
28
+ | 并口打印机 | 模拟器实现了 Epson ESC/P 虚拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。芯片手册只定义了 `$4016` 的位 1、0(OUT1、OUT0)、`$4017` 的位 0、`$4025`(数据寄存器,写入时产生选通)与 `$4026`(EIO7-EIO0);这里 `$4016` 位 2、`$4017` 位 2、3 的用法来自模拟器源码的注释,芯片手册没有定义,真机没有核实。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
20
29
  | 语音端口 `$4302` | 读:位 7 为 1 表示可以接收下一个字节(缓冲未满),语音播完时低 4 位为 `$F`。写:把一个语音数据字节送进环形缓冲,由模拟器的 LPC 语音线程解码播放。`$4026` 位 6 的上升沿复位语音(清缓冲)。BIOS 的 `$74`、`$75`(`API_74_PORT4302_CONTROL`、`API_75_PORT4302_SEND`)就是操作它 | 已确认(模拟器源码);`$74`、`$75` 的发送序列与“播完”结束都已实测(见 [系统调用手册](02-系统调用手册.md) 5.13 节);模拟器曾缺 `case 0x4302:`,已修复 |
21
30
 
22
31
  ## 软件环境
@@ -7,7 +7,6 @@
7
7
  | 事项 | 说明 |
8
8
  | --- | --- |
9
9
  | 发布四个 npm 包 | 由用户登录 npm 后按 [09-发布](09-发布.md) 的顺序执行 |
10
- | `darwin-arm64`、`linux-x64` 平台包 | 构建脚本已写,需要在这些系统上运行并验证后再发布;模拟器只支持 Windows,不做这两个系统的模拟器包 |
11
10
 
12
11
  ## 2. VS Code 扩展
13
12
 
@@ -26,6 +25,8 @@
26
25
  | 事项 | 说明 |
27
26
  | --- | --- |
28
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`) |
29
30
 
30
31
  ## 4. 目标
31
32
 
@@ -41,6 +42,6 @@
41
42
  | 事项 | 说明 |
42
43
  | --- | --- |
43
44
  | 其他映射器 | 现在只支持 NROM 与平铺二进制;其他映射器需要目标提供地址映射 |
44
- | 跳转表识别 | 例程内联的跳转表(如 `RTS` 跳转表)追踪不到,这部分按数据输出 |
45
+ | 跳转表识别 | 已识别 `LDA 表,X` 加间接 `JMP`、`PHA`/`RTS` 的表和 `JMP (地址)` 指向的表;例程内联的跳转表(`JSR` 之后紧跟地址表)、立即数拼出的分发指针还追不到,这部分按数据输出;补全覆盖靠运行记录:模拟器 `trace ... unique` 在步步高机型上可用,CDL 只对 SB2K 映射器有效,对步步高 RAM 里的程序没用。立即数拼出的指针可以让 `fcdev` 列出“可能的入口”供人工确认,还没做 |
45
46
  | 地址表与字符串识别 | 现在没追到的字节都是 `ByteTable` |
46
47
  | SB2000 固件页的 CDL 验证 | 没有做;模拟器自带 CDL 只对 SB2K 映射器有效 |
@@ -5,6 +5,6 @@
5
5
  | 编号 | 发现日期 | 缺陷 | 影响 | 状态 | 修复说明 |
6
6
  | --- | --- | --- | --- | --- | --- |
7
7
  | B001 | 2026-11-10 | 根 `.gitignore` 的 `build/` 规则把 `packages/fcdev/src/build/`(构建核心的 7 个源文件)排除在版本库之外,`git ls-files` 里没有它们 | 已提交的仓库缺少构建核心,别人克隆后无法使用 `fcdev build`;发布时因为 `files` 白名单仍会打进包,所以现有包内容不受影响 | 已修复 | 把 `.gitignore` 里的 `build/` 改为只忽略仓库根的 `/build/` 与各包根目录下的 `packages/*/build/`;修改后 `git check-ignore` 不再匹配 `packages/fcdev/src/build/`,该目录显示为未跟踪,需要用户自己暂存并提交 |
8
- | B002 | 2026-11-10 | [virtuanes/README.md](https://gitee.com/sungbin/fcdev/blob/master/virtuanes/README.md) 的目录图根写成 `emulator/`,一处链接指向不存在的文件 | 链接失效,目录图与实际不符 | 已修复 | 目录图改为 `virtuanes/`,删掉失效链接与不属于本仓库的说明 |
8
+ | B002 | 2026-11-10 | `virtuanes/README.md` 的目录图根写成 `emulator/`,一处链接指向不存在的文件 | 链接失效,目录图与实际不符 | 已修复 | 目录图改为 `virtuanes/`,删掉失效链接与不属于本仓库的说明 |
9
9
  | B003 | 2026-11-10 | `fcdev` 接受 `--verbose` 选项,但没有任何命令使用它 | 选项无效果;文档与帮助文字都没有提到它 | 待修复 | |
10
10
  | B004 | 2026-11-12 | `npm run check` 里需要启动模拟器的 SB2000 测试(`sb2000-library.test.mjs`)偶发失败:有时报“调试命令 run 300 超过 120000 毫秒没有应答”,有时报“等待调试服务就绪超时”,失败的用例每次不同;单独重跑通过 | 全量检查偶发 1 个失败,与代码改动无关 | 待修复 | |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fcdev",
3
- "version": "0.3.1",
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>",
@@ -13,11 +13,6 @@
13
13
  "sb2000",
14
14
  "disassembler"
15
15
  ],
16
- "repository": {
17
- "type": "git",
18
- "url": "https://gitee.com/sungbin/fcdev.git",
19
- "directory": "packages/fcdev"
20
- },
21
16
  "type": "module",
22
17
  "engines": {
23
18
  "node": ">=22"
@@ -30,12 +25,13 @@
30
25
  },
31
26
  "files": [
32
27
  "bin",
28
+ "CHANGELOG.md",
33
29
  "docs",
34
30
  "src",
35
31
  "targets"
36
32
  ],
37
33
  "optionalDependencies": {
38
- "@rujianjs/fcdev-cc65-win32-x64": "0.3.1",
39
- "@rujianjs/fcdev-emulator-win32-x64": "0.3.1"
34
+ "@rujianjs/fcdev-cc65": "0.5.0",
35
+ "@rujianjs/fcdev-emulator": "0.5.0"
40
36
  }
41
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);
@@ -37,7 +37,7 @@ export function parseAddress(text, option) {
37
37
  */
38
38
  export async function runDisasmCommand({ positionals, options, context }) {
39
39
  if (positionals.length !== 1) {
40
- throw new FcdevError('disasm 需要一个输入文件', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--symbols 文件] [--out 目录]' });
40
+ throw new FcdevError('disasm 需要一个输入文件', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--symbols 文件] [--out 目录]' });
41
41
  }
42
42
  const inputFile = path.resolve(context.cwd, positionals[0]);
43
43
  const config = loadProjectConfig(context.cwd, context.cwd);
@@ -18,7 +18,7 @@ import { FcdevError } from '../../shared/index.mjs';
18
18
  */
19
19
  export async function runDiskCommand({ positionals, options, context }) {
20
20
  if (positionals.length > 1) {
21
- throw new FcdevError('disk 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev disk [目录或文件]' });
21
+ throw new FcdevError('disk 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev disk [目录或文件]' });
22
22
  }
23
23
  const reporter = {
24
24
  log: (message) => context.stdout.write(`${message}\n`),
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:docs-command.mjs
3
- // 说明:docs 命令:列出开发文档的主题,查询某份文档的本机路径与在线地址。
3
+ // 说明:docs 命令:列出开发文档的主题,查询某份文档的本机路径。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
@@ -18,7 +18,7 @@ import { FcdevError } from '../../shared/index.mjs';
18
18
  export async function runDocsCommand({ positionals, options, context }) {
19
19
  const directory = docsDirectory();
20
20
  if (!existsSync(directory)) {
21
- throw new FcdevError(`找不到文档目录:${directory}`, { code: 'DOCS_MISSING', hint: '这份 fcdev 不带文档,请改读在线文档,地址见 package.json 的 repository' });
21
+ throw new FcdevError(`找不到文档目录:${directory}`, { code: 'DOCS_MISSING', hint: '这份 fcdev 不带文档,请升级到带文档的版本' });
22
22
  }
23
23
 
24
24
  const query = positionals.join(' ').trim();
@@ -31,14 +31,14 @@ export async function runDocsCommand({ positionals, options, context }) {
31
31
  const width = Math.max(...docs.map((doc) => doc.topic.length));
32
32
  const lines = [`fcdev 开发文档:${docs.length} 份`, `本机目录:${directory}`, ''];
33
33
  for (const doc of docs) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
34
- lines.push('', '查询:fcdev docs <主题>(本机路径与在线地址)、fcdev docs <词>(按主题、文件名、标题与说明搜索)');
34
+ lines.push('', '查询:npx fcdev docs <主题>(本机路径)、npx fcdev docs <词>(按主题、文件名、标题与说明搜索)');
35
35
  context.stdout.write(`${lines.join('\n')}\n`);
36
36
  return 0;
37
37
  }
38
38
 
39
39
  const { kind, matches } = queryDocs(query);
40
40
  if (matches.length === 0) {
41
- throw new FcdevError(`没有找到“${query}”`, { code: 'DOCS_NOT_FOUND', hint: '不带查询词运行 fcdev docs 可以看到全部主题' });
41
+ throw new FcdevError(`没有找到“${query}”`, { code: 'DOCS_NOT_FOUND', hint: '不带查询词运行 npx fcdev docs 可以看到全部主题' });
42
42
  }
43
43
  if (options.json) {
44
44
  context.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
@@ -46,13 +46,13 @@ export async function runDocsCommand({ positionals, options, context }) {
46
46
  }
47
47
  if (matches.length === 1) {
48
48
  const [doc] = matches;
49
- context.stdout.write(`${doc.title}(主题 ${doc.topic})\n说明:${doc.summary}\n本机:${doc.localPath}\n在线:${doc.onlineUrl}\n`);
49
+ context.stdout.write(`${doc.title}(主题 ${doc.topic})\n说明:${doc.summary}\n本机:${doc.localPath}\n`);
50
50
  return 0;
51
51
  }
52
52
  const width = Math.max(...matches.map((doc) => doc.topic.length));
53
53
  const lines = [`包含“${query}”的文档:${matches.length} 份(${kind === 'file' ? '按文件名' : '按关键词'})`];
54
54
  for (const doc of matches) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
55
- lines.push('', '用 fcdev docs <主题> 查看某份文档的本机路径与在线地址');
55
+ lines.push('', '用 npx fcdev docs <主题> 查看某份文档的本机路径');
56
56
  context.stdout.write(`${lines.join('\n')}\n`);
57
57
  return 0;
58
58
  }
@@ -20,7 +20,7 @@ import { FcdevError } from '../../shared/index.mjs';
20
20
  */
21
21
  export async function runRunCommand({ positionals, options, context }) {
22
22
  if (positionals.length > 1) {
23
- throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:fcdev run [目录或文件]' });
23
+ throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev run [目录或文件]' });
24
24
  }
25
25
  const reporter = {
26
26
  log: (message) => context.stdout.write(`${message}\n`),
@@ -62,7 +62,7 @@ export async function runRunCommand({ positionals, options, context }) {
62
62
  context.stdout.write(`等 DOS 启动后,在提示符下输入 ${path.basename(result.outputFile, path.extname(result.outputFile))} 运行程序\n`);
63
63
  }
64
64
  if (options.debug) {
65
- context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 fcdev debug run 60\n`);
65
+ context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 npx fcdev debug run 60\n`);
66
66
  }
67
67
  return 0;
68
68
  }
package/src/cli/index.mjs CHANGED
@@ -54,7 +54,7 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
54
54
  sync 生成 IDE 的 C/C++ 配置
55
55
  info [--json] 显示目标、工具链与头文件目录
56
56
  api [词] [--json] 查询目标的 C 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
57
- docs [词] [--json] 查询开发文档:主题名或关键词,给出本机路径与在线地址;不带词列出全部主题
57
+ docs [词] [--json] 查询开发文档:主题名或关键词,给出本机路径;不带词列出全部主题
58
58
 
59
59
  选项:
60
60
  --target <名> 指定目标,覆盖 fcdev.json