契约先行:冻结 contract.ts 后 CPU、PPU、主板三个 AI 会话并行开发,IF/IE 所有权这类契约盲区靠结构推导提前统一,集成零分歧。CPU 周期不查表,read8/write8/idle 三个记账点按真实总线活动累加,instr_timing 反向验证全部 500 条 opcode;blargg 结果文本经 $FF01/$FF02 逐位移出串口当裁判;差分对拍抓到的两个 bug 都在参考模型自己身上。952/952。PPU 用双 16 级 Pixel FIFO,另留逐行参考渲染器做差分 100 例逐像素一致,弹出节拍实测标定(空行第 k 像素于 dot 86+k 弹出),160 像素闸门是开发中最大的 bug。385/385。主板实现 CPU 预留的 readAt/writeAt T 级时序协议让 mem_timing 三连挂一夜翻盘;MBC1「类型含 RAM 但尺寸码 0」兜底 8KB 破解 halt_bug;性能基准挪进干净 node 子进程(vitest 模块包装有 3-8 倍放大)。整机 1439/1440,唯一红项 dmg-acid2 差 784 像素:右眼与下颌两条横带,期望深灰、实拍白。主板排除 CPU/总线/时序后移交,PPU 会话两个假设先后被证据杀死——mode 3 帧中写寄存器被 acid2 README 自证排除、WX 边界被探针证伪——最终反推出 pandocs 没写的真机规则:LCDC.5(窗口使能)下降沿把窗口行计数器 WLY 复位为 0,acid2 的眼睛全靠这条规则每帧归零重画。修法 4 行,新增 5 条回归(含两帧帧缓冲逐字节一致),gb-main 1445/1445 连续三次复现。整机 01-special 1.378ms/帧约 725fps,dmg-acid2 渲染相 0.127ms,已部署 https://gb-emu.pages.dev。
浏览器标签页里是一块 160×144 的灰绿屏幕。我把 dmg-acid2 的 ROM 拖进去,头几十帧是乱滚的条纹,然后一张脸站定了:眉毛、眼睛、咧开的嘴。这张脸不输出一行文字——它本身就是测试,窗口语义差一处,脸就变形。

屏幕背后是一台完整的 Game Boy(DMG):SM83 一条指令一条指令执行,Pixel FIFO 一个 dot 一个 dot 吐像素,主板把两者焊在同一根 T 周期节拍上。三个部件出自三个互不知道彼此存在的 AI 会话,第一次见面是在集成日。这张脸最初差的 784 个像素,是整个项目里最硬的一仗。
第四站:又一台冻结的硬件
「从零造机器」系列走到第四站:nand-computer 的软件栈、电路仿真器画出的 Hack 计算机、NES,这次是 1989 年的 Game Boy。同一套「契约先行、三会话并行」第三次落地,前两次的账都算过,这次要看的只有新问题。
选 DMG 的理由与 NES 一脉相承:规格冻结三十多年没人改一行,完工即封存,零维护。裁判也是现成的——blargg 测试 ROM 全家桶,加上 mattcurrie 的 dmg-acid2。任务书给 acid2 的定位只有一句:它是 PPU 的 nestest。
三部曲与契约盲区
开工前把 contract.ts 冻死:Bus、CpuState、SM83、PPU 四个接口,加上 4.19MHz、每行 456 dot、每帧 154 行的常量。三个会话逐字节照抄,谁都不许改;发现缺陷写偏差记录,不许现场协商。
| 部 | 职责 | 测试 |
|---|---|---|
| gb-cpu | SM83 全指令集、中断、T 周期精确语义 | 952/952 |
| gb-ppu | 三层渲染、LCD 时序、STAT 中断、Pixel FIFO | 385/385 |
| gb-main | 总线/Timer/MBC/主循环/Web UI + 三部集成 | 1445/1445 |
契约里有个谁都没写的地方:IF(FFFF)归谁所有。主板会话动工前从契约结构推出唯一可行设计——IF/IE 归总线存储,CPU 的 requestInterrupt 走「读 FF0F、置位、写回」,提前写进集成核对清单。事后对码:gb-cpu 的实现与这个推导一字不差,三方零分歧。契约盲区靠结构推导提前统一,比集成日吵架便宜得多。
另一处缺口是 PPU 没有中断输出通道,解法是给 createPPU 加可选第二参数 onInterrupt,不动任何既有签名——和 NES 那轮 nmiCallback 的先例同款。冻结契约唯一的自我修整方式,就是这种加法。
CPU:串口当裁判
cpu_instrs 不看屏幕。blargg 把结果文本按 bit 位移出串口:FF02(SC)写 0x81 触发发送,总线层逐位拼字符,就能抓出完整的 01:ok 到 11:ok。对模拟器作者来说这近乎奢侈——纯 CPU 加总线壳就能跑官方裁判,PPU 不必在场。
第一部的核心主张:周期数不查表。全 CPU 只有三个记账点,read8、write8、idle,各记 4T。LD A,(nn) 是 16T,因为它的总线活动恰好是取指、读低、读高、读数据各一次;RET cc 不成立 8T、成立 20T,因为不成立时省掉的是两次真实出栈。周期表是账本的输出而不是输入,这笔账随后被 instr_timing 反向对拍:500 条指令的实测周期逐条吻合。
全 opcode 枚举对拍(官方 244 条加 CB 页 256 条,条件类 taken/not-taken 各一遍,共 530 条)开工第一天就抓出 4 个真缺陷:RLCA/RRCA/RLA/RRA 漏实现、INC/DEC rr 少记内部周期、INC/DEC (HL) 多记、RST 目标算错。差分对拍的战果更有意思——它抓到的两个 bug 都在参考模型自己身上:独立书写的暴力版把寄存器 ALU 的码点映射转录错了位。主实现有 blargg 背书,裁判自己也要受审,两个独立实现互为对方的测试。
中断服务 20T 里藏着一个重叠:向量取指读到的就是处理程序第一条指令的 opcode,硬件在这里把取指与服务重叠。实现锁存这条 opcode,处理程序首条不再重复取指,step() 返回 20T 与下一条指令便宜 4T 同时成立。HALT bug 的因果链完整复现:IME=0 且中断挂起时执行 HALT 不真停机,PC 少走一字节,操作码被当操作数再读一遍,整条指令流错位。11 个非法 opcode($D3 之流)执行即锁死,此后每次 step 空转 4T。
几个钉子补全:EI 延迟用计数器建模,EI 置 2、每条指令边界递减——EI 后接 DI 直接取消悬置,EI;EI 第二条结束即生效,EI;HALT 停机结束时生效,全部有专项断言;DAA 在四象限金向量之外,再铺 400 组「以十进制算术真值为裁判」的 BCD 性质对拍兜底。
第一部还埋了一颗为集成准备的种子。mem_timing 的原理是拿 TIMA 当秒表,对出指令内 (HL) 读取落在哪个 T 周期——这要求计时器与总线访问在 T 级交错,而冻结契约的 Bus.read(addr) 没有时序通道。解法是契约外可选协议:总线若实现 readAt/writeAt(addr, tInStep) 就走它,否则回退普通读写,行为不变。当时看这扇暗门近乎多余,集成日它救了主板一命。
最终 952 条全绿,其中枚举 530、ALU 矩阵 178、CB 页 94、中断系统 31、blargg 官方裁判 14(cpu_instrs 01-11、instr_timing、mem_timing、halt_bug)、差分与模糊 12。CPU 单帧 0.21ms,吞吐 333M T/s,约 79 倍实机。
PPU:Pixel FIFO 和它的影子
第二部的硬骨头是 Pixel FIFO:BG 与 OBJ 各一条 16 级 FIFO,取指器每 2 dot 取一个 tile 的低/高字节,凑够 8 像素一次推入;精灵取指要把流水线冻结 6 个 dot,按槽合并进 OBJ FIFO;灰度不在入队时定,而在弹出时刻经调色板映射——行中改 BGP,切换点前后像素各用新旧映射。这个精确到 dot 的节拍手推三版都对不上,最后写探针实测标定:空行第 k 个像素于 dot 86+k 弹出,精灵区 94+k,测试按实测写边界、注释留推导。
开发中最大的 bug 是少一道闸门。FIFO 管线在 mode 3 内持续产像素,160 之外没有停止条件,一行最多「画」了 177 个像素,溢出部分写进下一行左侧——全帧测试互相覆盖,谁也看不出谁被涂了,一个行中读帧缓冲的测试才暴露。pandocs 那句「达到 160 就不再推像素」就是闸门本体。
STAT 中断最初按「模式切换事件就请求」实现,对照 pandocs 才发现真实模型是四个中断源电平 OR 成一条线、上升沿请求。改成线模型后,STAT blocking、LYC 掩蔽、DMG 写 STAT 毛刺全部变成自然推论——测试里写得出「LYC=100 把第 100、101 两行的中断沿全部屏蔽」这种断言。LY=153 的古怪也钉死了:前 4 个 dot 读 153,之后读 0。
还有一出自摆乌龙:窗口测试全军覆没,插桩到取指器内部才发现,想要的 bit6+bit5 是 0x60,写成了 0xB3——bit6 是窗口 tilemap 选择位,它为 0 时窗口内容恰好等于 BG 内容,看起来就像窗口没开。实现从头到尾是对的,错的是测试里的位常量。教训:位常量要么写二进制字面量,要么用命名位。
窗口与精灵的边角统一由计数器模型导出:WX=0 的左移、WX 1-6 的无文档地带、WX≥167 的天然隐藏,都无需特判;精灵绘制优先序按 DMG 规则是 X 小者胜、同 X 取 OAM 序小者,屏外 X 照样占用每线 10 个名额。
逐行参考渲染器是差分的影子:与 FIFO 共享同一套时序状态机,只有像素产出策略不同,100 例(95 随机加 5 压力)每例跑两帧、逐像素一致。差分有个前提条款——寄存器仅在 VBlank 修改。当时看是合理的测试域约定,后来它在 acid2 身上变成学费,这是后话。
交付时 380 条全绿;385 是修复轮再加 5 条回归之后的事。
主板:暗门、兜底与全家桶
主板前四个里程碑全程用 mock 顶住,不空等两个并行会话。11:19,三方 contract.ts 逐字节一致校验通过,拷贝、接线、全仓跑测。GB 的节拍和 NES 不同:CPU 的 1 个 T 周期就是 PPU 的 1 个 dot,Timer 和 Serial 挂在同一根节拍上。
第一个下马威是 mem_timing 三连挂。主循环按契约是「指令粒度」的,n = cpu.step(); for (i < n) ppu.cycle(),指令内所有总线访问看到的外设是同一时刻的快照,而真机上 TIMA 与指令内的读写交错在 T 级。破局点就是第一部埋的那扇暗门:主板实现 readAt/writeAt,每次总线访问前把 Timer/PPU/Serial 推进到访问时刻,指令尾余量由机器补齐。改完,mem_timing 一次性全过。
Timer 按 DMG 电路搭:mux、AND(enable)、下降沿检测,TIMA 溢出的延迟重载是一台四状态小状态机。pandocs 主页面与 obscure 页在「FF06 写 TMA」条目上互相冲突,按后来经硬件验证的 obscure 版实现——文档也会打架,仲裁标准是谁更新。
MBC1 的怪癖按 pandocs 逐条落地:00 到 01 的 bank 转译只作用于 5 位寄存器本身、小 ROM 上 bit4 置位可映出 bank0、mode1 低区换挡 40/$60,每条都有合成 ROM 测试盯着。集成本身几乎不等待——拷贝脚本可幂等重跑,源仓收尾期间重同步过一次,PPU 拷入后 380 条全绿。
blargg 的 halt_bug ROM 藏了个经典坑:卡带类型写 MBC1+RAM,RAM 尺寸码却是 0。真机上 RAM 芯片在不在与头部无关,而这个测试要把结果码写进 $A000。按社区惯例兜底:类型含 RAM 但码为 0,分 8KB。不兜底,结果码写不进去,测试永远红。模拟器作者与测试 ROM 作者之间的这种心照不宣,只能靠踩坑传承。
拷入代码原则上零改动。整个集成期对两部的全部修改,只有一条测试常量笔误(alu 测试里 0x8C/0x9C 应为 0x88/0x98)和 import 深度调整,逐条记进偏差记录。
性能测量还上了一课:同一份代码,干净 node 进程 1.4ms/帧,vitest 里测出 23ms——模块包装的稳态开销有 3-8 倍放大。基准挪进独立 node 子进程跑,测试护栏只管正确性。
Web UI 走极简路线,esbuild 打包单文件 43.7KB:
- 拖入 .gb 即玩,整数倍缩放 pixelated canvas,浏览器实测 60fps;
- 方向键/Z/X/Enter/Shift 对应按键,电池存档落 localStorage,存档逻辑是纯函数、可单测;
- 调试面板显示寄存器/LY/STAT/IF/IE/DIV/TIMA/TAC;
- 串口控制台实时滚动 blargg 的判词——裁判的判词直接打在页面上。
dmg-acid2 的对拍架子:预期图用零依赖解码器(node:zlib 解 DEFLATE、手写五种 PNG 行过滤器)转成 92160 字节的 RGBA 快照入库,整机跑 600 帧逐像素比对。跑完:1439/1440,唯一红项就是那张脸。
修复战:差 784 个像素的笑脸
差异收敛得异常干净:两条横带,x 在 88 到 127 之间,右眼 y∈[40,55]、下颌 y∈[112,127],各 16 行——期望深灰(170),实拍白(255)。首个不匹配像素 (88,40),恰是第一窗口行的第一像素。
主板会话先自证清白:FIFO/逐行差分 100/100 自洽、窗口单元测试全绿——但这只证明实现和自己的影子一致,而差分的前提条款恰好把 acid2 的核心场景划出了保护圈:这张脸靠 LYC-STAT 中断逐行改寄存器。13:15,移交线索写成三行:
- 排除项:CPU/总线/时序——mem_timing 全过,指令内总线访问 T 级对齐;
- 存疑项:双渲染器一致域「寄存器仅 VBlank 修改」没覆盖帧中的 LCDC bit5 与 WX 切换;
- 排查建议:帧中写 LCDC 关窗口时,本行是否立即收起、WLY 是否照常递增。
PPU 会话的纪律是先测量再改。探针逐指令步进整机、逐行采样 PPU 内部态(LY/WX/WLY/yCond,每行取 dot 24 到 100 之间的稳定窗口):
LY 40 wx= 95 wly=238 yC=1 ← 眼区首行:WLY 应为 0,实为 238
LY 55 wx= 95 wly=253 ← 本帧内每行 +1,行为正确
LY 56 wx=240 wly=254 yC=1 ← WX 改屏外:冻结,帧内语义全对
LY 112 wx=240 wly=254 ← 恢复前 WLY 应为 16,实为 254
结论一句话:帧内语义全对,跨帧累加错误。WLY——窗口的内部行计数器——在实现里永不清零,600 帧后眼区首行锁存到 238,折算 tilemap 第 29 行、一片空白 map,眼睛与下颌整段取出白色空 tile。逐行加一对,屏外冻结对,错的是没有任何事件把它归零。
两个假设先后被证据杀死。假设一,mode 3 期间帧中写寄存器的收起时机不对——被 acid2 自己的 README 证伪,原文写明它不在 mode 3 期间写寄存器,全部写入发生在 mode 2。假设二,WX 边界语义——被探针证伪,wx=95 与 wx=240 的触发与冻结行为帧内完全正确。
剩下的路只有一条:读懂 acid2 的帧级编排。右眼在行 40 到 55(WLY 0 到 15);行 56 把 WX 改到 240 隐藏窗口,WLY 停在 16;行 112 恢复,下颌从 $9840 续画(WLY=16);行 129 把 LCDC.5 从 1 清到 0。参考图逐帧稳定,意味着每一帧眼睛都必须从 WLY=0 重画——把整段编排翻遍,唯一的归零事件就是行 129 那次 bit5 的 1→0。
由此反推真机规则:LCDC.5(窗口使能)的下降沿把 WLY 复位为 0;WX 移出屏外不复位,否则下颌无法从 $9840 续画。这条规则 pandocs 没有记载;cgb-acid2 的姊妹规则「CGB 下 LCDC.5 清零同时复位 Y 条件」恰好是它的对照,两代机型的窗口状态机拼起来才是全貌。acid2 的作者显然清楚这条规则,整张脸就是为它设计的探针,眼睛全靠它每帧归零重画。
修法落在 gb-ppu 源头:writeLcdc 检测 bit5 的 1→0 跳变(LCD 运行中)就把 wly 清 0,共 4 行,集成副本逐字节同步。防线加在测试里:5 条回归复刻 acid2 编排——行 16 使能、行 40-55 眼、行 56 屏外、行 112 恢复并切回 9840 续画、WLY 直接观测(下降沿归零、屏外保持 16),外加一条两帧帧缓冲逐字节一致,那是参考图逐帧稳定的前提。
结果:gb-ppu 385/385,gb-main 1445/1445,连续三次复现一致;差分 100/100 保持,契约零改动,探针清除。
这一仗值得记的不是那 4 行代码,是它被找到的路径。380 条测试与 100 例差分都拦不住它:每个测试都从 reset 起跑,而这个 bug 要 600 帧累加才显形;差分的域约定又恰好豁免了触发场景。能钓出它的只有 acid2 本身。「一致」不等于「对」,一致的域之外没人在看——这是那 784 个像素真正的教训。
成绩单
| 项 | 值 |
|---|---|
| gb-cpu | 952/952;500 opcode 全覆盖;cpu_instrs 01-11、instr_timing、mem_timing、halt_bug 全过 |
| gb-ppu | 385/385;FIFO 对逐行差分 100 例逐像素一致 |
| gb-main | 1445/1445;blargg 全家桶 + dmg-acid2 逐像素对拍,连续三次复现 |
| 性能 | 01-special 1.378ms/帧约 725fps;dmg-acid2 渲染相 0.127ms;验收线 4ms |
| CPU 单独 | 0.21ms/帧;333M T/s 约 79 倍实机 |
| 产物 | esbuild 单文件 43.7KB,已部署 https://gb-emu.pages.dev |
第四站收工
诚实交代已知限制:
- 没有 APU——三部任务书都没排声音,FF10-FF26 读 $FF 写忽略,wave RAM 保留真实读写(它是 RAM);
- 没有 boot ROM,上电寄存器按 pandocs 注入(A=01、F=B0、PC=0100、SP=FFFE);
- OAM DMA 即时拷贝,640T 总线锁定不模拟;
- MBC3 的 RTC 是 stub,锁存协议完整但不走真实时间;
- WX=1 到 6 至今是 pandocs 都没定论的荒地,按计数器模型的推论实现。
回头看,这套「契约先行、三会话并行」的打法第三次被验证,而 dmg-acid2 那张脸是最贴切的徽章:模拟器最难的部分从来不是把功能堆出来,是把硬件那些没写进文档的习惯摸出来——这一次,它藏在一个寄存器位的下降沿里。
同一批还有三篇在路上:DEFLATE、JPEG、mini-Git,都是「冻结规格加对拍验收」这个路数的新变种。前一站:《把一台红白机装进浏览器:NES 模拟器三部曲》。
继续阅读 · 相关文章
根据文章内容的语义相似度自动推荐