OXYGENHUB

Per Platform Notes

Andy McCall edited this page · 3 revisions

Per-Platform Notes

The contract is identical everywhere; the memory/register model and the launch flag differ. GET /status.platform tells the client which model to expect.

Commander X16 — x16emu (reference implementation)

  • Flag: -controlport <N> (single-dash, matching x16emu's -dump style).
  • Framebuffer: 640×480, native byte order BGRA8888; the server swizzles to PPM RGB.
  • Address space: 16-bit CPU (0x0000–0xFFFF). The banked window 0xA000–0xBFFF is selected by bank (RAM bank), backed by the emulator's read6502 debug path. Addresses below 0xA000 / at/above 0xC000 ignore bank.
  • Registers: a x y (8), sp pc (16), status (8), plus ram_bank, rom_bank.
  • Levels: the fork serves 0.5.0; the enhanced X16 emulator serves 0.6.0, with /perf. Its budget: 8 MHz, 525 lines a frame at 59.52 Hz, 134,400 cycles, 256 a line. Guest markers are writes to $9FBC (reads 1 there; the fork reads $FF and warns at every write, so detect first). platform carries VERA's bus per scanline and the sprite renderer's time — see Performance Metrics.
  • Pads: canonical layout → the SNES serial order, active low, converted in the backend.
  • Run recipe (headless, no Xvfb): 
    SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
    x16emu -rom rom.bin -warp -controlport 8080
    The SDL dummy video driver keeps video_step running (framebuffer fills, frame counter advances) with no display. Do not pass x16emu's -headless flag — it skips video stepping entirely, which blanks /screenshot and freezes /step.

Neo6502

  • Flag: --control-port <N>.
  • Address space: flat 64 KB; bank ignored.
  • Registers: 6502 a x y sp pc status.
  • Framebuffer: native resolution for the current video mode.

Agon (Console8 / Light 2) — FAB Agon Emulator

  • Adoption: conform-only — the FAB emulator is Rust, so it keeps its own HTTP server and matches the contract rather than vendoring the C core. See the two adoption paths.
  • Flag: --control-port <N>.
  • Address space: eZ80 24-bit, flat 16 MB (addr up to 0xFFFFFF); bank tolerated and ignored. Program load base 0x040000.
  • Registers (ADL) — /regs example (16-bit regs; mbase 8-bit; adl 0/1): 
    { "af":0, "bc":0, "de":0, "hl":0, "ix":0, "iy":0,
  "sp":0, "pc":262144, "mbase":0, "adl":1 }
  • Framebuffer: the VDP output (vgabuf); the server swizzles to PPM RGB. The offscreen path already keeps video alive (FAB's equivalent of x16's SDL_VIDEODRIVER=dummy), so the "don't add a no-video mode" gotcha is already satisfied.

NEC PC-FX — Mednafen fork

  • Port: the MEDNAFEN_CONTROLPORT=<N> environment variable (Mednafen has no free-form flag for a driver add-on); unset, the server is off. Vendors the core as a submodule, built with ./configure --enable-rrdc.
  • Input: a gamepad, not a keyboard: /key maps characters onto a WASD-style pad; /pad maps the canonical layout onto the FX pad word.
  • Pointer: none — refusing stubs (400), so it can advertise 0.5.0 for /pad.
  • Audio: fed by the mixer, so run with sound on (-sound 1 -sound.driver dummy) for headless capture.

The SPEC's appendix has the details for every platform.