Debug80 Engineering Manual

A technical reference for engineers working with the Debug80 codebase.

The chapters begin with the repository shape and project model, then follow the runtime path from launch configuration through the debug adapter, emulator, platform runtimes, extension UI, source mapping and extension points.

Part I — Orientation

Part II — The Debug Adapter

Part III — The Z80 Emulator

Part IV — Platform Runtimes

Part V — The Extension UI

Part VI — Source Mapping

Part VII — Extending the Codebase

Appendices

Current Codebase Notes

This manual is updated against the codebase state through 2026-05-10. These notes give maintainers a quick view of changes that affect several chapters:

  • Editor grammar: Debug80 owns TextMate syntax highlighting for Z80 assembly sources. package.json contributes z80-asm and z80-lst grammars, default file associations for .asm, .z80, .a80 and .s, and token colour customisations for comments, labels, directives, instructions, registers, conditions, strings, symbols, numbers and routine-comment annotations.
  • Assembler integration: asm80 is linked directly into the extension host. The launch pipeline writes the normal .hex, .lst and .bin artifacts; backend invocation now uses JavaScript APIs where available.
  • Runtime performance: createZ80Runtime() keeps stable decoder callbacks whose implementations read the current hardware hooks dynamically. This preserves decoder-cache reuse when a platform finalizes memRead or memWrite after runtime creation. Runtime-control also records starvation data so long chunks and yield delays can be observed during extension-host debugging.
  • Webview audio: speaker mute state is session-local. New webviews start muted because browsers and VS Code webviews require a user gesture before reliable audio playback.
  • Scaffold: new projects can merge a standard Debug80 .gitignore block via ensureDebug80Gitignore() in src/extension/project-gitignore.ts, invoked from scaffoldProject().
  • TEC-1G panel UI: section checkboxes persist. Merge order is built-in defaults, debug80.json tec1g.uiVisibility from the active launch, then workspace Memento keyed by debug target (debug80.tec1g.uiVisibilityByTarget).
  • Mapping and MON-style includes: Layer 2 include-anchor remapping and propagation of mis-attributed include segments improve stepping and stack frames when asm80 attributes bytes to the parent file while the real code lives in a sibling include such as glcd_library.z80. The same remap runs on native .d8.json maps.
  • Z80 debugger stepping: a single Step over the ED block-repeat instructions (LDIR, LDDR, CPIR, CPDR, INIR, INDR, OTIR, OTDR) runs the instruction to completion in one user-visible step.
  • ST7920 GLCD and matrix display: the emulator keeps a full 4-bit GLCD column counter and derives the upper/lower 64x64 chip bank from it. The TEC-1G 8x8 RGB matrix mirrors hardware column bits into left-to-right visible columns.
  • Webview modules: shared common/ modules cover serial UI, Web Audio, matrix rendering, seven-segment display, keypad handling, TEC keycap layout and styles. The TEC-1 and TEC-1G panels share more code and present consistent keyboard behaviour.
  • Extension file handling: .z80, .a80 and .s files are assigned the z80-asm language id on open so decorations and breakpoints align with files.associations in package.json.

Longer-standing architecture facts:

  • The project manifest uses the version 2 model: projectVersion, projectPlatform, profiles, defaultProfile and bundledAssets.
  • Project creation records bundled ROM asset references, and launch resolves missing workspace files from the extension bundle automatically.
  • The panel lifecycle has three states: noWorkspace, uninitialized and initialized.
  • The project header owns project selection, target selection, stop-on-entry, restart and workspace-folder addition.
  • Memory snapshot handling and mapping-cache decisions are split across debug and extension modules.

Table of contents