Support

If you like DeZog please consider supporting it.

DeZog - The Z80 Debugger

The objective of this project is to provide a development environment for Z80 assembler programs that offers similar features to those found in high-level programming languages, such as Eclipse, Visual Studio, or XCode.

This includes functionalities like

• easy stepping/navigation through source files with step-over, step-into and step-out capabilities
• data representation through memory views and data watches
• easy data access through hover-over information
• data display in structures
• a unit test framework

Additionally it offers some ZX Next specific capabilities like displaying sprites.

DeZog facilitates the debugging of Z80 assembler programs using Visual Studio Code (vscode) as the development environment. This tool can be used to build programs, step through sources, use labels, watches, memory views, and other useful features. Additionally, it can be used to reverse engineer old Z80 programs, such as ZX Spectrum, ZX81 or MAME arcade games, by debugging and creating commented list files of the program.

DeZog needs a "Remote" to execute the Z80 binaries. You can either use the built-in Z80/ZX simulator or connect to ZEsarUX, CSpect or MAME via a socket connection for more advanced projects.

Note: DeZog itself does not include any support for building from assembler sources. For this you need a build task and an assembler. For an example look into one of the 2 example projects:

• z80-sample-program (ZXSpectrum)
• zx81-sample-program

Gallery

Sprites

• Display of sprites with register indices and position
• Display of all patterns with indices

Execution time

Unit tests

Features

• supports the ZEsarUX emulator
• supports the CSpect emulator
• supports MAME
• can be used with the internal simulator (does not require ZEsarUX, CSpect, ...)
• reads .list and .sld files
  • supports stepping through source code
  • either in .list file or in .asm files
• step-over, step-in, step-out, continue, pause
• reverse debugging via step back and reverse continue
• code coverage visualization
• state save/restore
• breakpoints (and breakpoints with conditions)
• display of
  • disassembly
  • Z80 registers
  • stack
  • callstack
  • data
  • tbblue sprites and patterns
• changing of Z80 registers from vscode
• labels
  • number-label resolution, i.e. along with numbers also the corresponding label is displayed
• hovering
  • registers: reveals its contents and associated label
  • labels: reveals their value
• watches of labels
• formatting registers
  • customizable formatting for registers, e.g. format as hex and/or decimal and/or label etc.
  • different formatting for registers while hovering
• memory viewer / editor
• automatic display of memory that is pointed to by HL, DE, etc.
• change of program counter through menu
• display of ZXNext sprites and sprite patterns
• supports banking ('long addresses')
• support for Z80 unit tests
• custom extensions to the internal simulator to simulate peripherals.
• custom memory models

Installation

Prerequisites

In order to use DeZog you need at least vscode (Linux, macOS or Windows).

If you are writing pure Z80 programs, simple ZX Spectrum or ZX81 programs this might already be sufficient as you can use the internal Z80 Simulator.

For more demanding projects you have the choice to install a real emulator.

These are the options:

• the CSpect emulator (known to be interoperable is version 3.0.1.0)
• the ZEsarUX emulator (known to be interoperable is version 11.1. Versions older than 10.3 are not compatible.)
• MAME (known to be interoperable is version 0.242)

Note: The version numbers given here are versions that I have used myself. Newer versions probably also work.

The different DeZog/emulator configurations have different advantages. But which one you choose mainly depends on your personal preference. The table here shows a comparison of the features.

If you own a ZX Next you also have the option to debug your SW directly on the Next.

DeZog

To use DeZog in Visual Studio Code, simply install the "DeZog" extension (maziac.dezog) from the Visual Studio Code Marketplace. Although not required, there are several other helpful extensions available, including:

• ASM Code Lens, which provides syntax highlighting for Z80 assembler, as well as completions, references, jump to label, and renaming functionality.
• Z80 Instruction Set, which displays opcode, affected flags, and a description when hovering over a Z80 instruction.
• Hex Hover Converter, which converts numbers to decimal, hexadecimal, and binary formats when hovering over them.
• ZX SNA File Viewer/ZX NEX File Viewer, which allow viewing of ZX Spectrum snapshot (.sna) and ZX Spectrum Next (.nex) files (search for "snafile" and "nexfile" in the Marketplace).
• ZX81 BASIC to P-File Converter and P-File Viewer, which converts ZX81 P-Files (.p) to ZX81 BASIC (.bas) and vice versa.

All of these extensions can be easily installed directly from the marketplace.

Usage

Please refer to the 'Usage of DeZog' documentation.

You can also access the documentation from within vscode/DeZog. Enter "dezog: Show the DeZog Help page" in the command palette (F1 key) or reveal the "DeZog Help" from the debugging sidebar.

Contribution

If you would like to help extending the DeZog functionality in one of the following areas you are very welcome:

• Add new assembler parsers: The process of writing a parser is described in detail here: AddingNewAssemblers.md Shouldn't be to hard.
• Adding other Remotes (emulators): See AddingNewRemotes.md. S0urceror has done so for OpenMSX, so it is doable.

You can create a pull request so I can add your sources to the official release. Most probably I will first move them to a new feature branch for testing. Please note that all your contributions/sources should be under MIT license.

If you would like to contact me beforehand you can create a new issue in github and we can discuss.

Licenses

• DeZog, MIT license
• ZX81 ROM Copyright © 1981 Nine Tiles - Included with the permission of Nine Tiles
• ZX Spectrum ROM, "Amstrad have kindly given their permission for the redistribution of their copyrighted material but retain that copyright". See Amstrad ROM permissions.
• Z80.js (Z80 CPU simulator), Molly Howell, MIT license.
• vscode-whats-new, Alessandro Fragnani aka alefragni, MIT license.
• For the other included SW see the 'dependencies' section in package.json

Acknowledgements

I would like to express my gratitude to the following individuals for their invaluable support:

• Cesar Hernandez Bano for developing the great ZEsarUX emulator which very early offered the possibility to remotely connect to it. And for being patient with all my request for the ZRCP protocol. Without ZEsarUX I wouldn't have started DeZog at all. So, if you like DeZog thank Cesar.
• Mike Dailly for the wonderful CSpect emulator, for opening the debug interface to plugins and for giving support to use it properly.
• Molly Howell/DrGoldfire for the Z80 CPU simulation code.
• Kris Borowinski for his tireless efforts testing DeZog.
• Peter Ped Helcmanovsky for his support to get the display of the relative-sprites correct and for the changes he implemented for DeZog in sjasmplus in the SLD format.
• Cesar Wagener Moriana, Dean Belfield, Daren May, Patricia Curtis and A MAN IN HIS TECHNO SHED for writing tutorials.
• Luciano Martorella for his contribution of the custom memory model.
• Sebastien Andrivet for help with the ZX81 simulator and the ZX81 and ZX Spectrum keyboard svg files. Great work. Both are included under the CC BY-SA 4.0 license.
• Paul Farrow for the help on the ZX81 graphics modes.
• Víctor Morilla for the z88dk addition to label parsing, enabling setting of breakpoints and stepping through C source code.

Tutorials

Please note that the tutorials listed here are normally not updated when a new DeZog version arrives. Especially for changes in the 'launch.json' it might happen that some properties (names) have changed/removed/added.

If you are writing a tutorial please let me know, I'm happy to list it here. Any contributions are very welcome.

The tutorials that I'm aware of are listed here by date.

A Man in his Techno Shed

Date: Apr-2022, DeZog 2.7, ZX Next

The most recent and only tutorialtutorial for DeZog 2.x, by A MAN IN HIS TECHNO SHED. It shows debugging with a ZX Next and DeZog.

Patricia Curtis

Date: Sep-2020, DeZog 1.4, CSpect

A great tutorial by Patricia Curtis describing the setup with sjasmplus, CSpect and DeZog.

Retro Coder TV

Date: Sep-2020, DeZog 1.4, Internal Z80 Simulator, ZEsarUX, CSpect

A quite lengthy tutorial. But as a YouTube video it shows a 'live' DeZog setup. By Retro Coder TV.

L BREAK into program, 0:1

Date: Aug-2020, DeZog 1.4 (with a few updates for 2.0), ZEsarUX

And here is another shorter tutorial by Dean Belfield (L BREAK into program, 0:1).

Daren May

Date: May-2020, DeZog v1.2, CSpect

An excellent tutorial by Daren May which shows how to setup DeZog with CSpect on Windows. Although it was made for Windows you can easily apply it to macOS or Linux.

Please note: Daren creates an SD card image that is loaded when CSpect is started. For many projects this is not necessary as you can transfer .nex and .sna files directly from DeZog to CSpect.

Cesar Wagener Moriana

Date: Dec-2019, DeZog 0.9 (Z80 Debug), ZEsarUX

Here is an older (but still great) tutorial from Cesar Wagener Moriana. He documented how he put all things together. It describes how to setup an integrated development environment for ZEsarUX with DeZog. It deals with setting up

• sjasmplus
• ZEsarUX and the
• DeZog

and is available in English, Spain and German here.

Please note: The tutorial is a bit outdated, it uses 'z80-debug'. This was the former name of the project. It has been renamed to 'dezog'. This means especially that in the launch.json files you need to change 'z80-debug' to 'dezog'.

Nevertheless Cesar (W. M.) also shows how to setup the system under Windows and explains a few features of z80-debug/DeZog so that it is a great advice to get you started.

Fork

The ZX81 Debugger by Sebastien Andrivet is a specialized version of DeZog for the ZX81. Since v3.5 DeZog is capable to support ZX81 development in the internal simulator as well. However, Sebastien's DeZog fork in general is easier to setup as it contains the complete development environment for the ZX81 (assembler, syntax highlighting, sample code).

What else

DeZog also allows to start ZX Spectrum (.sna) and ZX81 (.p) binaries directly. In vscode's file explorer use a right click and select "Run with DeZog". This will start the ZX Spectrum / ZX81 simulator right away. But please note: this only runs the binary, all debugging features like breakpoints and stepping are disabled in this mode.

The feature can be used by other extensions. For example the ZX81 BASIC to P-File Converter and P-File Viewer starts a ZX81 BASIC program inside DeZog's simulator.