ZX Spectrum Knowledge Base

Knowledge about ZX Spectrum, clones, next-gen for software developers, demosceners, retro-enthusiasts.

Documentation Map

01 — Z80 CPU

Article	Description
z80_architecture.md	Registers, ALU, pinout, bus interface, and internal datapath
z80_addressing.md	All addressing modes — immediate, register, indirect, indexed, relative
z80_flags.md	S, Z, H, P/V, N, C flags — per-instruction behavior, DAA, BCD arithmetic
z80_instruction_set.md	Complete ISA: 698 instructions, opcode encoding, timing, groups, decision guides
z80_undocumented.md	IX/IY halves, SLL, MEMPTR, F3/F5, OUT (C),0, clone detection, R register
z80_timing.md	T-states, M-cycles, half-clock bus timing (opcode latched at T3 rising vs data at T3 falling), WAIT pin vs clock stretching, per-instruction costs, DRAM refresh
z80_interrupts.md	IM0/IM1/IM2, NMI, IFF1/IFF2, vector tables, EI latency, per-model timing
z80_vs_modern.md	Z80 vs x86-64/ARM64 comparison, register mapping, programming mindset shift
z80_coding_practices.md	Register discipline, instruction selection, arithmetic tricks, contention-aware coding, stack blitter

02 — Hardware

Original Sinclair/Amstrad

Article	Description
ula_timing.md	ULA frame timing per model, memory contention, multicolor effects, early/late timing, performance budget
ula_architecture.md	Inside the Ferranti ULA: video pipeline, bus arbitration, #FE register, keyboard/tape/sound cells, revisions, gate arrays, replacements
keyboard_matrix.md	The 8×5 keyboard matrix: membrane hardware, half-row scanning, ghosting, Interface 2/Sinclair/Cursor joystick mappings, game keyset conventions by genre and region, redefinable input

Soviet Clone Ecosystem

Article	Description
clone_timing.md	Clone video timing — Pentagon, Scorpion, Kay, ATM Turbo, FPGA implementations; why slot-based clones have no contention, Scorpion Even M1; detection techniques
clone_joysticks.md	Built-in Kempston on clone motherboards, Beta 128 coexistence, two-player conventions, single-standard software culture
atm_turbo.md	ATM Turbo: CP/M mode, 7 MHz turbo, 4 video modes (320×200 16-color, 640×200, 80×25 text), IDE controller, flexible memory paging, 64-color RGBI palette
scorpion.md	Scorpion ZS-256: Serge Zonov / Leningrad lineage, true 48K timing (69,888 T-states), no contention but "Even M1" fetch alignment (SC15.1 EPLD equations, boards, emulators), Shadow Service Monitor debugger, port #1FFD turbo+extended paging, #FF floating bus (correct), SMUC ISA bridge, GMX 2 MB / 640×200×16, ProfROM
profi.md	Profi 5.03/1024: CMR0/CMR1 paging (#7FFD + #DFFD: page high bits, SCO window position, NOROM, SCR, DS80), extended screen 512×240 hardware multicolor (half-screen interleave, 16-color attribute byte, 16-of-256 palette protocol), ISA bus, VGA output, paper-offset quirk

New Generation

Article	Description
zx_next.md	ZX Spectrum Next complete hardware reference: layer stack, NextReg system, Layer 2 framebuffer, hardware sprites, tilemap, copper, DMA, joystick system, Z80N extensions
sprinter.md	Peters Plus Sprinter (2000): Z84C15 @ 21 MHz, 4 MB RAM, Altera ACEX EP1K30 reconfigured from flash at boot, per-cell video modes (320×256×256 / 640×256×16), RAM-based soft port map, copy accelerator, IDE, ISA-8
sprinter_firmware.md	Sprinter firmware & sources: PLD configurations and bitstream loading, RAM copy accelerator (`LD r,r` opcodes, `#C7` scale), BIOS 2.02→3.07, Estex DSS 1.52→1.71, board history sp97→sp2016s 1996–2026, source-repository catalog
zx_evo.md	ZX Evolution (2007): hybrid Z80 + Altera FPGA + ATmega MCU, Pentagon 1024 hardware compatibility, modern extensions (turbo/IDE/SD/PS-2)
baseconf.md	BaseConf (default ZX Evolution firmware): Pentagon 1024 profile, `#7FFD`/`#DFFD`/`#EFF7` paging, Nemo IDE (16-bit words, both byte orders), turbo + emulated contention, revisions A/B/C
ts_conf.md	TS-Conf enhanced firmware: `#xxAF` register space, shared-DRAM architecture, 2 tile layers + 85 sprites in 3 layers, 4 modes × 4 geometries, RGB555 CRAM, 9-task DMA, CPU cache, 4 INT vectors
vdac2.md	VDAC2: FT812 EVE2 GPU card for the ZX Evolution IDE slot — display lists, coprocessor, 640×480/800×600/1024×768 @ 57–85 Hz, SPI + DMA programming, msel, VDAC lineage, DXT trick, VDAC2 games, emulation

04 — Operating Systems ✅ COMPLETE

ROM Internals

Article	Description
rom_48k.md	48K ROM: initialisation, RST vectors, command dispatch, calculator instruction set (66 ops), command handler internals, tape format
rom_128k.md	128K ROM 0: dual-ROM architecture, ROM call bridge, ROM swap calling convention, PLAY/SOUND/BANK handlers, AY-3-8912 register map, RAM disk, editor internals
rom_plus2.md	+2A/+3 ROM internals: 64 KB four-page layout, paging ports `#7FFD`/`#1FFD`, four paging modes (128K compat / all-RAM 0-3 / all-RAM 4-7 / Plus 3), CP/M boot, bugs
system_variables.md	ROM-defined system variables: FRAMES, PROG, VARS, CHANS, keyboard state, memory boundaries — the ROM's API surface
rom_versions.md	ROM version catalog: 48K Issues 1-6 CRC32 values, 128K, +2 grey, +2A/+3 four-page, localised ROMs, clone ROMs (Pentagon, Scorpion, ATM Turbo, ZX Evolution, Timex), modern replacements (SE BASIC, OpenSE, +3E, NextZXOS)

Disk Operating Systems

Article	Description
trdos.md	TR-DOS: the Soviet flat filesystem standard for Pentagon/Beta 128, 128 file slots, hook codes API, why it dominated the Russian scene
plus3dos.md	+3 DOS: Amstrad's CP/M-compatible DOS for +2A/+3, BDOS layer, RSX-based BASIC integration (`LOAD "a:..."`, `CAT`, `FORMAT`)
nedoos.md	NedoOS: multitasking OS for ATM Turbo 2 / ZX-Evo (nightly): kernels per board, 16 tasks, network stack, Moon Rabbit browser
esxdos.md	ESXDOS: modern Western DOS for DivIDE/DivMMC, FAT16/32, 8 KB dot-command overlays, hook codes API at `#0084`
is_dos.md	IS-DOS: 1990s Russian hierarchical filesystem alternative, MS-DOS-compatible 32-byte directory entries, subdirectories, attributes, jump-table API
nedo_dos.md	NedoDOS: modern DOS for ZX Evolution/NedoPC, FAT16/32 with VFAT long filenames, SD/CF/IDE, multiple partitions, NedoDOS Commander
nextzxos.md	NextZXOS: ZX Spectrum Next OS, ESXDOS-derived API with Next hardware extensions, dot commands, SD card, layer 2 / sprite / tilemap
evo_os.md	ZX Evolution BIOS/OS: three-layer stack (boot ROM firmware, BaseConf FPGA bitstream, OS), Pentagon 1024 / ATM Turbo / TS-Conf configurations, boot process

Alternative Operating Systems

Article	Description
cpm.md	CP/M 2.2 on Spectrum: +3 bootable CP/M, ATM Turbo, Sprinter, BIOS/BDOS layer, file control blocks, CCP, the CP/M software library
atm_cpm_bios.md	ATM Turbo CP/M BIOS & BDOS reference (MicroART 1993, translated): BDOS functions via `#0005`, BIOS vectors + ATM extensions, DPH/DPB tables, ROM monitor at `#F800`, ESC screen-driver sequences, channel-based disk monitor (RAM disk/FDD/HDD), 20 ms MUX clock
fuzix.md	FUZIX: Alan Cox's Unix-like Z80 OS — ~24 KB kernel, ~70 Unix V7 syscalls, pre-emptive multitasking at 50 Hz VBLANK, FCC C compiler, targets 128K/+2A/+3/Pentagon/ATM/Sprinter/Evolution/Next

BASIC Dialects

Article	Description
basic_dialects.md	Sinclair BASIC variants: 48K (1982), 128K (1986), +2/+2A/+3 (1987), TR-DOS ext, QL SuperBASIC (1984), SE BASIC / OpenSE (2002-2023), NextBASIC (2017). 17-feature comparison matrix

05 — Development

Sinclair BASIC

Article Description

basic_48k.md Sinclair BASIC 48K — comprehensive reference: what BASIC is (vs Microsoft BASIC), three ROM versions, memory layout, token system with abbreviations, variable types, 5-byte floating-point format, calculator stack (44 operations), parser pipeline, graphics commands (PLOT, DRAW, CIRCLE, POINT, ATTR), sound (BEEP with frequency formula), machine-code bridge (PEEK, POKE, USR), notable quirks (no ELSE, mandatory LET, single-line editor). Worked examples: Mandelbrot, Ode to Joy

basic_128k.md Sinclair BASIC 128K extensions: new full-screen editor, boot menu, the PLAY command mini-language in depth (notes c-b/C-B, sharps/flats, octave O0–O8, volume V0–V15, envelope W0–W7, tempo, channel mode, repeats, three-voice harmony), direct AY-3-8912 register access via OUT/IN, +2A/+3 disk commands (CAT, FORMAT, ERASE), token table differences, memory paging, RAM disk

Assembly

Article	Description
assembly_intro.md	Getting started with Z80 assembly: toolchain setup (SjASMPlus + Fuse + VSCode/DeZog), source file structure, 48K memory map, annotated Hello World walkthrough, building pipeline (.asm to .tap/.sna), output formats (SNA/TAP/TZX/TRD/NEX), first debugging session, when to use asm vs C vs BASIC
rom_calls.md	Calling the ROM from assembly: entry-point landscape, save/restore state (IY = #5C3A, ERR_SP), cookbook for character output, keyboard, screen, BEEP, math via FP calculator, 128K routines (PLAY), AY-3-8912 direct access, ROM-call wrapper macros, when NOT to use ROM
stack_and_rst.md	Stack, RST vectors, calling conventions: stack mechanics (T-state table), balanced stack rule, eight RST vectors, five calling conventions, shadow registers (EXX/EX AF,AF'), stack as temp storage, computed calls (JP (HL)), stack frames for locals, ERR_SP try/catch, recursion
assembly_patterns.md	Assembly design patterns: state machines (Moore/Mealy), dispatch tables, table-driven code, function pointer tables (plugin architecture), coroutines via stack swapping, self-modifying code patterns, macro systems, modular file organization, 128K memory banking patterns
assembly_optimization.md	Performance optimization: optimization workflow, T-state budgeting (69,888T/frame), hot-loop techniques (loop invariants, LDIR, DJNZ, unrolling), lookup tables (sine, multiply), fast multiply/divide algorithms, SMC in hot loops, contended vs uncontended memory, 10-recipe performance cookbook
c_interop.md	Mixed C and assembly: sccz80 vs zsdcc, calling conventions in depth (FASTCALL, __sdcccall), C-calls-asm + asm-calls-C, inline assembly, shared globals (PUBLIC/EXTERN), project structure (multi-file, Makefile), zcc build pipeline, performance patterns (which C ops are slow on Z80), z88dk newlib interop, complete worked project

Memory & I/O

Article	Description
io_port_decoding.md	I/O port concepts: partial decoding, masks, mirrors, conflicts
memory_and_io_48k.md	16K/48K: memory map + #FE port (border, EAR, keyboard, beeper)
memory_and_io_128k.md	128K/+2: 8 banks, #7FFD paging, shadow screen, AY ports
memory_and_io_plus3.md	+2A/+3: #1FFD, 4 paging modes, true double buffering, +3 FDC
memory_and_io_pentagon.md	Pentagon: #7FFD extended bank bits + #EFF7 control gate, Beta 128 FDC/TR-DOS, zero contention
memory_and_io_next.md	ZX Spectrum Next: 2MB MMU, 8 KB pages, Layer 2/sprite/copper/DMA ports
screen_layout.md	Nonlinear framebuffer: three-thirds structure, address calculation, attribute file
contention_model.md	Unified contention reference: why shared DRAM slows the CPU (clock stretch, WAIT, fixed slots), per-model table for all tracks, Ferranti vs gate array patterns, I/O contention, Scorpion Even M1 with T-counted example
bank_switching_patterns.md	Practical 128K+ paging: #7FFD, cross-bank access, double buffering, +2A/+3 modes

Interrupt Programming ✅ COMPLETE

Article	Description
interrupt_programming.md	Foundational guide: IM1/IM2 setup, 257-byte vector table, ISR patterns, T-state budgets, contention, cookbook, antipatterns
race_the_beam.md	Raster-synchronized multicolor: 8×8 constraint reframed, T-state budget per scanline, 5 sync strategies (HALT, floating bus, port-#FF, line interrupt, copper), BIFROST* engine deep dive
nmi.md	NMI and the Multiface: 74LS74 flip-flop hardware, NMI vs INT comparison, 4 NMI-safe code rules, NMI during common operations table, DivIDE/ESXDOS magic button
im2_effects.md	Demoscene IM2 effects: vector table placement rules, 15-game disassembly survey (256 vs 257-byte tables), 3 manager patterns (direct / JP trampoline / Hudson Hawk bank-switching), 5 ISR effect catalog, demo framework sequencer
im2_disk_music.md	Disk load with AY music: WD1793 byte budget, Ivan Roshchin concurrency math (Pentagon 48.83 Hz, 9.77 interrupts/rev, 138-byte drift), 3 workaround patterns (music-after-sector / stop-motor resync / custom WD1793 driver), Western DOS comparison
im2_advanced.md	Advanced IM2 platforms: ZX Spectrum Next hardware IM2 mode (core 3.02+, 8 prioritized sources, RETI mandatory), TS-Conf separate frame/line/DMA vectors, copper vs ISR decision matrix, Hudson Hawk 128K bank-switching ISR deep dive, sample-rate ISRs (AY/Covox/beeper PWM)

See 04_interrupts/README.md for the section index. All 6 articles complete.

Display & Timing

Article	Description
video_frame_overview.md	PAL fundamentals, ULA frame cycle, T-state budget, contentious vs non-contentious time
video_frame_48k.md	48K frame: T-state map, contention pattern, floating bus, performance budget
video_frame_128k.md	128K frame: odd-bank contention, shadow screen, floating bus differences
video_frame_pentagon.md	Pentagon frame: 320 lines, binary counter, zero contention, 48.83 Hz
video_frame_plus2a_plus3.md	+2A/+3 frame: Amstrad gate array contention, different contended banks, no I/O contention
floating_bus.md	Floating bus: per-model behavior, raster sync via IN A,(#FF), why it fails on +2A/+3 and Pentagon
raster_timing.md	Beam position calculation, HALT-based sync, per-model raster maps, cross-platform strategy
color_system.md	Attribute byte, 8-color palette, attribute clash, ULAplus 64-color, Timex HiColor/HiRes
border_effects.md	Border color via #FE, raster bars, rainbow borders, per-model timing
clone_video_modes.md	Clone video modes: GigaScreen, ATM hires, Profi 512×240, Kay CPLD, TS-Conf
spec256.md	Spec256: 256-color Z80_GFX co-processing model — lockstep shadow CPU, 8 planes per address, .gfx/.cfg formats, emulators and FPGA cores
zxpoly.md	ZX-Poly: four lockstep Z80s vs attribute clash (1994 concept, never manufactured) — SIMD bitplane platform, adapted-games corpus
video_frame_scorpion.md	Scorpion ZS-256 frame: 312 lines matching 48K macro timing, +9 T horizontal shift, no contention but Even M1 (RAM fetches on even T), 7 MHz turbo with paper-dependent slot waits
video_frame_other_soviet.md	Long-tail Soviet clones: Kay 1024 (48K-clean), ATM Turbo 7 MHz anomaly (99,880 T-states), Profi paper offset, Byte, Quorum, Leningrad, LEC
video_frame_next.md	ZX Spectrum Next: configurable timing modes (48K/128K/+2A/Pentagon), 4 CPU speeds (3.5/7/14/28 MHz), copper coprocessor
video_frame_sprinter.md	Sprinter: PAL-family frame (312 lines @ 50.08 Hz = Pentagon's 69,888 T exactly, or 320 lines @ ~48.8 Hz), 42 MHz FPGA clock tree, selectable INT timing, no contention
video_frame_zxevo.md	ZX Evolution (PentEvo): real Z80 + Altera MAX CPLDs, Pentagon-compatible base, BaseConf vs TS-Conf configurations
contention_timing.md	Per-T-state delay tables (Ferranti 6-5-4-3-2-1-0-0, Amstrad 1-0-7-6-5-4-3-2), per-instruction contended cost tables
interlace_and_flicker.md	Non-interlaced output, 50 Hz perception threshold, attribute flicker, GigaScreen flicker math, CRT vs LCD
crt_output.md	Developer view of CRT/LCD output: pixel aspect ratio, overscan, composite artifacts, per-display-type behavior
video_frame_comparison.md	Synthesis: all models side-by-side — T-states/frame, contention, turbo, compatibility matrix, detection decision tree

Graphics Techniques ✅ F12 COMPLETE

Article	Description
screen_access.md	Foundational primitives: address lookup tables (pixel + attribute), fast clear via stack push (DI/EI safety), block copy, attribute manipulation, custom font rendering (8×8 + FZX proportional), viewport clipping, dirty rectangle
sprites_and_masking.md	Software sprites: four compositing modes (XOR / OR / LOAD / MASK) with T-state budgets, pre-shifted sprites (24×16 effective ×8 shifts), masked sprite layout interleaved vs planar, three-screen buffered drawing with eight-phase frame loop, sprite pools, engine surveys (SP1, AGD/MPAGD, BIFROST*, NIRVANA+), color clash workarounds
scrolling_and_buffering.md	Scrolling: character-cell scroll, pixel-smooth horizontal scroll via stack push (Dean Belfield 25 Hz two-frame cycle, dixel), 128K shadow screen double buffering (port #7FFD bit 3, banks 5/7), dirty rectangle partial update, vertical scroll, parallax, split-screen
multicolor_engines.md	Multicolor engines: the direct continuation of race_the_beam.md — engine survey (BIFROST* 8×1 18×18, NIRVANA+ 8×2 32×23, ZXodus), ULAplus 64-color palette (G3R3B2 encoding, ports #BF3B/#FF3B, 4 palette groups, runtime detection), Timex HiColor (8×1 hardware) and HiRes (512×192 mono), Soviet-clone hardware modes (Pentagon 16c, Profi 512×240, ATM Turbo 320×200), decision matrix
3d_graphics.md	3D on the Z80: the math problem (no hardware MUL/DIV), table-driven quarter-square multiply, 8.8/1.15 fixed-point, Bresenham line draw, rotation matrices, perspective projection with reciprocal table, near-plane clipping, wireframe case study (Elite), filled-polygon case study (Driller/Freescape, 3D Construction Kit, painter's algorithm), isometric (Filmation engine, Knight Lore/Head Over Heels, projection math `(x-y, (x+y)/2-z)`), raycasting (pseudo-3D), performance budgets, common pitfalls
next_graphics.md	ZX Spectrum Next graphics: 6-layer stack (ULA + LoRes + Layer 2 + tilemap + hardware sprites + border), Layer 2 (256-color framebuffer, linear layout, 3×16 KB banks at MMU slots 0-2, palette via NextReg #40/#41, double buffering with banks 11-13), hardware sprites (64/scanline, 16×16, ports #303B/#57/#55, eliminates pre-shifting/masking), tilemap (hardware scrolling via two NextReg writes), copper coprocessor (MOVE/WAIT/STOP, zero CPU cost for raster effects), mixing-layer architectures, 28 MHz CPU with `MUL D,E`

See 06_graphics/README.md for the section index. All 6 articles complete (F12 series).

Game Development ✅ F13 COMPLETE

Article	Description
game_loop.md	Frame budget and sync architectures: the universal 8-bit loop `WAIT → READ → UPDATE → DRAW → WAIT`, three synchronization patterns (HALT-driven foreground for 48K, ISR-driven with `frame_flag` for 128K Ocean/Rare, cycle-counted tight loops for demos only), frame-synchronized update at ~50 Hz with no decoupled update/interpolation, T-state budget breakdown (69,888 / 70,908 / 71,680 for 48K / 128K / Pentagon), flat vs hierarchical state machines, 48K flat (~24 KB available) vs 128K banked (8 × 16 KB via port #7FFD) memory models, four ROM/RAM layouts (All-RAM tape / ROM cartridge Interface 2 / Banked 128K / Multiload), load screens and streaming, debugging symptoms
entities_collision_ai.md	Entity subsystem, collision, and AI: object pool pattern (8 bytes per entity via the `ENTITY` struct, 16–32 fixed slots, `type=0` sentinel for empty slots — no malloc/free), update ordering, dual-phase erase/draw rendering (prevents "holes" from overlapping entities), four collision algorithms (AABB ~80 T-states/pair, grid broad-phase, pixel-precise 200–500 T-states, attribute-based ~30 T-states as the cheapest), axis-separated tile collision resolution (X then Y), gravity with floor check, one-way platforms, conveyor belts, five AI patterns (FSM with state byte dispatch, fixed-path waypoints with the Manic Miner 7-byte horizontal guardian format, steering toward player, BFS pathfinding — rare and bounded), sprite integration interface
level_data_and_worlds.md	World model architectures: four canonical world models comparison table (single-screen Manic Miner / multi-room persistent Jet Set Willy / scrolling Green Beret / isometric Knight Lore), full Matthew Smith 1024-byte room format byte-offset table (offsets 0–1023, the screen-layout-as-collision-data trick), persistent state implementation pattern (immutable template + mutable state block with 1 bit per collected item), 1-direction vs bidirectional scrolling with camera update code and world-bound clamping, tile-map render pipeline, compression strategies (RLE, column-major + LZ with RCS preprocessing, tile-attribute separation, per-stage ZX0 packing), room transitions
input_sound_integration.md	Input and audio integration layer: input normalization across devices (Kempston active-high at port `#1F` vs keyboard/Sinclair active-low — polarity must be inverted before the OR-merge), edge detection pattern `input_edges = input_state AND NOT input_prev`, menu repeat timers (instant first response, 20–30 frame delay, then 4–6 frame repeat), redefine-keys UI pattern with Western (KEMPSTON/SINCLAIR/CURSOR/REDEFINE) vs post-Soviet (KEMPSTON/KEYBOARD/REDEFINE) conventions, four places music can live (foreground / ISR / separate ISR / dedicated hardware), 128K bank-switched music ISR pattern (save/restore #7FFD around the player tick), SFX channel-stealing with priority scheme (Channel C reserved for SFX, music's C ducked), memory budgets
game_case_studies.md	Engine case studies — architect's perspective on six canonical engines: Manic Miner (Matthew Smith engine, 9 KB engine underneath the screen, beeper-only foreground music), Jet Set Willy (persistent rooms, 60 rooms, multi-waypoint guardians with up to 8 waypoints each), Knight Lore (Ultimate's Filmation isometric engine, 2:1 projection `sx = x-y, sy = (x+y)/2 - z`, pre-rendered 4-view NE/SE/SW/NW sprites, painter's algorithm z-sort ~3,000 T-states for 32 objects), Alien 8 (stacking physics, batched sort), Head Over Heels (two-character gameplay Head+Heels, ~300 rooms with global persistence, 128K AY via ISR), Elite (table-driven quarter-square multiply ~100 T-states vs ~200 for shift-add, 1.15 fixed-point arithmetic, back-face culling for wireframe 3D), six cross-engine patterns (HALT-driven, fixed-pool, level-data-dominates, lookup tables, determinism, engine/data separation)

See 09_gamedev/README.md for the section index. All 5 articles complete (F13 series).

DOS & Tape

Article	Description
tape_programming.md	Tape loading and saving from assembly: ROM routines (SA-BYTES, LD-BLOCK, SAVE, LOAD), custom bit-banging loaders via port #FE, turbo loaders (3000+ baud), custom savers, border effects, error handling, decision matrix
trdos_programming.md	TR-DOS programming: ROM banking via port #FF, 9 standard hook codes dispatched at #3D13, file operations (LOAD/SAVE/ERASE/CAT), direct WD1793 sector I/O, catalog reader, demoscene double-buffered streaming from disk
dos_programming.md	Western DOS programming: +3 DOS RSX calls, ESXDOS hook codes at #0084, NextZXOS extensions, dot command development (8 KB overlays at #2000), API comparison matrix, portable code strategy, runtime DOS detection
file_format_handling.md	File format parsing: magic-byte detection, .TAP/.TZX/.TRD/.SCL/.DSK/.SNA/.Z80/.SCR formats, directory traversal from disk images, .Z80 RLE decompression, common pitfalls (byte order, compression flags, sector IDs)
mass_storage_programming.md	Direct mass storage access: IDE/CompactFlash register-level access (ATA commands), SD card SPI bit-banging, read-only FAT16/32 reader (boot sector parsing, cluster chain following), performance comparison vs OS-mediated

06 — Sound ✅ COMPLETE

Synthesis Techniques

Article	Description
ay_ym_synthesis.md	Comprehensive AY/YM sound generation: internal counter model, phase reset, sync-square, PWM, SID-sound, envelope exploitation, sample playback, drum synthesis
ay_ym_techniques.md	AY/YM Synthesis Techniques — sync-square, PWM, SID-sound, buzzer bass, note-colored noise, drum synthesis, sample playback
ay_vs_ym.md	AY vs YM Technical Comparison — DAC ladder differences, 5-bit envelope on YM, DC offset, SEL pin, per-unit variation, emulator modeling
ay_ym_perception.md	The AY Sound: Perception, Emotion, and the Hardware Soul — ABC vs ACB holy war, AY vs YM differences, why real hardware sounds different, psychoacoustics, nostalgia, recapturing the sound
beeper_synthesis.md	1-Bit Beeper Synthesis: PWM engines, multi-channel tricks, DSP emulation physics
shiru_ear_shaver_analysis.md	Case Study: Reverse engineering Shiru's Ear Shaver 1-bit engine
multitrack_multichip.md	Multi-track and multi-chip synthesis outline: TurboSound, cross-chip effects, synchronization

Sound Hardware

Article	Description
sound_overview.md	Sound hardware ecosystem overview + decision guide — navigation hub for the entire subdirectory
ay_3_8912.md	AY-3-8912 / YM2149F PSG: pinout, register map, clock domains, DAC characteristics, per-model differences
stereo_audio.md	Stereo audio modifications: ABC/ACB separation, BytesDelight
turbosound.md	TurboSound: dual/triple AY, port decoding, programming model
turbosound_fm.md	TurboSound FM: YM2203 (OPN) FM synthesis, 3 FM + 3 SSG channels
saa1099.md	SAA1099 PSG: Philips sound chip, 6-channel stereo
covox_sounDrive.md	Covox & SounDrive: 8-bit DAC hardware mixing, sample playback, TLC7226CN quad DAC
gs_general_sound.md	General Sound: dedicated Z80-based sound card, 4-channel sample mixing
moonsound.md	MoonSound (OPL4/YMF278B): 24-channel wavetable + 18-channel FM
zx_next_audio.md	ZX Spectrum Next audio: 3× AY + beeper + DMA sample playback

Trackers & Formats

Article	Description
tracker_history.md	30-year history of ZX music editors — beeper trackers (1985), Pro Tracker lineage (Golden Disk Corp.), VTII / Arkos split, modern cross-platform tools (AT3, VT3)
ay_music_formats.md	Master catalog: every AY/YM music file format (`.PT3`, `.PSG`, `.YM`, `.AY`, `.AKG`, etc.) — modules, dumps, containers, modern embedded
sound_tracker.md	Sound Tracker 1.1 (Bzyk, 1990) — the first AY grid editor; established the pattern/sample/ornament paradigm
asc_sound_master.md	Asc Sound Master (Sendetskiy, 1992) — Soviet alternative with envelope-mode-per-tick instrument model
protracker.md	Pro Tracker 1/2/3 (Golden Disk Corp., 1995–1997) — the format-defining lineage that produced `.PT3`
vortex_tracker.md	Vortex Tracker II — the de facto PC-based PT3 editor (Bulba, 2000–present)
arkos_tracker.md	Arkos Tracker 2/3 — modern cross-platform AY tracker (Targhan, 2003–present)
pt3_format.md	PT3 module format — byte-level binary specification (header, patterns, samples, ornaments, player operation)
psg_format.md	PSG register dump format — universal pre-rendered AY register stream

Player Routines

Article	Description
ay_player_routines.md	Player architecture: ISR integration, register writes, timing
player_comparison.md	PT3 vs Arkos (AKG/AKM/AKY): speed, size, features, decision table

See 06_sound/README.md for the full sound section catalog.

09 — Toolchain

Survey articles

Article	Description
native_toolchain.md	Native Spectrum toolchain — assemblers and monitors that ran on the Spectrum itself (1982–2000s). Zeus, HiSoft DevPac / GENS-MONS, ALASM+STS, XAS; pre-assembler era; editor workflow evolution; Soviet vs Western toolchain split
cross_platform_toolchain.md	Modern cross-platform toolchain — SjASMPlus, z88dk, SDCC, Pasmo, vasm, WLA-DX, zmac, RASM; VS Code + DeZog + Klive IDE; Fuse, ZEsarUX, CSpect, JSSpeccy 3, MAME; build systems, CI/CD, asset pipeline, recommended-setup decision matrix, worked Hello World example

Per-tool deep dives

Article	Description
sjasmplus.md	SjASMPlus — the de facto standard Z80 cross-assembler. Three-pass assembly, virtual device mode (14 machines), Lua scripting, ZX Spectrum Next Z80N support, complete output directives (SAVESNA/SAVETAP/SAVETRD/SAVENEX), SLD source-level debugging, comparison matrix against every alternative
z88dk.md	z88dk — the complete C development kit for the Z80 family. Two C compilers (sccz80 + patched SDCC), classic + newlib libraries, the `+target` system, the `zcc` front-end, full ZX Spectrum library API, `appmake` output formats, mixing C with assembly, worked example
sdcc.md	SDCC — the canonical reference for using the Small Device C Compiler standalone. Z80 port history, complete toolchain, Z80-specific flag reference, the stack-based ABI, custom CRT0, `.cdb` debug format, integration with SjASMPlus, worked bare-metal 48K example, and a comparison vs z88dk-sdcc
asset_tools.md	Asset Pipeline — the three-stage model (authoring → conversion → integration). Screen graphics (`.scr`/`.sch`/`.nic`), software sprites and Next hardware sprites, fonts (8×8 and FZX), AY music (VTII, Arkos) and 1-bit beeper engines (Beepola, BeepFX), compression (ZX0/ZX1/ZX2/ZX7/MegaLZ/RCS), tile maps, worked Makefile-driven pipeline
debugging.md	Debugging — the three-layer model: native monitor-debuggers (STS, MONS, Zeus Monitor), built-in emulator debuggers (ZEsarUX, Fuse, CSpect, UnrealSpeccy, ZXMAK2, MAME), and source-level / IDE-integrated debuggers (DeZog, z88dk-gdb, mainline GDB Z80 target, SpectNetIDE). Compiler-integration deep dive (SLD / `.lis` / `.map` / DWARF / `.cdb`), comparison matrix across 8 debuggers, three recommended workflows
disassemblers.md	Disassemblers — from raw Z80 bytes to annotated source. Three approaches (linear, smart static, trace-driven). z80dasm, z88dk-dis, z80dismblr / DeZog, z80-smart-disassembler, SkoolKit (with built-in cycle-exact Z80 simulator), IDA Pro, Ghidra (Z80 module caveats), Reko. Comparison matrices, decision tree, Fuse profiler + SkoolKit `trace.py` workflow
boriel_zxbasic.md	Boriel ZX BASIC — the modern BASIC cross-compiler (`zxbc`) emitting native Z80 machine code. Three-stage pipeline (`zxbpp`/`zxbc`/`zxbasm`), 8-type static type system, `SUB`/`FUNCTION` with `ByVal`/`ByRef`/`FastCall`, structured control flow, first-class inline `ASM`, ROM-binding standard library, full CLI flag reference, all output formats (`.bin`/`.tap`/`.tzx`/`.sna`/`.z80`), worked game-loop example, comparison matrix vs z88dk C and pure assembly, decision tree
vscode_integration.md	VS Code Integration — the canonical reference for VS Code as the ZX Spectrum IDE. Extension ecosystem (DeZog, Z80 Macro-Assembler, Z80 Assembly Meter, Hex Editor, Klive IDE, SpectNetIDE). DeZog deep dive — four backends (ZEsarUX, CSpect, MAME, internal simulator), reverse debugging via ZEsarUX history. Build tasks and problem matchers for SjASMPlus / z88dk / Boriel ZX BASIC. Complete worked `.vscode/` project setup. Stack comparison (DeZog+SjASMPlus+ZEsarUX vs Klive IDE vs SpectNetIDE), decision tree, best practices, pitfalls

03 — I/O — Peripherals ✅ COMPLETE

Article	Description
interface1.md	ZX Interface 1 (Sinclair, 1983) — triple-function expansion: Microdrive controller + RS-232 + ZX Net LAN. 8 KB shadow ROM paging via `M1` fetch at `#0008`, hook codes `#1B`–`#32`, ZX Microdrive sector format (254 × 543 bytes, bespoke non-CRC checksum), bit-bang RS-232, single-wire token bus for 64 Spectrums
interface2.md	ZX Interface 2 (Sinclair, 1983) — twin-joystick + ROM-cartridge expansion. MT62001 joystick decode IC, 28-pin cartridge socket mirroring 27128 EPROM pinout, `/ROMCS` pull-up disables internal ROM at `#0000-#3FFF`, the 10 released cartridges, +2A/+3 incompatibility (two-diode fix), homebrew cartridge ecosystem
multiface.md	Multiface (One / 128 / 3) (Romantic Robot, 1986–1988) — hardware overlay peripheral: 8 KB ROM + 8 KB RAM paged in via NMI vector fetch at `#0066`, three model variants with distinct port maps (`#9F`/`#1F` for MF1, `#BF`/`#3F` for MF128, `#3F`/`#BF` for MF3), `+3` paging-port back doors (`#7F3F`/`#1F3F`), stealth mode, dump-file format (precursor to `.z80`), Genie disassembler and Lifeguard poke-finder ecosystem, cultural impact on cheat codes and snapshots
keyboard.md	Keyboard Reading — software-side companion to `keyboard_matrix.md`. Half-row scan idiom, 40-key scan, ghosting and the QAOP/CS consensus, per-model differences (48K ULA, 128K AY port B, +2A/+3 multi-stage, PS/2 via Next/DivMMC/Harlequin), debounce/auto-repeat/redefine patterns, 10 pitfalls
mouse.md	Mouse Interfaces — Kempston Mouse (8-bit absolute counters at `#FBDF`/`#FFDF`/`#FADF`, quadrature decode in hardware) vs AMX Mouse (1-bit relative polling at `#1F`/`#3F`/`#DF`, conflict with Kempston joystick), Kempston Mouse Turbo PS/2, K-MOUSE Turbo, Next PS/2 mouse, PS/2 protocol primer, 10 pitfalls
joystick.md	Joystick interfaces: Kempston #1F, Sinclair/Interface 2, Cursor/Protek/AGF, Fuller, Timex, clone built-ins, unified multi-standard reader
printers.md	Printers — ZX Printer (1981, spark / electro-erosion, port `#FB` with `A2=0` decode, paper-start latch bit 7, next-pixel latch bit 0, +9V power removed on +2A/+3), Alphacom 32 thermal alternative, Centronics adapters (Kempston/DK'Tronics data `#0F` / status `#1F` / hardware-strobe on write), Soviet SM640 (IEEE 488/IEC 625) and SM646 (Centronics, GOST 19768-74 Cyrillic), Retro-Printer modern emulation, 10 pitfalls
zx_bus.md	ZX Bus — the 56-pin (28+28) expansion edge connector: full pinout, signal groups (address / data / control / interrupts / power), per-model differences (16K/48K vs 128K/+2 vs +2A/+3 — `+9V`/`/ROMCS` removal, `/ROM1OE`+`/ROM2OE` replacement), `/ROMCS` overlay trick, no `/RAMCS`, `M1`-triggered overlays, DMA via `/BUSRQ`/`/BUSACK`, peripheral stacking order, 12 pitfalls
mb02.md	MB-02 / MB-02+ — Czech all-in-one disk/DMA/memory/RTC/IDE expansion (8BC group, ~1996; ~90 units made): WD2797 FDC with HD floppies (1.4-1.8 MB), Z80-DMA (RFT U858D required due to BS-DOS init-order bug), 128K-512K SRAM, RTC-72421, full port map, BS-DOS, Hood's NMI menu, MB03+ Ultimate FPGA successor
video_output.md	Video Output — physical video output stage of every Spectrum model. 48K RF-only path (ULA Y/U/V → LM1889 → RF modulator on UHF ch.35/36) vs 128K/+2 TEA2000-based RGB+composite path vs +2A/+3 Amstrad 40077 gate-array path with RGB only; 8-pin DIN 45326 monitor socket pinouts for all three variants (128K TTL RGB vs +2 configurable via LK1-LK8 jumpers vs +2A/+3 with `+12V` on pins 1/5 and audio on 3); composite video vs composite sync distinction; SCART cable wiring tables (128K needs diode Bright mixing; +2 internal mixing; +2A/+3 requires 330 Ω series R for proper levels); 48K composite mod (LM1889 tap + 2N3904 buffer); S-Video alternative (Redhawk PCB); VGA/HDMI adapters (GBS-8200 with gbscontrol, OSSC, RGB-to-HDMI, ZX-VGA-JOY); Soviet clone composite outputs; 12 pitfalls
z_controller.md	Z-Controller — Russian multi-I/O peripheral designed by Alexey Zhabin (KingOfEvil) in 2007. Combines PS/2 keyboard, PS/2 mouse (Kempston Mouse emulation), Nemo IDE-compatible CompactFlash/hard disk, and SPI-mode SD card on a single ZX Bus board. Two-chip architecture: Altera EPM7128 CPLD (port decode + IDE latch + mouse registers) + KR1878VE1 MCU (PS/2 scan codes). Not bootable from SD; software support is Russian-scene-specific (Wild Disk Copier v1.21+, iS-DOS); functionality carried forward into MB03+ Ultimate FPGA and ZX Spectrum Neo
lightgun.md	Magnum Light Phaser — Amstrad's 1987 light gun, last first-party ZX Spectrum peripheral. Photo-diode + lens + trigger microswitch; CRT raster-beam detection. Three interface variants: +2/+2A/+3 AUX port (8-pin), 48K/128K Toastrack ZX Bus edge connector + MIC socket box, C64 user port + control port (uses VIC-II hardware light-pen input `$D013`/`$D014`). ZX Spectrum ULA has no light-pen register — detection is entirely software-driven (sensor pulse → ULA `/INT` → software T-state count → per-model calibration table for 48K/128K/+2/+2A/+3). ~15 known Spectrum titles (6 bundled, 9 separately-sold); rebranded variants: Trojan Phazer (white), Cheetah Defender, MARPES — all interchangeable; Stack Light Rifle is incompatible (emulates Kempston joystick). CRT-only — does not work on LCD/plasma/OLED; Sinden/GUN4IR are modern IR-LED-bar alternatives. 12 pitfalls

See 03_io/peripherals/README.md for the section index. All 12 peripheral articles complete.

07 — Demoscene ✅ COMPLETE

History & Culture

Article	Description
demoscene_history.md	ZX Spectrum demoscene: Western origins, Soviet explosion, modern revival, cultural impact
soviet_demo_scene.md	Russian/Ukrainian scene: Pentagon-centric development, FidoNet era, notable groups
demoscene_platforms.md	Cross-platform comparison: Spectrum vs C64 vs Amiga vs Atari ST vs MSX vs Amstrad CPC

Techniques

Article	Description
effects_catalog.md	Visual effects catalog: plasma, raycasting, 3D objects, multicolor, zoomers, tunnel effects, copper bars
multicolor_techniques.md	Multicolor / attribute interrupt: 8×1 and 8×2 color resolution, race-the-beam timing, per-model differences
precalc_trigonometry.md	Sine tables, fixed-point math, interpolation, compression of lookup tables
compression_packing.md	25 crunchers across 4 generations: ZX0/ZX1/ZX2/MegaLZ/Pletter/HRUM, depackers, RCS
size_coding.md	256 B / 512 B / 1 K / 4 K / 16 K intro competitions: squeeze, reuse, math tricks, compression, ROM routines
compression_mindset.md	Writing code for the compressor, not the assembler: why verbose/repetitive code can compress smaller than hand-squeezed code, plus forward vs. backward depack budgeting

Frameworks & Notable Works

Article	Description
demo_frameworks.md	Demo frameworks: effect sequencing, music synchronisation, memory layout, ISR architecture, part transitions
notable_demos.md	Analysis of landmark demos across four eras: Crack Intro (1986–89), Western Golden (1990–96), Soviet Peak (1996–2005), Modern Revival (2010–present)
hole17_case_study.md	Case study: "Hole 17 enigma" (RMDA, 256 B) — self-built `CALL`-chain engine, stack-pointer-as-plotter rendering, code-as-AY-data, and why nothing in it has a single fixed role
1bit_music_scene.md	1-bit beeper music scene: hardware, techniques, engine lineage, composers, community

See 07_demoscene/README.md for the section index.

00 — Overview ✅ F14 COMPLETE

Article	Description
history.md	Narrative synthesis of the ZX Spectrum's 40+ year story: five distinct eras (Pre-Spectrum 1972–1981, Sinclair 1982–1986, Amstrad 1986–1992, Post-Soviet clone 1989–2000s, Modern revival 2010s–present), verified dates from canonical Sinclair Wiki source, embedded Mermaid `timeline` diagram 1976–2022, cultural/economic context for each transition, 5 pitfalls
hardware_models.md	Navigational hub for hardware models across three tracks: Original/Soviet Clones/New Gen taxonomy, three per-track model tables (7 Original, 10 Soviet clones, 8 New Gen), three cross-track comparison matrices (frame timing, memory architecture, sound capability), "How to Choose a Model" decision matrix with 8 use cases, every model row links to per-model deep-dive article
glossary.md	Platform-specific terminology reference: 100+ terms organized by category (Hardware, Display, Memory, Storage, Software/System, Cultural/Demoscene, Track-Specific), each entry has 2–4 sentence definition with "See X" cross-reference, abbreviations listed both short form (ULA) and full form (Uncommitted Logic Array), 5 pitfalls

See 00_overview/README.md for the section index. All 3 articles complete (F14 series — 4-article plan consolidated to 3 by merging timeline into history per user approval).

03 — I/O · 08 — RE · 09 — Toolchain · 10 — References · 11 — Emulation

Section 03 — I/O (Snapshots / Storage / Peripherals / Networking)

Snapshots & Replay sub-section: ✅ COMPLETE (4/4). Tape sub-section: ✅ COMPLETE (6/6). Floppy sub-section: ✅ COMPLETE (13/13). Hard Disk / SD sub-section: ✅ COMPLETE (6/6). Peripherals sub-section: ✅ COMPLETE (1/1). Networking sub-section: ✅ COMPLETE (6/6).

Snapshots & Replay — machine-state capture formats (sub-section README)

Article	Description
sna_format.md	.SNA snapshot format — the original 1992 format (JPP emulator), 48K and 128K variants, 27-byte header, PC-on-the-stack trick, limitations
z80_format.md	.Z80 snapshot format — the 1994 "rich" format by Glen Lleston, three versions (v1 48K, v2 128K, v3 clones+AY), hardware IDs, RLE compression
szx_format.md	.SZX snapshot format — the modern ZEsarUX chunk-based (IFF-like) format, standard chunks (Z80R, RAM, AY16, CFGR), extensibility via skip-unknown
rzx_format.md	.RZX replay format — 2001 input-recording format for the RZX Archive, block-based, cryptographic signing, cycle-accurate replay

Storage Media Formats — tape, floppy, HDD, SD (sub-section README)

Article	Description
tape_interface.md	Tape interface hardware — EAR/MIC circuits, ULA, port `#FE` bit layout, ROM routines (SA-BYTES, LD-BYTES), pilot/sync pulses, bit encoding, turbo loaders
tape_format.md	Tape data format — 17-byte header structure, four block types (Program/Array/Code), XOR checksum, multi-block files
tap_format.md	.TAP file format — Thomas Schreiber's 1996 minimal format, just blocks with 2-byte length prefixes
tzx_format.md	.TZX file format — Tomaz Kac's 1996 comprehensive format, 30+ block types, turbo loader support, format of choice for preservation
csw_format.md	.CSW Compressed Square Wave — Simon Owen's 2001 pulse-level preservation format, RLE compression, for analog protections
pzx_format.md	.PZX format — Fredrik Öhrström's 2010 chunk-based pulse format, T-state pulse widths, cycle-exact by design

Floppy Disk — physical layer, hardware interfaces, 4 logical formats, 8 image formats (sub-section README)

Article	Description
mfm_encoding.md	MFM signal layer — IBM 3740 sector format, MFM bit encoding, address/data marks, CRC16, gap structure, 250 kbit/s data rate
fdc_vg93.md	WD1793 / KR1818VG93 FDC chip — 4-register file, Type I/II/III/IV commands, status bits, Soviet clone, turbo mods
beta_disk_interface.md	Beta Disk Interface (Soviet standard) — WD1793, port map, TR-DOS ROM bank switching, cable, variants
plus3_floppy.md	+3 floppy hardware — WD1772-PH, port map, 720 KB geometry, cable pinout, modern replacements
trd_disk_format.md	TR-DOS logical format (Soviet, 800 KB DSDD-10) — 128 entries × 16 bytes, sector allocation, file types
plus3_dos_format.md	+3DOS logical format (CP/M derivative, 720 KB DSDD-9) — 32-byte entries, 1 KB blocks, extents, DPB
cpm_disk_format.md	CP/M 2.2 disk format — BIOS/BDOS/CCP/TPA, FCB, DPB, +3/ATM Turbo/Sprinter variants
opus_discovery_format.md	Opus Discovery / MGT format (UK, 800 KB DSDD-10) — WD1770, 256-byte entries, sector bitmap, linked-list chaining
trd_scl_formats.md	.TRD / .SCL image formats — TR-DOS containers (raw sector dump vs file-level backup)
dsk_fdi_formats.md	.DSK / .EDSK / .FDI image formats — CP/M / +3DOS / Opus containers
udi_format.md	.UDI universal flux-level image — preserves every magnetic transition
scp_format.md	.SCP SuperCard Pro flux-level image — gold-standard preservation format
disk_format_overview.md	Top-level comparison — IBM 3740 physical layer, 4 logical formats, 8 image formats, decision tree

Hard Disk / SD — IDE / SD interfaces, FAT filesystem, image formats (sub-section README)

Article	Description
hdd_overview.md	Top-level overview — three generations (floppy → IDE → SD), why HDD mattered for the Soviet scene, the unifying FAT abstraction
ide_interface.md	IDE / PATA interfaces — 40-pin connector, port maps for DivIDE/SMUC/Nemo/ZC/ATM/KAY, Z80 read loop sketch
divide_divmmc.md	DivIDE / DivMMC hardware — board architecture, NMI boot, conmem/mapram paging, divman/divese TR-DOS image emulation (hardware companion to esxdos.md)
sd_interface.md	SD card interfaces (SD-SPI) — SPI command frames, 5-step init handshake, Z80 bit-bang sketch, port maps for DivMMC/ZXMMC/Next/ZC
hdd_partitioning.md	Partitioning & filesystems — MBR + 4-entry partition table, FAT12/16/32, BPB, directory entries, LFN, cluster allocation, IS-DOS
hdf_mgt_formats.md	Image formats (.HDF / .IMG / .MGT / .VHD) — raw vs headered HDF, four-names-for-same-thing, loopback mounting, sparse/compression
joystick.md	Joystick interfaces: Kempston #1F, Sinclair/Interface 2, Cursor/Protek/AGF, Fuller, Timex, clone built-ins, unified multi-standard reader

Networking — ZX Net, modems, modern WiFi/Ethernet (sub-section README)

Article	Description
zx_net.md	ZX Net (1983) — Sinclair's classroom LAN via Interface 1, 64-station daisy-chain, polling MAC, `NET` / `LOAD name N` ROM API, comparison with Econet
modems.md	Telephone modems — acoustic couplers (V.21), direct-connect (V.23/V.22/V.32/V.34), Interface 1 RS-232, Prism VTX-5000, Prestel/Micronet 800, Russian FidoNet, BBS software
spectranet.md	Spectranet (2007+) — Andrew Owen's Ethernet + TCP/IP interface, ENC28J60 SPI, BSD-style socket API via `RST #08`, software ecosystem (telnet/FTP/HTTP/IRC)
zifi.md	ZiFi (2014) — ESP8266 WiFi module + Hayes AT command set over UART, 3.3V/5V level shifting, ESP-01/ESP-12 modules, comparison with Spectranet
esp_wifi.md	ESP8266/ESP32 family — broader WiFi solution landscape, boot modes, topologies (serial/SPI/parallel), firmware choices (AT/ESP-NOW/custom), cross-platform companion projects (WiC64, WiFi232)
zx_next_wifi.md	ZX Spectrum Next WiFi — built-in ESP-12 on SPI (not UART), custom Next-team firmware, LwIP TCP/IP stack, NextBASIC `*WIFI` commands, up to 8 TCP/UDP connections with SSL/TLS

08 — Reverse Engineering ✅ COMPLETE (7 articles)

Section 08 — Reverse Engineering — RE methodology, protection cracking, game reversing, code compression analysis, snapshot repair (section README)

Article	Description
methodology.md	RE methodology hub: starting points (tape/disk/snapshot formats), snapshot-driven analysis, standard workflow, heuristics, patching, tools, pitfalls, ethics
protection_techniques.md	Protection catalog: tape loaders (Speedlock, Alkatraz), disk schemes (weak bits, non-standard sectors), NMI/snapshot defenses, memory integrity, code obfuscation, bypass techniques
analysis_techniques.md	Static/dynamic analysis: SkoolKit disassembly workflow, code/data separation, ROM call labeling, ZEsarUX/DeZog debugging, trace logging, reverse debugging, memory diffing
protection_cracking.md	Protection cracking: Speedlock/Alkatraz decryption analysis, timing check bypass, disk protection defeat, NMI countermeasure defeat, clean snapshot technique
game_reversing.md	Game reversing: engine identification (Ultimate, Ocean, Graftgold, Hewson), sprite/map/music ripping, cheat code creation, save game analysis, Z80-to-C reconstruction
code_crunching.md	Code compression RE: packer survey (MegaLZ, HRUM, Hrust, ZX0), format identification, LZSS fundamentals, generic depacker template, overlap depacking
snapshot_repair.md	Snapshot repair: fixing corrupted .SNA/.Z80, header validation, PC/SP repair, decompression error handling, format conversion, fixing mid-load crashes

11 — Emulation ✅ COMPLETE (20 articles)

Section 11 — Emulation — software emulators, FPGA cores, MCU-based chip replacements

Software Emulators — host-side Spectrum emulation (sub-section README)

Article	Description
fuse.md	Fuse — Free Unix Spectrum Emulator, the canonical cross-platform accurate emulator, GTK/Qt/SDL frontends, debuggers
zesarux.md	ZEsarUX — Second-cycle-exact emulator with TS-Conf, ZXEvolution, Pentagon support, comprehensive debugger, retro rendering options
cspect.md	CSpect — Windows-based accurate emulator with NextReg/layer-2/sprite support, popular for ZX Spectrum Next development
emulator_comparison.md	Emulator comparison — Fuse vs ZEsarUX vs CSpect vs UnrealSpeccy vs Spectaculator, accuracy, debugging, features matrix
cycle_exact_accuracy.md	Cycle-exact accuracy — frame timing divergence, CRT vs LCD, host sync strategies, AY audio clocks, judder mitigation, worst-case Pentagon@60Hz conclusion
test_suites.md	Test suites — ZEXALL, FUSE test suite, Sensible Software tests, Yamagraph, application-specific test ROMs

FPGA Cores — synthesized hardware re-implementations (sub-section README)

Article	Description
fpga_implementation.md	FPGA Spectrum implementations — why FPGA differs from software emulation, gate-level reconstruction, vendor families, development workflow
fpga_timing_accuracy.md	Timing accuracy in FPGA cores — sub-ns cycle-true reconstruction, ULA contention replication, video timing, audio clock matching
harlequin_sizif.md	Harlequin & SIZIF — Maxim Sichkov's gate-level ULA replacements for original Spectrum motherboards, repair-and-upgrade boards
zxevo.md	ZX Evolution — TS-Conf/Baseconf, ATM Turbo spiritual successor, Pentagon-compatible, configurable video modes, IDE/SD
zx_uno_core.md	ZX-Uno — compact FPGA board, all-Spectrum-on-one-board, multi-core (Pentagon/Scorpion/48K/128K), WiFi and SD built-in
mist_mister_core.md	MiST & MiSTer cores — Spectrum core on the MiSTer FPGA platform, alongside dozens of other retro computers, accurate and extensible

MCU Chip Replacement — replacing vintage silicon with microcontrollers (sub-section README)

Article	Description
mcu_z80.md	Z80 on MCU — bit-banged and PIO-driven cycle-true Z80 emulation in firmware, libz80/z80ex cycle engines, drop-in chip replacement
mcu_ula.md	ULA on MCU — RP2040 PIO reconstruction of the Ferranti ULA, contention timing, video pipeline, floating bus behavior
mcu_fdc_vg93.md	WD1793/VG93 on MCU — bit-banged floppy controller replacement, MFM decoding in firmware, SD-card image backing
mcu_psg_ay.md	AY-3-8910/YM2149 on MCU — software PSG synthesis, RP2040 PWM/DMA audio, drop-in pin-compatible replacements
mcu_keyboard.md	Keyboard on MCU — PS/2 keyboard matrix scanning, scan-code translation, 8×5 Spectrum matrix emulation, debounce
mcu_video_adapter.md	Video adapter on MCU — RGB/HDMI output from RP2040 PIO, scanline generation, multicolor effects, layer-2 style overlays
mcu_sd_interface.md	SD card interface on MCU — SPI/SDIO from MCU, file-backed disk images, DivMMC/DivIDE emulation on a single MCU
n_go.md	N-Go — complete Spectrum on MCU — synthesis article, RP2040 multicore architecture (Z80 core + ULA + PSG + SD), firmware structure
mcu_design_patterns.md	MCU design patterns — bus interfacing (memory-mapped/port/IO/DMA), 74HCT vs 74HC level shifting, RP2040 PIO timing-critical I/O, GPIO drive, ring buffers, lock-free SPSC queues, common pitfalls

10 — References ✅ COMPLETE (10 articles)

Section 10 — References — lookup tables and pin/byte/timing references (section README)

Article	Description
z80_opcode_table.md	One-page Z80 opcode lookup: every documented instruction by group with byte count, T-states, and flag effects
io_port_map.md	Complete I/O port reference: every port across all models, Black_Cat table with annotations, decoding bitmasks, per-model differences
zx_ports_full_table.md	Complete English translation of Black_Cat's ZX Ports Full Table (BC Info Guide #4, 2008) — all 32 sections verbatim with the original's model-code and function-code legends
character_set.md	ZX Spectrum character set: code ranges, ROM font layout, UDG system, CHARS redirection
color_palette.md	Standard 15-color palette (FUSE/Skoolkid/ZEsarUX variants), ULAplus 64-color, ZX Spectrum Next 256-color
memory_maps.md	Consolidated memory maps for every model (16K/48K, 128K/+2, +2A/+3, Pentagon, Scorpion, ATM Turbo, Next) — contended regions, banking registers, RAMTOP defaults, compatibility cheat sheet
basic_token_table.md	Sinclair BASIC token table: byte values and tokenisation rules for 48K/128K/+2/+2A/+3 ROMs — control codes, function tokens, UDGs, block graphics
error_codes.md	All BASIC/DOS error codes — 10 Sinclair BASIC, +3 DOS (12), TR-DOS (Russian), ESXDOS (POSIX-style), IS-DOS, NextZXOS — recovery patterns
timing_reference.md	Cycle-exact timing tables — CPU clocks per model, video frame timings (48K/128K/Pentagon), contention delay tables, INT/NMI timing, common instruction T-state counts
pinouts.md	Pin-by-pin reference — 48K/128K/+2 expansion edge connector (A and B side), Z80 40-pin DIP, AY-3-8912 28-pin DIP, joystick ports, Kempston mouse, EAR/MIC jacks, power connectors
rom_routines.md	ROM entry points — restart vectors, character output, keyboard, tape, math/calculator, 128K-specific routines, calling conventions with examples

Reading Order

New to Z80 assembly:

Emulator authors and demoscene programmers:

Spectrum assembly programmers (memory, I/O, display):

Sound and music programmers:

Sound Hardware Ecosystem Overview — the decision guide; read this first to know which hardware to target
AY-3-8912 / YM2149F PSG Silicon — the foundation chip on every 128K and clone
Stereo Audio Modifications — ABC/ACB/BytesDelight wiring
1-Bit Beeper Synthesis — PWM fundamentals, emulation physics, multi-channel tracking
Ear Shaver Case Study — Extreme 1-bit engine reverse engineering
AY/YM Sound Generation — internal counter model, phase reset, sync-square, envelope exploitation
TurboSound — dual/triple AY bank-switching
TurboSound FM — YM2203 OPN FM expansion
Covox & SounDrive PCM Playback — resistor ladders, TLC7226CN quad DAC, hardware mixing
General Sound — dedicated Z80 coprocessor sound card
MoonSound (OPL4) — wavetable + FM synthesis
SAA1099 Philips PSG — 6-channel stereo alternative
ZX Spectrum Next Audio — 3× FPGA AY + DMA + beeper
Multi-Track and Multi-Chip Synthesis — TurboSound, cross-chip effects
Tracker History — 30 years of ZX music editors: from Sound Tracker (1990) to Arkos Tracker 3
AY Music Formats — master catalog: .PT3, .PSG, .YM, .AY, .AKG, all module/dump/container formats
Sound Tracker 1.1 — Bzyk's 1990 first AY grid editor; established the pattern/sample/ornament paradigm
Asc Sound Master — Sendetskiy's 1992 Soviet alternative with envelope-mode-per-tick instruments
Pro Tracker 1/2/3 — Golden Disk Corp.'s 1995–1997 format-defining lineage that produced .PT3
Vortex Tracker II — the de facto PC-based PT3 editor
Arkos Tracker 2/3 — modern cross-platform alternative for new composers in 2025
PT3 Module Format — byte-level binary specification of the de facto interchange format
PSG Register Dump Format — the universal pre-rendered AY dump format

Toolchain and development environment:

Native Toolchain — assemblers and monitors that ran on the Spectrum (1982–2000s): Zeus, DevPac, ALASM, XAS
Cross-Platform Toolchain — modern development on PC/Mac/Linux: SjASMPlus, z88dk, VS Code, emulators, CI/CD
SjASMPlus — the de facto standard Z80 cross-assembler: three-pass assembly, virtual device mode, Lua scripting, Z80N, SLD debugging, every output format
z88dk — the complete C development kit: two compilers (sccz80 + SDCC), classic + newlib, +target system, full ZX Spectrum library API, mixing C with assembly
SDCC — Small Device C Compiler standalone: stack-based ABI, custom CRT0, .cdb debug format, integration with SjASMPlus, when to choose over z88dk
Asset Tools — the asset pipeline: screen graphics, software/hardware sprites, fonts (8×8 + FZX), AY/beeper music, ZX0/ZX1/ZX7/MegaLZ compression, tile maps
Debugging — three-layer model (native / emulator / source-level), every major debugger, debug-metadata formats, comparison matrix, recommended workflows
Disassemblers — linear / smart static / trace-driven approaches, z80dasm, z88dk-dis, SkoolKit, IDA Pro, Ghidra, decision tree
Software Protection Techniques — tape loaders (Speedlock, Alkatraz), disk schemes, NMI/snapshot defenses (anti-debugging countermeasures table, hardware vs software debugger comparison), snapshot devices (Multiface, MAGIC button, Shadow Monitor), memory integrity, code obfuscation, bypass techniques

Bridge to advanced optimization:

Z80 Coding Practices

Coming from modern platforms:

Z80 vs Modern

See PLAN.md for the full knowledge base catalog and writing priorities.

Name		Name	Last commit message	Last commit date
00_overview		00_overview
01_cpu		01_cpu
02_hardware		02_hardware
03_io		03_io
04_operating_systems		04_operating_systems
05_development		05_development
06_sound		06_sound
07_demoscene		07_demoscene
08_reverse_engineering		08_reverse_engineering
09_toolchain		09_toolchain
10_references		10_references
11_emulation		11_emulation
tools		tools
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
PLAN.md		PLAN.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation