Yakumo的355个代码Overlay深解:游戏如何在两帧之间热交换共享库
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 配置里:
0x0A001780 demo_sub、game_sub
0x0A055E80 P_m*/P_v* 地图
0x0A05E600 *_task 模式 Overlay
0x0A1BB000 em*m0 怪物……(共 12 个槽)
这就是难点所在:同一地址,在不同时刻装的是完全不同的代码。静态重编译在编译期生成的函数表无法覆盖"运行时才出现的地址"。Yakumo 的解法是——每个 Overlay 单独编译成一个共享库(.so / .dylib / .dll),运行时按图索骥地动态挂载。
预处理:每个 Overlay 变成一座共享库
构建阶段,build_overlays.sh 脚本做三件事:
- 抽取:用 databin.py 从
DATA.BIN中解出全部 355 个 Overlay 镜像; - 重编译:把每个 Overlay 的 MIPS 指令静态重编译为 C++(已有库的会跳过,脚本可断点续跑);
- 编译:在单次
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)。它的流程像一场精准的点名:
- 定位槽位:按 PC 找到地址落在哪个槽;
- 哈希比对:取该槽"64 字节头部 + 代码段"的 FNV-1a 哈希,与 355 个库逐一比对;
- 卸载旧代码:
unregister_functions()注销槽内上一个 Overlay 的全部函数(防止新旧代码串门); - 挂载新库:调用匹配库的
mhp3rd_register_overlay(),把新函数表装进同一地址区间; - 重试调度:钩子返回
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):
prepare_game.sh准备你的光盘镜像;generate.sh生成主程序重编译代码;- 运行
profiles/mhp3rd/scripts/build_overlays.sh——抽取、重编译、并行编译,可中断续跑; - 运行
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 时代最折腾的动态加载模型,变成了今天丝滑无损的原生体验。这正是静态重编译路线区别于传统逐指令模拟的魅力所在。
