feat: implement M2 emulator foundation

This commit is contained in:
2026-09-12 12:30:21 +08:00
parent b52de7eb4d
commit 5dfd0ef9f5
35 changed files with 1663 additions and 15 deletions
+54
View File
@@ -0,0 +1,54 @@
# NESLite 架构(M2 基线)
## 边界与线程
界面层只负责系统文件选择器、游戏列表、控制按钮、手柄事件和 GL Surface。ROM 的 `content://`
地址只在 Kotlin 导入层使用;导入完成后,原生层仅收到应用私有目录中的绝对文件路径。
FCEUmm 由一个原生工作线程独占。JNI 调用只向容量 32 的命令队列写入 `load/run/pause/reset/stop`
命令,命令携带单调递增的会话号。旧会话、重复命令和当前状态不允许的命令不会触碰内核,并在
状态快照的完成通知中报告 `stale` 或 `ignored`。状态集合固定为 Idle、Loading、Paused、
Running、Pausing、Stopping 和 Error。
## ROM 和索引
系统文件选择器的输入流先写入 `files/roms/.import-<uuid>.tmp`。导入过程限制为 64 MiB,校验
iNES/NES 2.0 魔数并计算完整文件 SHA-256;提交文件为 `files/roms/<sha256>.nes`。Room 以哈希
作为主键,因此相同内容去重、同名不同内容分别登记。写文件后、写数据库前中断留下的有效正式
文件会在下次启动恢复为索引项;残留导入临时文件会清除;索引缺少文件时标记为 `MISSING`,重新
导入相同内容可恢复文件和状态。
## libretro 宿主
固定 FCEUmm 提交见 `third_party/manifest.json`,构建定义在 `app/src/main/cpp/cmake/fceumm.cmake`。
环境协商清单如下;不在清单中的请求统一返回 `false`。
| 类别 | 处理 |
| --- | --- |
| 私有目录 | system、save、content,必须可建立,否则阻止加载 |
| 视频 | 固定核心使用的 RGB565 与重复帧;其他像素格式拒绝 |
| 选项 | core-options version 0 与 `SET_VARIABLES/GET_VARIABLE` 默认值 |
| 输入 | player 1 joypad、bitmask、输入/控制器描述 |
| 前端信息 | 日志、英语、60 Hz/48 kHz 目标、动态 geometry/AV、消息接口 v1、性能级别、内存映射、成就/内容声明 |
| 明确不支持 | VFS、扩展 game-info、硬件渲染以及未列出的请求 |
宿主在加载前核对 libretro API 版本和私有目录;必要能力缺失进入 Error。当前固定 FCEUmm 不把上述
明确不支持的请求作为加载必要条件。
加载、`retro_run`、重置、卸载和保存内存访问均在内核线程执行。时序来自
`retro_get_system_av_info`,以 `steady_clock` 调度;M2 完整消费音频回调并返回已消费帧数,但按阶段
要求暂不发声。
## 视频、输入和电池存档
视频回调逐行按 pitch 复制到原生 latest-only 缓冲;`data == nullptr` 表示重复帧并保留上一完整帧。
GL 线程只在原生侧读取最新缓冲和上传纹理,不经 JNI 逐帧复制图像。默认 4:3、最近邻显示,可切换
原始像素整数缩放;渲染掉帧不减少内核 `retro_run` 次数。
手柄状态在 Android 事件侧合成为 libretro joypad 位掩码,内核每帧按状态采样。后台、失焦和断柄
会清零并请求暂停。M1 的 X5 Lite 实测键码仍须在 G1 回填,因此当前只包含 Android 标准按键及
HAT/主方向轴映射。
电池存档按 ROM 哈希隔离为 `files/saves/<sha256>/battery/battery.sav`。暂停和正常退出时在内核线程
取得保存内存并以临时文件替换提交,状态通知用 `paused_saved`/`stopped_saved` 报告成功。更完整的
备份、故障注入和恢复保证属于 M5,不在此处提前声明。
+4 -4
View File
@@ -1,6 +1,6 @@
# NESLite 可复现构建说明
本说明对应 M0 基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
本说明对应 M0~M2 基线。命令使用系统默认 PowerShell 7.6.6(`pwsh`)从仓库根目录执行;不需要手工复制 `.so`、
FCEUmm 或 Oboe 文件。
## 前置条件
@@ -17,7 +17,7 @@ FCEUmm 或 Oboe 文件。
.\tools\fetch-third-party.ps1
```
该脚本根据 `third_party/manifest.json` 检出固定提交;M0 的 JNI stub 不依赖这些源码。
该脚本根据 `third_party/manifest.json` 检出固定提交;M2 构建需要 FCEUmm 与 libretro headers。
## 构建调试 APK
@@ -35,9 +35,9 @@ pwsh -NoProfile -File .\tools\check.ps1 -Scope Build
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Build` | 生成调试 APK | 单元、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Local` | Kotlin 本地单元测试 | APK、原生、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Module` | 原生 smoke test 与 Kotlin 本地单测 | APK、实机、长测 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Stage` | M0 构建加上述有界测试 | 设备、耐久、H 专项 |
| `pwsh -NoProfile -File ./tools/check.ps1 -Scope Stage` | 当前 APK、原生 smoke test 与 Kotlin 本地单测 | 设备、ROM 兼容、耐久、H 专项 |
`Stage` 是 M0 的阶段入口,不是未来 G1~G9 的替代。实机、ROM、存档、插拔和耐久验收必须在
`Stage` 是本地阶段入口,不是 G1~G9 的替代。实机、ROM、存档、插拔和耐久验收必须在
相应里程碑按 [acceptance.md](acceptance.md) 执行和记录。
## M1 诊断版安装
+1 -1
View File
@@ -6,7 +6,7 @@
| --- | --- |
| 显示名称 | `NESLite` |
| 正式 application ID/namespace | `org.neslite.app` |
| 当前开发版本 | `0.1.3`,`versionCode = 1003` |
| 当前开发版本 | `0.2.4`,`versionCode = 2004` |
| 调试 application ID | `org.neslite.app.debug` |
| 发布 ABI | `arm64-v8a` |
| min/target SDK | 28/36 |
+37
View File
@@ -0,0 +1,37 @@
# M2 内核、画面与基础操作记录
日期:2026-09-12
构建:`org.neslite.app.debug`,`0.2.4-debug`,versionCode 2004,arm64-v8a
APK:`app/build/outputs/apk/debug/app-debug.apk`,19,140,125 bytes,SHA-256
`C29E5664AFAC2736D3BA76FC091FB9ECC711596A88A7FFB66114CDDC141D3038`。
## 已实现
- 固定 FCEUmm `236ccdfc911e84c60fea6b9d0699c2d440a8de14`,无本地补丁;以
`__LIBRETRO__`、`FRONTEND_SUPPORTS_RGB565`、`HAVE_NTSC_FILTER`、`PSS_STYLE=1` 编译并静态链接
到 `libneslite_jni.so`。
- 单原生线程、32 项有界命令队列、递增会话号、完整 M2 状态集合、完成序号和结果通知;旧会话不能
激活当前内核。
- FCEUmm 环境协商、生命周期、AV 时序、静音音频消费、latest-only 原生视频缓冲和 GLES2 最近邻
显示;4:3 与整数像素缩放可切换。
- SAF 流式导入、64 MiB 上限、iNES/NES 2.0 校验、完整 SHA-256、Room 最小索引、重复内容去重、
中断恢复和缺失文件状态。
- 标准 Android 手柄键/HAT 状态送入 libretro;后台、失焦、断柄清零并暂停;界面提供加载、运行、
暂停、继续、重置和退出。
- 按 ROM 哈希读取/提交基础电池存档,暂停和正常退出报告保存成功。
## 本地验证
- `:app:testDebugUnitTest`:12 项通过,包括构建身份、iNES/NES 2.0/损坏头/短文件、流式复制/
超限清理和 M1 输入测试。
- `:app:assembleDebug`:通过;完整 FCEUmm 源码编译并链接 arm64-v8a APK。
- `llvm-nm` 在最终未剥离 arm64 库中确认 `retro_api_version`、`retro_get_system_info`、
`retro_load_game` 和 `retro_run` 入口。
- 原生 smoke test 覆盖允许/拒绝状态、必要能力、新旧会话号、非紧密 pitch、重复帧和缓冲切换分支。
## 尚未形成门槛证据
G1 未通过,且目标手机、X5 Lite 和 3 个有合法使用依据的 ROM 样本(其中一个电池存档样本)均不在
当前可用范围。因此 SAF 中文文件名/取消、GL 实际画面、组合输入、完整控制流程、电池进度恢复及
3-ROM 兼容结果尚不能进行 L2/L3 验收;`todo.md` 中的 M2 项和 G2 均保持未勾选。