EX DE, HL system emulating z80 debugger

Description

exdehl is a system emulating Z80 debugger. It’s purpose is to run and debug bare metal Z80 code that can be tested on a variety of systems.

The systems can be composed of loadable modules, which provide the devices around the cpu. The focus of these devices is not clock-perfect emulation, but rather a good-enough emulation of the observable behaviour of those devices, from the point of view of the cpu. This is not an emulator, but a debugger.

All configuration of exdehl is done through configuration files. The standard configuration file is named exdehl.conf and is looked for in the directory that exdehl is launched in. The composition of the system and general settings are configured in these files. There is a global configuration, that sets the base values for all available configuration options, and a project local configuration, where you can compose your system and set additional parameters. See the exdehl.conf(5) man page for details.

Without a local configuration file, exdehl will not start. You can get started by using the -S command line switch to generate a sample configuration file in the current directory, and modify that to suit your needs.

Building

exdehl is developed on linux, and builds there without much hassle. Other unixen may also work, I have not tested this. Windows will definitely require some work.

Just clone the repository, enter the exdehl directory and run

make

Afterwards you can install it to /usr/local with

sudo make install

Getting started

Create a directory for your project. There, you create a file exdehl.conf. You can create a basic one using exdehl -S. Select the modules you want. For starting, the builtin_mem and builtin_con modules will do, these are enabled in the generated config file. As configured in the sample config file, the console will be at io address 0x21.

create a small z80 assembler file called hello.z with this contents:

        org 0x0000

        jp print

        org 0x0100
print:
        ld hl, msg
chars:
        ld a, (hl)
        and 0x7f
        out (0x21), a
        ld a, (hl)
        and 0x80
        jr nz, exit
        inc hl
        jr chars
exit:   halt

msg:    defb 'Hello there', 10, 13 + 0x80

This can be assembled by, for example, zmac or pasmo. For zmac, the command line could look like this:

zmac --oo cim,lst hello.z

The resulting files would then be placed in the zout directory. You need to adjust the sample config file by changing builtin_mem.romfile to zout/hello.cim. Then run exdehl, and you should see the debugger prompt. There, type ? plus return so see a list of available commands.

Check out the manpages exdehl.1 and exdehl.conf.5 on where to go from here.

Additional documentation

In the doc directory of the source tree you can find manpages, which will be installed to /usr/local/man by the default install rule. exdehl has several command line options that will tell you what additional features (i.e. modules) you can find on your system. Invoke exdehl with the -h command line flag to get an overview of the available options.

There are also a few sample projects to get you started.