Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/310.lha/debug_v2.10/debugdoc

Text File | 1980-12-06 | 23KB | 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
    [phone]                [phone]


                    --  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.