Read this before you write a line of integration code. Model 3 differs from Model 2 in exactly one way that matters, and it is the way that decides whether your port runs or hangs.
Everything below was read out of The Lost World: Jurassic Park (lostwsga)
rather than assumed. Addresses are that game's; the structure is the board's.
The four program EPROMs interleave as 16-bit words into one 2 MB image:
| EPROM | Byte lane in each 8-byte group |
|---|---|
epr-19936.20 |
0–1 |
epr-19937.19 |
2–3 |
epr-19938.18 |
4–5 |
epr-19939.17 |
6–7 |
...with each 16-bit word byte-swapped (MAME's ROM_LOAD64_WORD_SWAP). The
image occupies the top of the address space, 0xFFE00000–0xFFFFFFFF, inside
the 8 MB fixed-CROM window at 0xFF800000.
You can check you got it right without a disassembler. The PowerPC exception
vectors land at 0xFFF00100 + 0x100 × n, and each one opens by loading its
own vector number:
0xFFF00200 li r7, 2 ; b 0xFFF01404
0xFFF00300 li r7, 3 ; b 0xFFF01404
0xFFF00500 li r7, 5 ; b 0xFFF01404
If the immediate matches the vector offset, the interleave is correct.
Every vector above branches to 0xFFF01404, and that routine clears HID0,
writes 0xAC to 0xF010003C, and spins forever. It is the fatal-error
handler. The external-interrupt vector at 0xFFF00500 goes there too.
So the vectors in ROM are not the game's interrupt handling. The game clears
MSR[IP] to move the vector base to 0x00000000 and installs real handlers in
RAM. A lifter that discovers functions by following bl targets will never find
them, because nothing ever branches to a vector — the processor jumps there.
This is the fact that shapes the whole tool.
The interrupt library at 0xFFF37BD0 installs its handler like this:
lis r9, 0x11
addi r9, r9, 0x7864 ; r9 = 0x00117864
lis r10, 0x1f
stw r9, -0x1284(r10) ; -> [0x001EED7C]
and later calls it:
lis r9, 0x1f
lwz r0, -0x1284(r9) ; [0x001EED7C]
mtlr r0
blrl ; call 0x00117864
0x00117864 is RAM. The bulk of the game is copied out of the 32 MB of
banked CROM into RAM at boot — that is what the 53C810 SCSI DMA engine is for
on Step 1.x — and executes there.
The copy is not verbatim: CROM offset 0x117864 is a lookup table, not code.
So the RAM layout cannot be recovered by inspecting the ROM alone.
tools/ppc_interp.py runs the reset path and the whole sequence is now known:
-
0xFFF00100calls0xFFF00508, a table-driven hardware initialiser. It reads a count at0xFFF00408and a base at0xFFF0040A, then walks a byte-code stream of(opcode, offset, value)items, writing bytes, halfwords and words relative to that base. It programs the MPC105 host bridge at0xF8FFF000. -
0xFFF0032Cruns the segment copy loop at0xFFF00354, which walks a table of(src, dst, count)triples:0xFFF00354 lwzu r4, 4(r3) ; src cmpwi r4, 0 ; 0 terminates the table beq done lwzu r5, 4(r3) ; dst lwzu r6, 4(r3) ; count ... mtctr r6 0xFFF00374 lwzu r0, 4(r4) stwu r0, 4(r5) bdnz 0xFFF00374 b 0xFFF00354 ; next entry -
For The Lost World that table has two entries:
RAM from CROM size 0x000000..0x0FFFFC0x0000001 MB, verbatim 0x100000..0x13B2D40x120004237 KB The first carries the exception vectors and their handlers, which is why
RAM 0x500is byte-for-byte the external-interrupt handler shown above. The second carries the interrupt library and the game. -
Finally, the handoff:
0xFFF0013C mfspr r0, HID0 andi. r0, r0, 0x3FFF isync ; sync ; mtspr HID0, r0 0xFFF00150 lis r0, 0 0xFFF00154 mtlr r0 0xFFF00158 blr ; jump to RAM 0x00000000
That last blr is the whole game. PowerPC uses mtlr + blr as a computed
jump, and a lifter that translates every unconditional blr to return;
turns the boot's handoff into a no-op: the port falls out of the guest and
does nothing, silently, with no crash and no missing function to point at.
The two cases are told apart by where LR's value came from:
| Sequence | Meaning | Emit |
|---|---|---|
lwz r0, N(r1) ... mtlr r0 ... blr |
LR restored from the stack | return; |
lis r0, X ... mtlr r0 ... blr |
LR built from an immediate | CALL(PPC_LR); return; |
tools/ppc_lifter.py tracks which registers hold immediate-derived values and
picks accordingly. Across the whole 2 MB program ROM this fires exactly
once -- on the boot handoff -- so the rule is narrow enough not to corrupt
ordinary function epilogues.
There is no static answer for the RAM layout. The lifter therefore boots the machine before it lifts anything:
- A small PPC interpreter runs from the reset vector, against the same bus, SCSI and system-control code the runtime uses.
- It stops when the guest first branches into RAM.
- RAM is snapshotted.
- The snapshot is what gets lifted, at its RAM addresses.
This is less code than a static analysis that would have to prove what the DMA engine does, and it is exact rather than approximate. It also gives the conformance harness its oracle for free: the interpreter and the lifted code are two implementations of the same instruction set, and they must agree.
The interpreter only has to cover the instructions the boot path actually uses — it is not a general Model 3 emulator and must not grow into one.
Model 2 busy-waits on a video status bit, and answering that read is the frame. Model 3 does not, and the first design here got this wrong.
The obvious hook looks right: 0xF0100018 is read seventeen times across the
program ROM and never written, so it is read-only interrupt status. Hanging the
field off it is the exact analogue of the Model 2 design.
It does not work, and the interpreter is what proved it. The Lost World's main
loop never reads 0xF0100018 at all:
0x00118284 lwz r0, -0x126C(r29) ; service-routine pointer in RAM
mtlr r0
blrl ; call it
0x00118290 lbz r0, 1(r30) ; flag byte at RAM 0x000006ED
cmpwi cr1, r0, 0
0x001182A0 bc 0x00118284 ; spin until the flag changes
Only the VBlank handler sets that flag. A frame hook that waits to be asked will never fire, and the game spins forever having rendered nothing.
So interrupts are delivered on a timer, which is what the hardware does
anyway. irq_tick() advances the field when one is due and dispatches the
handler. It is called from func_table_call(), because a main loop that waits
on an interrupt-set flag still has to dispatch its service routine through a
pointer every iteration -- that is the one hook the runtime reliably gets.
irq_status_read() remains wired to 0xF0100018 so that a game which does
poll the controller still gets a field out of it.
Both were hit here, and neither announces itself:
-
Pacing the field off nothing. The headless platform first reported a field as always due. Since
irq_tick()runs fromfunc_table_call(), the guest then took an interrupt on every indirect call, its main loop never ran between them, and the game ticked 17,000 fields without writing a single byte of tilemap VRAM. A virtual clock that advances per query fixed it. -
Dispatching with interrupts masked. The handler must only be entered when the guest has
MSR[EE]set and the pending bit is enabled, or it re-enters itself.
This is the single most important routing in the whole library. The game's
handler acknowledges an interrupt by writing the bit to the tilegen at
0xF1180010, then re-reads 0xF0100018 and spins until the bit clears:
0xFFF37EB8 stw r8, 0(r11) ; r11 = 0xF1180010, r8 = 0x01000000
0xFFF37EBC lwz r0, 0x18(r10) ; r10 = 0xF0100000
0xFFF37EC0 andis. r9, r0, 0x100
0xFFF37EC4 bne 0xFFF37EB8 ; spin
If a write to 0xF1180010 does not clear the matching bit in 0xF0100018
before the next read, the game hangs there forever. Note the asymmetry --
pending is read from the system controller, acknowledged at the tilegen. That
is genuinely how the board is wired.
Two more registers hang the boot if they return a constant, and both were found the same way: the bus counts what it is asked for and names the address a stalled guest is polling.
0xF0040000 is a latch. The boot strobes a bit, reads the register back,
and waits for it to mirror -- first for the bit to set, then for it to clear:
0x001178A8 stw r10, 0(r11) ; r11 = 0xF0040000, r10 = 0x01000000
lwz r0, 0(r11)
andis. r9, r0, 0x100
beq 0x001178A8 ; spin until it SETS
...
0x001178CC stw r10, 0(r11) ; r10 = 0
lwz r0, 0(r11)
andis. r9, r0, 0x100
bne 0x001178CC ; spin until it CLEARS
Return 0 and the first loop never exits; return 0xFFFFFFFF and the second never does. It has to read back what was written.
0xF0040004 carries a serial ready line. The boot bit-bangs a byte to
0xF0040000 with delay loops, then waits on bit 0x20000000 here, again for
both edges:
0x0011A650 li r4, 0x51 ; bl <bit-bang>
lwz r0, 0(r30) ; r30 = 0xF0040004
andis. r9, r0, 0x2000
bne 0x0011A650 ; wait for CLEAR
... same again waiting for SET
The runtime toggles that bit rather than modelling the protocol, which is enough to get through I/O init. Buttons and coins will need the real 315-5649 serial protocol.
Step 1.x moves bulk data with the SCSI controller's SCRIPTS processor, not the
host bridge. No SCSI bus and no target device are involved -- the game uses it
as a memory-to-memory DMA engine, and without it the boot polls ISTAT at
0xC1000014 about twelve million times and stops.
The chip is on the PCI side and is little-endian, which the game's own
traffic shows plainly: it writes DSP = 0x4C2C1A00, and that is the address
0x001A2C4C. Every 32-bit quantity, including the SCRIPTS instructions
themselves, is byte-reversed relative to the PowerPC.
Only three SCRIPTS operations are modelled, because only three are used:
memory move, jump, and interrupt. The game's first real program, sitting in
RAM at 0x001A2C4C, is:
C000000C memory move, 12 bytes
001BAA50 from work RAM
9C000000 to the Real3D texture port
98080000 INT
Two things about that are worth keeping in mind. It writes to the Real3D,
not to RAM, so a DMA engine whose idea of a valid destination covers only
memory will reject it. And it ends in INT, which is what sets ISTAT[DIP] --
the bit the guest is polling. Reject the move and return, and the interrupt
never fires and the guest reads 0xC1000014 about twenty million times. So a
move the engine declines is skipped, not fatal: the program runs on to its
INT.
The boot also sweeps the whole register file with a test pattern, DSP
included. Without the chip's manual-start mode (DMODE[MAN]), every one of
those writes launches a "program" that is really whatever PowerPC code happens
to live at that address -- the giveaway being a move from 1A00603D, which
byte-reversed is 3D60001A, lis r11, 0x1A.
See src/scsi.c.
Status and enable both live in the upper 16 bits of the word. The game
tests them with andis. and sets them with oris, never with andi./ori,
which is the giveaway:
| Bit | Meaning |
|---|---|
0x02000000 |
Start of VBlank |
0x01000000 |
End of VBlank |
0x04000000 |
SCSI DMA complete |
0x08000000 |
Sound |
0x10000000 |
Network board |
0xF0100014 is the enable mask, read-modify-written with oris/rlwinm.
There is nowhere to preempt — lifted code owns the C stack — so interrupts are delivered at the field boundary, which is where VBlank arrives on hardware anyway. For the interrupt that matters this is not an approximation.
irq_dispatch() walks the guest's own path rather than hardcoding anything:
- Read the installed handler pointer out of guest RAM.
func_table_call()it.
Because the pointer is read from RAM at dispatch time, a game that swaps handlers mid-run keeps working, and a handler the lifter missed shows up as a named func-table miss instead of a silent wrong branch.
The reset vector at 0xFFF00100 is three calls into the spare space inside the
exception-vector slots — the vectors only use 8 bytes of their 256, so the boot
code lives in the gaps:
0xFFF00100 bl 0xFFF00508
0xFFF00104 bl 0xFFF00208
0xFFF00108 bl 0xFFF00908
0xFFF00508 is a table-driven hardware initialiser. It reads a count at
0xFFF00408 and a base at 0xFFF0040A, then walks a byte-code stream of
(opcode, offset, value) triples, writing bytes, halfwords and words to
registers relative to that base. It is not code you need to understand — it is
code you need to run, which the boot interpreter does.
model3recomp_field_due() asks how much work the guest has done, not what
time it is. That distinction was learned the hard way.
It used to ask the platform layer for the time. Headless that returns
m3_work, so it was the right answer by accident. Against SDL it returns
real microseconds, so fields arrived sixty times a second whether the guest
had got anywhere or not -- and a recompiled 603e uploading three megabytes of
texture does not run at real time. The guest got a fraction of the
instructions per field it needed.
What that looked like was not a timing bug. Built headless, field 1500 was the attract scene: 18688 lit pixels, 3774 colours, textured. Built against SDL2, the same field was the Sega boot logo, 190296 pixels, 15 colours, and it stayed there for 30000 fields. Two builds of the same emulator disagreeing about what the game was doing.
Finding it meant ruling out everything that looked more likely first: the
cabinet buttons, the framebuffer, the video driver, and checking out both
bus.c and real3d.c from before the divergence. All of them behave the
same. What was left was the one function in the platform interface that
returns a number the rest of the runtime does arithmetic on.
A host that wants to run at the right speed throttles in
platform_present(). It does not get to decide when the guest's video
hardware retires a frame.
A recompiled game has no program counter to inspect. When it stops making
progress the only visible thing is the sequence of addresses going through
func_table_call(), so M3_TRACE_CALLS=N prints the first N of them and
N@F starts counting at field F -- which is what you want, because the
interesting moment is thousands of fields after boot.
Coin, credit, trigger, and then a screen that was byte-identical for 2750 fields looked like a hang in the game. It was not. Fifty fields of trace at field 3400 were five addresses repeating:
0001D68C 0007F67C <-- NOT LIFTED
00000900 00000500 00001578
0x900 and 0x500 are the decrementer and external-interrupt vectors, so
interrupts were still being delivered and the runtime was still running. The
game was calling a function that did not exist. func_table_call() returns
0 for a miss and the caller spins.
The five addresses a credit reaches -- 0x2B6C0, 0x2BD78, 0x2C3E0,
0x2FCF8, 0x7F67C -- are all inside the lifted RAM range. They are
indirect targets the static walk never saw because nothing in attract mode
reaches them. Append them to the entries file and lift again.
Which is the general shape of this: entry coverage is not a property of the program, it is a property of the paths you have run. Attract mode converging on zero misses says nothing about the paths a coin opens.
Feeding runtime misses back with --entries converges, but each round only
buys one more state. Five addresses, lift, build, run, five more addresses one
step further along. The addresses themselves said why:
00121860 0001C0E4 <- the game-state dispatch table
... (21 entries)
001218A8 0007F67C
001218AC 0007F8EC
001218B0 0001BFB0
Three separate holes in discover() were hiding the rest.
Offset jump tables. scan_tables knew one shape -- a table of addresses
read with lwzx -- and this compiler emits the other:
0002BE24 addis r9,0,3 ; addi r11,r9,-0x41B8 ; r11 = 0x0002BE48
0002BE2C add r9,r0,r11 ; lwz r0,0(r9) ; the offset
0002BE34 addis r11,0,3 ; addi r9,r11,-0x41B8 ; the base again
0002BE3C add r8,r0,r9 ; mtctr r8 ; bctr ; base + offset
0002BE48 00000020 0000003C 000000BC ... ; eight arms
Every word in that table is small and none of them decodes as code, so a scan looking for addresses walks straight past it.
addi rD, rA, lo where rD != rA. The address-pair tracking required the
addis and the addi to name the same register. This compiler routinely
writes the low half into a different one -- addis r9,0,3 ; addi r11,r9,lo --
and every table built that way was invisible. Relaxing that one condition took
discovery from 2596 entries to 3229.
Function prologues. stwu r1,-N(r1) is one instruction, its immediate
must be negative, and every non-leaf C function opens with it. 1429 of them in
the RAM image. This matters because the handlers a credit runs are reached
through pointers that only exist in RAM after an overlay loads: they are in
no table the boot snapshot holds and no bl names them.
Two things about the prologue scan are load-bearing:
- The addresses go in
entriesand not inhard. A prologue is an extra way into code, like an address fed back from a runtime miss; making it a boundary truncates whatever function branches across it, and the symptom is the machine resetting to the WARNING screen on the first coin. - It runs before the table scans and walks from its own finds, because
those scans only look at code that
seenreaches. A jump table inside a function nothing calls statically is exactly the case that matters.
Together: 1254 -> 3244 functions, and the game goes from freezing on the credit to the stage-one intro and an in-game HUD.
The general shape is worth stating once. Entry coverage is not a property of the program, it is a property of the paths that have been run. Attract mode converging on zero misses says nothing at all about the paths a coin opens.
Halfway through the first round the screen went black and stayed black for seven thousand fields. The loop guard said where: one guest function entered 251,700,076 times, and every other count identical to a thousand fields earlier, so nothing else had run at all.
00118A80 x251700076 <- new
0002E618 x11418712 <- same count at field 4600 and at 5600
0x118A80 reads a byte at RAM 0x6FB and returns a pointer if it is 1, else
zero; its caller is the Real3D frame sync and spins until it is non-zero.
That byte is set once at boot, after a PCI probe of device 13 answers
0x16C311DB -- Sega's vendor ID 0x11DB, device 0x16C3. It was 1 at field
4500 and 0 at 5600, and the only instruction in the image that writes it
writes 1.
M3_WATCH existed for exactly this and missed it twice. First because it
fired only on an exact address match, and a byte is most often cleared by a
word store two bytes below it -- it now fires on any store that covers the
address. Then because it lived in lift.h, which only sees stores from lifted
code: this one came through bus_write8(), from a SCRIPTS DMA.
The DMA was 0x68 -> 0x00000000, 262232 bytes, which copies the low quarter
megabyte of RAM over itself. It came from a SCRIPTS program the game never
wrote. The SCSI decode was
(a & 0xFE000000u) == 0xC0000000u
which is two 16 MB pages, and the game uploads 40 KB to a device at
0xC0020000. All 10272 of those words landed on the 53C810's 64-byte
register file, DSP among them, and every DSP write launched a "program" made
of whatever the upload happened to contain.
The game says where the chip really is. It writes DSP at 0xC100002C, and in
a whole boot it touches 0x0C, 0x14, 0x2C, 0x38 and 0x39 there and
nothing else in that space. One page, 0xFF000000.
What is at 0xC0000000 is a device this port does not have: the game writes
0xDEB00BED there and reads it back to see whether it exists. With the SCSI
window narrowed the read no longer answers, the probe fails, the game sets
its own "absent" flag and skips the upload -- which is the honest model, and
costs a device that was never emulated anyway.
A SCRIPTS program that contains a move to nowhere is also now abandoned rather than skipped over. That alone did not fix this -- the destructive move was in range and perfectly plausible -- but walking on through 4096 more "instructions" of garbage is how a bogus program finds a plausible move in the first place.
emit_function() writes the body in address order, and the entry is not
always the lowest address in it. A function that ends with a backward branch
into a block it shares with a routine below it gets that block first, so
calling the function falls into the wrong code.
The matrix push at 0x0010ED58 is exactly that shape:
0010ED58 lbz r4,0x1256(r2) ; stack depth
cmpi r4,20 ; full?
... ; depth++, pointer += 48
0010ED78 b 0x0010EBBC ; tail: copy current -> new slot
0x0010EBBC is the tail of the copy routine 0x6C bytes below, so the lifted
function came out as
void lwram_0010ED58(void)
{
M3_FN(0x0010ED58u);
L_0010EBBC: ; <- execution starts here
... the copy ...
return; <- and returns
PPC_R(4) = MEM_R8(...); <- the push, unreachable
...
}
So the stack depth never moved, nothing was ever pushed or popped, and every matrix the game built accumulated onto the last one. In a round that put the 2D overlay's screen-space scales -- 496 and 68 -- into the camera matrix, twice, which is why its rows measured 1.99e4, 4624 and 2.45e5: 68 squared and 496 squared. The matrix inverse downstream was faithfully inverting an ill-conditioned matrix, and every object in the scene came out rank 1.
94 functions in this game are shaped that way.
The fix is one line -- emit goto L_<entry>; when the entry is not the
lowest address -- and the tell was on the build the whole time:
warning C4102: 'L_00001FDC': unreferenced label
A lifted function whose own entry label is never referenced is one that nothing jumps to, including the function itself. Those warnings are worth reading.