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.
- package/CHANGELOG.md +46 -32
- package/README.md +8 -8
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +9 -8
- package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +5 -5
- package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +3 -3
- package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +69 -62
- package/docs/06-/345/217/215/346/261/207/347/274/226.md +3 -3
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +13 -10
- package/docs/09-/345/217/221/345/270/203.md +16 -11
- package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
- package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +7 -7
- package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +4 -1
- package/package.json +5 -2
- package/src/cli/args-parser.mjs +1 -1
- package/src/cli/commands/debug-command.mjs +20 -58
- package/src/cli/commands/run-command.mjs +36 -39
- package/src/cli/index.mjs +4 -4
- package/src/config/config-loader.mjs +1 -1
- package/src/disasm/disassembler.mjs +1 -1
- package/src/disasm/trace.mjs +4 -3
- package/src/docs/doc-topics.mjs +38 -38
- 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 +101 -0
- 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/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
- package/targets/sb2000/target.json +1 -1
- package/src/emulator/debug-client.mjs +0 -125
|
@@ -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';
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:sb2000-session.mjs
|
|
3
|
+
// 说明:学习机(SB2000)在 Ember 里的启动与操作:经调试服务添加固件、放入磁盘镜像、整机开机,并在 SB-DOS 里输入程序名运行;还有按键与运行帧数的小工具。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-15
|
|
7
|
+
// 备注:固件是学习机的 BIOS(iNES 文件),Ember 把它复制进自己的 BIOS 目录;磁盘镜像按 fcdev disk 生成,里面只有程序,开机后进入 SB-DOS 命令行,要输入程序名才运行。
|
|
8
|
+
// 帧数按 Ember 的运行速度估计:runtime.run 不限速,几千帧只要几秒;SB-DOS 启动后先问日期与时间,回车跳过。
|
|
9
|
+
// ------------------------------------------------------------------------
|
|
10
|
+
import { existsSync } from 'node:fs';
|
|
11
|
+
import { FcdevError } from '../shared/index.mjs';
|
|
12
|
+
|
|
13
|
+
/** 整机机型的标识 */
|
|
14
|
+
export const SB2000_MACHINE = 'sb2000';
|
|
15
|
+
|
|
16
|
+
/** 开机到 SB-DOS 询问日期所需的帧数 */
|
|
17
|
+
export const DOS_PROMPT_FRAMES = 2600;
|
|
18
|
+
|
|
19
|
+
/** 按键按下与松开之后各运行的帧数,让 BIOS 读到 */
|
|
20
|
+
const KEY_DOWN_FRAMES = 5;
|
|
21
|
+
const KEY_UP_FRAMES = 4;
|
|
22
|
+
|
|
23
|
+
/** 一次运行请求等待的上限,单位毫秒 */
|
|
24
|
+
const RUN_TIMEOUT_MS = 120_000;
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* 字符对应的物理键位(KeyboardEvent.code)。
|
|
28
|
+
* @param {string} char 程序名里的一个字符,只支持字母与数字
|
|
29
|
+
* @returns {string} 键位
|
|
30
|
+
* @throws {FcdevError} 不支持的字符
|
|
31
|
+
*/
|
|
32
|
+
export function keyCodeOf(char) {
|
|
33
|
+
if (/^[a-z]$/i.test(char)) return `Key${char.toUpperCase()}`;
|
|
34
|
+
if (/^[0-9]$/.test(char)) return `Digit${char}`;
|
|
35
|
+
throw new FcdevError(`无法在 SB-DOS 里输入字符“${char}”`, { code: 'DOS_KEY_UNSUPPORTED', hint: '程序名只能用字母与数字(用 fcdev.json 的 name 改名)' });
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* 运行指定的帧数,运行结束才返回。
|
|
40
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
41
|
+
* @param {number} frames 帧数
|
|
42
|
+
* @returns {Promise<{stopped: string, frames: number, cycles: number}>} 运行结果,stopped 说明停止原因
|
|
43
|
+
*/
|
|
44
|
+
export function runFrames(client, frames) {
|
|
45
|
+
return client.request('runtime.run', { frames, wait: true }, { timeoutMs: RUN_TIMEOUT_MS });
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* 按下并松开一个键,期间运行若干帧。
|
|
50
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
51
|
+
* @param {string} code 物理键位(KeyboardEvent.code),如 KeyA、Enter、F1
|
|
52
|
+
* @returns {Promise<void>}
|
|
53
|
+
*/
|
|
54
|
+
export async function tapKey(client, code) {
|
|
55
|
+
await client.request('input.key', { code, down: true });
|
|
56
|
+
await runFrames(client, KEY_DOWN_FRAMES);
|
|
57
|
+
await client.request('input.key', { code, down: false });
|
|
58
|
+
await runFrames(client, KEY_UP_FRAMES);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* 添加固件、放入磁盘镜像,并让整机机型开机:开机后已上电,没有运行。
|
|
63
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
64
|
+
* @param {{firmware: string, diskImage: string}} input 固件(BIOS)文件与磁盘镜像
|
|
65
|
+
* @returns {Promise<void>}
|
|
66
|
+
* @throws {FcdevError} 文件不存在,或 Ember 拒绝固件、镜像
|
|
67
|
+
*/
|
|
68
|
+
export async function bootSb2000(client, { firmware, diskImage }) {
|
|
69
|
+
if (!existsSync(firmware)) throw new FcdevError(`找不到固件:${firmware}`, { code: 'FIRMWARE_MISSING', hint: '在 fcdev.json 的 firmware 里指向学习机的 BIOS 文件' });
|
|
70
|
+
if (!existsSync(diskImage)) throw new FcdevError(`找不到磁盘镜像:${diskImage}`, { code: 'EMULATOR_FILE_MISSING' });
|
|
71
|
+
const steps = [
|
|
72
|
+
['添加固件', 'machines.setBios', { machine: SB2000_MACHINE, path: firmware }],
|
|
73
|
+
['开机', 'machines.boot', { machine: SB2000_MACHINE, powerOn: true, resume: false }],
|
|
74
|
+
['放入磁盘镜像', 'media.floppyInsert', { drive: 0, path: diskImage }],
|
|
75
|
+
];
|
|
76
|
+
for (const [name, method, params] of steps) {
|
|
77
|
+
try {
|
|
78
|
+
await client.request(method, params);
|
|
79
|
+
} catch (error) {
|
|
80
|
+
throw new FcdevError(`Ember ${name}失败:${error.message}`, { code: 'EMULATOR_LOAD_FAILED', cause: error });
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* 在 SB-DOS 里运行程序:等 DOS 起来,回车跳过日期与时间,输入程序名回车。返回时程序刚被启动,机器仍是暂停的。
|
|
87
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
88
|
+
* @param {string} programName 程序名(不含扩展名)
|
|
89
|
+
* @returns {Promise<void>}
|
|
90
|
+
* @throws {FcdevError} 程序名里有无法输入的字符
|
|
91
|
+
*/
|
|
92
|
+
export async function enterProgram(client, programName) {
|
|
93
|
+
const codes = [...programName].map(keyCodeOf);
|
|
94
|
+
await runFrames(client, DOS_PROMPT_FRAMES);
|
|
95
|
+
await tapKey(client, 'Enter');
|
|
96
|
+
await runFrames(client, 60);
|
|
97
|
+
await tapKey(client, 'Enter');
|
|
98
|
+
await runFrames(client, 120);
|
|
99
|
+
for (const code of codes) await tapKey(client, code);
|
|
100
|
+
await tapKey(client, 'Enter');
|
|
101
|
+
}
|
|
Binary file
|
|
Binary file
|
package/targets/nes/target.json
CHANGED
|
Binary file
|
|
Binary file
|
|
@@ -1,125 +0,0 @@
|
|
|
1
|
-
// ------------------------------------------------------------------------
|
|
2
|
-
// 名称:debug-client.mjs
|
|
3
|
-
// 说明:模拟器调试服务的客户端:连接本机端口,发送一行命令,读取以单独的“.”行结束的应答。
|
|
4
|
-
// 作者:sungbin
|
|
5
|
-
// 邮箱:sungbin@3578.cn
|
|
6
|
-
// 日期:2026-11-10
|
|
7
|
-
// 备注:协议见 virtuanes/README.md;服务只监听 127.0.0.1,一次只处理一条命令。
|
|
8
|
-
// ------------------------------------------------------------------------
|
|
9
|
-
import net from 'node:net';
|
|
10
|
-
import { FcdevError } from '../shared/index.mjs';
|
|
11
|
-
|
|
12
|
-
/** fcdev 的调试服务默认端口 */
|
|
13
|
-
export const DEFAULT_DEBUG_PORT = 5699;
|
|
14
|
-
|
|
15
|
-
/** 连接调试服务的超时,单位毫秒 */
|
|
16
|
-
const CONNECT_TIMEOUT_MS = 5_000;
|
|
17
|
-
|
|
18
|
-
/** 一条命令默认的应答超时,单位毫秒 */
|
|
19
|
-
const COMMAND_TIMEOUT_MS = 30_000;
|
|
20
|
-
|
|
21
|
-
/**
|
|
22
|
-
* @typedef {object} DebugReply
|
|
23
|
-
* @property {boolean} ok 应答首行以 OK 开头
|
|
24
|
-
* @property {string} head 应答首行
|
|
25
|
-
* @property {string[]} lines 首行之后的各行
|
|
26
|
-
*/
|
|
27
|
-
|
|
28
|
-
/**
|
|
29
|
-
* 解析不含结尾“.”行的应答文本。
|
|
30
|
-
* @param {string} text 应答文本
|
|
31
|
-
* @returns {DebugReply} 解析结果
|
|
32
|
-
*/
|
|
33
|
-
export function parseReply(text) {
|
|
34
|
-
const lines = text.split('\n').filter((line) => line.length > 0);
|
|
35
|
-
const head = lines[0] ?? '';
|
|
36
|
-
return { ok: head.startsWith('OK'), head, lines: lines.slice(1) };
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
/** 调试服务客户端 */
|
|
40
|
-
export class DebugClient {
|
|
41
|
-
#socket;
|
|
42
|
-
#buffer = '';
|
|
43
|
-
#waiter = null;
|
|
44
|
-
|
|
45
|
-
/**
|
|
46
|
-
* @param {net.Socket} socket 已连接的套接字
|
|
47
|
-
*/
|
|
48
|
-
constructor(socket) {
|
|
49
|
-
this.#socket = socket;
|
|
50
|
-
socket.setEncoding('utf8');
|
|
51
|
-
socket.on('data', (chunk) => {
|
|
52
|
-
this.#buffer += chunk;
|
|
53
|
-
this.#deliver();
|
|
54
|
-
});
|
|
55
|
-
socket.on('close', () => {
|
|
56
|
-
this.#waiter?.reject(new FcdevError('调试连接已关闭', { code: 'DEBUG_CONNECTION_CLOSED' }));
|
|
57
|
-
this.#waiter = null;
|
|
58
|
-
});
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
/**
|
|
62
|
-
* 连接本机调试服务。
|
|
63
|
-
* @param {{port?: number, timeoutMs?: number}} [options] 端口与连接超时
|
|
64
|
-
* @returns {Promise<DebugClient>} 客户端
|
|
65
|
-
* @throws {FcdevError} 连接失败或超时
|
|
66
|
-
*/
|
|
67
|
-
static connect({ port = DEFAULT_DEBUG_PORT, timeoutMs = CONNECT_TIMEOUT_MS } = {}) {
|
|
68
|
-
return new Promise((resolve, reject) => {
|
|
69
|
-
const socket = net.connect({ host: '127.0.0.1', port });
|
|
70
|
-
const timer = setTimeout(() => {
|
|
71
|
-
socket.destroy();
|
|
72
|
-
reject(new FcdevError(`连接调试服务(端口 ${port})超时`, { code: 'DEBUG_CONNECT_FAILED' }));
|
|
73
|
-
}, timeoutMs);
|
|
74
|
-
socket.once('connect', () => {
|
|
75
|
-
clearTimeout(timer);
|
|
76
|
-
resolve(new DebugClient(socket));
|
|
77
|
-
});
|
|
78
|
-
socket.once('error', (error) => {
|
|
79
|
-
clearTimeout(timer);
|
|
80
|
-
reject(new FcdevError(`无法连接调试服务(端口 ${port})`, {
|
|
81
|
-
code: 'DEBUG_CONNECT_FAILED',
|
|
82
|
-
hint: '先用 npx fcdev run --debug 启动模拟器,或检查端口是否一致',
|
|
83
|
-
cause: error,
|
|
84
|
-
}));
|
|
85
|
-
});
|
|
86
|
-
});
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
/** 如果缓冲区里已经有完整应答,交给等待者 */
|
|
90
|
-
#deliver() {
|
|
91
|
-
if (!this.#waiter) return;
|
|
92
|
-
const end = this.#buffer.indexOf('\n.\n');
|
|
93
|
-
if (end < 0) return;
|
|
94
|
-
const reply = parseReply(this.#buffer.slice(0, end + 1));
|
|
95
|
-
this.#buffer = this.#buffer.slice(end + 3);
|
|
96
|
-
const { resolve, timer } = this.#waiter;
|
|
97
|
-
clearTimeout(timer);
|
|
98
|
-
this.#waiter = null;
|
|
99
|
-
resolve(reply);
|
|
100
|
-
}
|
|
101
|
-
|
|
102
|
-
/**
|
|
103
|
-
* 发送一条命令并等待应答;应答为 ERR 时不抛错,由调用者看 ok。
|
|
104
|
-
* @param {string} command 命令文本,不含换行
|
|
105
|
-
* @param {{timeoutMs?: number}} [options] 应答超时
|
|
106
|
-
* @returns {Promise<DebugReply>} 应答
|
|
107
|
-
* @throws {FcdevError} 上一条命令未返回、连接关闭或超时
|
|
108
|
-
*/
|
|
109
|
-
send(command, { timeoutMs = COMMAND_TIMEOUT_MS } = {}) {
|
|
110
|
-
if (this.#waiter) throw new FcdevError('上一条调试命令尚未返回', { code: 'DEBUG_BUSY' });
|
|
111
|
-
return new Promise((resolve, reject) => {
|
|
112
|
-
const timer = setTimeout(() => {
|
|
113
|
-
this.#waiter = null;
|
|
114
|
-
reject(new FcdevError(`调试命令“${command}”超过 ${timeoutMs} 毫秒没有应答`, { code: 'DEBUG_TIMEOUT' }));
|
|
115
|
-
}, timeoutMs);
|
|
116
|
-
this.#waiter = { resolve, reject, timer };
|
|
117
|
-
this.#socket.write(`${command}\n`);
|
|
118
|
-
});
|
|
119
|
-
}
|
|
120
|
-
|
|
121
|
-
/** 关闭连接 */
|
|
122
|
-
close() {
|
|
123
|
-
this.#socket.end();
|
|
124
|
-
}
|
|
125
|
-
}
|