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

DebugCPUs (Debug CPU) are simulated AVR, Z80, 68HC11, and 6502 CPU Debuggers that might be helpful to the hobbyist who wishes to develop and debug code for a AVR, Z80, 68HC11, or 6502 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 or Debug 6811 version 1.1* or greater are 32-bit Windows applications that can run on 32-bit or 64-bit Windows. They are not digitally signed so you will get a warning when you install them that the author is unknown. If you get a dialog inidicating 'Windows protected your PC', select 'More info', and then 'Run anyway'. 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 the teraKUHN project. 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, Debug 6811 to debug 68HC11 code, or Debug 6502 to debug 6502 code, you can use the KAsm80, KAsm11, or KAsm65 assemblers respectively that comes with them. The command to run KAsm80, KAsm11, or KAsm65 will look something like this:

  KAsm80.exe {source_file_name}.a80
  KAsm11.exe {source_file_name}.a11
  KAsm65.exe {source_file_name}.a65

KAsm80, KAsm11, or KAsm65 will produce a *.hex file in the same directory as the *.asm, *.a80, *.a11, or *.a65 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 or on the toolbar. The Go command will run the code just like if you had uploaded it to a AVR, Z80, 68HC11, or 6502 board. Once you start the code with the Go or resumed with the Proceed command, you can stop it with the Stop Debug command. The Proceed and Step commands are for assembly level debugging of the assembly code generated when you compiled and/or assembled your code.

In addition to the menu and toolbar commands, you can run code by entering commands in the text window on the left. By using the command window, you can enter breakpoint addresses for the Go or Proceed commands to stop at. You can determine useful addresses to stop your code at by looking at an assembly map file which KAsm* will generate with the -M option. You can also enter the address to start execution at, and you can enter how many assembly instruction Steps the Trace command should execute.

For Debug 6811 (or Debug AVR) there is a window on the right that displays a simple representation of the CPUs input and output pins. As your program runs the pins will be white or black indicating the pin would be at 0 volts or 5 volts. Digital outputs will show bits that are on or 5 volts as black buttons and bits that are off or 0 volts as white buttons. Digital inputs can be clicked on to toggle between if the input is on (black) or off (white). Clicking on a bit configured as digital output should generate a beep and will not change it's state. Analog inputs are controlled by sliders going from minimum value on the left to maximum value on the right. Any text that is programmed to be sent to the CPUs serial output port will show up in a simulated 5 line LCD display below the digital and analog controls.

In addition to the menu and toolbar commands, you can enter other debugging 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. 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. 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.