fcdev 0.6.0 → 0.7.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 (33) hide show
  1. package/CHANGELOG.md +46 -32
  2. package/README.md +8 -8
  3. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +9 -8
  4. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +5 -5
  5. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +3 -3
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +69 -62
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +3 -3
  8. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +13 -10
  9. package/docs/09-/345/217/221/345/270/203.md +16 -11
  10. package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
  11. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +7 -7
  12. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +4 -1
  13. package/package.json +5 -2
  14. package/src/cli/args-parser.mjs +1 -1
  15. package/src/cli/commands/debug-command.mjs +20 -58
  16. package/src/cli/commands/run-command.mjs +36 -39
  17. package/src/cli/index.mjs +4 -4
  18. package/src/config/config-loader.mjs +1 -1
  19. package/src/disasm/disassembler.mjs +1 -1
  20. package/src/disasm/trace.mjs +4 -3
  21. package/src/docs/doc-topics.mjs +38 -38
  22. package/src/emulator/debug-cli.mjs +48 -0
  23. package/src/emulator/emulator-launcher.mjs +107 -29
  24. package/src/emulator/emulator-locator.mjs +7 -7
  25. package/src/emulator/index.mjs +4 -3
  26. package/src/emulator/sb2000-session.mjs +101 -0
  27. package/targets/nes/lib/fcnes.lib +0 -0
  28. package/targets/nes/lib/nes-font.o +0 -0
  29. package/targets/nes/target.json +1 -1
  30. package/targets/sb2000/lib/crt0.o +0 -0
  31. package/targets/sb2000/lib/sb2000.lib +0 -0
  32. package/targets/sb2000/target.json +1 -1
  33. package/src/emulator/debug-client.mjs +0 -125
@@ -49,4 +49,4 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
49
49
 
50
50
  ## 6. 运行
51
51
 
52
- `npx fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。
52
+ `npx fcdev run` 启动 Ember 直接加载 `.nes`,不需要固件;`--debug` 启动调试模式,程序载入后停在开机状态,继续用 `npx fcdev debug`,见 [05-模拟器与调试](../05-模拟器与调试.md)。验证记录见 [08-测试与验证](../08-测试与验证.md):NES 程序在 Ember 的调试模式里运行 60 帧并截图。
@@ -127,10 +127,10 @@ int main(void)
127
127
  ```bash
128
128
  npx fcdev build src # 生成 build/sb2000/<NAME>.EXE
129
129
  npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
130
- npx fcdev run src # 构建,挂载镜像,在模拟器里运行
130
+ npx fcdev run src # 构建后在 Ember 里运行(需要 firmware);加 --debug 停在开机状态
131
131
  ```
132
132
 
133
- `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,缺少时报错并提示怎么配置,不启动模拟器。运行流程见 [05-模拟器与调试](../05-模拟器与调试.md)。
133
+ `npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件(仓库里有一份:`reference/rom/SB2K_BIOS.NES`),没有设置时在构建之前报错。它把程序做成磁盘镜像挂到软驱,开机后自动在 SB-DOS 里跳过日期与时间、输入程序名运行(程序名只能用字母与数字);`--debug` 停在开机状态,由自己用 `fcdev debug` 操作,细节见 [05-模拟器与调试](../05-模拟器与调试.md) 第 3 节与第 7 节。本文下面写到的调试操作用 Ember 调试服务的请求表示。
134
134
 
135
135
  ## 6. 头文件与函数
136
136
 
@@ -228,11 +228,11 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
228
228
  | `copy` | 复制文件(文件不超过 64K) | `cp 源 目标` |
229
229
  | `peek` | 按十六进制偏移读文件 30 字节 | `peek 文件名 偏移` |
230
230
  | `poke` | 按十六进制偏移把文字写进已有文件(最长 60 个字符,大写) | `poke 文件名 偏移 文字` |
231
- | `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试命令 `pad 0 掩码` 按键) |
232
- | `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试命令 `mouse move dx dy` 移动) |
231
+ | `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试请求 `input.pad port=0 buttons=掩码` 按键) |
232
+ | `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试请求 `input.mouse kind=move dx=横向 dy=纵向` 移动) |
233
233
  | `play` | 把 NES 游戏装入并运行(mapper 0 与 4,PRG、CHR 各不超过 128K) | `play 文件名.nes`(放进软盘镜像的文件名要符合 8.3) |
234
234
  | `newcall` | 调用 BIOS 里新增的系统调用 $35,显示扩展版本号;原始 BIOS 不支持时显示 NOT SUPPORTED(演示给自己修改的 BIOS 做功能检测) | `newcall` |
235
- | `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试命令 `write cpu` 写请求块,格式见源码文件头) |
235
+ | `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试请求 `inspector.writeMemory space=cpu address=0x7E00 bytes=[...]` 写请求块,格式见源码文件头) |
236
236
 
237
237
  ## 11. 限制与没做过的事
238
238
 
@@ -252,8 +252,8 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
252
252
 
253
253
  ## 12. 运行库的测试
254
254
 
255
- 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。需要环境变量 `FCDEV_TEST_FIRMWARE` 指向 BIOS,没有时整组跳过。
255
+ 运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。测试经 Ember 的调试服务运行:`sb2000-runner.mjs` 随机取空闲端口启动 Ember,依次添加 BIOS(环境变量 `FCDEV_TEST_FIRMWARE`,没有时用仓库里的 `reference/rom/SB2K_BIOS.NES`)、开机、放入镜像,运行到 SB-DOS 询问日期,回车跳过后输入程序名;按键用 `input.key`,手柄与鼠标用 `input.pad`、`input.mouse`,读内存用 `inspector.readMemory`,存回镜像用 `media.floppySave`,截图用 `output.screenshot`,结束时只结束自己启动的 Ember。需要 Ember(环境变量 `FCDEV_EMULATOR`)、cc65 与已构建的调试 SDK,缺一整组跳过。
256
256
 
257
- 停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`bp w`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
257
+ 停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`inspector.addBreakpoint kind=write`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
258
258
 
259
259
  接口检查与参考文档的测试在 `test/sb2000-api.test.mjs`,`fcdev api` 命令的测试在 `packages/fcdev/test/api-command.test.mjs`。
@@ -24,7 +24,10 @@
24
24
 
25
25
  | 事项 | 说明 |
26
26
  | --- | --- |
27
- | 内核集成进 VS Code 面板 | 只要调试服务协议不变,`fcdev` 不用改 |
27
+ | 内核集成进 VS Code 面板 | 只要 Ember 的调试服务协议不变,`fcdev` 不用改 |
28
+ | 学习机 hello 的屏幕文字核对 | `fcdev run` 已能在 Ember 里运行学习机程序,运行库测试也已恢复;还没有把 C、汇编 hello 运行后的屏幕文字核对做成自动测试用例 |
29
+ | 已有 Ember 时 `fcdev run` 载入不进程序 | Ember 单实例,第二个进程只把已有窗口提到前面,不处理 `--cartridge`;需要 Ember 的 `second-instance` 处理它,或 `fcdev` 改用已开启的调试服务载入 |
30
+ | 存档(`savestate`、`loadstate`) | 旧模拟器有、Ember 没有,已登记在 Ember 的待办里,做完后通过 `fcdev debug call` 直接可用 |
28
31
  | 外设读数与真机对齐 | `hwtest` 在真机与模拟器上仍有差异的读数(`$4015` 位 4、`$4022` 开机值、`$4026`、`$4016`、`$4017`、`$4033` 位 6、`$3FFF`),具体数值见 [03-硬件说明](sb2000/03-硬件说明.md) 的“真机与模拟器仍有差异的行为”;程序不应依赖这些值,是否对齐由用户决定。|
29
32
  | `runnes` 与 `play` 的 DMA 写法 | 两个程序借用程序窗口 2(`$A000`)做 DMA 目的,真机上失败,模拟器对齐真机后也失败(`runnes` 现在用库函数 `sb_dma_to_cpu`,目的在窗口时函数直接返回出错、不复制);改成先 DMA 到 ERAM 缓冲再用 CPU 搬(参考 `apps/sb2000/bbk-loader`) |
30
33
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fcdev",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
5
5
  "license": "Apache-2.0",
6
6
  "author": "sungbin <sungbin@3578.cn>",
@@ -30,7 +30,10 @@
30
30
  "src",
31
31
  "targets"
32
32
  ],
33
+ "dependencies": {
34
+ "ember-debug-sdk": "0.7.0"
35
+ },
33
36
  "optionalDependencies": {
34
- "fcdev-cc65": "0.6.0"
37
+ "fcdev-cc65": "0.7.0"
35
38
  }
36
39
  }
@@ -4,7 +4,7 @@
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:debug 命令把命令名之后的全部参数原样交给调试服务,不再解析选项。
7
+ // 备注:debug 命令把命令名之后的全部参数原样交给 ember-debug,不再解析选项。
8
8
  // ------------------------------------------------------------------------
9
9
  import { FcdevError } from '../shared/index.mjs';
10
10
 
@@ -1,73 +1,35 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:debug-command.mjs
3
- // 说明:debug 命令:把命令原样转发给模拟器的调试服务并打印应答。
3
+ // 说明:debug 命令:把参数原样交给调试 SDK 的终端客户端 ember-debug,由它连接 Ember 的调试服务。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:模拟器的工作目录与终端不同,命令里的相对路径(shot、disk、trace、tape 等)先换成绝对路径;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699。
7
+ // 备注:fcdev 不解析调试命令;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699,找到 run --debug 启动的 Ember;
8
+ // ember-debug 的退出码原样作为 fcdev 的退出码,输出边读边转,watch 这类长时间运行的命令也能看到实时结果。
8
9
  // ------------------------------------------------------------------------
9
- import path from 'node:path';
10
- import { DEFAULT_DEBUG_PORT, DebugClient } from '../../emulator/index.mjs';
10
+ import { spawn } from 'node:child_process';
11
+ import { debugEnvironment, resolveDebugCli } from '../../emulator/index.mjs';
11
12
  import { FcdevError } from '../../shared/index.mjs';
12
13
 
13
- /** 耗时长的命令使用的应答超时,单位毫秒 */
14
- const LONG_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
15
-
16
- /** 耗时长的命令 */
17
- const LONG_COMMANDS = new Set(['run', 'step']);
18
-
19
- /** 命令里路径参数的位置(命令名之后的第几个词,从 1 起);disk 的路径可含空格,取剩余全部 */
20
- const PATH_POSITIONS = {
21
- shot: 1,
22
- disk: 1,
23
- trace: 1,
24
- io: 1,
25
- disklog: 1,
26
- calllog: 1,
27
- savestate: 1,
28
- loadstate: 1,
29
- };
30
-
31
- /**
32
- * 把命令里的相对路径换成绝对路径。
33
- * @param {string[]} tokens 命令的各个词
34
- * @param {string} cwd 终端当前目录
35
- * @returns {string[]} 处理后的词
36
- */
37
- export function resolveCommandPaths(tokens, cwd) {
38
- const [name, ...rest] = tokens;
39
- if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
40
- return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
41
- }
42
- if (name === 'tape' && (rest[0] === 'play' || rest[0] === 'rec') && rest[1]) {
43
- return [name, rest[0], path.resolve(cwd, rest.slice(1).join(' '))];
44
- }
45
- const position = PATH_POSITIONS[name];
46
- if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
47
- if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
48
- const resolved = [...rest];
49
- resolved[position - 1] = path.resolve(cwd, rest[position - 1]);
50
- return [name, ...resolved];
51
- }
52
-
53
14
  /**
54
15
  * 执行 debug 命令。
55
- * @param {{positionals: string[], context: import('../index.mjs').CliContext}} input 调试命令的各个词与运行环境
56
- * @returns {Promise<number>} 应答为 OK 时 0,否则 1
57
- * @throws {FcdevError} 没有给命令,或无法连接调试服务
16
+ * @param {{positionals: string[], context: import('../index.mjs').CliContext}} input ember-debug 的各个参数与运行环境
17
+ * @returns {Promise<number>} ember-debug 的退出码
18
+ * @throws {FcdevError} 没有给命令,或终端客户端不可用
58
19
  */
59
20
  export async function runDebugCommand({ positionals, context }) {
60
21
  if (positionals.length === 0) {
61
- throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug status、npx fcdev debug run 60、npx fcdev debug shot out.png' });
62
- }
63
- const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
64
- const tokens = resolveCommandPaths(positionals, context.cwd);
65
- const client = await DebugClient.connect({ port });
66
- try {
67
- const reply = await client.send(tokens.join(' '), { timeoutMs: LONG_COMMANDS.has(tokens[0]) ? LONG_COMMAND_TIMEOUT_MS : undefined });
68
- context.stdout.write(`${[reply.head, ...reply.lines].join('\n')}\n`);
69
- return reply.ok ? 0 : 1;
70
- } finally {
71
- client.close();
22
+ throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug call runtime.status、npx fcdev debug screenshot out.png;npx fcdev debug --help 查看全部命令' });
72
23
  }
24
+ const cli = resolveDebugCli();
25
+ const env = debugEnvironment(context.env);
26
+ return new Promise((resolve, reject) => {
27
+ const child = spawn(process.execPath, [cli, ...positionals], { cwd: context.cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
28
+ child.stdout.setEncoding('utf8');
29
+ child.stderr.setEncoding('utf8');
30
+ child.stdout.on('data', (chunk) => context.stdout.write(chunk));
31
+ child.stderr.on('data', (chunk) => context.stderr.write(chunk));
32
+ child.once('error', (error) => reject(new FcdevError('无法运行调试 SDK 的终端客户端', { code: 'DEBUG_CLI_START_FAILED', cause: error })));
33
+ child.once('close', (code) => resolve(code ?? 1));
34
+ });
73
35
  }
@@ -1,14 +1,14 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:run-command.mjs
3
- // 说明:run 命令:构建程序后在模拟器里运行;--debug 时启动调试模式,由 debug 命令继续操作。
3
+ // 说明:run 命令:构建程序后在 Ember 里运行;--debug 时启动调试模式,由 debug 命令继续操作。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk 加载固件(fcdev.json 的 firmware),挂载磁盘镜像后复位。
8
- // firmware-disk 方案需要调试服务挂载镜像,挂载完成后用 live 命令转为自由运行(加 --debug 则保持调试模式)。
7
+ // 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk(学习机)加载 fcdev.json 的 firmware 指定的固件,
8
+ // 把程序放进磁盘镜像挂到软驱并开机,自由模式再在 SB-DOS 里输入程序名运行,调试模式停在开机状态。
9
9
  // ------------------------------------------------------------------------
10
10
  import path from 'node:path';
11
- import { buildDiskImage, buildPath } from '../../build/index.mjs';
11
+ import { buildDiskImage, buildPath, createBuildPlan } from '../../build/index.mjs';
12
12
  import { DEFAULT_DEBUG_PORT, launchEmulator, locateEmulator } from '../../emulator/index.mjs';
13
13
  import { FcdevError } from '../../shared/index.mjs';
14
14
 
@@ -16,53 +16,50 @@ import { FcdevError } from '../../shared/index.mjs';
16
16
  * 执行 run 命令。
17
17
  * @param {{positionals: string[], options: {target?: string, debug: boolean, port?: number}, context: import('../index.mjs').CliContext}} input 参数与运行环境
18
18
  * @returns {Promise<number>} 退出码
19
- * @throws {FcdevError} 目标没有运行方案、找不到模拟器或构建失败
19
+ * @throws {FcdevError} 目标没有运行方案、学习机没有配置固件、找不到 Ember 或构建失败
20
20
  */
21
21
  export async function runRunCommand({ positionals, options, context }) {
22
22
  if (positionals.length > 1) {
23
23
  throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev run [目录或文件]' });
24
24
  }
25
+ const input = { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env };
26
+ const { target, config } = createBuildPlan(input);
27
+ if (!target.run) {
28
+ throw new FcdevError(`目标 ${target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
29
+ }
30
+ const withFirmware = target.run.mode === 'firmware-disk';
31
+ if (withFirmware && !config.firmware) {
32
+ throw new FcdevError(`${target.name} 目标运行需要固件,fcdev.json 里没有设置 firmware`, {
33
+ code: 'FIRMWARE_MISSING',
34
+ hint: '在 fcdev.json 里用 firmware 指向学习机的 BIOS 文件(iNES 格式),例如 "firmware": "SB2K_BIOS.NES"',
35
+ });
36
+ }
37
+ const emulator = locateEmulator({ configured: config.emulator, env: context.env });
38
+ const port = options.port ?? DEFAULT_DEBUG_PORT;
39
+
25
40
  const reporter = {
26
41
  log: (message) => context.stdout.write(`${message}\n`),
27
42
  write: (text) => context.stderr.write(text),
28
43
  };
29
- const { plan, result } = await buildPath(
30
- { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env },
31
- reporter,
32
- );
33
- const run = plan.target.run;
34
- if (!run) {
35
- throw new FcdevError(`目标 ${plan.target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
36
- }
37
- const emulator = locateEmulator({ configured: plan.config.emulator, env: context.env });
38
- const port = options.port ?? DEFAULT_DEBUG_PORT;
39
-
40
- if (run.mode === 'rom') {
41
- const { pid, client } = await launchEmulator({ executable: emulator.executable, romFile: result.outputFile, debug: options.debug, port });
42
- client?.close();
43
- context.stdout.write(`已启动模拟器(进程 ${pid}),加载 ${result.outputFile}\n`);
44
- } else {
45
- if (!plan.config.firmware) {
46
- throw new FcdevError(`目标 ${plan.target.name} 的运行需要固件(BIOS)`, {
47
- code: 'FIRMWARE_MISSING',
48
- hint: '在 fcdev.json 里用 firmware 指定固件文件;fcdev 不提供任何 BIOS 或 ROM',
49
- });
50
- }
44
+ const { plan, result } = await buildPath(input, reporter);
45
+ let launch;
46
+ let description;
47
+ if (withFirmware) {
51
48
  const { imageFile } = buildDiskImage(plan, result);
52
- const { pid, client } = await launchEmulator({ executable: emulator.executable, romFile: plan.config.firmware, debug: true, port });
53
- try {
54
- for (const command of [`disk ${imageFile}`, 'reset', ...(options.debug ? [] : ['live'])]) {
55
- const reply = await client.send(command);
56
- if (!reply.ok) throw new FcdevError(`模拟器拒绝命令“${command}”:${reply.head}`, { code: 'EMULATOR_COMMAND_FAILED' });
57
- }
58
- } finally {
59
- client.close();
60
- }
61
- context.stdout.write(`已启动模拟器(进程 ${pid}),固件 ${plan.config.firmware},磁盘镜像 ${imageFile}\n`);
62
- context.stdout.write(`等 DOS 启动后,在提示符下输入 ${path.basename(result.outputFile, path.extname(result.outputFile))} 运行程序\n`);
49
+ const programName = path.basename(result.outputFile, path.extname(result.outputFile));
50
+ launch = { sb2000: { firmware: config.firmware, diskImage: imageFile, programName } };
51
+ description = `磁盘镜像 ${imageFile}(程序 ${programName})`;
52
+ } else {
53
+ launch = { romFile: result.outputFile };
54
+ description = result.outputFile;
63
55
  }
56
+ const { pid, client } = await launchEmulator({ executable: emulator.executable, ...launch, debug: options.debug, port });
57
+ client?.close();
58
+ context.stdout.write(`已启动 Ember(进程 ${pid}),加载 ${description}\n`);
64
59
  if (options.debug) {
65
- context.stdout.write(`调试模式:端口 ${port},模拟器只在收到 run 命令时运行,例如 npx fcdev debug run 60\n`);
60
+ context.stdout.write(withFirmware
61
+ ? `调试模式:端口 ${port},固件已加载、磁盘已放入软驱、整机已开机,但没有运行;程序要在 SB-DOS 里输入程序名才会运行,继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`
62
+ : `调试模式:端口 ${port},程序已载入并上电,但没有运行;继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`);
66
63
  }
67
64
  return 0;
68
65
  }
package/src/cli/index.mjs CHANGED
@@ -47,10 +47,10 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
47
47
 
48
48
  命令:
49
49
  build [目录或文件] 构建:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序
50
- run [目录或文件] 构建后在模拟器里运行(--debug 启动调试模式)
50
+ run [目录或文件] 构建后在 Ember 里运行(--debug 启动调试模式)
51
51
  disk [目录或文件] 构建后把程序放进磁盘镜像(只有支持磁盘的目标可用)
52
52
  disasm <文件> 反汇编 NES 程序或平铺二进制为 ca65 源码,并回读校验
53
- debug <命令> 把命令转发给模拟器的调试服务,如 debug run 60、debug shot out.png
53
+ debug <参数> 交给 Ember 调试 SDK 的终端客户端 ember-debug,如 debug call runtime.status、debug screenshot out.png
54
54
  sync 生成 IDE 的 C/C++ 配置
55
55
  info [--json] 显示目标、工具链与头文件目录
56
56
  api [词] [--json] 查询目标的 C 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
@@ -58,7 +58,7 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
58
58
 
59
59
  选项:
60
60
  --target <名> 指定目标,覆盖 fcdev.json
61
- --debug run 以调试模式启动模拟器
61
+ --debug run 以调试模式启动 Ember
62
62
  --port <端口> run 的调试端口,默认 5699;debug 命令读环境变量 FCDEV_DEBUG_PORT,默认也是 5699
63
63
  --json info 输出机器可读格式
64
64
 
@@ -67,7 +67,7 @@ disasm 的选项:
67
67
  --base <地址> 平铺二进制的加载地址(十六进制)
68
68
  --entry <地址> 追踪代码的入口,可重复;iNES 会自动使用中断向量
69
69
  --cdl <文件> CDL(FCEUX、Mesen 格式),代码段的起点也当作入口
70
- --trace <文件> 模拟器 trace 命令记录的指令轨迹,执行过的指令地址都当作入口
70
+ --trace <文件> Ember 的 inspector.traceStart(instruction)记录的指令轨迹,执行过的指令地址都当作入口
71
71
  --symbols <文件> 符号文件,每行“名字 = $地址”
72
72
  --out <目录> 输出目录,默认 build/disasm/<文件名>
73
73
  -h, --help 显示帮助
@@ -39,7 +39,7 @@ const KEY_TYPES = {
39
39
  * @property {string[]} include 额外头文件目录的绝对路径
40
40
  * @property {string|undefined} toolchain 自备 cc65 根目录的绝对路径
41
41
  * @property {string|undefined} firmware 固件文件的绝对路径
42
- * @property {string|undefined} emulator 自备模拟器路径
42
+ * @property {string|undefined} emulator Ember 可执行文件的路径
43
43
  * @property {Record<string, unknown>} targetOptions 目标专用选项
44
44
  */
45
45
 
@@ -47,7 +47,7 @@ function detectFormat(buffer, format) {
47
47
 
48
48
  /**
49
49
  * 反汇编一个文件,并回读校验。
50
- * @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL、模拟器轨迹、符号文件、输出目录、工具链与 da65 要读的符号定义文件
50
+ * @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL、Ember 轨迹、符号文件、输出目录、工具链与 da65 要读的符号定义文件
51
51
  * @returns {Promise<DisassemblyReport>} 报告
52
52
  * @throws {FcdevError} 输入不合法、da65 失败,或回读校验不一致
53
53
  */
@@ -1,14 +1,15 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:trace.mjs
3
- // 说明:读取模拟器 trace 命令记录的指令轨迹:每行以 T 开头,第二列是执行到的指令地址。
3
+ // 说明:读取 Ember 的 inspector.traceStart(kind 为 instruction)记录的指令轨迹:每行是 nestest 日志的写法,行首是四位十六进制的指令地址。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
7
  // 备注:轨迹里的每个地址都是被真实执行过的指令开头,比 CDL 的“代码字节”更精确;用作追踪代码的入口。
8
+ // io、irq 与调用记录的行不是指令行,一律忽略;只认 Ember 的格式,不兼容旧模拟器的 T 行。
8
9
  // ------------------------------------------------------------------------
9
10
 
10
- /** 轨迹的一行:T、四位十六进制的指令地址,后面是物理地址、字节、寄存器 */
11
- const TRACE_LINE = /^T ([0-9A-Fa-f]{4}) /;
11
+ /** 指令行:四位十六进制的地址、两个空格,后面是至少一个两位十六进制的字节(调用记录的“8123 A:01”不符合) */
12
+ const TRACE_LINE = /^([0-9A-F]{4}) {2}[0-9A-F]{2}(?: |$)/;
12
13
 
13
14
  /**
14
15
  * 取出轨迹里被执行过的指令地址。
@@ -1,38 +1,38 @@
1
- // ------------------------------------------------------------------------
2
- // 名称:doc-topics.mjs
3
- // 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
4
- // 作者:sungbin
5
- // 邮箱:sungbin@3578.cn
6
- // 日期:2026-11-11
7
- // 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
8
- // ------------------------------------------------------------------------
9
-
10
- /**
11
- * @typedef {object} DocTopic
12
- * @property {string} topic 主题名
13
- * @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
14
- * @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
15
- * @property {string} title 标题
16
- * @property {string} summary 一句话说明
17
- */
18
-
19
- /** @type {DocTopic[]} */
20
- export const DOC_TOPICS = [
21
- { topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
22
- { topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
23
- { topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
24
- { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
25
- { topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、模拟器定位、调试服务与命令表' },
26
- { topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
27
- { topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
28
- { topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
29
- { topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
30
- { topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
31
- { topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
32
- { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
33
- { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
34
- { topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
35
- { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
36
- { topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
37
- { topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
38
- ];
1
+ // ------------------------------------------------------------------------
2
+ // 名称:doc-topics.mjs
3
+ // 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-11
7
+ // 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /**
11
+ * @typedef {object} DocTopic
12
+ * @property {string} topic 主题名
13
+ * @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
14
+ * @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
15
+ * @property {string} title 标题
16
+ * @property {string} summary 一句话说明
17
+ */
18
+
19
+ /** @type {DocTopic[]} */
20
+ export const DOC_TOPICS = [
21
+ { topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
22
+ { topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
23
+ { topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
24
+ { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
25
+ { topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、Ember 定位、调试服务与 debug 命令' },
26
+ { topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
27
+ { topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
28
+ { topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
29
+ { topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
30
+ { topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
31
+ { topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
32
+ { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
33
+ { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
34
+ { topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
35
+ { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
36
+ { topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
37
+ { topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
38
+ ];
@@ -0,0 +1,48 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:debug-cli.mjs
3
+ // 说明:debug 命令的底层:找到调试 SDK 随包提供的终端客户端 ember-debug,并决定它找 Ember 调试服务的环境变量。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-15
7
+ // 备注:fcdev 自己不实现任何调试命令,全部交给 ember-debug;没有显式指定地址、令牌、端点文件或用户数据目录时,
8
+ // 按调试端口(环境变量 FCDEV_DEBUG_PORT,默认 5699)找到 fcdev 用 run --debug 启动的那个 Ember。
9
+ // ------------------------------------------------------------------------
10
+ import { existsSync } from 'node:fs';
11
+ import { fileURLToPath } from 'node:url';
12
+ import { FcdevError } from '../shared/index.mjs';
13
+ import { DEFAULT_DEBUG_PORT, debugUserDataDirectory } from './emulator-launcher.mjs';
14
+
15
+ /** 用户显式指定调试服务位置的环境变量,设置了任何一个就不再按端口推算 */
16
+ const EXPLICIT_ENV_NAMES = ['EMBER_DEBUG_URL', 'EMBER_DEBUG_TOKEN', 'EMBER_DEBUG_ENDPOINT', 'EMBER_USER_DATA'];
17
+
18
+ /**
19
+ * 调试 SDK 的终端客户端(ember-debug)的入口文件。
20
+ * @returns {string} 入口文件的绝对路径
21
+ * @throws {FcdevError} SDK 没有安装或没有构建
22
+ */
23
+ export function resolveDebugCli() {
24
+ let file = null;
25
+ try {
26
+ file = fileURLToPath(new URL('./cli.js', import.meta.resolve('ember-debug-sdk')));
27
+ } catch {
28
+ // 下面统一报错
29
+ }
30
+ if (file === null || !existsSync(file)) {
31
+ throw new FcdevError('找不到调试 SDK(ember-debug-sdk)的终端客户端', {
32
+ code: 'DEBUG_SDK_MISSING',
33
+ hint: '在本仓库里先运行 npm run build -w packages/ember-debug-sdk;用 npm 安装的 fcdev 会自带',
34
+ });
35
+ }
36
+ return file;
37
+ }
38
+
39
+ /**
40
+ * 运行终端客户端时用的环境变量。
41
+ * @param {NodeJS.ProcessEnv} env 当前环境变量
42
+ * @returns {NodeJS.ProcessEnv} 新的环境变量;没有显式指定位置时加上 fcdev 启动的 Ember 的用户数据目录
43
+ */
44
+ export function debugEnvironment(env) {
45
+ if (EXPLICIT_ENV_NAMES.some((name) => env[name])) return env;
46
+ const port = Number(env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
47
+ return { ...env, EMBER_USER_DATA: debugUserDataDirectory(port) };
48
+ }