NAME

exdehl - the EX DE, HL system emulating z80 debugger

SYNOPSIS

exdehl [ -h?Vr ] [ -c configfile ] [ -v verbosity ]

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.

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.

Upon startup, the debugger will attempt to read a batch file and execute the commands contained within. If such a file is specified via the -b command line option, that file will be used. If not, and it is specified via the init_batch configuration option, then that file will be used. Otherwise the default file name exdehl.init will be used. It is not an error if this file is not present.

The batch file may contain any debugger command except for those that cause the execution of code (r, t, s, n, R, N). Also, it may contain comments, which are lines that start with a semicolon.

modules

The emulated systems are composed of the EX DE, HL program and modules, which implement devices, and, with the exception of builtin_mem and builtin_con, are available as shared libraries. A module must implement 2 functions, mod_init() and mod_exit(), and is used by the debugger via a device struct. See emu.h and the included builtin devices (implemented in builtin.c) or the devices in src/modules for details.

builtin_con is a simple output-only text console. The io base address can be configured using the builtin_con.io_base_addr configuration variable. Characters can be output to this console by sending them to port the port at offset 1 within this range (i.e. when io_base_addr is 0x20, write to port 0x21). At offset 2 in this range, there is a status byte that can be read. It has bit 0 set when reading is possible (never for the builltin console), and bit 1 set when writing is possible (always for the builtin console). This is not really needed for the builtin console, but the tcpconsole module also offers this, so it is here for compatibility.

builtin_mem is a simple memory device, which consists of 64KB of ram and 16KB of rom, which may be mapped to any 16K block of the Z80 address space. The io base address for the mmu is configured using the builtin_mem.io_base_addr configuration variable. The mmu register is at offset 0 within this address range.

The memory mapping can be determined by sending a byte to this port, the lower 4 bits of which form the mapping. Each bit corresponds to a 16KB block of memory, with bit 0 being the first 16KB, and so on. Setting a bit to 1 will map the address space into the corresponding 16K block of ram, setting it to 0 will map the rom there. On reset, all bits are 0 an the rom is mapped to each 16KB block.

The rom is populated at startup from a file with at most 16KB, which can be configured using the builtin_mem.romfile configuration variable.

helpers

The EX DE, HL debugger can read symbol files exported from assemblers, and expects those as a pair of a name followed by a colon if the symbol is a label, or an equals-sign if it is a variable, followed the corresponding value, one per line. Any value may map to multiple symbols, but a symbol may only refer to one value. It can read these files either directly or with the help of helper scripts. These helper scripts take the file that was generated by an assembler as a command line argument, and output a symbol list as needed by EX DE, HL on their stdout.

OPTIONS

exdehl accepts the following options:

-h, -?: print help and exit
-V: print version
-C: print combined global configuration files. Useful to check what config options are available.
-D: dump current configuration
-M: list available modules
-H: list available helpers
-S: generate a sample exdehl.conf file in the current directory
-r: run the system instead of directly entering the debugger cli. The debugger may be entered at any time by pressing the escape key.
-c configfile: specify a different configuration file. It is an error if this file can not be read.
-b batchfile: specify a different batch file for the debugger, default is exdehl.init. This batch file is read upon debugger startup, if it is present.
-v verbosity: specify verbosity level. level 0 will output only error messages, level 1 will add warning messages, level 2 will add informational messages, and level 3 will add debug messages.

The flags -h, -?- -V, -C, -D, -M and -H can be combined. Specifying any of them will cause exdehl to exit before starting the debugger.

EXAMPLES

See the example projects in the samples folder for examples.

FILES

/usr/local/etc/exdehl.conf: global configuration file for exdehl
/usr/local/etc/exdehl/*.conf: per-module configuration files
/usr/local/lib/exdehl/modules: directory for globally available modules
/usr/local/lib/exdehl/helpers: directory for globally available helpers

BUGS

string interning, and all internal database like things are very simplistic. This may have to change in the future.