The retail kernel differential: run the game's own routine beside its port

At a glance

Coverage. 765 of the 1043 retail addresses a // PORT: tag names (73.3%) are run by a differential; 554 tests run 783 retail routines in all. Generated from the tests' declarations by scripts/ci/update-progress-metrics.py, and ratcheted by differential-coverage.py --check.

Where it sits among the project's other checks, and what it cannot see, is the verification ladder.

What it can run

Integer instructions, hi / lo, unaligned loads and stores, RAM and the scratchpad. A routine with no break guard can run a div by zero as the chip does (Cpu::hardware_zero_div), since that result is what ships. COP0 carries its register moves and rfe; anything else there, or a syscall, stops with Stop::Unsupported.

The GTE is psx_retail_exec::gte: both register files with their quirks, every command, the 44-bit accumulator with its overflow flags, the FLAG saturation bits, the UNR divider and the MVMVA far-colour bug. It is written from the hardware documentation, not from the engine's GTE, so a defect the two shared could not cancel. Unit tests pin hand-worked spec values; gte_capture re-runs the RTPS / RTPT / NCLIP / AVSZ commands the PCSX-Redux state library's register files hold and lands on their outputs; gte_engine holds the engine's live divide and its light-source NCCS kernel to it with no disc.

• Cpu::hook replaces a call, which is how rand() is scripted so both sides draw one stream.
• Cpu::calls records the calls made, which is how a test proves it reached the arm it claims.

How to add a routine

1. Read the disassemblyFind what it reads and writes. Seed those bytes with the shapes a game reaches, including the caps and the empty cases.
2. Compare whole regionsA write the port does not know about is exactly what this is for, and a field-by-field test cannot see one.
3. Assert the armsHold that the run reached the interesting arms, so a seed change cannot leave the test passing on nothing.
4. Declare the routineOpen the test with differential!(scus(VA)) or differential!(prot(ENTRY, VA)), naming every routine it compares. A test with no declaration fails the coverage gate.

Declaring what a test runs

Every test opens with differential!(..), naming the routines it compares as scus(VA) or prot(ENTRY, VA), or with not_a_differential!("why") when it compares a table and runs nothing. Each argument is a literal or a const of the test file, so the declaration reads without compiling anything.

• The run checks the declaration. Cpu::call notes every entry it runs, with the bytes there, in a thread-local ledger. When the test passes with the disc present, the macro's guard fails it unless each declared routine was entered and its bytes are the named image's. A wrong address, or the right VA in the wrong overlay, fails the test that carries it.
• The count needs no disc. scripts/ci/differential-coverage.py reads the declarations and the // PORT: tags and reports how many tagged addresses a differential runs; --check fails on a test with no declaration or on coverage below its baseline, in the pre-commit hook and in CI.
• Other tools read it. The port catalog carries a differential column and a --no-differential worklist; the provenance checker counts a differential-run address as verified.
• The declaration can be derived. --record runs the suite with the ledger written to target/ (it holds the executable's bytes, so it is never committed), --propose names each entered routine's image off extracted/, and --apply writes the missing declarations.

The credit is per address: a passing differential proves which routine ran and that the kernel the test calls computes what it wrote, not that every tag carrying the address sits on that kernel, nor that every arm was reached.

What it has found

Every row was a disagreement between the bytes and a port that read as finished.

Several routines matched on their first run, which is a finding too: the Magic list's probe FUN_8003053C (it greys a spell row and refuses its cast), the menu stat block behind the Status page, the Equip compare and the shop preview draw (FUN_801CF5D0 / FUN_801CF650), the scene record dispatcher FUN_8003BDE0 over every such record of every scene on the disc, the camera zone ramp FUN_80037018, and the field walk-regen tick FUN_801D0B90 (the step counter, the HP / MP / AP Walk bumps with their clamps, a fallen member’s bump, and the Incense window’s wear-off edge). The battle cue router FUN_8004FE5C, the escape timer’s HUD actor FUN_801D2EBC over whole countdowns, the death arm of FUN_8004AD80 and the MP-cost leaf FUN_80035394 match. The death arm's table test leaves out row 0xBF, which holds the neighbouring table's [9, 0]: retail would add item 0 there and the port refuses it, and a second test holds that no shipped monster reaches such a row. The field follow camera's ease FUN_801DB510, its composer FUN_801DAB90 and the focus edge clamp FUN_801DAA50 match over generated parameter blocks of every camera mode. The overlay colour tween FUN_801DDC20 took its ramp progress as a word where the bytes take a halfword, which only a negative delay no shipped script seats can reach; the SCUS fade actor's tick FUN_80025000 matches, and so does a fade loaded through FUN_80020B00 and played tens of thousands of frames past its end, except at a zero duration, where the loader's unguarded divide lands the fade on its target at once and the port had divided by one. The battle overlay's two scans of a caster's spell list, the already-known Seru test and the summon return's “No effect.” pass, match but for a byte-wrapped compare no game reaches. Run over every distinct field-VM instruction on the disc for what it stores into its context, the VM wrote op 0x4B's keyframe count one byte off (+0x6D for +0x6C), kept the half-tile bit in op 0x23's tile bytes, and cleared the minigame warp's walk lock on the context running the script instead of on the player. Stepped on the real engine rather than an inert host, the seat op 4C 51 matched on every tile but the off-map hide box, which the engine ignored: the Rim Elm blackboard's tour now parks the villagers round the map as retail does, and its re-seat brings them back.

The per-art attack camera FUN_801D71B8 and the framing cases of FUN_801D5854 run against their ports in attack_camera and battle_framing: they found the art 0x1A arms' target fade unported, case 7's midpoint truncating where retail floors, case 8's Normal and scripted-fight arms missing, and the far framing's box built over fallen seats. The HUD glide stepper, the ledge-hop probe, the typewriter count and the cast dispatchers match.

With the GTE in, MulMatrix FUN_8005B3A8, the Euler builder FUN_80026988, the overworld curvature table FUN_800271A8, the drop shadow's grid FUN_800460AC and packets FUN_8001C394, and the billboard projector FUN_800195A8 match their ports.

The field-to-battle transition runs off the disc packet for packet. Its particle fields (FUN_801CFDA0, FUN_801D0370) rounded every per-frame step toward zero in the port, where retail’s shift floors. Its tile shatter (FUN_801D0D24, FUN_801D0E54, through the SCUS dispatcher FUN_80043390) drew every flying tile at full brightness: a tile that has started to move dispatches on the depth-cue bank, which fades it toward black by its progress and drops a quad wholly off screen. The swirl’s early submit FUN_801D1A20 rides the same bank, linking each quad at its deepest corner, and drops an edge-on quad even double-sided. The late swirl, which retail draws through the shatter renderer, is not carried faithfully.

The field camera build FUN_800172C0 and its single-point RTPS FUN_8003D368 match an integer port of the camera matrix. The framebuffer grab and the drop shadow had projected through the hosts’ floating-point view, which missed retail’s screen point on nearly every point by a pixel, and by far more near the eye; both now project through the integer camera. The procedural mesh builder FUN_80028158, the field frame blender FUN_8001BE80, the camera-relative glide FUN_80021248 / FUN_8002149C and the field-entry camera reset match.

The battle weapon trail runs whole: the band emitter FUN_800485BC with the billboard projector live beneath it, its sweep driver and its trigger. The emitter keeps the projector’s last corner, a view unit right and down of the control point, through the integer battle matrix; the port had projected through the hosts’ floating-point view, a pixel off on about one point in twenty, and now projects as retail does.

The op-0x45 camera mover’s tick FUN_801DC0BC stores nine of its ten pairs: focus Y holds through a glide, where the port walked it to the beat’s target, and the tick re-rolls the shake about the mover’s own pose, which the port skipped. The arming routine works on halfwords. The tween builder and the shake match.

The transition’s seeders, run with the production environment, showed its sine and cosine tables swapped, so every particle and tile tumbled about the wrong axis and the swirl’s rings were built transposed; the heading and the root were floating-point stand-ins for retail’s bearing and root. All four seeders now match given the same draws, and the draws are the game’s own: its one rand() stream, taken where the transition’s setup finds it.

The battle monster loader FUN_80055468 uploads a whole 256 x 1 CLUT row, whose last sixteen entries are the page’s first halfwords; the port wrote fifteen palettes. The party battle mesh’s splice, post-pass and texture relocation, the TMD registrar, the sprite arm and the visible-tile crop’s decoration pass FUN_801F7088 match. The PsyQ St sector ring matches over generated movies, except that a header claiming zero chunks never completes its frame in retail.

The anim-node cursor FUN_80047430, its readout ramps, the tint machine, the pose decoder FUN_8004998C, the walk among seated actors, the hop arc and the action effect stepper FUN_801DEA50 run against their ports; the cursor differential found a Slowed idle under slow motion still advancing at a fraction retail drops.

The battle side's frameless kernels run on their own too. The cast roll's scale stage FUN_801DD864 matches over every seat pairing, both weaken bits, the Spirit stance and the summon body's magic level, but its products wrap at the word where the port saturated. The group aim FUN_801DCEAC floors a spread read back as a halfword, so a spread past 0x7FFF takes the floor; the body colour pass FUN_8004A908 scales a depth-cue channel over whole words where the port truncated to 16 bits. None of the three is in a staged fight's reach. The Seru learn, the magic-level line, the swing camera height, the popup ring, the cursor step and placement copies, the Super tail replace, the learned-art check, the monster install with both boost profiles, the dead-target redirect, the arts flash ramp, the cast-start cue, the attach swap, the chip marks, the arts pager, the cue-group expander, the target banner, the bolt ribbon with its generator, the near-camera ghost pass and the clip interpolator match on their first run.

The field and menu side runs too. The CLUT-cell HSV writer FUN_80019D50, behind jou's pulsating flesh, repacks each texel with an add where the port used an or: under a white-blend amount below zero, which op 0x44's signed velocity can reach, a negative channel carries into its neighbour. Everything else matched on its first run: the system flag bank and the field VM's operand loaders, the actor node pool, the MAN record resolver over every scene, the pad's camera remap and wall-slide resolver, the walkability probe and the elevation lookup over every field map, the camera height ease, the floor-ladder oscillator, the eased move and their spawners, the camera-zone loader and re-query, the property-ramp pool, the morph envelope and clip cursor, the arc hop, the fog emitter and spawner, the world map's entry fade, the L1 map display, and the menu overlay's category check and preview mode.

The sound driver's per-frame tier runs in the interpreter too: libsnd's SsSeqCalc FUN_80062F98 with its tempo slide, volume slides, track end, transport arms, event decoder and delta-time pump; the voice chooser FUN_80066B00; the key-on volume chain FUN_80067550; the key-on and bend pitch; the SEQ slot release. The volume slides cached their pair unclamped where retail reads it back through the set's 0x7F clamp, and the ascending fast arm wrapped a halfword where retail sums 32 bits.

So do libsnd's per-voice walks, stood on one voice file with the port's sequencer: the note-off FUN_8006688C, the bend FUN_80067C1C, the CC7 / CC10 re-volume FUN_8006861C, the sequence-volume walk FUN_80067E9C, the flush's envelope read and silent history FUN_80065BAC, the explicit cue key-on FUN_80065034 and the game's BGM pause FUN_80026740. Each run seats a random record file on both sides (notes of the sequence sounding or released, voices a cue took, records another sequence owns) and compares the shadow registers and dirty bits each walk writes with the port's voices. They agree; the two differences left are a second key-off of a voice already releasing and a pause that keys off a vsync sooner under a level already zero, neither audible.

The slot-B stagers, the routine a module’s parts reach through move-VM op 0x20, run arm by arm off their images (stager_spawns, stager_states): every seat call, each seated part’s buffer, the module image, the fades and the pool spawns. PROT 0959’s arm 1 reaches arm 5’s tail by j 0x801F87A4 and seats two records the port left off; Spoon’s and Steal’s arm 1 spawn into the efect.dat pool, which no port carried; Gizam’s arm 1 stores the creature’s tint word 0x3FF00000, which the port dropped; and Evil Seru Magic’s stager arm 4 opens on Juggernaut’s salmon flash and camera shake, which its host never raised.

The capture-class cameras (capture_cameras) run every ported director’s body pass by pass, comparing each pass’s tween builder call, countdown word and hold. Water Hazard’s and Mystic Circle’s arm 0 turn the caster onto its target before framing it; Melt Spray’s and Chaos Flare’s arm 2 turn on the victim’s display pair; Stone Circle’s arm 1 cuts to the origin. Dead End Crisis’s arm-0 line-up and its restore now have a port and a differential of their own (dead_end_crisis), as does Juggernaut’s stager arm 7, which fans the Dark Eclipse rays off three rand()s.

The phase-chain tick bodies (chain_ticks) run from arm 0 to their Done against the port’s whole pass: the chain runner, the camera director on every pass, the caster pre-pass and the party-row and hit rates, over the whole context and all eight records less the bytes another owner writes. Dead End Crisis’s arm 5 holds the party at rate 2 where the port froze it, which stalled the engine’s Done band for some 1800 ticks after Final Crisis; Genocidal Cannon slows its struck seats; Megaton Press freezes a victim on its +0x1F2 clip; Hyper Lightning’s arm 7 left a pass late; and a replayed caster’s return to idle belongs to the runner. The summon tick bodies’ phase walks match but for Water Crystals, whose arm 5 is terminal.

The LZS decoder FUN_8001A55C matches over every container section on the disc. The SCUS root FUN_8005AF0C under the fishing lure counted a negative input's leading zeros where the GTE's LZCR counts leading ones. The field animator's sampler and angle lerp, the "ME" art-animation reader and codec, the VDF morph, the MAN section-0 carve and motion-script installer, the slot machine's LCG, landing search and marquee, the fishing prize gate, the coin counter's panel, the publisher-logo quads and the mode table's handlers match.

The battle routines too large to run whole run arm by arm. The Triangle arts-list driver FUN_801D3444 latches its View Hyper Arts list caption, and the latch keeps it up while a list closed just before the entry ended slides out; the port now draws it. The after-image walk FUN_80049348 divides by the anim rate with no guard, so a frozen actor casts no ghost, and a monster at rate 1 samples depth 16 where the port clamped to 15. The damage finisher FUN_801DDB30, called on its own with the two rolls, matches on the value, the Stone nullify, the strip, the rumble and the summon XP, but its Spirit fill caps a halfword, so a big hit on a tiny max HP can wrap the gauge under the cap. The Final Heal sweep FUN_801E6968 keeps the ability bit when no Lost Grail was spent; the multi-cast readout FUN_801E805C draws a five-digit row's cells fourteen rows tall; the result build FUN_801D84C0 publishes one buffer into two placement records. The side-band tick, the battle floor's grid with every packet, the per-actor draw, the per-hit numeral and the arts-entry chip build match.

The menu side runs through a window-VM harness: the interpreter FUN_801D6628 with its SCUS window-list helpers live, every program the menu overlay holds chained at random, the whole list compared node by node. The port's window model created windows with the wrong style byte, never computed the screen edge a window slides in from, and closed a sliding window from frame 0 where retail reverses the slide. With the helpers live, the small sub-screens that wait on them run frame by frame: the pause menu's ready check stepped on Left and Right and stopped at the ends, where retail wraps two rows on Up and Down and tests confirm before any move. The casino prize counter FUN_801DC1CC commits a redeem on the frame after Yes, which the port did on the press itself, and the menu's decimal writers FUN_80034B78 / FUN_80034E4C print a value wider than its field digit by digit from the pen, where six copies in the port stacked the overflow on one cell or cut it to the field.

A second pass over the field side. The move VM FUN_80023070, run over random programs, does not end a frame on an opcode past 0x46 or on 0x0B: both land on the loop's epilogue, which skips the word by the width the previous opcode left behind, where the port stopped the frame or spun. Op 0x46 stores three words where the port wrote two halfwords. Its overlay escape FUN_801D362C, every sub-op against a host answering each global from the same RAM, saves and restores the 8-byte position vector, pad halfword included, where the port carried a different word in that slot; the Bezier it calls splits each weight into whole and fraction in 32-bit words, which the port now transcribes. The property-ramp ticker walks its ramps in install order, so the newer of two ramps on one value stands; the port walked slot order. The motion VM's player box and wander fan, the party-table rebuild that seats Terra, the field actor cull and the sub-area window rebuild over every field map match.

The field side's leftovers. The fog pass FUN_8003F348 / FUN_8003F3FC / FUN_8003F86C, run record for record and packet for packet, now projects through the integer camera: through the floating-point view fewer than one sheet in twenty landed on retail’s corners, a particle behind the eye was dropped where retail draws its saturated corners, and the overworld’s cull test bent all three corners where retail bends one; a map01 capture’s 104 sheets went from 6 to 103 exact. The battle effect pool (FUN_801DE914, FUN_801DFDF0, FUN_801E0080) writes an effect’s random spawn offsets into the shared script, so a second spawn re-deals an earlier one’s children, and stands still once the battle-end byte is down; the port kept the offsets per spawn and kept walking. Of the PROT 0900 screen widgets, the image panel draws its targets, so a zero-length move shows at once where the port kept the old position, and the scripted sprite tests its opcode byte only on entry. The entity tick FUN_801DA51C blocks the player’s movement during an activation, not its own, and hands the encounter roll the BGM poller’s answer. The move VM’s sub-op 0x29 writes and ramps a rung of the floor-height ladder, which the engine had stored where nothing read it. The mask, the letterbox and the shared tween match on their first run.

A pass over the menus and the save path. The shop’s quantity spinner FUN_801DBC5C re-arms its list result on the frame it settles, so that frame never routes; the port routed on whatever the word held. The mode select’s Buy row clears only the staged item, quantity and list result, not the staged slot. The sprite-descriptor dispatcher FUN_800198E0 ends every upload by recording the texpage’s CLUT row in the table at 0x8007BEC0, which the port skipped, and wraps its strip width at 16 bits where the port saturated. The slot add FUN_80042FE8 refuses a slot past the window’s end; the first-live-monster scan FUN_801DB8B4 falls through to the fifth monster’s seat. The save composer FUN_801E1934, the equip applier FUN_801E5A08, the root picker, the Use list, the notify window, the Options popup, the card drivers, the list-row resolvers and the cold reset match on their first run.

The STR overlay runs from frame bytes to the MDEC word list. Its Iki converter FUN_801D0378 and the table’s LZSS FUN_801D0604 match the port word for word over frames of all six movies; the port’s decoder now goes through that list and a separate MDEC stage, as retail does, with the pixels unchanged. The STRv2 decoder FUN_801D070C, one-shot and resumed in chunks, its table unpacker, the play loop’s context, frame poll and slice callback, the stream open and frame pump over the nine retail cutscene slots, and the MDEC sync routines match.

So do a set of system and render leaves: the boot SPU-base seeder, the fade ramp step, the rumble actuator, the scene-name sync, the prompt line counter, the gouraud colour spread, the display mirror, the battle intro’s style pick and quad builder, the CLUT-walk shimmer stepper, the placement spawner’s model-bank select, the field-load entry step, the sustained-cue teardown and the battle XA seek-ahead.

The move-FX streak ribbon FUN_801E1D98 grows its first segment above the bottom quad whatever the baseline: the chain loop is a do-while, and the port tested first, so a ribbon whose bottom quad sat at the screen top drew one segment short. Its single-quad sibling, the cast colour wash, Swordie’s split panels and slash streak, and Deadly Rain, run frame after frame on the real GTE, match.

A pass over the format readers and the cast band. The battle-stage stream walker FUN_8001FE70 copies its lead chunk whole and type-tests only the chunks after it, so a lead of type 0x02 does not end the walk, where the port’s walk stopped on it. The boot loader’s PROT TOC read, the CDNAME table loader, the scene-entry script install over every field scene, the New Game seed, the container walkers, the capture-class trampolines, the single-target Curse, the clip morph and the battle-texture upload match on their first run.

See also