50 frames a second on a 1989 Atari ST

For developers

The game's rules move in steps of one original frame. scroll.c holds the original's scroll rule as it is: the world line, the set speed, the doubling after 35 frames off it, the lowest line, the 16-line reverse window, the backdrop's half step on odd frames. scroll_pace() turns vertical blanks into steps with a phase in 1/256ths of a VBL, so a step can be any number of VBLs, not only three.

For developers

The two windows. The cartridge's 128 KB are $FA0000, which holds the ST's program (16 KB at most) and everything the two sides share, and $FB0000, which the ST only reads to send signals (see the read-only port). The program starts before the AUTO folder, copies a little of itself into RAM, and takes over the vertical blank, the keyboard and the sound chip. Its two screen pages sit at $70000 and $78000, within the first 512 KB. It asks TOS whether there is a blitter, and checks the machine's type for the DMA sound chip.

Chunky to planar. Four pixels sit in one 32-bit word, a byte each with the colour in its low nibble. One multiply gathers the four bits of a plane into a nibble:

/* q: four pixels, one byte each. Plane k's four bits, in order. */
uint32_t nibble = (((q >> k) & 0x01010101u) * 0x80402010u) >> 28;

The worker, fb_c2p_half in fb_chunked_asm.S, runs that over a range of the picture with the two constants in registers and no lookup table. Core 0 converts the top 100 rows while core 1 converts the bottom 100, handed the job through the inter-core FIFO (fb_core1_dispatch / fb_core1_wait, the only way the app uses core 1).

The copy, backwards. The ST's loop is 666 pairs of:

movem.l (a6)+,d0-d7/a1-a4    ; 48 bytes from the cartridge
movem.l d0-d7/a1-a4,-(a5)    ; to the screen page, walking down

The pre-decrement store is 4 cycles a pass faster than an indexed one, but it lays each chunk at a lower address than the one before. So the RP2040 publishes the picture with its 48-byte chunks in reverse order (fb_chunk_reverse_copy48), and each lands where it belongs. a0 and a7 stay out of the register list: a0 is the sound interrupt's cursor and a7 keeps the stack valid so interrupts can fire in the middle of the copy.

No tearing. The RP2040 bumps a frame counter as the last write of each publish. The ST copies only when the counter's low word has changed since its last copy (one move.w: a longword arrives as two reads with its halves swapped), then flips and acknowledges by reading $FB84xx. The RP2040 waits for that acknowledgement before it writes the next picture. A game slower than a frame drops frames instead of tearing them.

For developers

The stopwatch is TIME_STUDY = 1 in userfw.s (off in releases; it costs about 40 µs a VBL). MFP Timer-A runs free at /10, 4.07 µs a tick; an interrupt counts its wraps. The VBL and four points of the loop (the wake, the copy's start and end, the loop's end) each report the ticks' low 16 bits by reading $FB8Bxx (the point) and $FB8Cxx / $FB8Fxx (the ticks), so every duration is a difference on one timeline, even across a VBL. With a Debug Probe, tools/dev/swd.py stopwatch reads the points and the slack histogram (fbSlackHist) from the running RP2040.

The sample interrupt is measured at about 152 cycles, not the 112 of the tables: the MFP's acknowledge and the sound chip's accesses add the rest. The blitter copies in pieces of 40 chunks, about 1 ms each, so the keyboard's interrupts run between them. Who copies is a word the RP2040 sets (CART_BLIT_MODE_OFFSET): by default the blitter only when the sound goes through the DMA chip, since on a Mega ST fitted with a blitter it delays the YM's sample interrupts and roughens the sound; or always the blitter, or always the 68000, with the chunks per piece in its high byte.

For developers

commemul.c runs a PIO program and a DMA chain that store every address read in the window into a 4 KB ring, with no interrupt per read; the main loop drains it with commemul_poll(), and a reader that falls a whole ring behind is counted and resynchronised. The ST reads the keyboard ACIA from its receive interrupt, one byte an interrupt, and forwards it with a read; polling it from inside the copy left gaps longer than a byte time and lost bytes.

The keyboard processor is set to report both joysticks as events, with the mouse off ($12 $14 $16). The decoder (ikbd_demux.c, plain C, host-tested) watches for every sign of a lost byte: an overrun, a full ring, the ST's byte count not matching what arrived, a packet open at its second VBL, an invalid joystick byte, a packet never asked for. After one it holds back presses and joystick data until a VBL in which the ST read no byte, where the stream is certainly back in step; releases always pass, so no key stays down. The RP2040 owns the keyboard processor's commands too: a block of generation, length and up to 12 bytes that the ST sends a byte per VBL, only when the ACIA can take one.

The exits. The command word at $FA4000 is a level, not a queue: the ST samples it once a frame, the RP2040 clears it only on the next boot's hello. For X, the RP2040 saves Booster as the next app, writes CMD_RESET and restarts; the ST masks its interrupts (their handlers live in the cartridge, which stops answering), copies a small routine to $77F00, the unused end of a screen page, and runs it from there: a wait, then a cold reset. The RP2040 can also refuse a boot with a status word and a message the ST prints before returning to the desktop.

For developers

The converter is plain C with no SDK: x2game.c (the loader's two decryption layers and the game image's chained XOR passes, the level stream's virtual sectors, the CRC-32s of the known release in x2_known), stx.c (Pasti images, sector by sector on demand), lzhuf.c (LHarc -lh1-, about 8.6 KB of state, the caller's) and crc32.c, streaming through the hooks in x2io.h. The same sources build tools/x2conv on a computer, which makes the same bytes. Host tests run the C core under AddressSanitizer and UBSan against the Python reference (tools/re/x2disk.py) on synthetic disks; no test uses a byte of the game.

The study tools are in tools/re. hatari_run.py runs the original in Hatari headless, one folder a run, driven by expectation files that wait on Hatari's output (an FDC trace line, a breakpoint), press keys and fire, swap disks and run debugger command files; fdc_map.py turns an FDC trace into a load map; render_level.py draws a playfield exactly as the original does, the reference the RP2040's renderer is checked against.

For developers

Size. The whole game is about 347 KB of Thumb code. Drawing the 192-line playfield from the level's map and the store (world.c) takes about 1.5 ms of core 0 a frame.

The objects. enemies.c is the original's object system: a pool of 96 objects on the heap, the wave and scenery tables fired by the world line, the spawner (trails, rows, chains, groups), the path interpreter, fire, hits, explosions, cash, capsules, tokens and restart points. A dead object is freed when the update walk reaches it, as the original frees it, so the objects behind it still see it that frame. Each level's own code sits behind a table of hooks (enemies_level.h: its scenery kinds, its every-frame code, its objects' updates, hits and drawing), one file a level, level1.c to level5.c.

The screens. The original's screens wait for frames in the middle of their routines. screen.c turns each into a coroutine (pt_t) stepped a VBL at a time, on a model of the ST's clock: each drawing step costs what the original's takes in 68000 cycles (fitted to Hatari's timings), a frame is at least 3 VBLs, and the swap comes at the picture's end. That is how the shop and the attract keep the original's pace at any frame rate.

The rule. No 68000 interpreter, anywhere on the RP2040. An interpreter of the original's code may serve on a computer as a reference while porting, never in the firmware: the firmware reads only the game's data, and every routine is C that can be read, tested and timed.

Tests. make -C tests/host test builds firmware units unchanged with the host compiler under the address and undefined-behaviour sanitizers, with core 1 as a thread: the scroll, the ship, the weapons, the enemies, the world's renderer against a planar reference, the sound driver, the shop, the screens, the options, the blits' clipping, the chunk layout through a model of the ST's copy, the keyboard decoder under lost bytes, the audio against a simulated ST and STE. They run on synthetic data, in a few seconds, on every pull request.

For developers

At 50 with the sprites at the original's speed, a step of the game runs every third VBL, and the VBLs between run only the world (world_vbl() in play.c): the last step's scroll again, so waves still fire as the world reaches their line. Before each step enemies_snapshot() and weapons_snapshot() keep every object's place; when drawing, each is pulled back by the part of its last move not yet shown:

/* the part of the last step not shown yet, in 256ths */
back = (vbls_per_step - shown) * 256 / vbls_per_step;
x -= (dx * back + 128) >> 8;      /* en_back() */
y -= (dy * back + 128) >> 8;

Three refinements make it look right. What rides the world is moved with it to the line drawn, and its last move is taken against the world, which moves in whole lines, so a gun on a wall stays on the wall (place() in enemies.c). Objects that keep a world line of their own (the level 1 and 2 bosses, level 3's walls, level 4's movers: enemy_t.world) are drawn from it. A move longer than 32 pixels for an enemy, 112 for a projectile, is a jump, a new object or a teleport, and is drawn where it lands.

Shots ×3 runs the weapons' step three times per game step, held fire's timer included (ship_fire_step). The frame rate lives in the options as VBLs a step in 1/256ths, so scroll_pace() needs no special case, and the options are packed into one setting (OPTIONS; 0 means every original value).

For developers

Writing flash under a running ST. The cartridge is served by PIO and DMA from a 64 KB window in RAM, so the bus doesn't need flash. store.c erases in 64 KB blocks (about 150 ms each) and programs 4 KB sectors, each with interrupts off; core 1 is parked in a loop that runs from RAM (never write flash while a job runs on core 1). Each section's magic is programmed last, and checked with the CRC-32 of the file it came from, so a power cut mid-copy leaves a section that fails its check and is made again.

Pitfalls we hit.

• Never let a DMA read the flash while the cartridge is live. An SD card write from a pointer into flash held up the DMA that answers the ST, and the ST crashed with four bombs. The level images go to the card through a 4 KB RAM buffer.
• Core 0's stack is 4 KB, with an MPU guard below it. The converter's stack plus FatFs's did not fit, so the converter writes only to flash and a second pass copies flash to the card; large locals moved to the heap.
• newlib grows the heap by a whole request its top block cannot hold, so a large allocation could fail with more than enough free. The heap is grown to its limit once at boot; every allocation is checked.
• The cartridge must answer 0.4 s after power-on, when TOS looks for it. Nothing slow may run before the image is in RAM: the first start's conversion runs later, behind a screen.
• Never read the RP2040's flash over SWD while the firmware writes it: the debugger's reads locked the chip up.

For developers

sfx.c is the driver: the effect requests (channel 2, then 1), then the tick, every VBL, its state kept in the cartridge window at the original's addresses (CART_SFX_WINDOW_OFFSET) so the songs' and effects' bytes are read in place. Its register writes go into ym_ring, words of a register and a value with an end marker written before each new word, at CART_YM_RING_OFFSET; the ST's VBL drains them into the YM. Checked against Hatari: every write of 87,032 driver calls.

The samples go through the framework's audio path: 12,517 Hz on the DMA chip, 5,585 Hz on the YM. On the YM, the cartridge holds four slices of a VBL each; the ST reports the slice it starts each VBL and the RP2040, from a 4 ms timer interrupt, writes only the slices after it, from a FIFO the main loop tops up, so the sound never tears or repeats whatever the frame rate. Each 8-bit sample maps through a 64-entry table of channel A and B volume pairs, which reaches about 6 bits from the YM's logarithmic volumes; Timer-B plays a pair per interrupt. On the DMA chip, the ST copies a 4 KB mirror into a ring in its RAM at $6F000, three VBLs ahead of where the chip plays, which it reports every VBL; byte i of the ring is byte i XOR 1 of the RP2040's buffer, the bus's byte order.