vMac/DOS release 0.1.9.5 Debugger manual Yoav Shadmi (yoav@nettaxi.com) vMac/DOS features an online debugger, which has only recently begun taking the form of a close-to-decent debugger, and many new features were added to make it usable for vMac users. Some of its features are: - Ability to set breakpoints, even in ROM code. - Enable/Disable ROM write access. - Write to registers and memory [including ROM and hardware memory]. - CPU stepping functionality. - Ability to run scripts and redirect screen output to files/devices. Using the debugger ------------------ The debugger can be started in two ways: - Starting vMac with '-d' or '--debugger' option. This will run vMac straight to the debugger. - Pressing F9 during run-time, will halt the execution and switch to the debugger. Debugger features and commands ------------------------------ The debugger commands can be divided into four groups of functionality: Memory control, CPU control, Macintosh control and Debugger control. Memory control commands: "m
" - This command dumps the memory contents to screen [or file, if output is redirected]. 'address' is used to specify the starting location of the memory dump. 'lines' is the number of lines to dump. If no arguments are given, 'm' will dump 16 lines from its last position. [The starting position is the value in the program counter register] The numerical notation in this command is hexadecimal. This command does not alter any memory value or cpu register. example: "m 580000 20" will display the memory contents starting address 580000h through 58002FFh [32 lines]. "d
" - This command dumps the memory contents to screen [or file, if output is redirected] in the form of 68k assembly code. 'address is used to specify the starting location. 'lines' is the number of lines to dump. If no arguments are given, 'd' will disassemble the next 8 instructions from its last position. [The starting position is the value in the program counter register] The numerical notation in this command is hexadecimal. This command does not alter any memory value or cpu register. example: "d 400000" will disassemble 8 instructions starting address 400000h. "w
" - This command writes the specified value [byte size] to the specified address. This command requires all arguments. The numerical notation in this command is hexadecimal. This command does not alter and cpu register. This command can also alter readonly addresses, such as ROM. It can also access the hardware address space. example: "w b22 80" will write 80h to address B22h. "W " - This command writes the specified value [double-word size] to the specified CPU register. This command requires all arguments. Also, 'register' must have valid information [see below]. The numerical notation in this command is hexadecimal. The valid values in 'register' are: A0 - A7 and D0 - D7. This command does not alter any memory value. example: "W a7 66666" will change the value in a7 [the stack pointer] to 66666h. "i" - This command will switch the ROM address space write access on and off. This command does not use any arguments. It affects the working mode of the emulator, even during run-time. "V" - This command will view the screen contents. Press any key to return to the debugger. This command does not use any arguments. This command does not alter any memory value or cpu register. CPU control commands: "r" - This command dumps the current state of the 68k CPU - all registers, including FPU registers [If 68881 emulation is enabled]. This command does not use any arguments. This command does not alter any memory value or cpu register. "g
- This command starts/continues CPU execution and returns to the emulator. 'address' is the starting point of the execution, and may be omitted. If no arguments are given, the CPU continues execution from the address specified in the program counter register. The numerical notation in this command is hexadecimal. This command exits the debugger, and can be also used to terminate input and output redirection. example: "g 40E125" will set the program counter to 40E125h and start executing from that address. "t" - This command steps one CPU instruction. It does not return to the emulator nor leave the debugger, but it does affect the memory and hardware state of the Macintosh. This is useful to trace through a program step by step. This command does not use any arguments. "z" - This command is similar to 't' with one exception. Unlike 't' it will step through instructions. Which is useful to "skip" subroutines. This command does not use any arguments. "Z " - This command steps through a specified number of instruction, which makes it useful when tracing through loops, etc. 'count' may not be omitted. The numerical notation in this command is hexadecimal. example: "Z 40" will step through 64 instructions. "f
" - This command steps through the instructions until it reaches the specified address. This can be used as a primitive form of setting breakpoints. 'address' may not be omitted. The numerical notation in this command is hexadecimal. example: "f 12333" will step through instructions until it reaches address 12333h. "b
" - This command sets a breakpoint in the specified address, and can break execution during runtime. If the breakpoint is met during runtime, the emulator is stopped and switches to the debugger. 'address' may not be omitted. The numerical notation in this command is hexadecimal. Currently, only one breakpoint can be set. example: "b 41ffc6" will set the break point to address 41FFC6h, or remove it if it was already set to 41FFC6. Macintosh control commands: "1" - This command saves ALL memory, cpu and hardware information into a file [Approximately 16.5mb] named "vMac.RAM". This command does not use any arguments. "2" - This command restores the saved information in "vMac.RAM" and loads it back to the memory, cpu and hardware. This can be used with "1" to save the Mac state to a file and examine it offline or loaded it at a later session and continue from the saved state. This command does not use any arguments. Use with caution, or vMac might crash [or worse, crash and corrupt your disk-images]. "M" - This command emulates the Macintosh Interrupt key. Its function is the same as pressing F11 during runtime. This command does not use any arguments. "R" - This command emulates the Macintosh Reset key. Its function is the same as pressing F12 during runtime. This command does not use any argumnets. Debugger control commands: "h", "?" - These commands display a summary of all debugger commands. This command does not use any arguments. "I " - This command redirects keyboard input to a file, thus allowing you to run debugger scripts. The scripts must end with either "I" with no arguments, the "g" command or the "Q" command. "I" with no arguments sets the input stream to default - keyboard. "O " - This command redirects the output from screen to a file. "O" with no arguments disables the redirection and sets the output stream to default - screen. "g" and "Q" also disable this redirection. "S" - This command spawns a DOS child - command.com. vMac's footprint is about 50kb, so you should have sufficient conventional memory if your system is configured right. Typing "exit" in the DOS prompt closes the DOS child and returns to the debugger. This command does not use any arguments. "Q" - This command exits the debugger [and the emulator] and returns to DOS. This command also disables any input/output redirection. This command does not use any arguments.