返回

合金装备在 ESP32-S3 上原生运行

XIAO ESP32S3 掌机在底座上运行《合金装备》,右上角显示雷达

我从小就喜欢《合金装备》。当我拿到一块小小的 ESP32-S3 开发板时,一个问题一直萦绕在我脑海里:一款 PlayStation 游戏能在这玩意儿上跑起来吗?

Seeed Studio XIAO ESP32S3 Sense:21 × 17.8 × 15 毫米,附带摄像头扩展板(照片:Seeed Studio)

这块板子是 Seeed Studio XIAO ESP32S3 Sense:双核 ESP32-S3,8 MB PSRAM 和 8 MB flash,模块尺寸仅 21 × 17.8 毫米。Sense 版本还附带一块带摄像头和 microSD 卡槽的扩展板,而游戏数据就存放在那张 microSD 卡里。

我花了很长时间才搞清楚。首先,我寻找一个已经被重构成可在 PC 上运行的 C 代码版本的游戏,然后检查所有这些逻辑能否装进 ESP32-S3 的 flash 和一张 microSD 卡里。经过多次尝试,最终成功了。一款美妙的游戏如今能在一块售价约 15 美元的微控制器开发板上运行。

掌机上的实机演示:在 YouTube 上观看。

在本文中,我将介绍《合金装备》(PlayStation,1998)如何作为原生移植在 ESP32-S3 上运行。游戏的 C 源码由 FoxdieTeam 的 mgs_reversing 反编译项目重建,直接编译为 Xtensa 机器码。PlayStation 硬件过去提供的一切都被软件替代:

本文涵盖硬件、平台层、内存布局、调试方法、最关键的 bug、性能表现、掌机,以及目前尚不能工作的部分。

代码及相关项目:

你需要自备光盘。仓库中不包含任何源自游戏的内容,port/extract_disc.py 会从你自己的光盘镜像中提取文件。

硬件

在底座上用掌机玩《合金装备》

ESP32-S3 拥有两个 240 MHz 的 Xtensa 核心和 512 KB 内部 SRAM。这里使用的两块板子还都配有 8 MB PSRAM,与 flash 共用同一缓存。

Waveshare ESP32-S3-Touch-LCD-2DIY 掌机(Seeed XIAO ESP32S3 Sense)
屏幕ST7789,320x240ILI9341,原生 320x240
Flash16 MB8 MB
游戏数据microSD,或精简后的 STAGE.DIR 存入 flashmicroSD(完整 STAGE.DIR)
输入通过串口的键盘(play.py)无人机云台摇杆、6 键电阻梯形网络、2 个直连按键

写代码之前先测量差距

在编写任何移植代码之前,我先测量了反编译项目距离能为 Xtensa 构建还差多远:

我故意留下唯一编译失败的文件 libdg/chanl.c 不去修复。那个本可以消除报错的强制类型转换,同时也会悄悄改变步长(参见下文关于排序表的章节)。

其余部分则通过机械化的批量处理完成,每一轮都解决一整类问题:

结果是 497 个 C 文件中的 497 个都成功编译为 Xtensa。ELF 有 0 个未定义引用和 0 个重复定义(text 987,073 B,bss 2,434,276 B)。游戏自身的内存占用为 804 KiB(428 KiB 堆加上两个 188 KiB 的数据包缓冲区),可以轻松放入 PSRAM。

----- END POST -----

架构

该移植在游戏与 SoC 之间有三层:

移植的三层结构与两个核心:所有 mts 任务和 vblank 节拍运行在核心 0,LCD 扫描输出运行在核心 1,LCD 与 microSD 共享 SPI2

从游戏到硬件的各层依次为:

  1. MGS 引擎:反编译后的 C 代码,编译为 Xtensa
  2. psyz:用 C 实现的 PlayStation SDK 与 GTE,软件光栅化器
  3. 平台层:基于 FreeRTOS 的 mts 调度器、vblank 节拍、虚拟光驱、LCD、输入
  4. ESP32-S3

psyz 与 GTE

psyz 是 Xeeynamo 对 PlayStation SDK 的重新实现,它已经用 C 建模了整个 GTE 寄存器文件和所有 GTE 操作,并通过 PCSX-Redux GTE 测试套件进行了验证。

我最初的估计是缺少 64 到 70 个宏。这个估计过高了。MGS 自带 MIPS 内联汇编头文件(inline_n.h、inline_x.h),而 -fsyntax-only 并不会检查寄存器名称。一旦把这些头文件重定向到 psyz,真正的缺口是 41 个宏。我把它们加进了 psyz,并以游戏自身的汇编作为规范,来确定每个宏会触及哪些 COP2 寄存器。随后,我用修改后的 psyz 重新构建了其他基于 psyz 的项目,以确保没有破坏任何东西。

当你为 GTE 宏设置别名时,要检查每个约束是输入还是输出。例如,gte_read_opz 有一个 "=r" 输出,因此它的别名必须接受 &x。

排序表标签:PSX 上一个字,psyz 中两个字

这是最重要的布局差异,也导致了最多的 bug。在 PlayStation 上,每个图元都以一个 32 位标签开头:24 位指向下一个图元的地址,8 位表示长度。主机指针无法放进 24 位,因此 psyz 使用 两个字,tag 和 len。每个图元增加 4 字节,标签之后的每个字段都移动一个字。

MGS 还滥用了长度字节。libdg 对 16 位深度执行两遍基数排序:

  1. divide.c 按低字节分桶,并把高字节暂存在标签的长度字段中。
  2. sort.c 按该高字节重新分桶,并写入真正的长度。

由于 psyz 将这两个字段分开,转换是精确的:

pack->tag = (hi << 24) | *ot;  *ot = pack;     /* PSX */
addPrim(ot, pack); setlen(pack, hi);           /* psyz */

把 42 个局部声明和 100 个参数重新标注为 OT_TYPE* 是容易的部分。困难的是那些默认采用打包布局却没有明说的代码:

还有一个加剧问题的因素。在主机上,addPrim() 每次插入都会重写整个标签字,因此忘记设置长度永远不会被察觉。而在 psyz 中,从未设置过的长度就永远不会被写入。

FreeRTOS 中的 Konami 调度器

MGS 运行在 Konami 自己的协作式调度器上。启动横幅仍然显示 Multi Task Scheduler for PSX ver2.02 Jul 11 1998。它建立在 BIOS 线程 API(OpenTh/ChangeTh)之上,并使用 vblank 中断来唤醒定时器已到期的任务。

在移植中,每个 mts 线程都是一个 FreeRTOS 任务,并且同一时间只有一个任务处于可运行状态。最终设计如下:

mts_GetTcbEntry 还会读取固定地址 0x100 处的 BIOS 表之表,并通过结果进行写入。在 PSX 之外,该地址存放的是垃圾数据,因此现在改用私有的 TCB 表。

vblank 节拍与两个时钟

port/esp32_vblank.c 每 16 ms 触发一次游戏的 VSync 回调。这需要在 psyz 中实现 VSyncCallback(),而那里甚至没有存储该指针。

VSync(-1) 必须返回一个自由运行的 vblank 计数。第一个版本返回的是已呈现的帧数,当没有任何绘制时它就会停止递增,因此任何定时器都不会到期。

帧率会变化:走廊中每帧 2 个 vblank,开阔房间中为 4 到 5 个。因此,有两件看似属于 vblank 的事情实际上属于游戏帧:

内存布局

所有内容的所在位置:任务栈和热循环位于内部 SRAM,游戏的 RAM 映射和 1 MB VRAM 位于 PSRAM,固件位于 flash,STAGE.DIR 位于 microSD

内部 SRAM 稀缺且快速。PSRAM 充足且缓慢。Flash 读取会禁用 PSRAM 同样依赖的缓存。

有一类 bug 只存在于这种内存映射上:基于符号位的指针测试。 MGS 通过 proc_id < 0 来区分脚本块指针和 16 位 proc id。PSX RAM 位于 0x8xxxxxxx,作为有符号值是负数。PSRAM 位于 0x3Cxxxxxx,是正数。结果是 PROC 3C1987D2 NOT FOUND,随后在 EXCVADDR 0x00000003 处发生 LoadProhibited。一个 GCL_IS_BLOCK_PTR 宏修复了被命中的位置。其他具有相同模式的位置仍需审计。

基于 FAT 的虚拟光驱

虚拟光驱:libfs 请求绝对扇区,virtual_cd.c 将其转换为 microSD 上的文件和偏移,并一次返回一个扇区

libfs 以绝对扇区为单位工作。它读取一次 ISO9660 目录,之后再也不使用文件名。port/virtual_cd.c 替换了 CD BIOS:

数据最初存放在 PSRAM 中,这使游戏只能加载少数几个关卡。真正的解决方案是 microSD。该卡是一个 SPI 外设,与 XIP flash 分离,因此读取它不会禁用指令缓存。文件留在卡上,不消耗 PSRAM。

该卡与 LCD 共享 SPI2,而 ESP-IDF 不会在它们之间进行仲裁。一个 LCD 帧是 30 个排队的异步传输,因此在一帧中间进行卡读取会触发 assert failed: spi_hal_iram.c:134 并导致重启循环。修复方法是显式的总线所有权(Mgs_SpiBusTake/Give),在释放总线之前排空正在进行的传输。

方法:测量,而非猜测

在这个项目中,大约三分之一的显而易见解释最终被证明是错误的。真正有效的方法是让开发板打印出一个数字,用来在多个假设之间做出判断。最有用的教训来自那些给出错误答案的探针:

不烧录开发板也能运行每一次构建

这种方法只有在尝试成本很低时才奏效。经过几个小时的反复试错,每次改动后都去烧录开发板的成本并不低:通过 USB 把镜像写入 XIAO,等待重启,读取串口日志,然后再来一遍。所以我用 Velxio 的命令行客户端 velxio-cli 来运行和检查每一次构建。它接收我的工具链生成的同一个 .bin,在 Velxio 模拟的 ESP32-S3 上运行固定的模拟时长,并返回串口输出,这样上面那些探针都能在不碰硬件的情况下读到。只有当某次构建值得时,开发板才会被写入新的镜像。

# velxio.toml, next to the build: board = "xiao-esp32-s3", firmware = the merged .bin
velxio-cli run --timeout 5000 --timeout-exit-code 0 --serial-log-file serial.log .

安装并完成第一次运行只需几分钟:参见 velxio-cli 快速入门。

那些 bug

掌机上的游戏画面,雷达位于右上角

严格别名优化删掉了一次旋转

白屏:五个错误假设,三个真正原因

GPU 尺寸规则:一个被钉在 GTE 的 -1024 饱和极限处的多边形伸入 320x240 屏幕;PlayStation GPU 拒绝任何大于 1023x511 的东西,而软件光栅化器却把它画了出来

假设 4 中的剔除修复是真实的,尽管它不是原因。包围盒测试把穿过近裁剪面的盒子与完全在其后方的盒子同等对待。将这两种情况分开后,kept-saturated 从 16,090 降到 4,947。早先一次尝试以饱和坐标为键,它救回了屏幕测试所拒绝内容的 97%(光栅化 +40%),因为一面巨大而遥远的墙也会饱和。直接询问 Z(SZ <= H/2)得到的是 1,440 而不是 15,000。

Square0 移位了 12 位:所有距离都除以 64

Snake 会走三步,撞到墙,弹回来,永远无法前进。帧率是第一个嫌疑对象。一个观察排除了它:世界移动正常,只有玩家不正常。GM_ActControl 中的探针显示一步为 +4481,随后是 -14641 的回弹。

在 PSY-Q 中,数字后缀就是移位量:Square0 不移位,Square12 才移位。移植版的 Square0 移位了 12 位,所以每个 Square0 -> sum -> sqrt 长度都变成了 /64。这破坏了:

移除移位后,轨迹变得单调了。

五个 GTE 操作码从错误的行复制而来

Snake 掉出了世界(Y = -3250),移动被钉在每帧 0,1,码头也没有水。psyz 的 Psyz_GteRtv0/Rtv1/Rtv2/Ll/Llv0 使用了来自 MGS 自己的 inline_n.h 表中错误行的 MVMVA 操作码。“旋转这个向量”变成了“旋转它并加上陈旧的平移量”,而光照使用了旋转矩阵而不是光照矩阵。

修复后:

空荡荡的码头是一个两遍脚本

码头只有少数几个对象组,脚本似乎只运行了一条命令。s00a 的真实结构是 if (var[5] < 6) { set up the Colonel's call } else { build the dock },而该呼叫的 proc 是一个 restart。世界是在第二遍构建的,而接听 codec 会触发它。

我自己为了避开崩溃而屏蔽了 codec,结果禁用了每个关卡中的每一个 radio -c ... -p proc。现在 MENU_RadioDrainHeadless 会接听呼叫并派发其 proc,而不打开 codec 屏幕。对象组从每 120 帧 480 个增加到 3,240 个,水域也被创建了。教训是:临时桩代码需要有某种东西迫使你回头处理它。

除以零:MIPS 能挺过去,Xtensa 会重启

libhzd/near.c 除以一个在退化情况下可能为零的二维长度平方。R3000 带着未定义的结果继续运行。Xtensa 会触发 IntegerDivideByZero,然后板子重启。HZD_DIV 被应用到那 7 处运行时除数的除法上。之后,向四个方向各走 80 秒——也就是过去会崩溃的模式——得到 0 次 panic。在这个移植中,每一次除以计算得出的除数都需要保护。

17.6 分钟的冻结

psyz 的 VSync 在所有模式下都把结果截断为 16 位,但 VSync(-1) 必须返回 32 位的场计数。在 65,536 场(60 Hz 下 17.6 分钟)时,mts 时钟从 64,800 回绕到 1,064,而某个任务在等待 65,537,于是它永远等下去。修复方案是在 mode < 0 时返回完整计数。它影响每一个基于 psyz 构建的项目。依赖经过时间的 bug 永远不会在 60 秒的测试中显现。

看起来像卡死的启动

有好几个小时,启动似乎卡住了。Konami 的 mts_printf 在 PSX 上是一个空桩,而我的 #define printf mts_printf 把游戏的所有输出都送进了它,所以启动其实在无声地推进。一旦 mts_printf 调用 vprintf,日志就显示游戏已经到达 memcard_init()。在诊断卡死之前,先确保输出有地方可去。

一场其实是 malloc 失败的优先级死锁

文件守护任务(任务 10)从未获得 CPU 时间,跟踪看起来像优先级死锁。两个真正的修复(ChangeThFromISR 语义和 VSync(-1) 时钟)都没有改变任何东西。然后一行日志定了案:[thread] OpenTh: xTaskCreate failed。

我把栈提高到 32 KB,FreeRTOS 从内部 SRAM 分配它们,而第四个任务放不下。OpenTh 返回 -1,而 ChangeTh 永远拒绝那个 tid。在这个 SoC 上,即使还有数兆字节的空闲 PSRAM,也一定要检查 xTaskCreate 的返回值。

添加过场数据后的黑屏

把 DEMO.DAT、VOX.DAT 和 ZMOVIE.STR 复制到卡上后,屏幕变黑了:720 帧,0 次 panic,发送的图元为零。

关卡切换代码等待 GM_StreamStatus() == -1。过场的 DEMO.DAT 流从未推进,因为虚拟 CD 提供扇区读取,但不提供连续的环形缓冲区流式路径。在这些文件存在之前,该流在早期就被拒绝,一切照常继续。

当前的处理方式:

较小的 bug

性能

光栅化时间是指光栅化器中 esp_timer 计数器的值,在同一位置对 120 帧求和。

第一轮测试在 s07a,一个小房间。总光栅化时间从 923,000 降到 903,900,再到 794,000,再到 741,700 微秒(每帧从 7.69 降到 6.18 毫秒)。三个步骤:

  1. SOFT_RASTER_IRAM 在 MGS 构建中是空的,所以逐像素循环从 flash 运行。它应该是 IRAM_ATTR。修复后提升了 -2%。
  2. PSRAM 和 flash 运行在 120 MHz 提升了 -12%。 我最初得出结论,这块板子做不到。错误信息 “FLASH and PSRAM Mode configuration are not supported” 只是意味着缺少 CONFIG_IDF_EXPERIMENTAL_FEATURES=y。检查生成的 sdkconfig.h 中的 CONFIG_SPIRAM_SPEED 120。
  3. 扫描输出以 62.5 Hz 运行,而游戏是 30 fps。 一半的推送重复发送同一图像,每次读取约 120 KB 的 PSRAM,并驱逐另一个核心上光栅化器的纹理。匹配游戏帧率后提升了 -6.6%。

帧时间:s07a 中的光栅化在三个步骤中从 7.69 降到 6.18 毫秒,码头场景一帧为 40.9 毫秒光栅化加上约 25 毫秒逻辑,约 15 fps,目标是 33.3 毫秒

码头场景(s00a) 要重得多。在那里做的一次性能分析测得每帧 46,400 个纹理像素和 71,680 个平面像素:40.9 毫秒光栅化加上约 25 毫秒逻辑和 GTE,大约是 15 fps。README 目前给出码头场景带敌人的帧率约为 15 fps。状态文档按场景给出 8 到 15 fps,目标是 30。

平面填充的 32 位快速路径只提升了 2%。开销在于 纹理像素,每个约 207 个周期。2D 游戏在同一个光栅化器上运行快得多:瓦片地图沿直线遍历纹理,一条 64 字节缓存行可服务 128 个像素。在 MGS 的旋转三角形中,U 和 V 都逐像素变化,几乎每个像素都是缓存未命中。数据缓存已经达到 64 KB 的上限。

下一步 是将热纹理页移入内部 SRAM,状态文档估计这会快 40 倍。这需要释放困在过大 mts 栈中的约 90 KB(大任务 24 KB,其余 6 KB)。缩小纹理不是选项,因为 UV 已烘焙进模型。

加载 也很慢:从卡上加载 1.1 MB 约需 11.5 秒(大约 95 KB/s)。

搭建掌机

掌机接线:XIAO ESP32S3 Sense、ILI9341 面板、D0/D1 上的模拟摇杆、D2 上的六键电阻梯以及 D5/D7 上的两个直连按钮

组装好的洞洞板掌机:左侧是模拟摇杆,中间是按钮梯的电阻,底部是 XIAO

掌机由以下部分组成:

XIAO ESP32S3 Sense 盒子里有什么:带摄像头的板子、Wi-Fi 天线、排针和散热片(照片:Seeed Studio)

XIAO 的全部 11 个引脚都用上了。接线记录在 硬件指南 中。搭建笔记:

MGS 现在可以在掌机上启动、挂载卡、加载码头场景并运行而不崩溃,帧率 README 描述为与 Waveshare 板相似。

尚不可用的部分

下一步

  1. 调整 mts 栈大小,并将热纹理页移入内部 SRAM。
  2. 在 XIAO 上测量 120/120 MHz 内存时钟。
  3. 修复 RADIO.DAT 索引,然后检查电梯是否随之修复。
  4. 在虚拟 CD 中实现流式传输,以恢复过场动画和语音。
  5. 通过软件 SPU 添加音频。
  6. 移除调试探针。

结论

PlayStation 容忍类型双关、除零、越界读取和符号测试指针。现代编译器和 CPU 一个都不容忍。在这个移植中奏效的方法是,设计每一次测量,使其能够失败。


分享到:
David Montero

作者

David Montero

Creator of Velxio, the open-source circuit and Arduino simulator.

GitHub velxio.dev

相关文章


上一篇
《恶魔城:月下夜想曲》在 ESP32-S3 上原生运行
下一篇
222 个 Seeed Grove 模块现已在浏览器中运行