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

这块板子是 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 硬件过去提供的一切都被软件替代:
- SDK。
- GPU。
- GTE 几何协处理器。
- CD 光驱。
- 垂直消隐中断。
- 手柄。
本文涵盖硬件、平台层、内存布局、调试方法、最关键的 bug、性能表现、掌机,以及目前尚不能工作的部分。
代码及相关项目:
- MGS 移植:davidmonterocrespo24/mgs_reversing,分支
esp32-port。 - 掌机硬件指南:HARDWARE.md。
- psyz 分支:davidmonterocrespo24/psyz。
你需要自备光盘。仓库中不包含任何源自游戏的内容,port/extract_disc.py 会从你自己的光盘镜像中提取文件。
硬件

ESP32-S3 拥有两个 240 MHz 的 Xtensa 核心和 512 KB 内部 SRAM。这里使用的两块板子还都配有 8 MB PSRAM,与 flash 共用同一缓存。
| Waveshare ESP32-S3-Touch-LCD-2 | DIY 掌机(Seeed XIAO ESP32S3 Sense) | |
|---|---|---|
| 屏幕 | ST7789,320x240 | ILI9341,原生 320x240 |
| Flash | 16 MB | 8 MB |
| 游戏数据 | microSD,或精简后的 STAGE.DIR 存入 flash | microSD(完整 STAGE.DIR) |
| 输入 | 通过串口的键盘(play.py) | 无人机云台摇杆、6 键电阻梯形网络、2 个直连按键 |
写代码之前先测量差距
在编写任何移植代码之前,我先测量了反编译项目距离能为 Xtensa 构建还差多远:
- 引擎库(libgv、libdg、libgcl、libhzd、libfs)几乎立刻就能用
xtensa-esp32s3-elf-gcc14.2 配合 psyz 头文件编译通过:58 个文件中的 57 个。 - 它们都不包含绝对的
0x800xxxxx地址。 - 所有图形输出都经过 11 个 libgpu 调用(
DrawOTag、LoadImage、ClearOTagR等)。这正是 psyz 软件渲染器所替代的那一层。
我故意留下唯一编译失败的文件 libdg/chanl.c 不去修复。那个本可以消除报错的强制类型转换,同时也会悄悄改变步长(参见下文关于排序表的章节)。
其余部分则通过机械化的批量处理完成,每一轮都解决一整类问题:
-std=gnu17和-mlongcalls都是必需的。GCC 14 默认的 gnu23 会拒绝这段代码,而 Xtensa 的call8只能覆盖 ±512 KB 的范围。- psyz 和 MGS 都有一个
common.h,因此 MGS 的 include 路径必须放在前面。 - 12 处将强制类型转换用作左值(GCC 2.x 扩展)的表达式被重写。
- MGS 用自己的桩函数替换了 libc 的
printf。我把它重命名为mts_printf,而这后来导致了最具有误导性的 bug 之一(参见“看似卡死的启动过程”)。 - 16 个文件中的 346 个字面量暂存器地址(
0x1f8000xx)被改为SCRPAD_ADDR + offset,由一个数组支撑。
结果是 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 之间有三层:
从游戏到硬件的各层依次为:
- MGS 引擎:反编译后的 C 代码,编译为 Xtensa
- psyz:用 C 实现的 PlayStation SDK 与 GTE,软件光栅化器
- 平台层:基于 FreeRTOS 的 mts 调度器、vblank 节拍、虚拟光驱、LCD、输入
- 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 位深度执行两遍基数排序:
divide.c按低字节分桶,并把高字节暂存在标签的长度字段中。sort.c按该高字节重新分桶,并写入真正的长度。
由于 psyz 将这两个字段分开,转换是精确的:
pack->tag = (hi << 24) | *ot; *ot = pack; /* PSX */
addPrim(ot, pack); setlen(pack, hi); /* psyz */
把 42 个局部声明和 100 个参数重新标注为 OT_TYPE* 是容易的部分。困难的是那些默认采用打包布局却没有明说的代码:
DG_PrimInfos把第一个顶点放在 +8,而不是 +12。LinkModelToParent预计算父顶点偏移时使用*52 + 8,而不是*56 + 12。- 下文“白屏”一节中描述的图元构造函数。
还有一个加剧问题的因素。在主机上,addPrim() 每次插入都会重写整个标签字,因此忘记设置长度永远不会被察觉。而在 psyz 中,从未设置过的长度就永远不会被写入。
FreeRTOS 中的 Konami 调度器
MGS 运行在 Konami 自己的协作式调度器上。启动横幅仍然显示 Multi Task Scheduler for PSX ver2.02 Jul 11 1998。它建立在 BIOS 线程 API(OpenTh/ChangeTh)之上,并使用 vblank 中断来唤醒定时器已到期的任务。
在移植中,每个 mts 线程都是一个 FreeRTOS 任务,并且同一时间只有一个任务处于可运行状态。最终设计如下:
- 所有 mts 任务都固定到核心 0,vblank 节拍也固定在核心 0,优先级为 10,因此节拍会像 PSX 中断那样抢占游戏。LCD 扫描输出运行在核心 1。交叉这些分配会导致竞态,使已停放的任务在栈中途被重新唤醒。有一份日志显示两个
Main()副本逐行交错执行。 - 新任务会在其 trampoline 中挂起自身。
xTaskCreate后接vTaskSuspend不是原子操作,在两个核心上,任务会在其控制块填充完成之前就开始运行。 - 临界区是真正的临界区。 每个任务都有一个绝对标志,在每次切换时像 MIPS 状态寄存器一样保存和恢复。它使用标志而不是计数器,因为游戏会调用
ExitCriticalSection而没有匹配的Enter。 - 节拍仅在空闲任务(11)处于活动状态时运行 mts 回调。 该任务是 Konami 的 SIO 控制台循环,是唯一从不触碰调度器状态的代码。在主机上,它正是出于这个原因在中断启用的情况下运行。游戏每一帧都会经过空闲,因此唤醒延迟保持在一帧以内。这一改动从根源上消除了间歇性挂起,而早期基于标志的版本只是缩小了竞态窗口。
mts_GetTcbEntry 还会读取固定地址 0x100 处的 BIOS 表之表,并通过结果进行写入。在 PSX 之外,该地址存放的是垃圾数据,因此现在改用私有的 TCB 表。
vblank 节拍与两个时钟
port/esp32_vblank.c 每 16 ms 触发一次游戏的 VSync 回调。这需要在 psyz 中实现 VSyncCallback(),而那里甚至没有存储该指针。
VSync(-1) 必须返回一个自由运行的 vblank 计数。第一个版本返回的是已呈现的帧数,当没有任何绘制时它就会停止递增,因此任何定时器都不会到期。
帧率会变化:走廊中每帧 2 个 vblank,开阔房间中为 4 到 5 个。因此,有两件看似属于 vblank 的事情实际上属于游戏帧:
- 串行按键保持在
DG_ActFirst中递减,紧跟在GV_UpdatePadSystem之后,这是唯一表示“某一帧已读取手柄”的位置。在那里计算 vblank 要么会让 Snake 走得太远,要么会在游戏看到按键之前就释放它们。 - LCD 仅在
DG_SwapFrame中递增的序列号发生变化时才发送一帧,并带有 250 ms 的回退。
内存布局
内部 SRAM 稀缺且快速。PSRAM 充足且缓慢。Flash 读取会禁用 PSRAM 同样依赖的缓存。
- 游戏的 RAM 映射挂在一个宏
MEM_BOTTOM上。两个数据包区域、堆和 libfs 扇区缓冲区都通过减法从它派生。它被重定位到一个静态 PSRAM 数组(mgs_main_ram[0xC9000],EXT_RAM_BSS_ATTR)。它必须是静态的,因为RESIDENT_BOTTOM被用作静态初始化器,这就排除了malloc。 - 1 MB 的 PSX VRAM 位于 PSRAM 中。如果没有
EXT_RAM_BSS_ATTR,dram0 会溢出约 900 KB。 - 任务栈来回折腾过。
- 来自内部 SRAM 的 32 KB 栈使第四次
xTaskCreate静默失败(参见“一个其实是 malloc 失败的优先级死锁”)。 - 移到 PSRAM 的栈可以工作,直到某个任务调用
fopen。Flash 驱动禁用缓存,任务失去自己的栈,SoC 在没有打印 panic 的情况下复位。 - 现在栈是内部 SRAM 中的 20 KB。高水位标记显示五个任务使用约 2 KB,一个任务使用 14,484 B。
- 来自内部 SRAM 的 32 KB 栈使第四次
- 类型错误的桩最终会进入只读 flash。
_spu_transferCallback是一个函数指针。把它声明为函数会将其放入.text,因此第一次= 0就会崩溃。我通过对一个可工作的基于 psyz 的 ELF 和这个 ELF 运行nm,用comm比较它们,并列出在那里是B/D而这里是T的符号,从而找到了它。
有一类 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 以绝对扇区为单位工作。它读取一次 ISO9660 目录,之后再也不使用文件名。port/virtual_cd.c 替换了 CD BIOS:
- 每个文件获得一个合成的 1,000,000 扇区范围,因此扇区号可以通过一次除法映射回(文件,偏移)。
CDBIOS_ReadRequest逐扇区交付数据,并在每个扇区后调用回调。回调可以重写剩余大小。FS_CdStageFileInit依赖这一点,从其前 4 字节得知STAGE.DIR表的大小。把请求当作普通的字节复制并忽略回调,会使每次关卡查找都返回NOT FOUND。- 交付必须是异步的。 解析器和“光盘”是共享同一个缓冲区窗口的协程。一次性交付所有内容会让文件 2 在被解析之前就覆盖文件 1。现在
ReadRequest只记录请求,而ReadSync会泵送扇区,直到回调返回 2(“缓冲区已重定向”)。
数据最初存放在 PSRAM 中,这使游戏只能加载少数几个关卡。真正的解决方案是 microSD。该卡是一个 SPI 外设,与 XIP flash 分离,因此读取它不会禁用指令缓存。文件留在卡上,不消耗 PSRAM。
- 完整的 71,892,992 字节
STAGE.DIR(全部 96 个关卡)按需读取。 - 在 93 个关卡文件中,65 个拥有完全符号化的 actor 表。其余 28 个仍保存原始 MIPS 地址,因为它们的 actor 代码尚未反编译。
- 一个生成器构建了一个去重的 actor 表和一个白名单:56 个关卡和 149 个 actor 类。脚本的关卡切换命令会在当前世界仍然完好时检查白名单。
该卡与 LCD 共享 SPI2,而 ESP-IDF 不会在它们之间进行仲裁。一个 LCD 帧是 30 个排队的异步传输,因此在一帧中间进行卡读取会触发 assert failed: spi_hal_iram.c:134 并导致重启循环。修复方法是显式的总线所有权(Mgs_SpiBusTake/Give),在释放总线之前排空正在进行的传输。
方法:测量,而非猜测
在这个项目中,大约三分之一的显而易见解释最终被证明是错误的。真正有效的方法是让开发板打印出一个数字,用来在多个假设之间做出判断。最有用的教训来自那些给出错误答案的探针:
- 一个没人递增的计数器会凭空捏造出一个发现。
[trap] scanning 63 triggers, 0 entered so far差点变成“触发系统已死”。那个计数器根本没有++。加上真正的递增后,触发器从第一秒就开始触发了。 - 同义反复的检查会带来虚假的信心。 骨骼审计比较的是
|R·t|和|t|。对于任何旋转来说这两者都相等,所以这个检查连续数周都是绿的,而实际上每个骨骼都是变形的(见“严格别名删掉了一个旋转”)。 - 在解读一个字段之前,先检查它在哪里被写入。
eye_inv.t看起来像相机位置,但其实是一个旋转后的方向向量。把它当作位置来读,产生了一个详细但虚假的、关于相机飞走的故事。 - 在数据收窄范围之前,让探针保持宽泛。 我把全屏图元探针过滤成了无纹理图元,理由是闪光没有纹理。但探照灯锥体是有纹理的。
- 按原因拆分计数器。 “65% 的接缝是陈旧的”把四种原因混在了一个桶里,而其中最大的那个是无害的根对象。拆分之后,我的修复触发了零次,于是我把它删掉了。
- 给所有 N 个写入者加插桩。 当
DG_UnDrawFrameCount = 0x7fff0000让屏幕变黑时,我猜错了两次。给四个写入者打上"file:line"标签后,立刻定位到了game/gamed.c:476。 - 在怀疑解释器之前,先解码数据。 码头的脚本看起来只运行了一条命令。解码零售版字节码后显示出 19 个节点,其中只有一个会打印(见“空码头是一个两遍脚本”)。
- 检查探针是否真的在二进制文件里。 一条显示“(nothing)”的面包屑从未被插入,因为一个脚本化的
str.replace静默失败了。用grep在.bin里搜这个字符串。 - 用硬件观察点抓流氓写入者。
esp_cpu_set_watchpoint(0, addr, 4, STORE)显示大约 230 次 GPU 失同步来自DG_PcxRead4Bpp,这是一个纹理解码器,其暂存缓冲区与活动数据包重叠了。 - 对突然的改善保持怀疑。 当存储卡挂载失败时,开发板回退到 flash 中的 9 个阶段,加载时间从 693 个 vblank 降到 21 个。这看起来像是 35 倍的加速,但这意味着存储卡不见了。先检查
microSD mounted和table_size 1152 -> 96 stages。
不烧录开发板也能运行每一次构建
这种方法只有在尝试成本很低时才奏效。经过几个小时的反复试错,每次改动后都去烧录开发板的成本并不低:通过 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

严格别名优化删掉了一次旋转
- 症状: 每个角色的手臂都与躯干分离,一条腿向后弯曲,双脚朝向各不相同。世界本身没有问题。
- 死胡同:
- 一个
MulRotMatrix的“修复”让情况变得更糟,随后被回滚。 - 模型步长,通过三种独立方式从数据中证明为 88 字节。
- 陈旧的接缝,实测影响为零。
- 一份冻结的静止姿态转储显示,全部 16 个关节与从光盘解码出的位置误差都在一毫米以内,每根骨骼的
det = 4096且d2 == want。
- 一个
- 为什么这些检查都没发现它: 在静止姿态下每个旋转都是单位矩阵,
d2 == want是恒真式,而det检查的是 3x3 块,那部分是正确的。 - 什么抓住了它: 两个不同帧中的关节位置。父到子的偏移逐字节完全相同,而父节点旋转了 19 度。
- 根本原因:
CompMatrix通过(VECTOR*)&tmp.t[0]在long[3]上写入平移量。GCC 14 在-O2下断定没有任何东西读取这些存储,于是删除了该调用。反汇编中没有任何乘法指令。 它计算的是m2->t = m0->t + m1->t。 - 修复: 使用
long long算术,不做类型双关,并为整个游戏加上-fno-strict-aliasing。libdg/display.c:318中存在第二个相同的情况,所以这个编译选项才是真正的保护。现在有一个[rig]审计,使用相对于最长骨骼的尺度不变比例来检查每一具骨架:共审计 14,416 个关节,0 个异常。
白屏:五个错误假设,三个真正原因
- 症状: 当敌人发现 Snake 时,一片白色覆盖了场景。HUD 仍然可见,还有颜色闪烁。
- 通过测量排除的假设:
- 全屏闪光。探针记录了 0 行。
- 将
change camera -1视为错误。它是“此处无固定摄像机”的哨兵值,把它当作错误处理会让摄像机冻结在玩家身后。 - 摄像机失控。那是误读的
eye_inv.t;真实位置是稳定的。 - 绘制队列溢出。一项剔除修复将绘制的模型从 25,093 减少到 14,054,白屏依旧。
divide.c中的setlen(pack, z_idx >> 8)。setlen会转换为u_char,所以它不可能产生像0x2E000000这样的长度。
- 原因 1:
SetDrawStp执行了((u_long*)p)[1] = 0xE6000000 | stp。在 psyz 中,第 1 个字是len,而该命令应放在code[0]中。读取端看到一个长达数十亿字的包,将其丢弃,并在图元中间恢复,把顶点当作命令来解码。它在战斗中触发,因为枪口闪光和烟雾正是开启半透明的东西。psyz 已经在自己的setDrawTPage中修复了同样的错误,但没有人审查过游戏侧的孪生代码。修复后:0 丢弃,0 失步。 - 原因 2:
DG_MakePrim从未初始化长度。通过推导len = psize/4 - 2并对照 psyz 宏检查结果(FT4 得到 9,GT4 得到 12,TILE 得到 3),在一处修复了它。 - 原因 3,缺失的硬件规则: 一旦把带纹理的图元包含进来,探针就显示
[cover] code 3E abe 1 tex 1 box -1024,-1024..142,66,这正是 GTE 的饱和极限。穿过摄像机后方的多边形会被钉在那里,变成横跨屏幕的四边形。PSX GPU 拒绝任何大于 1023x511 的多边形,而游戏依赖这一点。我们的光栅化器却把它们画了出来:每 120 帧 27.8 M 纹素,约每帧三个屏幕,光栅化耗时 142 毫秒。现在尺寸测试在soft_raster.inc.c中裁剪之前运行,因为裁剪会把多边形缩小到屏幕大小,从而掩盖正在测试的那个特性。
假设 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 操作码。“旋转这个向量”变成了“旋转它并加上陈旧的平移量”,而光照使用了旋转矩阵而不是光照矩阵。
修复后:
- 一步
27,0得以维持。 - Y = 250。
- 转向平滑。
- 每帧带纹理像素从 23,500 上升到 107,877。
- 水也回来了,因为它以摄像机位于水体体积内为条件。
空荡荡的码头是一个两遍脚本
码头只有少数几个对象组,脚本似乎只运行了一条命令。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 提供扇区读取,但不提供连续的环形缓冲区流式路径。在这些文件存在之前,该流在早期就被拒绝,一切照常继续。
当前的处理方式:
- 所有输入流都在
NewStreamControl中通过运行其回调被拒绝,并以 600 帧的看门狗作为安全网。代价是失去过场和语音,换来一个能玩的游戏。 - 过场录制的手柄输入会立即开始,Snake 会自己走开。现在这种回放会以游戏在 START 时跳过它的同样方式被跳过。
- FMV 也被拒绝,因为 psyz 没有 MDEC 解码器。
较小的 bug
PSX_W是 256,继承自我复用的代码。MGS 渲染 320 列,所以图像丢失了五分之一。审计每一个继承来的常量。- 启动竞态: tick 在驱动安装之前就读取 USB 串口,在 6 次实测启动中有 2 次导致
LoadProhibited。 - Konami 的丢帧器: 两个 actor 在不同时刻读取跳过标志,所以缓冲区在未绘制的情况下被交换,屏幕闪烁。在
__psyz下两个标志都被强制为 0。现在重场景会运行得更慢,而不是闪烁。 - “碰撞损坏”: 墙面推挤实测约 452,而半径为 450,这完全正确。在 8 到 10 fps 下,450 单位的修正看起来就像一次跳跃。
性能
光栅化时间是指光栅化器中 esp_timer 计数器的值,在同一位置对 120 帧求和。
第一轮测试在 s07a,一个小房间。总光栅化时间从 923,000 降到 903,900,再到 794,000,再到 741,700 微秒(每帧从 7.69 降到 6.18 毫秒)。三个步骤:
SOFT_RASTER_IRAM在 MGS 构建中是空的,所以逐像素循环从 flash 运行。它应该是IRAM_ATTR。修复后提升了 -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。 - 扫描输出以 62.5 Hz 运行,而游戏是 30 fps。 一半的推送重复发送同一图像,每次读取约 120 KB 的 PSRAM,并驱逐另一个核心上光栅化器的纹理。匹配游戏帧率后提升了 -6.6%。
码头场景(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)。
- 突发从 16 个扇区增加到 128 个扇区只提升了 7%。
- 在 Waveshare 板上,卡在 20 MHz 下可靠。在 40 MHz 下会出现 CRC 错误。
- 跳过冗余的
fseek调用已实现,但尚未测量。
搭建掌机

掌机由以下部分组成:
- 一块 XIAO ESP32S3 Sense,其扩展板提供 microSD 卡槽。
- 一块 ILI9341 SPI 面板。
- 一个无人机遥控器云台。
- 8 个按钮:6 个接在一个 ADC 引脚上的电阻梯,加上开火和瞄准各自独立的引脚,因为电阻梯一次只能识别一个按钮。

XIAO 的全部 11 个引脚都用上了。接线记录在 硬件指南 中。搭建笔记:
- 缺失的地线。 面板发白光,并在发送数据时改变亮度,因为它通过输入端的保护二极管给自己供电。在那之前,测量已排除了接线、复位脉冲、供电电压和 SPI 设置。我的一个 bug 还浪费了两轮:一个本应插入
lcd_bus_init()的脚本化编辑静默失败了,面板白白重新焊接了一次。 - 是 ILI9341,不是 ILI9488。 计划假设是 480x320 的 ILI9488,它在 SPI 下只接受 3 字节 RGB666。我之前一个使用相同面板的项目表明它是 320x240 的 ILI9341。这比计划更好:原生分辨率、无需缩放、每像素 2 字节。颜色顺序通过同时显示三条标注的 R/G/B 条纹来检查。
- RST 接在真实引脚上。 当 RESET 接 3V3 且只有软件复位时,ILI9341 无法可靠启动,所以 RST 移到 D4。D4 空闲是因为卡的 CS 是 GPIO21,位于 Sense 板内部。一次网络搜索给出了错误的 SD 引脚。错误是
ESP_ERR_INVALID_ARG,是配置错误而非卡错误,这指向了 Seeed 的官方文档。 - 按钮和电位器。 四脚开关要焊对角脚,否则一个按钮会一直读作按下。对于电位器:
- 读数固定在 0 或 4095 意味着线接在外侧脚上。
- 读数卡在中间刻度意味着电位器没有 3V3/GND。
- 范围宽意味着轴是健康的。
- 摇杆校准。 云台静止在 2317,不是 2048,X 从 141 到 2888。
- 中心是启动时的静止读数,每一半按该方向观察到的行程缩放。
- 死区是 60 个计数(约为测得 +/-15 噪声的 4 倍),两侧都减去,使运动平滑开始。
- 每个轴平均 8 次读数,两个轴在软件中反转。
- 自启动以来累积的最小/最大值在这里没用,因为浮空输入在上电时会触及 0 和 4095。使用滑动窗口。
- 在 vblank 节拍中读取 ADC 会冻结一切。 每节拍 24 次转换会阻塞节拍和每个 mts 任务。警告已经写在
esp_input.c中。现在核心 1 上的一个任务每 10 毫秒采样一次并发布三个整数。 - 通过原生 USB 的
printf会阻塞,当没有主机读取时(UART 不会)。MGS 打印很多,所以一次阻塞的打印会停止协作式调度器。port/mgs_printf.h以零超时写入。 - 时钟配对。 PSRAM 120 MHz 配 flash 80 MHz 不是受支持的 MSPI 配对,失败看起来像工具链 bug。XIAO 目前运行 80/80,120/120 是下一个要测量的。
- 面板 SPI。 用跳线时面板在 40 MHz 下稳定。在 80 MHz 下,图像会出现横向滑动的条带。
MGS 现在可以在掌机上启动、挂载卡、加载码头场景并运行而不崩溃,帧率 README 描述为与 Waveshare 板相似。
尚不可用的部分
- 编解码器通话。 417,792 字节的面部组现在从静态 PSRAM 保留区加载,因为游戏的池拒绝分配。
RADIO.DAT索引仍然是错的:计算出的起始扇区是 31,392,而文件有 867 个扇区。输入值是错的;算术没问题。启用真正的编解码器画面还会在printf内部崩溃。 - 开场。 从标题画面启动产生了 11 次崩溃。第一次崩溃前的最后一行是
this memcard is OK。游入和简报需要记忆卡、CD 流式传输和编解码器。 - 电梯。 两个电梯构造函数中的探针在整个会话中都保持沉默,所以舞台脚本从未请求它。可能的原因(尚未证实)是一个只有编解码器通话才会推进的剧情变量。
- CD 流式传输(过场动画、语音)、FMV(没有 MDEC)、音频 和 记忆卡存档。
- 28 个关卡,其角色代码仍是 MIPS 汇编。
- 性能 超过约 15 fps。
下一步
- 调整 mts 栈大小,并将热纹理页移入内部 SRAM。
- 在 XIAO 上测量 120/120 MHz 内存时钟。
- 修复
RADIO.DAT索引,然后检查电梯是否随之修复。 - 在虚拟 CD 中实现流式传输,以恢复过场动画和语音。
- 通过软件 SPU 添加音频。
- 移除调试探针。
结论
PlayStation 容忍类型双关、除零、越界读取和符号测试指针。现代编译器和 CPU 一个都不容忍。在这个移植中奏效的方法是,设计每一次测量,使其能够失败。