Debug80 as a System
The Debug80 architecture functions as a small and tightly integrated system. It combines a JavaScript-based Z80 assembler with a software execution model. The standard VS Code debugging interface sits on top to provide user control. Each component plays a specific functional role, and the ultimate value of the system depends on the precise alignment of these responsibilities. The development of Debug80 concentrates on integration rather than the invention of new core technologies. Because the underlying pieces already exist and remain well understood in the industry, the primary challenge involves connecting them in a way that respects the realities of Z80 programming. This integration ensures that execution remains observable and meaningful within a modern development environment.
VS Code as the execution host
VS Code provides a mature debugging framework that defines how the environment launches programs and how the user controls execution. The framework already exposes the essential operations needed for stepping through code and inspecting state. Debug80 adapts this framework directly to a Z80 execution context.
When a debug session starts, VS Code drives execution through its standard mechanisms while the actual processor and memory run inside the internal software model. From the user’s perspective, Z80 machine code participates naturally in the same debugging workflow used for contemporary high-level languages. This approach allows the project to concentrate on machine behaviour and hardware state rather than building a custom debugger interface from scratch.
asm80 and the role of listings
The system utilizes asm80, a Z80 assembler implemented in JavaScript for Node. This tool produces machine code alongside listing files. These listing files record exactly how source lines correspond to assembled addresses and bytes. They form the central input for Debug80 because they capture the assembler’s decisions directly without any reinterpretation. Debug80 uses these listings to establish a precise relationship between source text and generated machine code. This mirrors the traditional workflow of Z80 development, where the listing represents the bridge between the programmer's intention and the machine's reality. By treating the listing as a primary source of truth, the system ensures that the debugger always accurately reflects the assembled output.
Mapping source to execution
While the VS Code debugger operates in terms of source locations, the Z80 processor operates entirely in terms of memory addresses. Debug80 connects these two disparate views by generating explicit mappings from the assembler listings. These mappings relate source files and line numbers to assembled addresses. They also relate them to runtime instruction execution.
Breakpoints and stepping pass through this critical mapping layer. State inspection depends on it as well. When execution stops, the system shows exactly where the processor resides and how that location corresponds to both the original source and the assembled binary output. Mapping remains a structural foundation of the system rather than a secondary convenience, and much of the debugger's core behaviour depends on its accuracy.
Initialisation and workflow
The design of Debug80 prioritises minimal friction during setup and daily use. Since the core pieces all use JavaScript, the project simplifies distribution. This architecture runs across the major desktop platforms. The extension coordinates the build step and the launch step into a single workflow.
This integration means that editing source code and observing execution happen within one environment using familiar controls. While the underlying complexity of the machine remains visible to the developer, the system organises the information into a coherent structure. By consolidating these disparate tools, Debug80 allows the programmer to focus on the logic of their program rather than the mechanics of the toolchain.
Execution under debugger control
During a debug session, the Z80 processor and all attached devices execute within the software model. Machine execution advances under the direct control of the VS Code interface. The interface routes execution control through the same mechanisms on every platform, so the user sees a consistent machine state.
The debugger actively drives the execution process rather than simply observing it from the outside. At every step it exposes the registers and memory for examination. The I/O state stays visible as well. This deep integration ensures that the tool behaves like a first-class debugger for an 8-bit architecture, providing the same level of control one expects from modern software development tools.
System coherence
Taken together, Debug80 forms a coherent environment rather than a loose collection of disparate tools. The assembler establishes the ground truth of the machine code while the platform model defines the hardware behaviour. The debugger interface supplies the control and visibility. Every component reinforces the others to maintain a consistent user experience. The emphasis throughout the project remains on architectural alignment and keeping the number of moving components small. This strategy allows low-level programming to remain approachable for a wider audience. By providing a clear window into the machine's internal state, Debug80 recovers the clarity of early computing within a modern context.