Debugging mode
- Gunther Strube
If you specified the debugging mode at the command line (or with File->Debug Command Line) , you automatically get an extra window in OZvm. The small white area at the bottom (just the size of a single line of text) is the OZvm debug command line. Here, you will find the blinking cursor (or caret), ready for input (just after OZvm has been started from host operating command line (eg. MSDOS shell or UNIX shell). The large window above is for text output of debug commands.
When you start OZvm in debug mode, the Z88 system isn't automatically booted. You will see a grey screen (switched off state). The OZvm environment has everything loaded and initialized, ready to be executed. At this stage, you're actually able to set monitoring breakpoints and other stuff, before letting OZvm run the code.
The debug mode is also available when the Z88 is being executed. That means that you can monitor execution by looking at Z80 registers, viewing memory, and disassemble Z80 instructions while the Z88 is running. At all times you can switch keyboard focus between the OZvm debug command line and the Z88 screen input by pressing the F12 key or just click with the mouse on the Z88 screen if you need the Z88 to be aware of the PC keyboard.
When the Z88 screen has input focus (all keyboard input from your PC keyboard gets typed in the Z88), you can press F5 to halt Z80 the processor at any time (or use the 'stop' command in the debug command line) . A small message will be displayed in the Runtime Messages Window. Input focus has already been transferred to the debug command line with a blinking cursor.
The debug command line also supplies a command history. Just press the <UP> arrow key get the the previous command. You can also use the <Up> or <Down> arrow keys to browse the command history. Just press ENTER at the command, you wish to re-execute.
When specifying an address for the various commands that needs an address, you can either use the local 64K address range, eg. 0000h - FFFFh, or use extended addressing that enables you to get access to the full 4MB memory range of the Z88. An extended address is first specified with a bank number (00h - FFh), followed by the 16K bank offset (full 64K absolute address may be used as well), eg 203800 (bank 20h, offset 3800h). You may use a segment mask in the bank offset; it makes it easier to read in various output but is otherwise ignored by the command line.
The following debug and register commands displayed below can all be typed in upper or lower case (register commands below are just displayed in upper case for readability):
Command: | Function: |
| help | Display a list of the available commands (see below). |
| run | Execute Z88 virtual machine from PC register; the Z80 processor is run and the Blink interrupt scheme is enabled/resumed. |
|
|
| stop | Stop currently running Z88 (or press F5 when Z88 window has focus). |
| z | Trace z88 subroutine machine code at PC register and break at next instruction on same call level. Blink interrupts are not enabled during tracing (only the 'run' command enables Blink interrupts). |
| . | Single step instruction at PC register. Blink interrupts are not enabled during single stepping. |
|
|
| dz [<address>] | Disassemble at default PC register (if no address), otherwise at specified address. |
|
|
| ldc filename [<address>] | Load code from file into bank address. The file image must fit within the bank boundary. You cannot load a file image into an empty slot. |
| wb <ext.address> <byte> [<byte>] | Write a single or several byte(s) to memory at address. |
| |
| m [<address>] | View memory at default PC register (if no address), otherwise at specified address. |
| bp [<address>] | List breakpoints (if no address), otherwise toggle stop breakpoint at specified address. |
| bpd [<address>] | List display breakpoints (if no address), otherwise toggle display breakpoint at specified address. |
| apps | Display a list of current installed applications and podowns in the operating system and on external application cards. The list shows the name of the application and entry point (when OZ enters the application). The 24bit entry pointer is useful for debugging purposes when it is needed to catch the execution of the running application. This command will be extended with display of further information from the application DOR. |
| bl | Display Blink register contents. |
| sr | Display Blink Segment Register Bank Binding. |
| rg | Display current Z80 registers. |
| f/F | Display current Z80 flag register. |
| cls | Clear debug command out window. |
| fcdX [options] | Manage file cards (or file areas in application cards). fcd1, fcd2 and fcd3 commands represent the base for a range of optional sub commands for slots 1-3. If no options are defined, a list of files that are stored in the file area are displayed to the console output window. |
| Options: | |
| Create or re-format a file area in specified slot. All current files in file area will be lost. |
| Create a file area header in specified slot, but without formatting the file area. |
| Preserve current active files and reclaim file space of deleted files |
| Mark specified "oz" file in file area as deleted. |
| Import file from the host operating system into the file area. The file will be added to the end of the current file list. The filename is operating system dependent. Imported file(name)s are stripped of any path that was specified from the host file system. |
| Import files from the host operating system directory into the file area. The files will be added to the end of the current file list. The directory-pathis operating system dependent. Imported file(name)s are stripped of any path that was specified from the host file system. |
| Export file from the file area to the host operating system host-path. The filename must match the existing filename in "oz" fileformat, with a leading "/". The path of the "oz" filename will be stripped; the core filename will be used as to save the file in the specified host-path. |
| Export file card (area) to the host operating system host-path. The path of "oz" filenames will be stripped; the core filename will be used as to save the file in the specified host-path. |
| dumpslot X [filename] | Dump slot (1-3) as file with optional 'filename' (might include path), or default 'slotX.epr' if no filename is specified. |
| dumpslot X -b [dir/filename] | Dump slot (1-3) as 16K banks, optionally to specified directory, otherwise dumped to current OZvm program directory. Default filename is "slotXbank.<bankNo>'. You can also specify a base filename for the 16K bank files, eg. "dumpslot 2 -b E:\temp\app2005" will dump the 16K bank files in "E:\temp" using "app2005.0" - "app2005.63" (if a 1Mb card were dumped). |
| savevm [filename] | Save a snapshot of the current Z88 (Z80 / Blink registers and memory) to a file. If no filename is specified, the snapshot is saved in current program directory as 'boot.z88'. When supplying a filename for the snapshot, the extension '.z88' is automatically added, if not specified. You can only save a snapshot when the Z88 is not running (use stop command first). |
| loadvm [filename] | Load a Z88 snapshot (replaces current virtual machine). If no filename is specified, a 'boot.z88' snapshot file is attempted to be loaded from current program directory. When supplying a filename for the snapshot file, the extension '.z88' is automatically added, if not specified. You can only load a snapshot when the Z88 is not running (use stop command first). |
| BC DE HL IX IY SP PC[<address>] | Display or set 16bit registers, eg HL 40CC (set register). |
| A B C D E H L [<byte>] | Display or set 8bit registers, eg B 40 (set register). |
| BC' DE' HL' [<address>] | Display or set 16bit alternate registers. |
| A' B' C' D' E' H' L' [<byte>] | Display or set 8bit alternate registers. |
| FZ, FC, FN, FS, FV, FH [1 | 0] | Display or set Flag Register bits, eg. FZ 1 enables Zero flag. |