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
|
@@ -0,0 +1,104 @@
|
|
|
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 开始读键盘所需的帧数;日期提示约 850 帧才读键盘,更早按的回车会丢 */
|
|
17
|
+
export const DOS_PROMPT_FRAMES = 900;
|
|
18
|
+
|
|
19
|
+
/** 按键按下与松开之后各运行的帧数,让 BIOS 读到 */
|
|
20
|
+
const KEY_DOWN_FRAMES = 5;
|
|
21
|
+
const KEY_UP_FRAMES = 4;
|
|
22
|
+
|
|
23
|
+
/** 在 SB-DOS 命令行里输入时,按下与松开之后各运行的帧数,更短会丢键 */
|
|
24
|
+
const DOS_KEY_FRAMES = 8;
|
|
25
|
+
|
|
26
|
+
/** 一次运行请求等待的上限,单位毫秒 */
|
|
27
|
+
const RUN_TIMEOUT_MS = 120_000;
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* 字符对应的物理键位(KeyboardEvent.code)。
|
|
31
|
+
* @param {string} char 程序名里的一个字符,只支持字母与数字
|
|
32
|
+
* @returns {string} 键位
|
|
33
|
+
* @throws {FcdevError} 不支持的字符
|
|
34
|
+
*/
|
|
35
|
+
export function keyCodeOf(char) {
|
|
36
|
+
if (/^[a-z]$/i.test(char)) return `Key${char.toUpperCase()}`;
|
|
37
|
+
if (/^[0-9]$/.test(char)) return `Digit${char}`;
|
|
38
|
+
throw new FcdevError(`无法在 SB-DOS 里输入字符“${char}”`, { code: 'DOS_KEY_UNSUPPORTED', hint: '程序名只能用字母与数字(用 fcdev.json 的 name 改名)' });
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* 运行指定的帧数,运行结束才返回。
|
|
43
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
44
|
+
* @param {number} frames 帧数
|
|
45
|
+
* @returns {Promise<{stopped: string, frames: number, cycles: number}>} 运行结果,stopped 说明停止原因
|
|
46
|
+
*/
|
|
47
|
+
export function runFrames(client, frames) {
|
|
48
|
+
return client.request('runtime.run', { frames, wait: true }, { timeoutMs: RUN_TIMEOUT_MS });
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* 按下并松开一个键,期间运行若干帧。
|
|
53
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
54
|
+
* @param {string} code 物理键位(KeyboardEvent.code),如 KeyA、Enter、F1
|
|
55
|
+
* @param {number} [downFrames] 按下后运行的帧数
|
|
56
|
+
* @param {number} [upFrames] 松开后运行的帧数
|
|
57
|
+
* @returns {Promise<void>}
|
|
58
|
+
*/
|
|
59
|
+
export async function tapKey(client, code, downFrames = KEY_DOWN_FRAMES, upFrames = KEY_UP_FRAMES) {
|
|
60
|
+
await client.request('input.key', { code, down: true });
|
|
61
|
+
await runFrames(client, downFrames);
|
|
62
|
+
await client.request('input.key', { code, down: false });
|
|
63
|
+
await runFrames(client, upFrames);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* 添加固件、放入磁盘镜像,并让整机机型开机:开机后已上电,没有运行。
|
|
68
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
69
|
+
* @param {{firmware: string, diskImage: string}} input 固件(BIOS)文件与磁盘镜像
|
|
70
|
+
* @returns {Promise<void>}
|
|
71
|
+
* @throws {FcdevError} 文件不存在,或 Ember 拒绝固件、镜像
|
|
72
|
+
*/
|
|
73
|
+
export async function bootSb2000(client, { firmware, diskImage }) {
|
|
74
|
+
if (!existsSync(firmware)) throw new FcdevError(`找不到固件:${firmware}`, { code: 'FIRMWARE_MISSING', hint: '在 fcdev.json 的 firmware 里指向学习机的 BIOS 文件' });
|
|
75
|
+
if (!existsSync(diskImage)) throw new FcdevError(`找不到磁盘镜像:${diskImage}`, { code: 'EMULATOR_FILE_MISSING' });
|
|
76
|
+
const steps = [
|
|
77
|
+
['添加固件', 'machines.setBios', { machine: SB2000_MACHINE, path: firmware }],
|
|
78
|
+
['开机', 'machines.boot', { machine: SB2000_MACHINE, powerOn: true, resume: false }],
|
|
79
|
+
['放入磁盘镜像', 'media.floppyInsert', { drive: 0, path: diskImage }],
|
|
80
|
+
];
|
|
81
|
+
for (const [name, method, params] of steps) {
|
|
82
|
+
try {
|
|
83
|
+
await client.request(method, params);
|
|
84
|
+
} catch (error) {
|
|
85
|
+
throw new FcdevError(`Ember ${name}失败:${error.message}`, { code: 'EMULATOR_LOAD_FAILED', cause: error });
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* 在 SB-DOS 里运行程序:开机运行 900 帧,直接按两次回车跳过日期与时间,输入程序名回车。返回时程序刚被启动,机器仍是暂停的。
|
|
92
|
+
* @param {import('ember-debug-sdk').EmberDebugClient} client 已连接的调试客户端
|
|
93
|
+
* @param {string} programName 程序名(不含扩展名)
|
|
94
|
+
* @returns {Promise<void>}
|
|
95
|
+
* @throws {FcdevError} 程序名里有无法输入的字符
|
|
96
|
+
*/
|
|
97
|
+
export async function enterProgram(client, programName) {
|
|
98
|
+
const codes = [...programName].map(keyCodeOf);
|
|
99
|
+
await runFrames(client, DOS_PROMPT_FRAMES);
|
|
100
|
+
await tapKey(client, 'Enter', DOS_KEY_FRAMES, DOS_KEY_FRAMES);
|
|
101
|
+
await tapKey(client, 'Enter', DOS_KEY_FRAMES, DOS_KEY_FRAMES);
|
|
102
|
+
for (const code of codes) await tapKey(client, code, DOS_KEY_FRAMES, DOS_KEY_FRAMES);
|
|
103
|
+
await tapKey(client, 'Enter', DOS_KEY_FRAMES, DOS_KEY_FRAMES);
|
|
104
|
+
}
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
//
|
|
7
|
+
// 备注:目标定义的字段含义见仓库根目录 docs/02-目标规范.md 第 2 节;新增机型只需新增目标目录,不改这里。
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
import { readdirSync } from 'node:fs';
|
|
10
10
|
import path from 'node:path';
|
|
@@ -23,6 +23,9 @@ const RUN_MODES = new Set(['rom', 'firmware-disk']);
|
|
|
23
23
|
/** 目标专用选项允许的类型 */
|
|
24
24
|
const OPTION_TYPES = new Set(['boolean', 'string', 'number']);
|
|
25
25
|
|
|
26
|
+
/** 源文件转码支持的目标编码 */
|
|
27
|
+
const SOURCE_CHARSETS = new Set(['gb2312']);
|
|
28
|
+
|
|
26
29
|
/**
|
|
27
30
|
* @typedef {object} BankedSpec 多页(换页)程序的定义
|
|
28
31
|
* @property {string} option 目标专用选项名,值为库页个数
|
|
@@ -55,6 +58,7 @@ const OPTION_TYPES = new Set(['boolean', 'string', 'number']);
|
|
|
55
58
|
* @property {object|null} run 运行方案
|
|
56
59
|
* @property {Record<string, {type: string, default: unknown, links: string[]}>} options 目标专用选项;布尔选项为 true 时额外链接 links 里的文件(路径值)
|
|
57
60
|
* @property {BankedSpec|null} banked 多页(换页)程序的定义;不支持时为 null
|
|
61
|
+
* @property {string|null} sourceCharset 机器用的文字编码;不为 null 时,构建前把 UTF-8 的源文件转成这个编码(目前只有 gb2312)
|
|
58
62
|
*/
|
|
59
63
|
|
|
60
64
|
/**
|
|
@@ -129,6 +133,9 @@ export function parseTarget(raw, dir) {
|
|
|
129
133
|
options[key] = { type: spec.type, default: spec.default, links: spec.links ?? [] };
|
|
130
134
|
}
|
|
131
135
|
const banked = parseBanked(raw.banked, raw.name, options);
|
|
136
|
+
if (raw.sourceCharset !== undefined && !SOURCE_CHARSETS.has(raw.sourceCharset)) {
|
|
137
|
+
throw new FcdevError(`目标 ${raw.name} 的 sourceCharset 只能是 ${[...SOURCE_CHARSETS].join(' 或 ')}`, { code: 'TARGET_INVALID' });
|
|
138
|
+
}
|
|
132
139
|
return {
|
|
133
140
|
name: raw.name,
|
|
134
141
|
title: raw.title,
|
|
@@ -150,6 +157,7 @@ export function parseTarget(raw, dir) {
|
|
|
150
157
|
run: raw.run ?? null,
|
|
151
158
|
options,
|
|
152
159
|
banked,
|
|
160
|
+
sourceCharset: raw.sourceCharset ?? null,
|
|
153
161
|
};
|
|
154
162
|
}
|
|
155
163
|
|
|
Binary file
|
|
Binary file
|
package/targets/nes/target.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# SB2000 C 接口参考
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
本文由运行库头文件 `sb2000-*.h` 的文档注释生成。
|
|
4
4
|
共 204 个函数,17 个模块。随时查询用 `npx fcdev api`:`npx fcdev api <函数名>` 看完整文档,`npx fcdev api <模块名>` 看模块的函数列表,`npx fcdev api '$7B'` 看用到某个系统调用的函数,`npx fcdev api <词>` 按名称与说明搜索。
|
|
5
5
|
|
|
6
6
|
约定:
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
- 所有函数用 `#include <sb2000.h>` 引入;返回 DOS 出错码或软驱状态码的函数,0 表示成功,结果经指针参数带回。
|
|
9
9
|
- 字符串、缓冲区、结构体指针必须在程序窗口 `$8000-$BFFF` 里(系统服务换页后程序窗口不可见的,函数内部已经处理好,调用者不用管)。
|
|
10
10
|
- 程序最大 16K(窗口 `$8000-$BFFF`,C 软件栈占顶端 1K)。
|
|
11
|
+
- 汇编程序调用这些函数时,函数名前加下划线(如 `_sb_puts`),参数按 cc65 的 fastcall 约定传递;系统调用号、地址与寄存器的符号见 [SB2000 符号参考](symbols-reference.md)。
|
|
11
12
|
|
|
12
13
|
## 目录
|
|
13
14
|
|