Camputers Lynx 48K

Embedding

The Lynx is an all-Z80 machine, so this build pairs the vendored MIT Z80.js core (the same Zilog Z80 core reused across the emulators.org Z80 machines) with a from-scratch port of the board. Everything runs on the main thread from a host-owned loop, so the debugger can pause and single-step it.

Boot. Constructing the machine fetches the two 8 KB system ROMs into a 16 KB image, sets the reset banking, resets the Z80 and starts a 50 Hz loop; the machine comes up at the Lynx BASIC prompt:

var m = new CamputersLynx({ canvas, romBase, romFiles });
m.boot();                              // fetch ROMs, reset banking + Z80, run
// each 50 Hz field runs 80,000 T-states, then takes one VSYNC interrupt

The machine object. Everything the host and debugger need is a field or method on the machine; there is no wasm heap to reach into:

Video. The screen is 256×248 in eight colours, held in three 8 KB planes (red at 0x2C000, blue at 0x28000, green at 0x3C000 - or the alternate green at 0x38000 when port 0x80 bit 4 is set). Each byte is eight horizontal pixels, most-significant bit leftmost; the per-pixel colour index is (blue<<2)|(green<<1)|red into the 3-bit RGB palette. The renderer rasters all three planes into the canvas each frame.

Debugger integration

Because the whole board is ordinary JavaScript and the host owns the run loop, the debugger's controls need no changes to the CPU core: the loop can pause, single-step and check breakpoints between any two instructions. window.EMU_BOOT.transport maps the shared debugger onto the Z80A:

• pause / resume / isPaused - stop or restart the requestAnimationFrame loop.
• stepInsn(n) - run exactly n Z80 instructions through the core's run_instruction().
• step(n) - advance n whole 50 Hz fields, each honouring the one VSYNC interrupt.
• breakpoints - a Set of PC values checked before each instruction; a match pauses before the instruction runs.
• watchpoints - the Z80's memory-write path flags a hit when a watched address is written, and the loop pauses on it.

The stock Z80.js keeps its registers in a closure and exposes a whole-core getState()/setState(). To make the debugger's live register window cheap, the vendored core carries two small hooks - get_pc() and set_pc() - so the loop can read PC before every instruction (for breakpoints) without allocating a state object, plus get_iff1() so the host only delivers the VSYNC interrupt when the Lynx ROM has enabled interrupts. Register read/write goes through focused getReg/setReg/getFlag/setFlag helpers that pack and unpack the Z80 flag byte. Memory reads use the machine's side-effect-free dbgRead, which walks the current bank selection without touching the I/O ports, so inspecting memory never disturbs banking or the keyboard scan. The Z80 disassembler is the shared decoder at /debugger/src/cpus/z80.js - reused unchanged, since the Z80 is already a first-class debugger CPU.

Architecture

The Camputers Lynx 48K (Camputers Ltd, 1983) is a British Z80A home computer designed for high-resolution colour graphics:

• Z80A CPU at 4.0 MHz (a 24 MHz crystal divided by six). The core interprets one instruction per run_instruction(); the shared z80 decoder disassembles it.
• Banked memory - eight read banks of 8 KB over the 64K address space, each pointing at one of 32 entries (the 16 KB ROM, 64 KB of user RAM, or the video planes), selected by writing port 0x7F (mirrored at &FFFF). Writes fan out to several physical banks at once through a write-enable mask, which is how a screen write reaches the colour planes.
• Three colour planes - separate 8 KB red, green and blue video memories combined into a 256×248 eight-colour picture, timed on the real machine by an MC6845 CRTC.
• Keyboard - a 10-line matrix read over the I/O bus at IN (line<<8 | 0x80), active-low; Shift and Control are themselves matrix keys.
• Interrupts - the CRTC's VSYNC drives the Z80 /INT once per 50 Hz field; the ROM runs in interrupt mode 1, so each field vectors through RST 38h.
• System ROM - a 16 KB BASIC / monitor in two 8 KB chips (lynx48-1.ic46 + lynx48-2.ic45) that prints the BASIC prompt the machine boots to.

The 6-bit sound DAC on port 0x84 and the cassette interface are not emulated; the CPU, banked memory, colour planes and keyboard - everything the debugger inspects - are faithful.