fcdev 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +61 -32
- package/README.md +17 -16
- package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +14 -12
- package/docs/02-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +89 -0
- package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +13 -47
- package/docs/{07- → 04-}/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +1 -15
- package/docs/nes/{01-NES/347/233/256/346/240/207.md → 01-/345/274/200/345/217/221/346/214/207/345/215/227.md} +4 -9
- package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +25 -30
- package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +4 -4
- package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +5 -5
- package/package.json +5 -2
- package/src/build/bank-link-config.mjs +1 -1
- package/src/build/build-plan.mjs +1 -1
- package/src/build/program-builder.mjs +10 -5
- package/src/build/source-charset.mjs +111 -0
- package/src/cli/args-parser.mjs +1 -1
- package/src/cli/commands/debug-command.mjs +20 -58
- package/src/cli/commands/docs-command.mjs +2 -2
- package/src/cli/commands/run-command.mjs +36 -39
- package/src/cli/index.mjs +5 -5
- package/src/config/config-loader.mjs +2 -2
- package/src/disasm/disassembler.mjs +1 -1
- package/src/disasm/trace.mjs +4 -3
- package/src/docs/doc-index.mjs +1 -1
- package/src/docs/doc-topics.mjs +32 -38
- package/src/docs/index.mjs +1 -1
- package/src/emulator/debug-cli.mjs +48 -0
- package/src/emulator/emulator-launcher.mjs +107 -29
- package/src/emulator/emulator-locator.mjs +7 -7
- package/src/emulator/index.mjs +4 -3
- package/src/emulator/sb2000-session.mjs +104 -0
- package/src/targets/target-registry.mjs +9 -1
- package/targets/nes/lib/fcnes.lib +0 -0
- package/targets/nes/lib/nes-font.o +0 -0
- package/targets/nes/target.json +1 -1
- package/targets/sb2000/api-reference.md +2 -1
- package/targets/sb2000/examples-source.md +1330 -0
- package/targets/sb2000/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
- package/targets/sb2000/symbols-reference.md +670 -0
- package/targets/sb2000/target.json +2 -1
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -163
- package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
- package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
- package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +0 -92
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -72
- package/docs/09-/345/217/221/345/270/203.md +0 -70
- package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
- package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -47
- package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
- package/src/emulator/debug-client.mjs +0 -125
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:run-command.mjs
|
|
3
|
-
// 说明:run
|
|
3
|
+
// 说明:run 命令:构建程序后在 Ember 里运行;--debug 时启动调试模式,由 debug 命令继续操作。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
// 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk
|
|
8
|
-
//
|
|
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
|
-
|
|
31
|
-
|
|
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
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
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(
|
|
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,18 +47,18 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
|
|
|
47
47
|
|
|
48
48
|
命令:
|
|
49
49
|
build [目录或文件] 构建:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序
|
|
50
|
-
run [目录或文件]
|
|
50
|
+
run [目录或文件] 构建后在 Ember 里运行(--debug 启动调试模式)
|
|
51
51
|
disk [目录或文件] 构建后把程序放进磁盘镜像(只有支持磁盘的目标可用)
|
|
52
52
|
disasm <文件> 反汇编 NES 程序或平铺二进制为 ca65 源码,并回读校验
|
|
53
|
-
debug
|
|
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 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
|
|
57
|
-
docs [词] [--json]
|
|
57
|
+
docs [词] [--json] 查询使用文档:主题名或关键词,给出本机路径;不带词列出全部主题
|
|
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 <文件>
|
|
70
|
+
--trace <文件> Ember 的 inspector.traceStart(instruction)记录的指令轨迹,执行过的指令地址都当作入口
|
|
71
71
|
--symbols <文件> 符号文件,每行“名字 = $地址”
|
|
72
72
|
--out <目录> 输出目录,默认 build/disasm/<文件名>
|
|
73
73
|
-h, --help 显示帮助
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
// 备注:未知的键直接报错,避免拼写错误被忽略;配置项含义见 docs/
|
|
7
|
+
// 备注:未知的键直接报错,避免拼写错误被忽略;配置项含义见 packages/fcdev/docs/01-命令行与构建.md 第 3 节。
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
import { existsSync } from 'node:fs';
|
|
10
10
|
import path from 'node:path';
|
|
@@ -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
|
|
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
|
*/
|
package/src/disasm/trace.mjs
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:trace.mjs
|
|
3
|
-
//
|
|
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
|
-
/**
|
|
11
|
-
const TRACE_LINE = /^
|
|
11
|
+
/** 指令行:四位十六进制的地址、两个空格,后面是至少一个两位十六进制的字节(调用记录的“8123 A:01”不符合) */
|
|
12
|
+
const TRACE_LINE = /^([0-9A-F]{4}) {2}[0-9A-F]{2}(?: |$)/;
|
|
12
13
|
|
|
13
14
|
/**
|
|
14
15
|
* 取出轨迹里被执行过的指令地址。
|
package/src/docs/doc-index.mjs
CHANGED
package/src/docs/doc-topics.mjs
CHANGED
|
@@ -1,38 +1,32 @@
|
|
|
1
|
-
// ------------------------------------------------------------------------
|
|
2
|
-
// 名称:doc-topics.mjs
|
|
3
|
-
//
|
|
4
|
-
// 作者:sungbin
|
|
5
|
-
// 邮箱:sungbin@3578.cn
|
|
6
|
-
// 日期:2026-11-11
|
|
7
|
-
//
|
|
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: '
|
|
22
|
-
{ topic: '
|
|
23
|
-
{ topic: '
|
|
24
|
-
{ topic: '
|
|
25
|
-
{ topic: '
|
|
26
|
-
{ topic: '
|
|
27
|
-
{ topic: '
|
|
28
|
-
{ topic: '
|
|
29
|
-
{ topic: '
|
|
30
|
-
{ topic: '
|
|
31
|
-
{ topic: '
|
|
32
|
-
|
|
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: 'build', file: '01-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
|
|
22
|
+
{ topic: 'emulator', file: '02-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、Ember 定位、调试服务与 debug 命令' },
|
|
23
|
+
{ topic: 'disasm', file: '03-反汇编.md', title: '反汇编', summary: '反汇编的命令、输入、追踪规则与限制' },
|
|
24
|
+
{ topic: 'create', file: '04-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
|
|
25
|
+
{ topic: 'nes', file: 'nes/01-开发指南.md', title: 'NES 开发指南', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
|
|
26
|
+
{ topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
|
|
27
|
+
{ topic: 'examples', file: 'targets/sb2000/examples-source.md', inPackage: true, title: 'SB2000 示例程序源码', summary: '手册里提到的示例程序(hello、show、copy、pad、mouse、play 等)的完整源码,由示例项目生成' },
|
|
28
|
+
{ topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
|
|
29
|
+
{ topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
|
|
30
|
+
{ topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
|
|
31
|
+
{ topic: 'symbols', file: 'targets/sb2000/symbols-reference.md', inPackage: true, title: 'SB2000 符号参考', summary: '功能号、子功能号、系统变量地址、出错码、硬件寄存器与位、运行库入口的汇编名与 C 名,由 sb2000.inc 生成' },
|
|
32
|
+
];
|
package/src/docs/index.mjs
CHANGED
|
@@ -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
|
+
}
|
|
@@ -1,18 +1,26 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:emulator-launcher.mjs
|
|
3
|
-
//
|
|
3
|
+
// 说明:启动 Ember:自由运行模式直接打开窗口加载程序;调试模式用独立的用户数据目录与调试端口启动,连上调试服务后载入程序并停在开机状态。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
//
|
|
7
|
+
// 备注:Ember 进程与命令行脱离,命令行退出后窗口保持打开;调试模式不带 --cartridge,等连上调试服务后用 cartridges.load 载入并只上电不运行,由 debug 命令继续。
|
|
8
|
+
// 学习机(sb2000 参数)没有命令行入口,两种模式都经调试服务:添加固件、放入磁盘镜像、整机开机;自由模式再在 SB-DOS 里输入程序名并继续运行后断开,
|
|
9
|
+
// 调试模式停在开机状态(磁盘里的程序还没有被运行,由 debug 命令操作)。
|
|
10
|
+
// 调试服务的 SDK(ember-debug-sdk)只在需要连接时才加载,没有构建时只影响调试模式与学习机。
|
|
8
11
|
// ------------------------------------------------------------------------
|
|
9
12
|
import { spawn } from 'node:child_process';
|
|
10
|
-
import {
|
|
13
|
+
import { randomBytes } from 'node:crypto';
|
|
14
|
+
import { existsSync, mkdirSync, rmSync } from 'node:fs';
|
|
11
15
|
import net from 'node:net';
|
|
16
|
+
import { tmpdir } from 'node:os';
|
|
12
17
|
import path from 'node:path';
|
|
13
18
|
import { setTimeout as delay } from 'node:timers/promises';
|
|
14
19
|
import { FcdevError } from '../shared/index.mjs';
|
|
15
|
-
import {
|
|
20
|
+
import { bootSb2000, enterProgram } from './sb2000-session.mjs';
|
|
21
|
+
|
|
22
|
+
/** fcdev 的调试服务默认端口 */
|
|
23
|
+
export const DEFAULT_DEBUG_PORT = 5699;
|
|
16
24
|
|
|
17
25
|
/** 等待调试服务就绪的上限,单位毫秒 */
|
|
18
26
|
const READY_TIMEOUT_MS = 30_000;
|
|
@@ -20,8 +28,21 @@ const READY_TIMEOUT_MS = 30_000;
|
|
|
20
28
|
/** 轮询调试服务的间隔,单位毫秒 */
|
|
21
29
|
const READY_POLL_MS = 300;
|
|
22
30
|
|
|
31
|
+
/** 调试服务连接名,显示在 Ember 的连接列表里 */
|
|
32
|
+
const CLIENT_NAME = 'fcdev';
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* 调试模式下 Ember 使用的用户数据目录:每个端口一个,与用户平时使用的 Ember 互不影响(单实例锁与设置都按用户数据目录区分)。
|
|
36
|
+
* @param {number} port 调试端口
|
|
37
|
+
* @param {string} [base] 上级目录,默认是系统临时目录
|
|
38
|
+
* @returns {string} 目录
|
|
39
|
+
*/
|
|
40
|
+
export function debugUserDataDirectory(port, base = tmpdir()) {
|
|
41
|
+
return path.join(base, 'fcdev-ember', String(port));
|
|
42
|
+
}
|
|
43
|
+
|
|
23
44
|
/**
|
|
24
|
-
*
|
|
45
|
+
* 确认本机端口空闲。端口被占用时 Ember 的调试服务不会启动,客户端反而可能连到别的 Ember。
|
|
25
46
|
* @param {number} port 端口
|
|
26
47
|
* @returns {Promise<void>}
|
|
27
48
|
* @throws {FcdevError} 端口已被占用
|
|
@@ -31,7 +52,7 @@ export function assertPortFree(port) {
|
|
|
31
52
|
const server = net.createServer();
|
|
32
53
|
server.once('error', (error) => reject(new FcdevError(`端口 ${port} 已被占用`, {
|
|
33
54
|
code: 'EMULATOR_PORT_BUSY',
|
|
34
|
-
hint: '用 --port
|
|
55
|
+
hint: '用 --port 换一个端口,或关闭占用它的 Ember',
|
|
35
56
|
cause: error,
|
|
36
57
|
})));
|
|
37
58
|
server.listen(port, '127.0.0.1', () => server.close(() => resolve()));
|
|
@@ -39,42 +60,99 @@ export function assertPortFree(port) {
|
|
|
39
60
|
}
|
|
40
61
|
|
|
41
62
|
/**
|
|
42
|
-
*
|
|
43
|
-
* @
|
|
44
|
-
* @
|
|
45
|
-
* @throws {FcdevError} 文件不存在、无法启动,或调试服务没有在时限内就绪
|
|
63
|
+
* 加载调试 SDK 的 Node 入口。
|
|
64
|
+
* @returns {Promise<typeof import('ember-debug-sdk/node')>} SDK 的 Node 入口
|
|
65
|
+
* @throws {FcdevError} SDK 没有构建
|
|
46
66
|
*/
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
67
|
+
async function loadSdk() {
|
|
68
|
+
try {
|
|
69
|
+
return await import('ember-debug-sdk/node');
|
|
70
|
+
} catch (error) {
|
|
71
|
+
if (error?.code === 'ERR_MODULE_NOT_FOUND' || error?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
|
|
72
|
+
throw new FcdevError('找不到调试 SDK(ember-debug-sdk)的构建产物', {
|
|
73
|
+
code: 'DEBUG_SDK_MISSING',
|
|
74
|
+
hint: '在本仓库里先运行 npm run build -w packages/ember-debug-sdk;用 npm 安装的 fcdev 会自带',
|
|
75
|
+
cause: error,
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
throw error;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
53
81
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
82
|
+
/**
|
|
83
|
+
* 启动 Ember。
|
|
84
|
+
* @param {object} input 启动参数
|
|
85
|
+
* @param {string} input.executable Ember 程序
|
|
86
|
+
* @param {string} [input.romFile] 要加载的 .nes 文件(经典 FC);与 sb2000 二选一
|
|
87
|
+
* @param {{firmware: string, diskImage: string, programName?: string}} [input.sb2000] 学习机:固件(BIOS)、磁盘镜像,以及自由模式里要在 SB-DOS 运行的程序名
|
|
88
|
+
* @param {boolean} [input.debug] 是否调试模式
|
|
89
|
+
* @param {number} [input.port] 调试端口
|
|
90
|
+
* @param {number} [input.readyTimeoutMs] 等待调试服务就绪的上限
|
|
91
|
+
* @returns {Promise<{pid: number|undefined, client: import('ember-debug-sdk').EmberDebugClient|null}>} 进程号;调试模式下还有已连接的客户端,调用者负责关闭
|
|
92
|
+
* @throws {FcdevError} 文件不存在、无法启动、Ember 提前退出、拒绝载入,或调试服务没有在时限内就绪
|
|
93
|
+
*/
|
|
94
|
+
export async function launchEmulator({ executable, romFile, sb2000, debug = false, port = DEFAULT_DEBUG_PORT, readyTimeoutMs = READY_TIMEOUT_MS }) {
|
|
95
|
+
if (romFile !== undefined && !existsSync(romFile)) throw new FcdevError(`找不到要加载的文件:${romFile}`, { code: 'EMULATOR_FILE_MISSING' });
|
|
96
|
+
const cwd = path.dirname(executable);
|
|
97
|
+
|
|
98
|
+
if (!debug && sb2000 === undefined) {
|
|
99
|
+
const child = spawn(executable, [`--cartridge=${romFile}`], { cwd, stdio: 'ignore', detached: true });
|
|
100
|
+
const failure = new Promise((_, reject) => {
|
|
101
|
+
child.once('error', (error) => reject(new FcdevError(`无法启动 Ember ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
|
|
102
|
+
});
|
|
103
|
+
child.unref();
|
|
60
104
|
// 给启动失败留出报错的机会,再返回
|
|
61
105
|
await Promise.race([failure, delay(300)]);
|
|
62
106
|
return { pid: child.pid, client: null };
|
|
63
107
|
}
|
|
64
108
|
|
|
109
|
+
const { connectToEmber } = await loadSdk();
|
|
110
|
+
await assertPortFree(port);
|
|
111
|
+
const userDataDirectory = debugUserDataDirectory(port);
|
|
112
|
+
mkdirSync(userDataDirectory, { recursive: true });
|
|
113
|
+
// 上一次会话遗留的端点文件,不能让客户端读到
|
|
114
|
+
rmSync(path.join(userDataDirectory, 'run', 'debug-endpoint.json'), { force: true });
|
|
115
|
+
const token = randomBytes(16).toString('hex');
|
|
116
|
+
const child = spawn(executable, [`--user-data-dir=${userDataDirectory}`, `--debug-port=${port}`, `--debug-token=${token}`], { cwd, stdio: 'ignore', detached: true });
|
|
117
|
+
const failure = new Promise((_, reject) => {
|
|
118
|
+
child.once('error', (error) => reject(new FcdevError(`无法启动 Ember ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
|
|
119
|
+
child.once('exit', (code) => reject(new FcdevError(`Ember 启动后退出了(退出码 ${code})`, { code: 'EMULATOR_START_FAILED', hint: '检查可执行文件是否是 Ember,以及端口是否被占用' })));
|
|
120
|
+
});
|
|
121
|
+
// 启动成功之后 Ember 退出也会让 failure 失败,没有人等它时不能算未处理的拒绝
|
|
122
|
+
failure.catch(() => {});
|
|
123
|
+
child.unref();
|
|
124
|
+
|
|
65
125
|
const deadline = Date.now() + readyTimeoutMs;
|
|
66
126
|
while (Date.now() < deadline) {
|
|
67
127
|
try {
|
|
68
|
-
const client = await Promise.race([
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
128
|
+
const client = await Promise.race([connectToEmber({ userDataDirectory, clientName: CLIENT_NAME, connectTimeoutMs: 1000 }), failure]);
|
|
129
|
+
try {
|
|
130
|
+
if (sb2000 === undefined) {
|
|
131
|
+
await client.request('cartridges.load', { path: romFile, powerOn: true, resume: false });
|
|
132
|
+
} else {
|
|
133
|
+
await bootSb2000(client, sb2000);
|
|
134
|
+
if (!debug && sb2000.programName !== undefined) {
|
|
135
|
+
await enterProgram(client, sb2000.programName);
|
|
136
|
+
await client.request('runtime.resume', {});
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
} catch (error) {
|
|
140
|
+
client.close();
|
|
141
|
+
child.kill();
|
|
142
|
+
if (error instanceof FcdevError) throw error;
|
|
143
|
+
throw new FcdevError(`Ember 无法载入 ${romFile ?? sb2000.diskImage}:${error.message}`, { code: 'EMULATOR_LOAD_FAILED', cause: error });
|
|
144
|
+
}
|
|
145
|
+
if (!debug) {
|
|
146
|
+
client.close();
|
|
147
|
+
return { pid: child.pid, client: null };
|
|
148
|
+
}
|
|
149
|
+
return { pid: child.pid, client };
|
|
72
150
|
} catch (error) {
|
|
73
|
-
if (error
|
|
74
|
-
//
|
|
151
|
+
if (error instanceof FcdevError) throw error;
|
|
152
|
+
// 调试服务尚未就绪(端点文件还没写出、连接被拒绝),稍后重试
|
|
75
153
|
}
|
|
76
154
|
await delay(READY_POLL_MS);
|
|
77
155
|
}
|
|
78
156
|
child.kill();
|
|
79
|
-
throw new FcdevError(
|
|
157
|
+
throw new FcdevError(`等待 Ember 的调试服务(端口 ${port})就绪超时`, { code: 'EMULATOR_NOT_READY', hint: '检查端口是否被占用' });
|
|
80
158
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:emulator-locator.mjs
|
|
3
|
-
//
|
|
3
|
+
// 说明:定位 Ember(模拟器)的可执行文件:配置项、环境变量,按顺序查找,不去 PATH 里猜。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
@@ -10,25 +10,25 @@ import { existsSync } from 'node:fs';
|
|
|
10
10
|
import path from 'node:path';
|
|
11
11
|
import { FcdevError } from '../shared/index.mjs';
|
|
12
12
|
|
|
13
|
-
/**
|
|
13
|
+
/** 环境变量:Ember 可执行文件的路径 */
|
|
14
14
|
export const EMULATOR_ENV_NAME = 'FCDEV_EMULATOR';
|
|
15
15
|
|
|
16
16
|
/**
|
|
17
|
-
*
|
|
17
|
+
* 按顺序定位 Ember:配置项 emulator、环境变量。
|
|
18
18
|
* @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的绝对路径
|
|
19
|
-
* @returns {{executable: string, source: string}}
|
|
19
|
+
* @returns {{executable: string, source: string}} Ember 可执行文件与来源
|
|
20
20
|
* @throws {FcdevError} 都找不到
|
|
21
21
|
*/
|
|
22
22
|
export function locateEmulator({ configured, env = process.env } = {}) {
|
|
23
23
|
const explicit = configured ? { executable: configured, source: 'config' } : env[EMULATOR_ENV_NAME] ? { executable: path.resolve(env[EMULATOR_ENV_NAME]), source: 'env' } : null;
|
|
24
24
|
if (explicit) {
|
|
25
25
|
if (!existsSync(explicit.executable)) {
|
|
26
|
-
throw new FcdevError(
|
|
26
|
+
throw new FcdevError(`找不到 Ember:${explicit.executable}`, { code: 'EMULATOR_NOT_FOUND' });
|
|
27
27
|
}
|
|
28
28
|
return explicit;
|
|
29
29
|
}
|
|
30
|
-
throw new FcdevError('
|
|
30
|
+
throw new FcdevError('找不到 Ember', {
|
|
31
31
|
code: 'EMULATOR_NOT_FOUND',
|
|
32
|
-
hint: `任选一种:设置环境变量 ${EMULATOR_ENV_NAME}
|
|
32
|
+
hint: `任选一种:设置环境变量 ${EMULATOR_ENV_NAME} 指向 Ember 的可执行文件;在 fcdev.json 里用 emulator 指定`,
|
|
33
33
|
});
|
|
34
34
|
}
|
package/src/emulator/index.mjs
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:index.mjs
|
|
3
|
-
// 说明:emulator
|
|
3
|
+
// 说明:emulator 目录的对外入口:定位 Ember、启动 Ember、调试 SDK 终端客户端的定位。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
7
|
// 备注:无
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
|
-
export {
|
|
10
|
-
export { assertPortFree, launchEmulator } from './emulator-launcher.mjs';
|
|
9
|
+
export { debugEnvironment, resolveDebugCli } from './debug-cli.mjs';
|
|
10
|
+
export { DEFAULT_DEBUG_PORT, assertPortFree, debugUserDataDirectory, launchEmulator } from './emulator-launcher.mjs';
|
|
11
11
|
export { EMULATOR_ENV_NAME, locateEmulator } from './emulator-locator.mjs';
|
|
12
|
+
export { DOS_PROMPT_FRAMES, SB2000_MACHINE, bootSb2000, enterProgram, keyCodeOf, runFrames, tapKey } from './sb2000-session.mjs';
|