=========================================================
                Debug_68k User's Manual
=========================================================

Debug_68k.dll is a component that can be used by emulators to add a debugger for an emulated Motorola 68000 CPU.

====================
Installation
====================
Put debug_68k.dll in the directory containing the emulator executable file.

====================
The debug_68k window
====================
When you invoke the debugger, or when execution hits a breakpoint, the debug_68k window pops up.
At the bottom of the window there is a text input box (it looks like an horizontal white bar), with a "Continue" button to its right. Pressing the button closes the window and resumes execution.
The upper part of the window is divided in four parts. From left to right they are the disassembly area, the register display and the stack display, and the output area which is under the register and stack displays.
When you digit a debugger command on your keyboard, it appears in the input area, and it gets executed when you press the <Enter> key. When the command gets executed, the command and possibly its results are displayed in the output area.
All numeric values displayed in the debug_68k window are always hexadecimal.
Addresses are displayed with six hexadecimal digits, as this covers the 16MB address space of the 68000 processor.

======================
The disassembly window
======================
This window shows the disassembly for the 68000 code corresponding to a small area of memory. There's one machine code instruction per line (or a DC.W followed by a 2-byte value for codes that don't represent a valid Motorola 68000 instruction), preceded by its starting address in memory.
A line with red text in the disassembly area shows the machine code instruction that will be executed next.
After execution of one or more 68000 instructions, the range of disassembled addresses will change  to show the code at the next PC (Program Counter), and some code before and after the next PC.
You can scroll the code with the up arrow, down arrow, page up and page down keys.
To display the code around an address <addr>, you can use the command "u <addr>". ("U" stands for "Unassemble").
Hovering the mouse over some of the operands that are specified through addressing modes, shows the address value in a popup. The address value is computed according to the current register values, which may be different than the value it will have when the instruction will get executed. The exception is the PC register using in addressing modes, which takes the value of the instruction's address instead of the current value of the PC register.

====================
The register display
====================
Red text in the register display area highlights values that have changed after execution of the last instruction or group of instructions.
The bottom line in the register window may either be blank or display emulator-specific status. (For example, in Q-emuLator I use it to show whether special system code is executing, like system calls and interrupt handlers.)
To change a register value, type in "<reg>=<value>" (e.g. "D0=0"). <value> can be any valid expression (type "expr" for expression help).

=================
The stack display
=================
The upper right part of the debugger window shows the content of the stack, starting with the current stack pointer address on top. The content is shown in words, or longs when the values look like a valid address.

=================
Debugger commands
=================
Type "help" for a list of available commands.
Note that there is currently no "clear breakpoint" command. However, you can use "bp <bpNumber> 0" to clear a breakpoint.

==================
Stepping through code
==================
Use the F1 key to step to the next instruction. F1 steps into function calls.
Use F2 to step to the next instruction, but step over function calls as if they were a single instruction.
F3 works like F2, with the additional rule that if the instruction is a conditional branch, then it executes instructions until the next PC is reached (i.e. 1 instruction if the branch is not taken, or any number if it is taken). It is similar to setting a breakpoint to the next instruction and then restart emulation. This is especially useful for the branch instruction that ends a loop, when you want to go to the first instruction after the loop is completely executed.
Shift+F3 is complementary to F3: for conditional branch instructions, it runs until the branch target address is reached.
To run unconditionally (or until execution hits the next breakpoint), use F11, or type 'g', or press the 'Continue' button.

==========================
Using debug_68k.dll in emulators
==========================
It's easy to add debugging capabilities to an emulator of a M68000 based system by using debug_68k.dll. If you are an emulator author, write to qemulator@kagi.com to receive instructions, the header file with the interface, and sample glue source code. Use is free provided credit for it is given in the emulator's documentation, and the debug_68k.dll and this document are distributed in their original form with the emulator.

==================
Web site
==================
You can find the latest version of debug_68k.dll and the Q-emuLator Sinclair QL emulator for Windows and Mac OS at the following URL:

	http://users.infoconex.com/daniele/winql.html
