gem4xe — GEM for the Atari 8-bit

A port of GEM — the VDI graphics layer, then the AES — to an Atari XL/XE fitted with VBXE (video), a 65C816 accelerator with linear RAM (Rapidus, and in principle Antonia), and Ultimate 1MB.

The target surface is 640 × 240, 16 colours — VBXE's HR overlay, 4bpp chunky. That is a better GEM surface than the Atari ST's medium resolution.

Current version 0.7 — VERSION at the top of the tree is where it lives; make dist stamps a build with it and the commit, and make release is the same for the public, without the DOS 2 floppy (its DOS is not gem4xe's to give away) and named by the version alone.

The quickest way to try it is gem4xe-0.7.car on the release page: one file for an Ultimate Cart, a MaxFlash or an emulator's --cart, carrying the whole system on a read-only D1: of its own. No DOS, no disk, nothing typed — which is what the other media all needed first (docs/cartridge.md). With a DOS floppy in drive 1 as well, it saves to the floppy (docs/phase51.md).

A 65C816 with linear RAM is required. VBXE is not: one GEM.COM carries both display drivers and chooses at start-up, so a machine without a VBXE gets 320×168 on ANTIC mode F instead — make test-m26 boots the shipped binary three ways to prove it. The 6502 path is still deferred.

The desktop first came up on a real board on 2026-09-13 — a 130XE with a Rapidus, an Ultimate 1MB, a VBXE and a SIDE 2 — after two reports that did not get there: a white screen (docs/phase39.md), then a boot screen that stopped at its Vectors line (docs/phase40.md). That line says what the machine found under its OS ROM, how the Rapidus was set up and which RAM under the ROM took the interrupt vectors, and make diag builds GEMDIAG.COM — GEM.COM with a digit and a tone per start-up step and OPTION/SELECT/START to skip and single-step — for a machine with no emulator bridge to ask.

The product booted and used, photographed under AltirraSDL by make shots (tests/emu/shots.py, which reads its coordinates out of the running desktop's own object trees). Every picture is 640 × 480: the 640 × 240 overlay with its rows doubled, which is what a monitor shows.

The rest are in docs/shots/: the bare desk, the Desk and File menus, the About box, a folder in icon and text view, Show Info, and the three desk accessories — the control panel, the calculator and the clock — each open over a window. Two of them are taken from inside the control panel, which is the point of the shape: the panel lists what the AES loaded and calls a module's entry, so what is photographed is a dialog belonging to a separately linked file the panel has never heard of — one a settings CPX, one an event CPX being fed events by a host that owns the loop.

VBXE sits on the 1.79 MHz chip bus no matter how fast the CPU runs. Measured on target, a full-screen fill costs 0.51 of a frame through the blitter and a full-screen copy 0.88; the same work through the MEMAC window is roughly twenty times slower. So the VDI emits blitter control blocks, it does not plot pixels, and the window manager will use dirty rectangles rather than full-screen repaints.

make test runs all of them but the ones whose row says they need a fixture this tree cannot carry — the Ultimate 1MB flash and the Rapidus OS — and make movie and make bench, which are run by hand. Per-phase notes, including the bugs and what caught them, are in docs/ — one document per phase, with an index.

The VDI is complete across the classic opcode space — 1–39 and 100–131, which is all of it before Speedo/FSM — with four deliberate no-ops (v_clswk, the cell-array pair, valuator input), as DRI's own screen driver shipped them. The 37 the AES and the GEM Desktop use came first; phase 17 added the rest an application wants, the ten GDPs included. The AES object library draws, hit-tests and edits; form_do runs a dialog under keyboard and pointer input; the window manager keeps dirty-rectangle lists and blits a window across the screen (x snapped to even: the blitter has no shifter); the control manager turns a press on a frame into WM_* messages and holds the mouse until the button is up, as the ROM does; menus drop, are saved and restored through a VRAM form, and report MN_SELECTED — all compared call for call and pixel for pixel against the host model (docs/phase8.md). make movie runs all of that as one session on the emulated machine — About from the Desk menu, a window opened by double-click, dragged, sized, covered by the dialog, fulled and closed — screenshotting every frame, with every returned word and every shot checked against the model. Making it pass found that a pixel plotted through the MEMAC window costs 60–80 µs, so the pointer and vrt_cpyfm now go through the blitter like text does (docs/phase8b.md); reading the compiler's listing then cut the strip builder and the line stepper to a third of their instructions, and a blitter mode written off in Phase 2b turned out to do the whole icon in one blit — 60 ms an icon in Phase 8, 2 ms now (docs/phase8c.md). make bench then put GEMBench's headings on the machine — absolute milliseconds, since GEMBench's source is private and there is no ST here — and its first profile named the control-block builder and the VRAM upload: the dialog went from 78 to 51 ms and a 40-character line from 27 to 15 ms, and a seventh compiler defect turned up under the rewrite (docs/bench.md). Next is form_alert and the desktop, with the multiply-per-glyph and the upload loop still on the benchmark's list.

Phase 7 also found that the Rapidus resets with all of bank $00 on the 1.79 MHz bus, and that gem4xe had run its data, stack and direct page there for six phases without a gate noticing (docs/phase7.md, Step 4). src/sys/rapidus.c derives the speed map from the linker's placement and the MEMAC window rather than restating either, and make test-m6 reads the registers back.

Code lives above bank $00, in the accelerator's first megabyte. A .xex segment header is two 16-bit addresses, so a DOS loader cannot place anything above $FFFF; the far image therefore travels as chunks aimed at a staging buffer and DOS copies it up through INITAD as it reads the file. That took the code ceiling from ~28 KB to a bank at a time, and freed the $4000-$7FFF scaffold the test runner had been borrowing from U1MB. Since phase 38 the chunks are LZ-packed -- 143 KB of far image, and the whole of GEM.COM 100 KB with its near half, unpacked by src/farload.s as each chunk arrives -- which is what gave the floppy its DUP.SYS back (docs/phase38.md).

Bank $01 was 90% full by the time the benchmark landed, so the far code is now linked into one linker memory per bank, $01 through $0F, filled in order: the image spills into the next bank only when the current one cannot hold the next whole function, and no function ever straddles a bank boundary (the 65816 program counter wraps within its bank, and a single memory spanning banks let the linker place a function across the seam — tried, and it did). The far heap starts above the highest address the loader actually wrote, _fl_top, recorded chunk by chunk, since the linker has no operator for the end of a section that lives in several memories. Because the real build still fits in bank $01, make test-m6 also links the same objects with bank $01 cut to 16 KB and boots that: the code runs from bank $02, the heap starts at $03, and the mechanism is proved today rather than on the day the code outgrows the bank (docs/phase6.md, the follow-up).

Running this on a machine without a 65C816 would corrupt memory rather than fail — the long store the copier needs is an unstable undocumented opcode on an NMOS 6502 — so the loader identifies the CPU and probes for linear RAM before its first store, and prints a line and returns to DOS if either is missing.

Interrupts run in native mode (docs/phase9.md). The 65C816's native vectors sit at $FFE4-$FFEF, inside the OS ROM, which the Atari OS never fills — so from Phase 0 to Phase 8 gem4xe ran with NMI and IRQ off and polled everything. src/sys/irq.c copies the OS ROM into the Rapidus's SRAM under it, page by page through write-through, patches the six vectors to point at bank-$00 stubs, and switches the window in; the handlers count frames, run a POKEY timer at ~4 kHz that samples the joystick port and decodes a quadrature or trak-ball device into two counters, and put keys into a ring. The pointer layer consumes the counters, so an ST mouse, an Amiga mouse and a CX80 trak-ball now work as well as the tablet did — in Altirra; no real hardware has been near this. On exit the ROM is switched back, $0000-$3FFF is written back to the motherboard, and DOS's own keyboard IRQ echoes the next key typed at its prompt, which is what the gate checks. Getting the gate green also found that the emulator was reading a phantom joystick: the host keyboard's "System Control" HID interface, which SDL enumerates as a joystick with one out-of-range axis, held PORTA's left line low through AltirraSDL's input maps. The rig now keeps SDL's joystick subsystem off every host input device it can find in sysfs.

Applications call in through COP (docs/phase10.md). COP #$56 is a VDI call, COP #$41 an AES call and COP #$44 a GEMDOS call, the parameter block's address in X:C — the ST's trap #2 and trap #1 on a 65C816, with letters for signatures because Rapidus OS owns $00 and $01 and WDC reserves $80-$FF; any other COP is passed to Rapidus OS when it is running. The handler is the saveds entry point of the plan: it takes gem4xe's direct page, data bank and stack for the duration and gives the caller's back, and the shim behind it keeps DRI's copy-in/copy-out discipline, so an application's arrays can be anywhere in the 16 MB. A program is linked on its own rules (src/app/gemapp.scm) and packed as a .g4a by tools/mkg4a.py, which derives the fixups Calypsi's linker does not emit by linking the same objects three times and diffing; the loader puts the near part in a bank-$00 pool and the code in a far bank. The gate application makes eighteen VDI and AES calls and the harness checks what each returned, from the application's own memory, against the reference.

More than one thing at a time (docs/phase26.md). Every file operation could already work on a set — the delete, the copy and the move all walk the window's entries and act on each one flagged — but a click chose exactly one. Now SHIFT-click adds and removes, and a press on a window's background draws a rubber band whose box is the new selection. A press is read in a new order: the drag is recognised before the click semantics, because SHIFT means "move" to a drag and "add to the selection" to a click and the same press cannot be both. The band is what test-m19 drives, and not by preference: no harness here can hold SHIFT down through a mouse click, which is the same block that has kept the SHIFT-drag move ungated since phase 18.

The desktop remembers (docs/phase25.md). Save desktop writes the window layout to DESKTOP.INF on the boot drive and Read .INF file reads it back, closing what is open first; at start-up the desktop looks in the shell buffer, then the file, then its built-in default — which is the donor's order, and the difference between surviving a program and surviving the power being switched off. Most of it was already there: the format, the writer and the parser have carried the windows between programs since milestone 6. What was missing was a file.

The loader switches the machine (docs/phase23.md). A Rapidus always cold-boots as a 6502 — Altirra's device does it in ColdReset() and the card does the same — so gem4xe used to refuse a machine that could have run it, and every gate got past that by poking $D1FF/$D191 over the test bridge. Thirty-five bytes in src/farload.s now probe the eight PBI slots for a card that answers on both of the registers measured at a DOS prompt ($D190 reads $00, $D191 bit 6 set; open bus reads $FF at each), set COLDST so the restart is a cold one, and switch. The CPU resets inside that write. test-boot now does nothing to the machine after power, and test-m6 boots the same image with the Rapidus taken out, which is where the refusal is still right — and gates that the probe leaves such a machine exactly as it found it.

⚠ And it found a real one (docs/phase24.md). Those thirty-five bytes turned test-m14x red, and thirty-five bytes of dead padding did the same, at some sizes and not others — a fault with no clean boundary. It was not the near memory at all: far_alloc was a bump allocator with nothing stopping a block from straddling a bank boundary, and Calypsi's __far pointer arithmetic is 16 bits within a bank (carrying into the bank byte is what __huge is for). A buffer that straddles one wraps to the bottom of its own bank the moment it is indexed past the edge — and the bottom of a far bank is the far code image. It is the phase 6 corruption by another road, the file selector's 900-byte name list was the block, and master was green by luck. Eight lines start the next bank rather than straddle, and tests/host/test_farmem.py asks the allocator for the blocks that used to break it.

And then the room (same notebook). Bank $00 had four bytes free and seven; the 608 bytes of fill patterns — 23% of all the near memory there is — went to cfar with the far code, and the boundary moved to share what that bought. It moved again on 2026-09-16, 192 bytes, to buy the far window title the two 41-byte buffers it bounced through, and a third time on 2026-09-19, 16 bytes, for the owner wind_get(WF_OWNER) has to answer with. The title buffers were then given back: w_ptext stopped copying and reads the far string where it lies, which is 82 bytes of LoRAM returned and the forty-character cap gone with them (docs/phase47.md). 323 bytes free in LoRAM and 167 in Near today, which make memcheck prints.

Which boundary, though, took two red gates to learn. Growing zwin at the application pool's expense went first, and test-m28 answered DESKTOP.RSC is not on the boot disk: rs_load holds the whole resource file before the icons go far, so the conformance runner's pool had 348 bytes of headroom, not the 1,884 its resident figures showed. Shrinking the 2 KB stack went second, on the evidence that the deepest the engine has ever gone is 1,390 bytes — and test-m32 answered ENSMEM to every Pexec, including one for a file that does not exist, because GEMDOS reserves 1 KB of that stack for a child's calls (GD_PEXEC_STACK). A low-water mark measures what has happened, not what is reserved. What made the third attempt the right one is that Near holds code and constants, so what it needs is settled at link time: taking too much fails the link, where the other two failed on a running machine under conditions no link could see. tools/memreport.py models both pools and rs_load's peak now. The workstation holds the pattern as a source and a first row rather than a pointer, because a pointer that could name either a far table or the user's own near array has to be far, and then "is this the user's?" is a near-to-far comparison on the workstation switch. That version passed test-m3 86/86 and crashed the desktop — the conformance suite drives the physical workstation and never reaches that code.

make dist is what a tester is handed (docs/phase22.md): the bootable disks, the system's files loose for a disk of their own, the kit, and a page that says how to try it — half of which is generated from the desktop's own menu and from the disk images, so it cannot claim something the resource greys out. It carries 816.COM, which is the piece that was actually missing: a Rapidus always cold-boots as a 6502, so a tester's first screen is the loader's refusal, and until now only the test harness could make the switch. Fourteen bytes set COLDST and write $D1FF/$D191; test-boot now types 816 at the SpartaDOS prompt rather than poking those registers, so what the page says to do is what the gate does.

There is a kit (docs/phase21.md). make sdk packs thirteen files — the header, the bindings and the start-up as source, the linker's rules, the packer and a commented example — with no part of gem4xe itself in them, because an application links against none of it. make in the kit turns example/hello.c into hello.g4a; make APP=mine.c turns yours into mine.g4a. Its gate builds it out of a copy of itself in a directory of its own, and then rebuilds the Phase 10 gate application with it and compares the bytes: they are identical, so what test-m11 proves about that binary on real hardware is what the kit inherits.

And there is a binding for every one of them (docs/phase20.md). src/app/gem.h declares the whole surface the system serves — the VDI in the names it has had since 1984, the GDPs as v_bar/v_arc/… rather than a raw v_gdp, every vq* inquiry, the raster calls with a real MFDB, the file selector, objc_edit, the shel_* family, and the GEMDOS calls phase 16 added — so GEM source written for an ST compiles against it. The four opcodes the driver answers with v_nop are deliberately absent: a binding that silently does nothing is worse than a name that is not there. tests/host/test_bind.py calls every binding in the compiler's simulator with the three call gates replaced by recorders, and compares the parameter block each one builds with the contract — which is how a vqt_width that put its deltas in the wrong words was found, in a gap the conformance gate cannot see.

SpartaGEM: gem4xe runs on SpartaDOS (docs/phase13.md), 3.2 from disk and X 4.50 from its cartridge, as well as on DOS 2 -- the same binary, which asks the DOS what it is at start-up (src/sys/dos.h) and reads its answer for the shape of a path and the mark on a folder in a listing; a GEM application sees A:\DIR\NAME.EXT on all three. Making room for the cartridge moved the application pool and the test stage into $4000-$7FFF, the banked window the port had kept out of for twelve phases: a DOS banks there only inside its own call, and puts it back. Two things bit on the way. SpartaDOS 3.2 keeps 7 KB of itself under the OS ROM, where the interrupt layer's ROM copy had overwritten it, so the copy now goes to the Rapidus's SRAM alone -- gem4xe on SpartaDOS 3.2 needs the accelerator. And the bridge reads what the CPU sees, SpartaDOS X's bank included, so the one word the harness polls during a call moved out of the window. Every call costs more than on DOS 2 (a directory read about twice as long a record), measured in docs/phase13.md, and everything is Altirra: no real SpartaDOS machine has been near this.

GEMDOS, and two emulator bugs (docs/phase14.md). The ST's trap #1 is gem4xe's third COP face: a call block laid out as the ST's stack frame with the result in front, so an ST binding's picture of the arguments is the block's picture four bytes along, and the donor's desktop code can read unchanged above it. Building it found two places where Altirra's 65C816 is not a 65C816 in native mode -- a taken branch that does the 6502's page-crossing dummy read, in bank $00, which puts $D5xx on the cartridge bus from code running at $xxD5xx; and SEI with an IRQ pending, whose "one more interrupt" shadow the native vector states never clear, an IRQ storm that wraps the stack. Both are fixed in tools/altirra/ and sent upstream; until then the linker map leaves the $D5 page of every far bank empty. The Ultimate 1MB, which the SDL emulator could not switch on headlessly, now can be: the same patches add the switches, and the two *u gates boot SpartaDOS X from the machine's own flash.

The desktop (docs/phase14.md, milestones 3 to 7). The AES's shell loop runs DESKTOP.PRG, then whatever it asks for, then the desktop again; GEM.COM is that loop from the DOS prompt, back to it at shutdown. The desktop is the donor's deskmain.c, deskobj.c and deskwin.c cut to what shows so far -- the bar, an icon for each drive GEMDOS reports and the trash, About, Quit, folder windows, and a program run from its icon, and now a folder made and a folder tree deleted: a drive or a folder double-clicked lists through Fsfirst/Fsnext into a window, folders first, with an icon per entry, the name and information lines, the fuller, the arrows and the closer; a program double-clicked goes to shel_write, and the desktop leaves its windows' places in the shell buffer as the text of DESKTOP.INF and opens them again when the shell brings it back; File -> New folder and File -> Delete (deskfun.c) put up the donor's dialogs, and the delete counts what it will do before it does it, walking folders inside folders with a DTA per level -- our GEMDOS keeps a search by the DTA that owns it, as the ST does. It loads its resource from the disk beside it, its icons EmuTOS's, checked in like the font. Its gate is a new kind: the desktop is a program, not a script, and which calls it makes depends on what the AES answers, so tools/deskref.py is the desktop transcribed against the model, and the harness syncs to the ABI's own call counter rather than a record count. A tenth compiler defect (parameters clamped in place, then read from a slot never written) put two of three icons off the screen on the first run; an eleventh (a near-to-far struct copy over 8 bytes is an internal error) is copied around byte by byte. The first window open ran the application's 256-byte stack out, and a .G4A's stack is sized per link now; and the hourglass that stayed over an opened folder was the donor's gsx_mfset hide-and-show, missing on both sides of the gate. The transcription found the next one on the host before the emulator ran: the desktop's loop ends on do_open's answer, and a drive's window opening had been answering TRUE -- as it found, a milestone later, that a New folder was answering the same way and quitting the desktop. The delete's dialog broke one of the compiler's own rules (a 16-bit load through a local pointer with the arithmetic in the same expression, tools/ccbug rule 5) and filled 25 KB with spaces, through GTIA space, which soft-resets VBXE, and through POKEY's IRQEN, which froze the machine in an interrupt storm: the gate's post-mortem -- which call the target is inside, what the delete had counted, the CPU's last thirty-two instructions -- is how that was read back.

What a double-click means (docs/phase48.md). The desktop reads the ST's vocabulary: .PRG, .APP, .TOS and .TTP are programs, and so is .G4A, the container's own name, which is what 0.5 installed and is kept so a disk somebody already has goes on working. .TTP asks for a command line first, which is the whole of what the extra P means. Anything else is a document, and a document double-clicked puts up Show | Print | Cancel — Show pages it through the desktop's text window, Print sends it to whatever GEM4XE.CFG names. The extension is the role; the format is the loader's business, and it reads the file's magic, so a 68000 .PRG off a real Atari is turned away with a message instead of run.

What starts before the desktop does (docs/phase48.md). \GEM\AUTO\ is run in name order before anything else, and a program there that ends with Ptermres is kept — all or nothing, the region being the unit, because both allocators are bump allocators and a partial release leaves a hole neither can use. Then *.CPX, then *.ACC, and only then the mark that fixes the permanent floor. The control panel is a host: it asks the AES for the modules it loaded (appl_getinfo(AES_CPX), the sixteenth subject), lists them, and calls the one you open through the vtable that module published — a form CPX runs its own form_do, an event CPX draws and is then fed events one at a time until it says stop. GENERAL.CPX is the worked example: double-click speed, menu delay, the date and the time, saved to a file of its own and put back at the next boot before anybody sees the desk. A module can also put up one of the panel's canned alerts, by number rather than by carrying a sentence of its own — so every module says "that file was not found" in the same words, and a translator translates it once. The ABI is one uint32_t per entry and not the pointer it wants to be, because a saveds function on this compiler switches its direct page before it reads a second argument, or a first one that is a pointer — measured, not assumed.

What is not built yet, and is written down so it shapes what is (docs/shipping.md). The system is 145 KB of files — 168 KB once it is on a floppy's 253-byte sectors — which is more than a single-density disk holds and more than an enhanced-density one holds either. Double density is where the DOS 2 product disk lives now, and tools/atr.py writes it: 253-byte sectors take the DOS, its shell, GEM and the desktop with 87 sectors to spare — enough for a DESKTOP.INF and not for a program. Since GEM.COM carries both display drivers (docs/phase34.md) that floppy is the system and nothing else; an application goes on the applications floppy, gem-apps.atr, or on the card (docs/media.md). The volume gem4xe belongs on is a CF card or a hard disk with APT partitions, and make writes one: build/gem-cf.img is a 16 MB image with an APT table, two 8 MB SDFS partitions and the install layout on the first — the system in \GEM\, an application in \APPS\, an AUTOEXEC.BAT that runs it. make test-cf boots that card into the desktop, on the machine the project is for: an Ultimate 1MB whose flash holds SpartaDOS X and the PBI BIOS, a SIDE 2 with the card on its IDE bus. Nothing on the card is a driver — the PBI BIOS reads the APT table and mounts the partitions as D1: and D2: before any DOS runs. Three things about that machine had to be read out of its own firmware first, including the wait at $D803 that stops the disk dead while the SIDE still claims the cartridge window (docs/shipping.md §3). make sd writes the same card in the shape a SubCart / AVGCART wants -- a FAT32 partition first, the APT after it -- and make test-sd boots that one. The floppy is now the bootstrap, not the ceiling. The product floppies come up in the desktop rather than at a prompt: the SpartaDOS X one from its AUTOEXEC.BAT, the DOS 2 one from AUTORUN.SYS — which DOS II+/D, the disk's old DOS, turns out not to have at all. Nothing is typed on the way in: a Rapidus always cold-boots as a 6502, and the loader switches it (docs/phase23.md). No string a person reads belongs in the C, and none does now: the desktop's fifteen alerts are free strings of DESKTOP.RSC, asked for by index (fun_alert, the donor's shape), and the gate puts one on the screen and compares it. The one exception is the alert that says the resource is missing, which cannot come from the resource.

A translation is two files (docs/phase15.md). LANG.RSC is what the system says — form_error's alerts, the shell's failures — kept far-resident and copied a string at a time into a near buffer, since bank $00 is the scarce thing, with the same bytes linked in as the English a disk without the file falls back on. SYSTEM.FNT is the character set it says it in: the 8x8 strip is loadable, so Latin-2, Cyrillic, Greek or Turkish (all of which EmuTOS ships, and make fonts writes out) replace the Atari ST set the system links. make test-m20 boots three disks — the English, a German one, and no file — and make test-m21 two, with and without a font; both are compared with the models given what that disk carries. The calls are GDOS's own (vst_load_fonts, vst_unload_fonts, vst_font, vqt_name) and none of the rest of GDOS: with 14 MB the memory was never the constraint, the AES's fixed character cell is. An application's own .RSC stays the third file, because a GEM dialog's geometry travels with its text.

The applications this is for (docs/gacs.md). GACS — the GURPS Autoduel Construction Set — and RetroWP are why gem4xe was started: a portable C89 engine each, a shell per platform, the Atari ST first. make gacs-check compiles GACS's engine with Calypsi for the 65C816 in both data models, links it with its working set in far memory, and runs it in Calypsi's simulator against the six tables GACS ships: 27 chassis, 13 engines, 10 tires, 20 weapons parsed, a design computed, ad_compute answering AD_OK, and the line GACS's own CLI prints. It wants 24 KB of code and ~56 KB of data, all far — and 84 bytes of bank $00. Every AES call its GEM shell makes is implemented here, its resource is the format we read, and its dialogs are laid out in character cells that fit 640×240. What is missing is a shell, one linker line, and — for both programs, eventually — a printer.

Every gate compares the target against a host reference model — tools/vbxeref.py, tools/vdiref.py, tools/aesref.py — which is treated as the specification. Both pixels and returned values are compared, byte for byte, running on emulated hardware with all three boards fitted.

Nothing here is asserted by eye. Two of the bugs found so far were invisible on screen and only a pixel diff caught them — and one went the other way: the file selector listed a file the reference did not, every returned value agreed, and only the screenshots disagreed (docs/phase11.md).

The numbers on this page are not typed in. The host suite's size, the version and the defect count below come from the tree, and make test-host fails when the page disagrees with it or when a gate make test runs is not described here at all — which is how four of them went a whole release unmentioned. make readme writes the numbers back. It writes numbers: what each gate proves is the third column of that table and no tool can generate it, so a gate nothing has said anything about is an error for a person rather than a row invented to go green.

Calypsi cc65816 5.18.2 has 23 defects this tree has met — mostly in code generation, plus two crashes in the compiler itself, a compile that never finishes, a refusal and a bad link — each reproduced in the vendor's own simulator and worked around at the source (or, for the divide flags, with a linker override). tools/ccbug/README.md lists them one by one with the rules the sources follow; make check-cc runs every workaround shape and reports which defects are still present, so one fixed upstream shows up as a workaround that can go.

Needs Calypsi 5.18+ for the 65816 and Python 3. There is no Atari target in Calypsi, so this tree carries its own board support: src/crt_atari.s, src/gem4xe.scm and tools/mkxex.py. The C itself is compiler-neutral: every word Calypsi adds to the language — __far, __attribute__((tiny)), __simple_call, the interrupt intrinsics — is mapped once in src/portab.h (FAR, TINY, SIMPLE_CALL, cpu_sei()…) and appears nowhere else, which tests/host/test_portab.py enforces; a second 65816 compiler needs a second block in that header and its own assembly sources, not a sweep through 36,000 lines. The GEM system font is extracted from an EmuTOS checkout at build time rather than committed here, so point EMUTOS= at one; CALYPSI= finds the tool chain. Both default to ~/dev/….

make            # build
make sdk        # the application kit, for writing a program that runs on it
make dist       # what a tester is handed: the disks, the kit, and how to try it
make release    # the same for the public, named by VERSION: tarball, zip, the two DOS-less floppies, checksums
make test-host  # the host tests: no emulator, no fixtures

The emulated gates need AltirraSDL, and the ones that put an Ultimate 1MB in the machine need the patches in tools/altirra/ as well. The CPU core, the U1MB switches and the bridge's 65C816 debugging went up as pull requests #88 and #90 and were merged on 2026-09-06, so a current upstream build has them; one patch is still outstanding — the H: device joins native paths with a backslash, which Linux takes as a character in the file name — so until that lands, run those gates with ALTIRRASDL=/path/to/patched/AltirraSDL.

They also need Atari disk images, and none is distributed here: a DOS 2 disk, a double-density DOS 2 disk, a SpartaDOS 3.2 disk, an SDX cartridge image, a U1MB flash image. Copy fixtures.toml.example to fixtures.toml (gitignored) and put your own paths in it; the harness copies an image into build/ before it touches it, and a gate whose fixture is missing says so and stops.

make test       # host tests + the emulated gates
make test-cf    # the CF card on the U1MB machine (needs [u1mb].flash)
make test-cf-dosclock   # the same, with the DOS as the clock

GPLv2 or later — see COPYING, and docs/licence.md for the position in full, including the one thing still outstanding. The lineage is EmuTOS, which is the Caldera-GPL'd Digital Research GEM source carried forward in C, so the licence is inherited rather than chosen.

It is v2-or-later throughout, including the AES, and the reason is in GPLv2 itself rather than in an assumption: EmuTOS's vdi/*.c say "version 2 or at your option any later version", its aes/*.c name no version at all, and section 9 says that when a program does not specify a version "you may choose any version ever published by the Free Software Foundation". Silence is the recipient's choice, not a v2-only grant.

No Apache-2.0 object is linked — src/sys/clib.c supplies the eight ISO C functions Calypsi took from NuttX — and the 826 bytes of GEM.COM, 0.8% of it, that is the compiler's own runtime falls under the GPL's System Library carve-out for "a compiler used to produce the work" (GPLv3 §1; GPLv2 §3 more loosely), so the binaries are wholly distributable as they stand. Calypsi's own licence expressly permits "producing application software for vintage and retro computing systems". tests/host/test_licence.py reads the linker maps and fails if the Apache-2.0 half regresses or the runtime set grows.

Where a file follows EmuTOS, its header names the donor file it follows, and the two trees are read side by side deliberately — this is a port, not a clean room. Two provenance rules hold everywhere else:

• The Atari Corp VDI/AES corpus is a specification only. It settles what a real ROM does; no line of it appears here.
• Nothing that is not ours to give is in the tree. No ROM images, no disk images, no firmware: the disk images are the user's own (fixtures.toml), and the Altirra patches in tools/altirra/ are diffs against a GPLv2 project that are also filed upstream. What is here from elsewhere is GPL'd and says so in its own header: the GEM 8×8 font and the standard fill patterns, extracted from EmuTOS by tools/fontconv.py and tools/patconv.py and checked in — so the host reference reads the same bytes the target links, and an EmuTOS checkout is needed only to regenerate them.