Dice/DD Dice/DD Dice Debugger (DD) User's Manual OVERVIEW DD is a debugger designed exclusively for the DICE compiler environment. In previous versions of DICE, all debugging had to be done with assembly language debuggers or by inserting printf() calls in the code. This is no longer the case! DD takes advantage of many old and many new features in the DICE compiler to provide you with the ability to debug on the source level. DD is both command-line and mouse driven. DD allows you to examine your program in a variety of display modes and using as many windows as you desire. DD also features ARexx support, the ability to replace any of the builtin commands with an Arexx program, and user-definable menus with amiga-key equivalents for the commands of your choice. Its point-and-click input capabilities allow you to build complex command lines by almost exclusively using the mouse. DD is designed to be OS friendly under OS versions 1.3 and 2.0 (and up). You may DD as many programs at a time as you like, limited only by the memory in your machine. In fact, DD is so OS friendly, it is one of the only debuggers that can actually be used to debug itself! To further enhance the usefulness of DD, full source code (written in DICE 'C' and A68K assembler) will be made available - you can add new commands and features that you need to solve your particular debugging problems. DICE FEATURES The DICE features that DD specifically takes advantage of are important to consider when writing your programs. The more you take advantage of these great features in DICE, the better DD is able to do its job, too. First and foremost, the DICE compiler now supports level 1 DEBUG hunks, as does the SAS compiler and many available assemblers. In order to enable source-level debugging capabilities of DD, you need to compile with the -d1 option to generate these hunks. You can then use DICE or any other debugger that supports the -d1 hunk format to do source level debugging. The DICE compiler also generates the standard Amiga SYMBOL hunks. These are used by DD to provide you with symbolic debugging capability. When these symbols are found in the executable by DD, you will be able to use your symbolic names to reference subroutines, variables, and so on. To cause DICE to generate the symbol hunks, you must use the -s option when compiling. Lastly, DD will cause the program being debugged to call exit() under various circumstances. If you decide to quit DD while partway debugging through a program, your program will immediately exit(). You should take advantage of this to have your program clean up any resources it used during the debugging session (close your windows, free memory allocated, etc.). DICE supports the ANSI atexit() function, which allows you to specify a subroutine to be executed at exit() time. You should use the atexit() function to specify your cleanup routine. ADDitionally, DICE supports the __autoexit keyword, which allows you to declare subroutines that are to be executed at exit() time as well. Use either method, or a combination of both, and DD will help you to minimize the number of reboots you will have to do when debugging those difficult bugs. THEORY OF OPERATION A brief discussion of how DD is implemented will help you to understand the capabilities of the debugger more fully. DD has its own custom LoadSeg() routine that is used to load the executable from disk. The entire executable is loaded into contiguous memory, and memory is allocated for your program's hunks as suggested by the CBM documentation. When your program is RESET (see the reset command below), your program's hunks are initialized from the originally loaded and relocations then performed. This allows you to reset your debugging session and start over without quitting and reloading all over again. The symbolic and debugging information found in the original file are kept track of in the original file memory, to conserve memory. DD actually shares its process with the program being debugged. This is done in a similar fashion to the Exec Signal Exceptions. The main difference is that DD uses two stacks, one for the program being debugged and one for the debugger itself. This is to eliminate the need for your program to have enough extra stack to support the debugger, too. Only a single signal bit (shared among the display windows) and the TC_TrapCode pointer of your Task structure will be seen by your program while it is being debugged. Otherwise, DD is completely invisible to the program and it will behave as if it were run from the CLI alone. While debugging, your process will be in one of two states - debugger state or program state. When in debugger state, the debugger has full control, responds to your inputs, etc. When in program state, your program is in full control and will run until it exits or until you hit a breakpoint or other stoppage (guru) of your program. The debugger is careful NOT to do DOS calls which might cause DOS to be entered twice - DOS is not reentrant... GETTING STARTED The DD executable should be in your DCC:bin directory along with your other DICE executables. DCC:bin should also be on your path. Note that DD is not a PURE program so you can not make it resident! Now you can go to any directory you have a DICE compiled program and debug it. Remember to compile with -s -d1 to get full debugging capability. To launch the debugger, just type: 1> DD myprog parm parm parm ... Where myprog is the name of your program (to be debugged) and parm parm parm is the typical CLI arguments that you would give to your program. DD will open a console window for you to enter commands. If you are debugging a 'C' program (DD works for assembly programs, too), DD will automaticall set a breakpoint at _main() or @main(), which is the main() routine of your program. You can quit your debugging session at any time by hitting ^C while the debugger is active, and DD will exit after causing your program to exit(20). DD'S WINDOWS You initially start DD and have a single console window to control the debugger from. The top few lines of the window are used to display the CPU registers of the current state of your program. All the standard 68000 Data and ADDress Registers are displayed, as well as the PC, and SR registers. The individual bits of the condition codes (CCR) are displayed to the right of the SR. Also, the program's state is displayed. Many states are possible, but typically your program will be stepped, steppedover, at a breakpoint, exited, or crashed (CPU exception). As you maneuver through your program with the debugger, values that change in these lines will be highlighted - a visual clue to what's changing. If you use the watchpoint features of DD, your watchpoint display will appear below the register display. Below this is a general purpose scrollable display window which DD uses to display various information that you ask it to. To change the information in the display area, you change the Display Mode to that of your choice. Initially, the display area is in MIXED MODE, where your program is shown to you as lines of source code with disassembly intermixed. When you start DD, your MIXED MODE display will show you where the PC register points. The lines of source and disassembly that represent the current PC location will be highlighted - most likely _main or @main. Below the general purpose display is the Status: line, where DD will display its various status and error messages. Initially, this line says: Status: Ready for command. Below the status line is the command line itself. As you type in your commands, they will be displayed on the command line. The left side of the command line is your prompt, which consists of some funny looking sequence of characters (described in the mouse input section) and the name of the source file that the PC is in. It is always good to know what file your bug is in... And finally, below the command line are two lines reserved for display of the current function key bindings. By default, these are bound to some very common commands that you would otherwise have to type. DD supports multiple windows - but all share the same command line. You use the "open" command to open a new console window. You may enter commands into any window. Commands that change a window's mode or display position will affect the window you type into. MOUSE INTERFACE The right mouse button is used, as normal, to operate the Intuition Menus that are bound to the window. The left mouse button is a select button and operates differently, depending on where you click. Clicking on text in the window generally causes the word you clicked on to be entered onto the command line automatically for you. That funny character string on the left of the prompt is there so you can click to generate those characters. Clicking to the right of the command line is like hitting return to execute the command. You can click in any combination of windows to build your command lines. COMMAND SUMMARY Below is the command summary as found in the help command (help mode display). NAME again - repeat last command alias - replace command with arexx script bp {expr} - set breakpoint at expression bp ALL - set all breakpoints in table breakpoints - display breakpoint table bytes {expr} - display bytes {at expression} changewindow - move/size current window clear expr - clear breakpoint at expression clear ALL - clear all breakpoints in table close - close a display devs - display Exec Device List dism {expr} - change to dism mode {at expression} dosbase - intelligent display of DOSBase struct down - move display down one line eval {expr} - evaluate an expression execbase - display ExecBase (SysBase) fkey - set function key definition go {expr...} - set {expr...} temp breakpoints & go help - online help hunks - change to hunks mode info - display ThisTask info intrs - display Exec Intrs List jump {name} - jump to public screen libs - display Exec Libs List longs {expr} - display longs {at expression} mbar - add menu bar mend - add menu end mark memlist - display Exec Mem List mitem - add menu item mixed {expr} - change to mixed mode {at expression} menus - activate a new set of user menus msub - add a sub menu item mtitle - add menu title offsets - toggle display address/offsets open {type} - open a new display over {range} - stepover one instruction or range pagedown - move display down one page pageup - move display up one page rendlist - end the arexx list rgetbyte {expr} - get bytes at {expr} rgetcom - get command line input rgetdism {expr} - get the dissembled line rgeteval {expr} - evaluate the expression rgetinfo {expr} - get the program nam rgetline {expr} - return the source/mixed line rgetlong {expr} - get longs at {expr} rgetword {expr} - get words at {expr} rgetpc - return the program counter rputlist - add an item to the arexx list rshowlist - show the arexx list rstartlist - start the arexx list rx rexx-script - execute ARexx macro saveprefs - save DD prefs to disk set {addr} {val} - set address to val ports - display Exec Ports List process {expr} - display process {at expression} resources - display Exec Resource List quit - _exit(20) & quit DD refresh - refresh the window registers - toggle the register display reset - _exit(20) & restart program rstep - toggle library call auto stepover flag source {expr} - change to source mode {at expression} step - step program one instruction or range symbols {expr} - display symbol {at expr} symlist - display sorted symbol list tasks - display Exec Task Lists unalias - restore command with arexx script up - move display up one line watchbyte {expr} - set/clear (toggle) byte watchpoints watchclear - clear all watchpoints watchlong {expr} - set/clear (toggle) long watchpoints watchword {expr} - set/clear (toggle) word watchpoints words {expr} - display words {at expression} EXPRESSIONS The expression evaluator can handle most C style expressions, and can be used on the command line to set breakpoints, display source, and so on. KEYBINDINGS The following keys are bound, as defaults, in DD: upcursor = up downcursor = down shift upcursor = pageup shift downcursor = pagedown leftcursor = left rightcursor = right return = execute command HELP = toggle to help display (help = help mode, help again = previous mode) AREXX SUPPORT DD is the base name of DD's ARexx port. The ARexx commands that are supported by DD are identical to those that you type in at the command line. DD also has the rexx command to allow you to run rexx scripts as macros from inside DD. These rexx script files should have the .DD extension, so you can identify which scripts are for DD. The ALIAS command allows you to replace any of the built in commands with an Arexx script of the same name (with an appended .dbug). DD looks first in the current directory, then in dcc:rexx/ for the command. UNALIAS cancels a previous alias. From within the ARexx script, the internal command can be called by name. (as can all internal commands) The results of an internal command called by an ARexx program are placed in the ARexx result variable. NOTE: Aliases are part of the DD preferences saved to disk, and automatically loaded on starting DD. The Rexx port name of the first port is DD.01 Subsequent ports are named DD.02, DD.03, and so on. COMMAND DESCRIPTIONS AGAIN This command repeats the last command entered. It is occasionally useful when a complicated command was entered. ALIAS This command provides a limited alias function for all internal commands. When an internal command is aliased, DD looks for an AREXX program with the same name (with the .DD extension) and executes that instead of the internal command. The internal command is still available, however, by specifying the name within the ARexx program. This allows you to, for instance, write a replacement pagedown command that first sends a message to the AME editor, then calls the built in DD pagedown command. To save the change, the saveprefs command must be used. BP {expression} The BP command sets a breakpoint. If the optional {expression} is given, DD will set the breakpoint at that address. The expression can also be a source line number (indicated by the trailing period.) DD will look up the source line specified, and set the breakpoint at the start of the code for that source line. If no expression is given, DD sets the breakpoint at address in the Program Counter. A line containing a breakpoint is underlined on the display. The mouse can also be used to set (and unset) breakpoints. Just doubleclick on the left (address) column of the display area, and the breakpoint is set. (If you doubleclick on an already set breakpoint, it will be unset). If there is no more room in the breakpoint table, and there are unarmed breakpoints, one will be replaced by a newly set breakpoint; otherwise the attempt to set a new breakpoint will fail. BP ALL When a breakpoint is hit, it is automatically unset. However, it is still in the breakpoint table, and can be rearmed. The bp all commnd rearms all breakpoints in the table. BREAKPOINTS This command displays the table containing the current breakpoint list, and current status. Breakpoints can be set and unset directly on the table display itself. BYTES {expression} The bytes command changes the display mode of the current window to the bytes display. The optional expression allows you to specify the start of the byte display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed. CHANGEWINDOW This command is used to move and size the curren DD window. It only operates under AmigaaOS 2.0 or greater (so, why haven't you upgraded yet ?). The command takes the two coordinates of the upper left corner of the window, the width, and the height, and moves the window there if possible. CLEAR {expression} This command clears the breakpoint at the expression. If no expression is given, the breakpoint is cleared at the PC location. The breakpoint is not removed from the breakpoint table, and may be re-armed by the BP command. CLEAR ALL Clear all clears the entire breakpoint table. CLOSE This command closes the current display window. If the current window is the only DD window open, DD exits. DEVS This command displays the current Exec Device List DISM {expression} The dism command changes the display mode of the current window to the disassembly display. The optional expression allows you to specify the start of the disassembly display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed. DOSBASE This command displays the pulic fields of the AmigaDOS DOSBase structure. DOWN This command is used to move the cursor down one line. New informtion is displayed at the bottom of the display area if the display scrolls. This command acts the same as pressing the cursor down key. EVAL {expression} This command evaluates an expression, and prints the result to the screen. EXECBASE This command displays the current contents of the public fields of ExecBase. FKEY num definition This command is used to set one of the ten function key definitions. The command takes the function key number (from 1 to 10) and the definition string. GO {expression} The go command sets all the breakpoints in the breakpoint table, and starts execution on the program being debugged. Execution begins at the expression if provided; otherwise execution begins at the address contained in the program counter (PC). The program runs at full speed; the debugger does not regain control until either the program exits, or the program encounters one of the breakpoints. If more control over the execution is desired, you should use one of the single step functions (step or over) instead. HELP {command} Provide short online help list HUNKS This command changes the current display to a table of the hunks in the progra being debugged. INFO This command displays information on the current task, taken from the task structure. INTRS The intrs command displays the Exec interrupt list. JUMP {name} The jump command is used to jump a DD window to another public Intuition screen. With no argument, the jump command jumps the window to the next public screen. If an argument is specified, the jump command jumps the window to that public screen. If the screen does not exist (or there is only one public screen, ie Workbench) nothing happens. LIBS This command diplays the Exec library list. LONGS {expression} The longs command changes the display mode of the current window to the longs display. The optional expression allows you to specify the start of the longs display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed. MBAR slot This command is used when setting up the programmable menu system, to add a menubar at the specified slot. The slot can be a positive integer (from 0 to 127) or -1 (which tells DD to append the new menu bar to the existing menus) When this command is used, menus are automatically turned off, and must be turned on with the menus command. MEND This command is used when setting up the programmable menu system, to add a menu end marker at the specified slot. The slot can be a positive integer (from 0 to 127) or -1 , which tells DD to append the new menu end marker to the existing menus. When this command is used, menus are automatically turned off, and must be turned on with the menus command. MEMLIST This command displays the current Exec memory lists mitem slot label command shortcutkey This command is used when setting up the programmable menu system, to add a menu item at the specified slot. The slot can be a positive integer (from 0 to 127) or -1 , which tells DD to append the new menu item to the end of the existing menus. The label is what is displayed in the menu. The command is what is executed when the menu item is selected. The optional shortcut key is used to assign a Right Amiga key shortcut to the function. When this command is used, menus are automatically turned off, and must be turned on with the menus command. MIXED {expression} The mixed command changes the display mode of the current window to the mixed display. The optional expression allows you to specify the start of the longs display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed. The mixed mode display consists of the source for the program being debugged (if available) interspersed with the disassembled instructions that each source line compiles to. MENUS This command activates the DD menus. MSUB slot label command shortcutkey This command is used when setting up the programmable menu system, to add a menu subitem at the specified slot. The slot can be a positive integer (from 0 to 127) or -1 , which tells DD to append the new menu subitem to the end of the existing menus. The label is what is displayed in the menu. The command is what is executed when the menu item is selected. The optional shortcut key is used to assign a Right Amiga key shortcut to the function. When this command is used, menus are automatically turned off, and must be turned on with the menus command. Sub items are automatically attached to the nearest previous menu item. DD does not support sub items under 1.3. Instead, they are treated as menu items. MTITLE slot label This command is used when setting up the programmable menu system, to add a menu title at the specified slot. The slot can be a positive integer (from 0 to 127) or -1 (which tells DD to append the new menu title to the existing menus) Each menu title must have at least one menu item following it. The label is used as the menu title. When this command is used, menus are automatically turned off, and must be turned on with the menus command. OFFSETS This command toggles the display of addresses as either offsets from a listed symbol name or plain hex addresses. OPEN {type} This command is used to open a new DD display. If no type is specified, a new window is opened with the same display as the current window. Otherwise, a display of the specified type is opened. The displys are somewhat independent ... each can display a different address, but share breakpoints, the registers, Rexx port name, etc. OVER {range} This command is used to single step the program under debug, stepping over subroutines. The subroutine is executed, and control returns to the debugger at the instruction immediately following. The optional range parameter allows you to set up an address range for execution. Control returns to the debugger if the program under debug leaves the range. PAGEDOWN This command is used to move the cursor down one page. New informtion is displayed at the bottom of the display area if the display scrolls. This command acts the same as pressing the shifted cursor down key. PAGEUP This command is used to move the cursor up one page. New informtion is displayed at the top of the display area if the display scrolls. This command acts the same as pressing the shifted cursor up key. RENDLIST This command is used to signal completion of a buffer list creation by an external ARexx program. DD allows external commands to create an information list through its ARexx port. The list is then available for display; DD handles scrolling, refresh of the list, and so on. This command tells DD that the list is complete and ready for display. RGETBYTE {expression} This command is used to get one line of bytes at expression. If no expression is provided, the bytes will be fetched from the location specified by the PC. The bytes are returned in the ARexx RESULT variable. RGETCOM This command is used to get the command line. The command line is returned in the ARexx RESULT variable. RGETDISM {expr} This command is used to get one line of disassembly at expression. If no expression is provided, the disassembly will be fetched from the location specified by the PC. The bytes are returned in the ARexx RESULT variable. RGETEVAL {expr} This command evaluates the expression, and passes it back in the ARexx RESULT variable. RGETINFO {expr} This command is used to get the program name and current line number of the expression. If no expression is provided, the information will be fetched from the location specified by the PC. The results are returned in the ARexx RESULT variable. RGETLINE {expr} This command is used to get one line of mixed display at expression. If no expression is provided, the disassembly will be fetched from the location specified by the PC. The lines are returned in the ARexx RESULT variable. RGETLONG {expr} This command is used to get one line of long words at expression. If no expression is provided, the long words will be fetched from the location specified by the PC. The bytes are returned in the ARexx RESULT variable. RGETWORD {expr} This command is used to get one line of words at expression. If no expression is provided, the words will be fetched from the location specified by the PC. The bytes are returned in the ARexx RESULT variable. RGETPC This command is used to get the value if the current Program Counter (PC). The bytes are returned in the ARexx RESULT variable. RPUTLIST This command is used to add a line of text to the buffer list being created by an external ARexx program. DD allows external commands to create an information list through its ARexx port. The list is then available for display; DD handles scrolling, refresh of the list, and so on. This command gives a line for DD to add to the list. RSHOWLIST This command is used to display the external buffer list previously created with the rputlist commands. RSTARTLIST This command is used to signal the start of creation of a buffer list by an external ARexx program. DD allows external commands to create an information list through its ARexx port. The list is then available for display; DD handles scrolling, refresh of the list, and so on. This command initializes the buffer list. RX rexx-script This command executes an external ARexx script file. DD will treat any command given by the user which is not an internal command as an ARexx command; the rx command is to execute scripts with the same name as internal commands, or the same name as a symbol from the program under debug. SAVEPREFS This command saves the configuration file for DD to dcc:config/dd.config. This file contains information on which commands are aliased, window position information, etc. SET {address} {value} This command is used to set the address to the specified value. If the value is not given, a 0 will be used. This command can also change the value of the registers (A register is denoted by the trailing :, ie A0: or PC:). PORTS This command is used to display the Exec port list. PROCESS {expression} This command is used to display process information for the process at {expression}. If no expression is given, the address contained in the Program Counter will be used instead. RESOURCES This command is used to display the Exec resources list. QUIT This command calls the exit routine (_exit or @exit) of the program under debug with a 20 in D0, then exits from the DD program. REFRESH Refresh the current window display. REGISTERS This command toggles the register display. Some windows contain the register display by default (the mixed mode display, for instance). Others do not (the source display). The registers command changes this for a particular window. Once the registers command has been executed in a window, the register display is on 'manual', and just obeys the register command. RESET This command calls the exit routine (_exit or @exit) of the program under debug with a 20 in D0, then restarts the it. RSTEP - toggle library call auto stepover flag This command toggles the auto stepover flag for libraries. If rstep is on, then DD will automatically use OVER when asked to STEP into an Amiga rom routine. source {expression} The source command changes the display mode of the current window to the source display. The optional expression allows you to specify the start of the source display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed. STEP This command is used to single step the program under debug. The optional range parameter allows you to set up an address range for execution. Control returns to the debugger if the program under debug leaves the range. SYMBOLS {expression} This command is used to display the symbol table for the program under debug. Breakpoints can be set from this table. This table is ordered by address. SYMLIST This command is used to display the symbol table for the program under debug. This table is sorted. TASKS This command will display the Exec task list. UNALIAS This command removes a previously set alias. To save the change, the saveprefs command must be used. UP This command is used to move the cursor up one line. New informtion is displayed at the top of the display area if the display scrolls. This command acts the same as pressing the cursor up key. WATCHBYTE {expression} - set/clear (toggle) byte watchpoints This command is used to see the values of bytes at the specified expression. This command sets or clears a watchbyte. If there are any watchbytes, the display is added to the current DD window; otherwise there is no watchbyte display. The expression can be an address, or a symbol. WATCHCLEAR - clear all watchpoints This command removes all watchbytes, watchwords, and watchlongs. WATCHLONG {expr} - set/clear (toggle) long watchpoints This command is used to see the values of longss at the specified expression. This command sets or clears a watchlong. If there are any watchlongs, the display is added to the current DD window; otherwise there is no watchlong display. The expression can be an address, or a symbol. WATCHWORD {expr} - set/clear (toggle) word watchpoints This command is used to see the values of words at the specified expression. This command sets or clears a watchword. If there are any watchwords, the display is added to the current DD window; otherwise there is no watchword display. The expression can be an address, or a symbol. WORDS {expression} The dism command changes the display mode of the current window to the word display. The optional expression allows you to specify the start of the word display. (DD attempts to keep enforcer happy; most illegal accesses are trapped). If no expression is specified, the address of the display remains the same; just the mode is changed.