home *** CD-ROM | disk | FTP | other *** search
/ PC World 1999 June / PCWorld_1999-06_cd.bin / software / temacd / vmacx / DOCS / DEBUG.TXT < prev    next >
Text File  |  1998-06-28  |  8KB  |  235 lines
  1. vMac/DOS release 0.1.9.5
  2. Debugger manual
  3. Yoav Shadmi (yoav@nettaxi.com)
  4.  
  5.  
  6. vMac/DOS features an online debugger, which has only recently begun
  7. taking the form of a close-to-decent debugger, and many new features
  8. were added to make it usable for vMac users.
  9.  
  10. Some of its features are:
  11.  
  12. - Ability to set breakpoints, even in ROM code.
  13. - Enable/Disable ROM write access.
  14. - Write to registers and memory [including ROM and hardware memory].
  15. - CPU stepping functionality.
  16. - Ability to run scripts and redirect screen output to files/devices.
  17.  
  18.  
  19. Using the debugger
  20. ------------------
  21.  
  22. The debugger can be started in two ways:
  23. - Starting vMac with '-d' or '--debugger' option.  This will run vMac
  24.   straight to the debugger.
  25. - Pressing F9 during run-time, will halt the execution and switch to
  26.   the debugger.
  27.  
  28.  
  29. Debugger features and commands
  30. ------------------------------
  31.  
  32. The debugger commands can be divided into four groups of functionality:
  33. Memory control, CPU control, Macintosh control and Debugger control.
  34.  
  35.  
  36. Memory control commands:
  37.  
  38. "m <address> <lines>"  -  This command dumps the memory contents
  39.    to screen [or file, if output is redirected].  'address' is used to
  40.    specify the starting location of the memory dump.  'lines' is the
  41.    number of lines to dump.  If no arguments are given, 'm' will
  42.    dump 16 lines from its last position. [The starting position is
  43.    the value in the program counter register]
  44.  
  45.    The numerical notation in this command is hexadecimal.
  46.    This command does not alter any memory value or cpu register.
  47.  
  48.    example: "m 580000 20" will display the memory contents starting
  49.             address 580000h through 58002FFh [32 lines].
  50.  
  51.  
  52. "d <address> <lines>"  -  This command dumps the memory contents
  53.    to screen [or file, if output is redirected] in the form of 68k
  54.    assembly code.  'address is used to specify the starting location.
  55.    'lines' is the number of lines to dump.   If no arguments are given,
  56.    'd' will disassemble the next 8 instructions from its last position.
  57.    [The starting position is the value in the program counter register]
  58.  
  59.    The numerical notation in this command is hexadecimal.
  60.    This command does not alter any memory value or cpu register.
  61.    
  62.    example: "d 400000" will disassemble 8 instructions starting address
  63.             400000h.
  64.  
  65.  
  66. "w <address> <value>"  -  This command writes the specified value
  67.    [byte size] to the specified address.   This command requires all
  68.    arguments.
  69.  
  70.    The numerical notation in this command is hexadecimal.
  71.    This command does not alter and cpu register.
  72.    This command can also alter readonly addresses, such as ROM.  It can
  73.    also access the hardware address space.
  74.  
  75.    example: "w b22 80"  will write 80h to address B22h.
  76.  
  77.  
  78. "W <register> <value>"  -  This command writes the specified value
  79.    [double-word size] to the specified CPU register.  This command requires
  80.    all arguments.  Also, 'register' must have valid information [see below].
  81.  
  82.    The numerical notation in this command is hexadecimal.
  83.    The valid values in 'register' are: A0 - A7 and D0 - D7.
  84.    This command does not alter any memory value.
  85.  
  86.    example: "W a7 66666" will change the value in a7 [the stack pointer] to
  87.    66666h.
  88.  
  89.  
  90. "i" - This command will switch the ROM address space write access on and off.
  91.  
  92.    This command does not use any arguments.
  93.    It affects the working mode of the emulator, even during run-time.
  94.  
  95.  
  96. "V" - This command will view the screen contents.   Press any key to
  97.    return to the debugger.
  98.  
  99.    This command does not use any arguments.
  100.    This command does not alter any memory value or cpu register.
  101.  
  102.  
  103.  
  104. CPU control commands:
  105.  
  106. "r" - This command dumps the current state of the 68k CPU - all registers,
  107.       including FPU registers [If 68881 emulation is enabled].
  108.  
  109.    This command does not use any arguments.
  110.    This command does not alter any memory value or cpu register.
  111.  
  112.  
  113. "g <address> - This command starts/continues CPU execution and returns to the
  114.    emulator.  'address' is the starting point of the execution, and may be
  115.    omitted.  If no arguments are given, the CPU continues execution from
  116.    the address specified in the program counter register.
  117.  
  118.    The numerical notation in this command is hexadecimal.
  119.    This command exits the debugger, and can be also used to terminate
  120.    input and output redirection.
  121.  
  122.    example: "g 40E125" will set the program counter to 40E125h and start
  123.             executing from that address.
  124.  
  125.  
  126. "t" - This command steps one CPU instruction.  It does not return to the
  127.    emulator nor leave the debugger, but it does affect the memory and
  128.    hardware state of the Macintosh.   This is useful to trace through a
  129.    program step by step.
  130.  
  131.    This command does not use any arguments.
  132.  
  133.  
  134. "z" - This command is similar to 't' with one exception.  Unlike 't' it
  135.    will step through instructions.  Which is useful to "skip" subroutines.
  136.  
  137.    This command does not use any arguments.
  138.  
  139.  
  140. "Z <count>" - This command steps through a specified number of instruction,
  141.    which makes it useful when tracing through loops, etc.  'count' may not
  142.    be omitted.
  143.  
  144.    The numerical notation in this command is hexadecimal.
  145.  
  146.    example: "Z 40" will step through 64 instructions.
  147.  
  148.  
  149. "f <address>" - This command steps through the instructions until it reaches
  150.    the specified address.  This can be used as a primitive form of setting
  151.    breakpoints.  'address' may not be omitted.
  152.  
  153.    The numerical notation in this command is hexadecimal.
  154.  
  155.    example: "f 12333" will step through instructions until it reaches
  156.    address 12333h.
  157.  
  158.  
  159. "b <address>" - This command sets a breakpoint in the specified address, and
  160.    can break execution during runtime.   If the breakpoint is met during
  161.    runtime, the emulator is stopped and switches to the debugger.  'address'
  162.    may not be omitted.
  163.  
  164.    The numerical notation in this command is hexadecimal.
  165.    Currently, only one breakpoint can be set.
  166.  
  167.    example: "b 41ffc6" will set the break point to address 41FFC6h, or
  168.             remove it if it was already set to 41FFC6.
  169.  
  170.  
  171.  
  172. Macintosh control commands:
  173.  
  174. "1" - This command saves ALL memory, cpu and hardware information into a
  175.    file [Approximately 16.5mb] named "vMac.RAM".
  176.  
  177.    This command does not use any arguments.
  178.  
  179.  
  180. "2" - This command restores the saved information in "vMac.RAM" and loads
  181.    it back to the memory, cpu and hardware.  This can be used with "1" to
  182.    save the Mac state to a file and examine it offline or loaded it at
  183.    a later session and continue from the saved state.
  184.  
  185.    This command does not use any arguments.
  186.    Use with caution, or vMac might crash [or worse, crash and corrupt your
  187.    disk-images].
  188.  
  189.  
  190. "M" - This command emulates the Macintosh Interrupt key.  Its function is
  191.    the same as pressing F11 during runtime.
  192.  
  193.    This command does not use any arguments.
  194.  
  195.  
  196. "R" - This command emulates the Macintosh Reset key.  Its function is the
  197.    same as pressing F12 during runtime.
  198.  
  199.    This command does not use any argumnets.
  200.  
  201.  
  202.  
  203. Debugger control commands:
  204.  
  205. "h", "?" - These commands display a summary of all debugger commands.
  206.  
  207.    This command does not use any arguments.
  208.  
  209.  
  210. "I <filename>" - This command redirects keyboard input to a file, thus
  211.    allowing you to run debugger scripts.   The scripts must end with
  212.    either "I" with no arguments, the "g" command or the "Q" command.
  213.  
  214.    "I" with no arguments sets the input stream to default - keyboard.
  215.  
  216.  
  217. "O <filename>" - This command redirects the output from screen to a file.
  218.    "O" with no arguments disables the redirection and sets the output
  219.    stream to default - screen.  "g" and "Q" also disable this redirection.
  220.  
  221.  
  222. "S" - This command spawns a DOS child - command.com.  vMac's footprint is
  223.    about 50kb, so you should have sufficient conventional memory if your
  224.    system is configured right.   Typing "exit" in the DOS prompt closes
  225.    the DOS child and returns to the debugger.
  226.  
  227.    This command does not use any arguments.
  228.  
  229.  
  230. "Q" - This command exits the debugger [and the emulator] and returns to DOS.
  231.    This command also disables any input/output redirection.
  232.  
  233.    This command does not use any arguments.
  234.  
  235.