Debug80 IDE for Z80 Development

Source-level Z80 debugging and machine emulation for VS Code.

Debug80 turns VS Code into a practical development environment for Z80 assembly programs. It assembles your project, runs it inside an integrated Z80 runtime, maps machine addresses back to source with native D8 debug maps, and exposes the state you need while debugging: breakpoints, stepping, registers, flags, memory, terminal I/O, and hardware-specific panels.

The extension is designed for real single-board computer workflows, especially the classic TEC-1 and the TEC-1G MON-3 environment. Those profiles include bundled ROM assets and emulator panels for the front-panel hardware users actually interact with.

Full user guides, AZM course material, and engineering reference documentation are available at debug80.com.

Features

• Source-level Z80 debugging: set breakpoints in .asm and .z80 files, then continue, pause, restart, step into, step over, and step out using the normal VS Code debug controls.
• Native D8 debug maps: Debug80 uses D8 mapping data generated by the assembler to resolve addresses, included source files, symbols, and source locations directly from the build.
• Source-map-backed editor help: press F12 / Go to Definition on symbols, search active-target symbols through VS Code's workspace symbol picker, and hover over symbols for compact address/value/source details from the last successful build. The Project panel reports whether the active source map is current, missing, or stale; if no source map exists yet, build the target first.
• Run to Cursor: use VS Code's normal Run to Cursor action while debugging Z80 source; Debug80 resolves the current source line through the active source map and runs to the matching address.
• Z80-focused Watch expressions: add registers, flags, symbols, and byte memory reads to VS Code's Watch panel with expressions such as A, HL, zero, [PACMO_LIVES], [HL], or [IX + 4] eq 0.
• Conditional breakpoints: use the same Watch expression language in VS Code breakpoint conditions, for example [PACMO_LIVES] eq 0 or zero and A eq $20.
• Integrated assembler workflow: a Z80 assembler is packaged with the extension and linked directly, so users do not need a global assembler install or a separate command-line toolchain just to start debugging.
• Register, symbol, stack, and memory visibility: inspect CPU registers, source-map symbols and constants, best-effort symbolic stack entries, flags, program counter state, memory regions, RAM contents, ROM-protected ranges, and platform-specific memory behaviour while a session is paused. Mapped stack entries can be used as safe temporary run targets without directly rewriting SP or PC.
• TEC-1 and TEC-1G emulation: run programs against machine profiles that model memory layout, reset behaviour, keypad input, seven-segment display, speaker output, bit-banged serial, monitor ROM workflows, and platform-specific memory behaviour. The TEC-1G profile also models MON-3-oriented devices such as LCD/GLCD output, RGB matrix output, RTC and SD SPI hooks when enabled.
• Debug80 panel inside VS Code: the extension contributes a dedicated view in the Run and Debug sidebar for project selection, target selection, platform controls, display panels, serial/terminal output, memory tools, and quick access to the current debug session.
• Project setup from VS Code: open a folder, let Debug80 create the project setup, and choose from discovered runnable targets.
• Z80 assembly language support: file associations and syntax highlighting for .asm, .z80, and .asmi files, including layout types, enums, contracts, and interface files.

Quick Start

1. Open a Z80 project folder in VS Code.
2. Run Debug80: Create Project from the Command Palette.
3. Choose the TEC-1 or TEC-1G profile that matches your board.
4. Debug80 creates the project setup and looks for runnable targets in the folder.
5. Press F5 or run Debug80: Start Debugging.
6. Use breakpoints in your source files, the standard VS Code debug controls, and the Debug80 panel to inspect CPU and platform state.

Platform-focused starter workspaces are available separately:

• debug80-tec1 for classic TEC-1 monitor workflows.
• debug80-tec1g for TEC-1G and MON-3-oriented workflows.

Targets

Debug80 keeps its workspace setup in debug80.json, but you normally do not need to write that file by hand. The Create Project command generates the setup for the current folder, and Debug80 then looks for program entry points it can run.

For now, target discovery focuses on clear Z80 entry-point conventions:

• files ending in .main.asm
• files named main.asm

Files with .z80 are still supported as Z80/AZM source files, but they are no longer auto-discovered as runnable targets. Add them explicitly to debug80.json if a project still needs one as its entry file.

When more than one target is available, select the active target from the Debug80 panel or the Debug80: Select Active Target command.

Platforms

Debug80 currently promotes two hardware-focused profiles:

• TEC-1: classic monitor workflow with keypad, six-digit seven-segment display, speaker, bit-banged serial, and the expected ROM/RAM map.
• TEC-1G: MON-3 workflow with keypad, seven-segment display, speaker, serial, LCD/GLCD, RGB matrix output, memory protection/expansion behaviour, and optional RTC/SD hooks.

Scaffolded TEC-1 and TEC-1G projects use monitor ROM assets supplied by the extension. Copy the monitor ROM into your project only when you want to inspect, modify, replace, or debug the monitor source itself. Debug80 recognizes local monitor ROM entry points by convention (*.rom.asm) and uses the local ROM build instead of the bundled ROM when that entry point exists.

Useful Commands

Debug80 contributes commands for the normal project workflow:

• Debug80: Create Project: scaffold a project configuration and launch setup.
• Debug80: Start Debugging: launch the selected project and target.
• Debug80: Build Current Target: rebuild the active target and update the current debug session.
• Debug80: Select Workspace Folder and Debug80: Select Active Target: switch the active project context.
• Debug80: Set Program File: choose the source entry point from an editor or Explorer context menu.
• Debug80: Open Project Configuration Panel: open the active project config.
• Debug80: Open Auxiliary Source: open bundled or project-provided platform source material for the active platform profile.
• Debug80: Copy Monitor ROM into Project: copy the bundled monitor source into the project roms/ folder and create the local *.rom.asm ROM entry point used for monitor development.

Local VSIX Builds

For local testing as a packaged extension:

npm ci
npm run preflight
code --install-extension debug80-0.0.1.vsix --force

preflight runs lint, type checks, tests, packaging, and VSIX content verification. The full release checklist is in docs/release-process.md.

Development

npm install
npm run build
npm test

Debug80 packages its assembler dependency inside the VSIX. Published users should not need npm link, sibling checkouts, or globally installed assembler binaries.

Documentation

• debug80.com: published user guides and AZM books/manual.
• Using Debug80 in VS Code: project setup, debugging workflow, panels, ROMs, serial, source mapping, and troubleshooting.
• Debug80 Engineering Manual: extension architecture, launch pipeline, platform runtimes, webview panels, source mapping, extension points, release testing, and regression gates.
• D8 Debug Map Format: native source mapping format consumed by Debug80.
• AZM Books and Manual: Z80 learning material and AZM assembler reference.
• Release process: local checkout checklist for VSIX preparation and publishing.