How to Use Debug CPU App - A simulated CPU for embedded system debugging of Z80, AVR, 6502, or 68HC11 CPUs

DebugCPUs (Debug CPU) are simulated Z80, AVR, 6502, and 68HC11 CPU Debuggers that might be helpful to the hobbyist who wishes to develop and debug code for a Z80, AVR, 6502, or 68HC11 architect CPU. The current implementation supports commands similar to those that existed in DOS debug.

The Debug Z80 and Debug 6502 version 1.2* or greater apps are 32-bit Windows applications that can run on 32-bit or 64-bit Windows. The older Debug6811 and Debug8096 version 1.1* apps are 16-bit Windows applications that can run on 16-bit or 32-bit Windows, but not 64-bit Windows. If you're interested in more recent builds of Debug6811 or Debug8096, contact us at teraKUHN and we can discuss making them available. They are not digitally signed so you will get a warning when you install them that the author is unknown. Updates happen a few times a year so if something isn't working, make sure you have the latest version installed. Also, if you identify any problems please continue to report them to teraKUHN. The latest 1.3* Debug Z80 release adds the ability to trigger hardware interrupts, implements some instructions not completely implemented in earlier versions, and implements fixes for problems users have reported. The simulator runs about 10 to 50 times slower than actual hardware.

First you need to write a program. Here's an example of a Z80 assembly program that sets bits in I/O port 081h as if it's wired to an H-bridge circuit for turning on and off motors, and calling a wait routine in between each motor state.

  ORG 0
 
  setup:
  ;; do any I/O hardware setup operations here
 
  loop:
  ;; forward
    ld a, 03Ch ;; output bits 00111100
    out (081h), a
    call delay
    call stop
  ;; reverse
    ld a, 014h ;; output bits 00010100
    out (081h), a
    call delay
    call stop
  ;; forward on one side and reverse on the other
  ;; results in turning
    ld a, 01Ch ;; output bits 00011100
    out (081h), a
    call delay
    call stop
    jp loop
 
  stop:
  ;; stopped
    ld a, 000h ;; output bits 00000000
    out (081h), a
    call delay
    ret
 
  delay:
  ;; just count down from 255 (aka 0FFh) before returning
    ld b, 0FFh
  decrease:
    djnz decrease
    ret
 
  END

Otherwise pick almost any of the numerous pieces of example code on the internet for the CPU that you're working with.

While not required, if you're using Debug Z80 to debug Z80 code, you can use the KAsm80 assembler that comes with it. The command to run KAsm80 will look something like this:

  KAsm80.exe {source_file_name}.a80

KAsm80 will produce a *.hex file in the same directory as the *.asm or *.a80 source file. Make a note of the path to the directory where the *.hex file is created. That's the directory where you will load the *.hex file from inside of Debug CPU.

Once you think you're ready to compile and/or assemble and upload your code to a CPU board, you just need to create a *.hex, *.rom, or *.bin memory file with the compiler and/or assembler you've chosen to use.

You can load *.hex, *.rom, or *.bin memory files into the simulated CPUs main program memory space through two different ways. The simpler approach is to load *.hex or *.rom files that have the machine code you want to debug by loading them through the file open menu or by specifying the file as an argument when starting the Debug CPU executable (Dbg{CPU}.exe). The other way is to list the memory files in the Debug CPU initialization file (Dbg{CPU}.ini) located in the same directory as the executable. The entries in the Debug CPU initialization file include lines that have the path to the memory file followed by ' 0 0', or for *.bin files the path to the memory file followed by the 16-bit load address and the 16-bit size of the binary.

ex:
..\BASIC.hex 0 0
EPROM.bin 2000 1000
TEST.rom 0 0

Note that a *.rom file is similar to a *.bin binary file, except that it starts with 2 bytes indicating the 16-bit load address followed by 2 bytes indicating the 16-bit size of the binary followed by the actual binary data. Since *.hex and *.rom files have their load address embedded in the files, they can be loaded with File Open; however, loading a *.bin binary file needs the load address specified in the Debug CPU initialization file.

At this point you can select Go, Proceed, or Step/Trace commands under the Project menu. The Go command will run the code just like if you had uploaded it to a Z80, AVR, 6502, or 68HC11 board. Once you start the code with the Go command, you can stop it with the Stop Debug command. The Proceed and Step/Trace commands are for assembly level debugging of the assembly code generated when you compiled and/or assembled your code. When the code has been stopped, you can use the D or O commands in the command window to dump memory or I/O ports.

In addition to the menu commands, you can enter commands in the text window on the left. Debug CPU uses a text window to allow the user to enter assembly level debugging commands and inspect the state of the CPUs memory, I/O, and registers. The text window takes single line commands at the end of the text that are described with the following syntax:

where all fields in [] are optional and the fields have the following meaning:
B - breakpoints - Use this command to set breakpoints where you want execution to stop and to echo out what breakpoints are set. This command can set new breakpoints in the program's code, but will not clear any existing breakpoints. Breakpoints can only be set at an address containing the first byte of a valid instruction. Note that DebugCPU replaces the original instructions of any listed breakpoint addresses with a halt, break, or software interrupt. The instruction at these locations are restored to their original value if the breakpoint is encountered or when the G command is next used. If DebugCPU does not hit a breakpoint, then the breakpoint is still enabled.
C - compare memory - use this command to compare a range of memory to memory at another location.
D - dump memory - use this command to report what is stored in main program memory in hexidecimal.
8 - octel dump - use this command to report what is stored in main program memory in octel.
O - dump Output/RAM - use this command to report what has been received by IO ports.
E - enter memory - use this command to modify what is stored in main memory.
I - enter Input/RAM - use this command to modify what has been sent to IO ports.
G - go - Use this command to start executing code in the debugger. This is the same as selecting Go in the menu command. This command will clear any existing breakpoints and can set new breakpoints in the program's code.
M - move memory - use this command to move a range of memory to another location.
P - proceed - Use this command to continue executing code in the debugger. This is the same as selecting Proceed in the menu command. This command can set new breakpoints in the program's code, but will not clear any existing breakpoints.
R - register - use this command to report what is stored in registers.
T - trace - Use this command to execute one or more instruction in the debugger. This is the same as selecting Step or Trace in the menu command. This command will not clear any existing breakpoints.
U - unassemble - use this command to report what CPU opcodes are stored in main program memory.

address - a 16-bit hexidecimal memory address
addresses - a sequence of up to 8 16-bit hexidecimal memory addresses
value- an 8-bit hexidecimal data value
list - a sequence of up to 8 8-bit hexidecimal data values
=address - =# where # is a 16-bit hexidecimal memory address where something will start
range - either 2 16-bit hexidecimal memory addresses indicating start and end or 1 16-bit hexidecimal memory address indicating start and L # where # is the length to end

In addition to entering single line commands at the end of the text window the Go, Proceed, and Trace commands can be entered through menu commands.