Yakumo的355个代码Overlay深解:游戏如何在两帧之间热交换共享库

原创2026-11-15 21:57:452,297 阅读

Yakumo的355个代码Overlay深解:游戏如何在两帧之间热交换共享库

Yakumo 是一个将 PSP 游戏静态重编译为原生可执行文件的模拟器项目(基于 Vulkan 与 SDL3)。它最精妙的部分,是把游戏运行时动态加载的 355 个代码 Overlay 逐一重编译成 355 个独立共享库——当游戏换装其中任意一个时,Yakumo 就能在两帧之间完成"热交换",把对应的新库悄悄装上,全程不卡一帧。本文带你从原理到实现,完整看懂这套机制。

什么是代码 Overlay?为什么是 355 个

PSP 游戏(Yakumo 的目标是《怪物猎人 P3 HD》)的主程序只负责"骨架"。模式任务(game_task、lobby_task)、地图(P_m*、P_v*)、怪物(em*m0~m3)和武器(we*player00~03)等大块代码,都是以 Overlay 文件(*.ovl)的形式存在光盘归档 DATA.BIN 里,运行时才被拷入内存执行。

关键设计:全游戏只有 12 个固定的内存槽位,355 个 Overlay 轮流共享它们。地址列表直接硬编码在 profile 配置里:

📍 kOverlaySlots 槽位表

0x0A001780  demo_sub、game_sub
0x0A055E80  P_m*/P_v* 地图
0x0A05E600  *_task 模式 Overlay
0x0A1BB000  em*m0 怪物……(共 12 个槽)

这就是难点所在:同一地址,在不同时刻装的是完全不同的代码。静态重编译在编译期生成的函数表无法覆盖"运行时才出现的地址"。Yakumo 的解法是——每个 Overlay 单独编译成一个共享库(.so / .dylib / .dll),运行时按图索骥地动态挂载。

Yakumo PSP 游戏重编译项目:355 个代码 Overlay 被编译为共享库并实现帧间热交换

预处理:每个 Overlay 变成一座共享库

构建阶段,build_overlays.sh 脚本做三件事:

  1. 抽取:用 databin.py 从 DATA.BIN 中解出全部 355 个 Overlay 镜像;
  2. 重编译:把每个 Overlay 的 MIPS 指令静态重编译为 C++(已有库的会跳过,脚本可断点续跑);
  3. 编译:在单次 cmake --build 中并行编译 355 个库到 bin/overlays/。

整个流程首次约需 40 分钟。每个库只导出两个 C 符号,构成极简的"宿主 ↔ 库"ABI:

  • mhp3rd_overlay_info() —— 报出元信息:槽位基址、大小、代码段大小、FNV-1a 哈希和名字;
  • mhp3rd_register_overlay() —— 把该库重编译出的全部函数注册进运行时。

这套 ABI 定义在 overlay_module.hpp,库的入口由模板 overlay_module.cpp.in 生成。设计意图写在注释里:库放在可执行文件之外,意味着"新增一个 Overlay 的成本只是编译它自己的源码,什么都不用重编"。

热交换瞬间:一次"指令缓存刷新"就是换装信号

运行时最巧妙的部分,是如何知道游戏刚刚装好了新代码。

PSP 的规矩是:把代码拷入内存后,必须刷新指令缓存(icache)才能执行。游戏每次加载 Overlay 后都会调用 sceKernelIcacheInvalidateAll 或 sceKernelIcacheInvalidateRange——Yakumo 的 HLE 层就"劫持"了这个调用当作换装信号(见 hle_system.cpp):

游戏拷贝 Overlay → 调用 icache 刷新(HLE 拦截点)
   → forget_unmatched_overlays()   清除"无库可配"的缓存
   → revalidate_overlays()         复核每个已挂载槽位还是不是原来那个库

此外,在每一帧呈现之前(present_frame),宿主也会对已挂载的槽位做一次复核——注释原话就是"Overlays are swapped between frames"。校验发生在两帧之间的空隙里,游戏画面完全无感。

调度未命中钩子:真正的"装库"动作

当游戏第一次跳入某个槽位、而运行时的函数表里查不到地址时,"未命中钩子" missing_function_hook 被触发(overlays.cpp)。它的流程像一场精准的点名:

  1. 定位槽位:按 PC 找到地址落在哪个槽;
  2. 哈希比对:取该槽"64 字节头部 + 代码段"的 FNV-1a 哈希,与 355 个库逐一比对;
  3. 卸载旧代码:unregister_functions() 注销槽内上一个 Overlay 的全部函数(防止新旧代码串门);
  4. 挂载新库:调用匹配库的 mhp3rd_register_overlay(),把新函数表装进同一地址区间;
  5. 重试调度:钩子返回 true,分发器原路重试,这次跳入的就是刚装好的原生代码。

整个过程发生在一次函数调度的间隙,代价微秒级。控制台会看到一行日志:[overlay] installed game_task (… KiB) at 0x0A05E600。

双哈希识别:64 字节头部让检查"近乎免费"

为什么能用哈希认出"当前装的是哪个库"?每个 Overlay 镜像以魔术字 MWo3 开头,跟着 64 字节头部(镜像 ID、加载地址、代码/数据/BSS 大小、32 字节名字)。游戏只写数据段,从不改头部和代码段,所以这段字节是天然的指纹。

但给一整段内存反复做哈希太贵(README 估算约 1 MiB 级代码)。Yakumo 用两级哈希优化(revalidate_overlays):

  • 第一级:只哈希 64 字节头部,和上次记录的头部哈希比对——不同 Overlay 的头部必然不同,绝大多数调用在这一步就放行了;
  • 第二级:头部变了才做全量"头部 + 代码"哈希,确认真的换库了。

还有一个鲜活的优化案例:被 mod 补丁改过的 Overlay(如打过补丁的 demo_task.ovl)永远匹配不上任何库,若每次调用都重新搜索哈希,游戏菜单速度会从 100% 掉到 10%。于是用 unmatched_slots 表记忆"这个槽位已经搜过了",游戏重新加载代码时再遗忘(forget_unmatched_overlays)。

兜底方案:解释器保证游戏永不卡死

万一某个 Overlay 没有预编译库(mod 深度改码、新游戏版本等),运行时不会崩溃:外层分发器会转交解释器逐指令执行那段代码,只是约慢 20 倍。也就是说,355 个库全齐时全程高速,缺库时降级为"能玩但慢"——这正是 ARCHITECTURE.md 里描述的"解释器兜底"模型。

若发现未知 Overlay,设置环境变量 MHP3RD_DUMP_OVERLAYS=<目录>,运行时会自动把它从内存中 dump 出来,提示你用 add_overlay.py 重编译补库。

自己动手:构建全部 355 个 Overlay 库

源码构建的完整流程(见 profiles/mhp3rd/README.md):

  1. prepare_game.sh 准备你的光盘镜像;
  2. generate.sh 生成主程序重编译代码;
  3. 运行 profiles/mhp3rd/scripts/build_overlays.sh——抽取、重编译、并行编译,可中断续跑;
  4. 运行 out/mhp3rd/bin/Yakumo。

各阶段耗时、断点续建原理等细节,可查 docs/BUILDING.md 与 docs/DATA_BIN.md。

小结:一张表看懂热交换全流程

阶段 触发点 动作 源码
换装信号 游戏刷新 icache / 每帧呈现前 复核已装槽位是否仍是同一库 hle_system.cpp
首次跳入 分发未命中钩子 槽位定位 → 哈希匹配 → 卸载旧函数 → 挂载新库 → 重试 overlays.cpp
识别机制 头部 64 字节 + 代码段 两级 FNV-1a 哈希 overlay_module.hpp
兜底 无任何库匹配 解释器执行,降级但不中断 ARCHITECTURE.md

355 个 Overlay、12 个槽位、两帧之间完成替换——Yakumo 用"预编译库 + 运行时哈希识别 + 调度钩子"三板斧,把 PSP 时代最折腾的动态加载模型,变成了今天丝滑无损的原生体验。这正是静态重编译路线区别于传统逐指令模拟的魅力所在。

登录后查看全文
Yakumo