Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Assembler / dse-src3.dms / in.adf / Utilities / Debuggers / Debug.lha / debugdoc < prev next >

Wrap

Text File | 1989-10-15 | 22.4 KB | 710 lines

-- Amiga Debugger -- Debug v2.10 Software and documentation by Jim Thibodeau and Larry LaPlume. Debug is the official resident debugger here at SLADE Software. This is the second release of this program. Some of the added features include symbolic dissasembly, breakpoint toggling, workbench startup and simple expression parsing. As before, we welcome your comments and suggestions, and you can reach us like this: Jim Thibodeau Larry Laplume 35349 Janine Dr. 64 Garland Dr. #4 Zephyrhills, FL. 33541 Jackson, TN. 38301 (813) 788-2627 (901) 664-7059 -- Debug Notes -- Command line syntax: Is geared toward the heavy duty hacker. Generally, a command line consists of a single letter command, an optional space, and 1 or two arguments. Arguments may be numeric, symbolic, contain the simple math operators +,-,/,*,<<,>>, a register, or a segment number. The supported numeric formats are: Hexidecimal, decimal or binary. Some commands take no arguments, such as eXit and display Hunk list. Note that Debug shares its very own Task Control Structure with the program being debugged. Things that the program being debugged does to its Task Control Structure, it automatically does to Debug's Task Control Structure. Currently, Debug modifies the TC_TRAPCODE field of the TCB, so if your program changes this, Debug will NOT work. When Disassembling or dumping memory, none, one or two arguments may be given. If no argument is given, the operation will begin where the last operation left off. If one argument is given, the operation will begin at the address specified, and continue for a few lines. If two arguments are given, the operation will begin with the address specified by the first argument, and continue to the second argument. The disassemble and memory dump routines both support the ^C user break keystroke to stop them from continuing to their normal completion. When Debug is ready to accept commands it will display a minus sign as a prompt. Commands may then be typed at the keyboard, followed by the return or enter keys on the Amiga keyboard. Most of the time, spaces are optional, except where the parser may become confused. For example: -g_main _exit Will begin execution at _main, and quit at _exit. -g_main_exit Will attempt to begin execution at _main_exit. -- Expressions -- An expression is defined as 1 or more operands and 0 or more operators. An operator is one of the following: +, -, *, /, <<, or >>, and valid operands are as follows: s<segment-number> The first executable address of the seg- ent. This will be the same value as the the segment using the 'S' command. (<reg>[,<reg>]) Note that the second register is optional but the first is not. This MUST be in parentheses! $<hex-num> A hexidecimal number. +|-<dec-num> A signed decimal number. Because Hex is default, you must specify either + or -. %<binary-num> A binary number. <number> A hexidecimal number. (The default). <symbol> A symbolic label contained in the program being debugged. '<character>' A single character enclosed in quotes. '<string>' A string of ascii characters enclosed in single quotes. Each element will be checked for correct syntax before a value is returned. If the parser finds any errors, it will print a (hopefully) helpful error message and terminate the command. Valid registers are as follows. Note that they can be in either upper or lower case. a0-a7, d0-d7, sp, sr, pc, z, x, n, c, v. Symbols are treated in a case-sensitive way to maintain compatibility with the assembler. If the label _main is used in your program, it must be referred to in lower case only. Hexidecimal is the default input radix. If you type 3210, it is evaluated as hexidecimal, not decimal. To specify decimal, you must put a + or - in front of the number. Because parentheses are used to delimit registers, no expression nesting is allowed - i.e. 3 + (4*8) is illegal. Operator precedence is as follows: Highest Lowest *,/ +,- <<, >> There are no unary operators at this time. -- Command Summary -- Note: The following symbols and their definitions are used throughout this discussion: | - or [] - optional argument <> - description - replace with value Command: B (Breakpoint commands) Syntax: b|B [s|c|x|t|<bp-number>] <bp-number> <expression> Discussion: Debug supports limited, multiple break points. Up to 8 break points may be active at once. Use the -b command to view, set, or clear any or all break points. When setting a break point, Debug stores the requested address of a break point, stores the contents of that address, and replaces it with the MC68000's ILLEGAL opcode. Clearing the break point replaces the ILLEGAL instruction with the saved contents. When the Amiga attempts to execute the installed ILLEGAL instruction, via the 'g', 't', or 'z' commands, Debug considers it a breakpoint and displays the appropriate information. New to this version is the toggle subcommand. By using this once, the breakpoint is still set, but disabled (i.e. it will not cause the program to stop executing). By using it again, the breakpoint is enabled. Note that disabled breakpoints will not show up in the dissasembly. Examples: -b Lists all currently set break points. -b 1 List the current status of break point number one. -bs 1 100 Sets Break point number one to address $100. -bc 1 Removes break point one, and restores saved contents of that address. -bx Remove all of the eight break points that are set. -bt 0 If breakpoint 0 is enabled, disable it and vice/ versa. Command: C (Set Command Line Tail) Syntax: c|C [<parameter string>] Example: -c Desired Command line tail Declare "Desired Command line tail" as a command tail. Debug will set up the string in memory, and install a pointer to it and the length of the specified string in the MC68000s' A0 and D0 registers each time, BUT NOT UNTIL the registers are initialized. (See the "I" command). Command: D (Disassemble memory) Syntax: d|D [<start-address>] [<end-address>] Examples: -d 100 200 Will disassemble memory from address $100 to $200. -d (a0) Disassemble memory pointed to by the contents of register A0. -d (pc) Disassemble memory at the value of the Program Counter. -d (a0,d0) Disassemble memory at the value of the register A0 plus the contents of the D0 register. This is similar to the processor's d(An,Xi) mode except for the lack of index size specifier - the size always being long, and the lack of any dis- placement value. Command: f (Fill memory) Syntax: f.|F. <size> <start-address> <end-address> <value list> Discussion: This command fills successive memory locations from start- address to end-address with the values in value-list. As with the modify command, valid size specifiers are B, W and L. Examples: -f.l $4000 $5000 = 0 Fill memory between addresses $4000 and $5000 with zeros. -f.b $4000 $5000 = 7, 'This is a test...', 0 Fill memory with a stupid, repeating, flashing, NULL terminated message. Command: G (Go execute instructions) Syntax: g|G [=<start-address>] [<end-address>] Examples: -g_main Execute the program until the label _main. This is accomplished by setting a temporary breakpoint at the destination address. If processing halts before _main, the breakpoint will be cleared any- way - so if you still wanted to go to _main, you would have to type g_main again, not just g. -g=100 Begin executing instructions at address $100. -g Begin executing instructions at the current program counter. Command: H (Show Segment list of loaded file) Syntax: h|H Example: -h Display segment list of current file. Command: I (Initialize MC68000 Registers) Syntax: i|I Discussion: When initializing, Command line tail values (if any) are installed in registers A0 and D0. Also initialized are the Program Counter, and User Stack Pointer registers. When initializing the USP, the top of stack is found, then the address of a termination routine is pushed onto the stack, so the program can run to its completion, and remain in Debug for further examination. * * * N O T E * * * The following conditions AUTOMATICALLY perform the "I" command: 1. Normal termination of the program. (registers are displayed before reset). 2. Attempting to Load a file. (even if the load fails). Example: -i Initialize ALL MC68000 register values. Command: L (Load a file for debugging) Syntax: l|L [<path>/]<filespec> [<arguments>] Example: -l fred abc Will attempt to read the file fred, and set its arguments to the string 'abc'. Command: M (Memory dump) Syntax: m|M [<start-address>] [<end-address>] m|M [B|W|L] Discussion: This command presently only dumps data as longwords. As noted in the version changes above, dumping will proceed from an odd address if specified. Examples: -m 100 200 Display memory contents from address $100 to $200 -m (sp) Display memory contents pointed to by the stack pointer. -mb Change future memory dumps to eight bit format (byte). -mw Change future memory dumps to sixteen bit format (word). -ml Change future memory dumps to thirty-two bit format (long). Command: N (Change default input radix) Syntax: n|N [<H|D|B>] Discussion: Debug initially uses hexidecimal as the default input radix. This may be changed to Decimal or Binary, by using the "n" command. Note that typing $, +, -, or % before any argument will override the default radix. Example: -nd Changes the default input radix to decimal. Command: R (Display/Set MC68000 Register/Flag values) Syntax: r|R [<register>] Examples: -r Display the contents of MC68000 registers. -ra0 _main Set register a0 to the address of _main. -r a0 100 Load register A0 with the value $100. -r d0 +100 Loads register D0 with the decimal value +100. -r d0 -1 Loads register d0 with the decimal value of -1. -r sr %101 Loads the Status Register with the binary value %101. -r z 1 Forces the Zero flag on. Command: S (Display symbols) Syntax: s|S [g|<symbol>] Examples: -s Display all of the symbols. -sg Just display the global symbols. A local symbol is defined as one containing a '$'. -s_fred Display _fred and its address. Command: T (Execute in Trace mode) Syntax: t|T [=<start-address>] [<trace-count>] Discussion: Trace works just like Go, except that only ONE instruction is executed, and a register frame is displayed AFTER the instruction executes. Additionally, Debug will disassemble the next instruction to be executed. A trap number of 9 will usually appear when tracing. Note that due to characteristics of the Amiga's multitasking system, attempting to trace certain types of processor errors, including zero divide condition, can, and probably will crash the entire system. Examples: -t=_main Trace the instruction at _main. -t=ralph 4 Trace 4 instructions beginning at the label ralph. -t4 Trace 4 instructions beginning at the current program counter. Command: W (Toggle private window on/off). Syntax: w|W Discussion: When Debug is initially loaded, all I/O uses this window. Using it once, forces Debug to use _stdin and _stdout for its I/O. If the program being debugged uses _stdin and _stdout and Debug is using the window, the system WILL hang up when trying to do a Read(), therefore, use the 'w' command before beginning execution. Note that this command does nothing if Debug is run from the workbench because a workbench program has no default I/O handles. Note that this window uses the CON: device. Example: -w Close private window if it's open, Open private window if it's closed. Command: X (eXit Debug) Syntax: x|X Example: -x Bye bye! Command: Z (Zip through a subroutine) Syntax: z|Z Discussion: Zip is useful when tracing code. When the next instruction to be executed is a BSR or a JSR and tracing through the subroutine is not desirable, just press "z". Debug will attempt to execute the subroutine, and stop at the instruction immediately following it. Zip performs this feat of magic by setting a temp- orary breakpoint after the next instruction. Zip is also handy for skipping loops: just trace to the bottom of the loop, and type Z - Zip will execute up to the instruction following the loop. Example: -z Zip through instruction at the current Program counter. Command: . (Modify memory) Syntax: . <size> <start-address> = <value list> Discussion: The modify memory command will insert the values in the value list in memory starting at the start address. The size specifier is the familiar B, W or L, and each value in the value list must be separated by commas. Examples: -.b $4000 = 1, 2, 3, 4, 5, 6, 7, 8, 9, a Writes the values 1 to 10 at successive memory locations starting at address $4000. -.w _main = 1, 2, 3, 4, 5 Writes the values 1 to 5 at every OTHER address starting at the address of the symbol _main. -.l $4000 = 1, 2, 3, 4, 5 Writes the values 1 to 5 as 32 bit values beginning at address $4000. -.b $4000 = 'Fred''s dog' 10 'has fleas.', 0 Stores the string: "Fred's dog has fleas" at address $4000 complete with an embedded linefeed and (') character. Command: . (Modify memory) Syntax: . <size> <start-address> = <value list> Discussion: The modify memory command will insert the values in the value list in memory starting at the start address. The size specifier is the familiar B, W or L, and each value in the value list must be separated by commas. Examples: -.b $4000 = 1, 2, 3, 4, 5, 6, 7, 8, 9, a Writes the values 1 to 10 at successive memory locations starting at address $4000. -.w _main = 1, 2, 3, 4, 5 Writes the values 1 to 5 at every OTHER address starting at the address of the symbol _main. -.l $4000 = 1, 2, 3, 4, 5 Writes the values 1 to 5 as 32 bit values beginning at address $4000. -.b $4000 = 'Fred''s dog' 10 'has fleas.', 0 Stores the string: "Fred's dog has fleas" at address $4000 complete with an embedded linefeed and (') character. Command: > (Redirect output to a file) Syntax: > [<Filename>] Discussion: The > command may be used to direct all of debug's output to a file, if desired. To restore console output use the > command with no paramaters. Note that all output including prompts, are redirected until normal output is restored. Examples: ->ram:temp Directs all debug output to the file "temp" on the ramdisk. ->SER: Sends all debug output to the Amiga serial port. -> Restores the normal output stream. Command: < (Get input from a file) Syntax: < [<Filename>] Discussion: Debug may be used in non-interactive mode via the < command. In this case, a file is specified. The file is read, and interperted exactly as if the contents of the file were typed on the keyboard. At the end of the file, debug will terminate unless the default input stream is restored via the < command with no paramaters WITHIN the file. Note that any or all commands may be used in script files written for debug. This feature is useful for redundant debugging. Examples: -<DebugScriptFile Gets input from DebugScriptFile. -<SER: Gets input from the Amiga's serial port. < (Within a file) Restores default input. Command: ? (Help) Syntax: ? Example: -? Display the help message. Command: = (Evaluate expression). Syntax: = <expression>. Discussion: This command will evaluate the expression following the '=' and print the result in ascii, binary, hexidecimal and decimal. Examples: -= 1*2 Evaluate 1 * 2 and print it. -= fred + 4 Evaluate fred + 4 and print the value. -- Using symbols -- If you are developing with an assembler, you must use the '-C S' or similar switch when assembling your program. This switch puts the symbols from your program in the symbol hunks of the executable file. (see the AmigaDOS manual for more inform- ation on symbol hunks). No special software tool is required. If you are developing in another language, see your language reference for details on generating symbol hunks. Unfortunately, if your language processor does not support symbol hunks, Debug won't be able to use symbols. -- Error messages -- - Segment out of range: The segment number is greater than the number of segments loaded. Use the 'S' command to see the segment list. - Bad register: The register was not recognized. See the section on expressions for valid registers. - Bad register number: The digit after an 'a' register or 'd' register was not recognizable or out of range. - Bad number format: The number typed in was illegal. - Bad character format: The character typed in was invalid. - Symbol not found or bad number format: The parser could not evaluate the element as a hex- idecimal number or a symbol. To avoid confusion between a hexidecimal number and a label, prefix the number with a '$'. - Missing expression: This error usually occurs when a binary operator is used with only 1 operand, or the '=' command is used with no expression following it. - No file loaded: This error occurs when you specify a segment in an expression, with no loaded file. If there is no file, there is no segment list! - Breakpoint number out of range: Breakpoints must be in the range 0-7. - No breakpoint to toggle: Debug cannot enable or disable a breakpoint that is not set. - Pc MUST be word aligned: To prevent accidental address errors, the program counter is tested for word alignment each time it is set. - Out of range for 16-bit number: This error occurs when you try to set the status register to a number greater than it will hold. - Breakpoint not set: This message is printed if you try to clear a breakpoint that was not set. - Symbol not found: Either the symbol was mis-typed, or it is non-existant. Remember that symbol names are case sensitive. - Out of range for 8 bit number. The number specified was > 255 or < -256 - Missing address. The address was not specified for the '.' or the 'f' command. - Missing or invalid size specifier. Valid size specifiers are: B(yte), W(ord) or L(ong). - Operation MUST be word aligned. For data sizes other than byte, the start address for the '.' or 'f' command must be EVEN. - No symbols loaded. Either there is no file loaded (hence no symbols to print), or your program contains no symbol hunks. Consult your language reference on symbol hunks. - No memory available. Pretty much what you would expect from such a message - no memory! - <=> expected. See the syntax for the '.' and 'f' commands. - <,> expected. See the syntax for the '.' and 'f' commands. -- Bugs -- Some of the following are real bugs, others are just things that may cause suprises to the unwary. - The name of the program really belongs in the Task control block of the debugger (which it shares). If you are looking for it there, you won't find it. - Even if no parameters are supplied to a program, AmigaDos sticks the end-of-line character in a buffer and sets the argument string length to 1. Debug does not. If there are no parameters, D0 is 0, and A0 is 0. - Debug's replacement Exit() function assumes that the first three bytes of the library call are: moveq #2,d0 bra.s xxx If this changes in a future Dos library version, calling calling Exit() from within Debug will probably crash the system. Because Dos library is not implemented as a 'standard' jump table, Exec's SetFunction() doesn't work. - Debug has unexplainedly crashed a few times, and it seems to be a memory allocation/deallocation error. It may have something to do with Metacomco's assembler, which has a few bugs of its own. Any clues are welcome. - Although Debug loads the registers so you can examine BCPL code, something does not work right. Try loading C:List, and typing G. Debug gets the initial registers at startup, and saves them for the loaded program. Again any clues are welcome. - The command line arguments are terminated with an ascii null character - not a newline ($10). Although it may seem more consistent to end the line the way AmigaDOS does, an end of file indicator will also terminate the line (^\), so you should check for any value < ' ' for a terminator in your debugging. - Do not attempt to debug Debug. Because Debug changes the TCB in a non-reentrant way, Debug has to be modified in order for it to debug itself. -- Future plans -- All (2) of us at SLADE software want to make this THE public domain debugger. Toward this end, the next version will contain a few more 'needed' features. If you have any ideas, or commands you would like to see, let us know. 1. The addition of watch-point commands. These are similar to breakpoints, but they trap on data writes instead of executable instructions. 2. The ability to list symbols by segment number and hunk type. 3. The addition of the 'type' subcommand to dump. 4. The ability to use breakpoints and watchpoints in expressions. They would have a syntax similar to segments. 5. Linked list traversal. -- Addenda -- When displaying local symbols (symbols of the form nnn$), they may have an extra 1 to 3 digits following them. This is the 'fault' of the Amiga assembler, not this program. Some types of errors including zero divide, TRAP #x, and address errors may alter the value of the program counter displayed in the register frame. In other words, it may be necessary to scan back a few bytes or words, with the disassembler to view the offending instruction.