45:


























































U

U










                                              7CHAPTER  1


                                        DB: THE ATARI DEBUGGER




            Db 5is a debugger for the Atari ST and TT series of 68000-family computers.  It
            is  intended  to  replace 7sid 5as the assembly-level debugger of choice.  It is
            not a source-level debugger, but it does handle both Alcyon C and Mark  Willi-
            ams C"187  (new and old) symbol table formats.

            Db can use any of the ST's character devices for its input and output, includ-
            ing  the  screen,  the  serial  port,  and  the  MIDI port.  The I/O device is
            selected with a switch on the command line (or in the TTP  window  if  started
            from the desktop).

            Db is capable of debugging programs running on one machine while the  bulk  of
            the  debugger  runs  on another.  This is called 6remote5 6debugging5, and permits
            debugging of operating systems while they boot, for example.  This feature  is
            described in the chapter REMOTE DEBUGGING.


            7USAGE

                5From a command shell, db can be started as follows:

                                 3  47db 5[ 6options5 ] [ 6program5 [ 6args5 ... ] ]

                If started as a TTP program from the desktop, the arguments line looks the
                same without the word 7db 5at the beginning.


            7OPTIONS

                56Db5 can use many different devices for its input and  output.   This  makes
                debugging graphics- and keyboard-oriented programs easier.

                These 6options5 on the command line select the output device to use:


                7-g

                    5Use GEMDOS to access the ST screen and keyboard.  This is the  default
                    case,  but it does have limitations.  See the section 7DB AND GEMDOS 5in
                    the chapter 7OPERATING SYSTEM CONSIDERATIONS 5for more information.


U3

4            ________________________
3

43

4               "187 Mark Williams C is a trademark of Mark Williams Company.


U3

4            JANUARY, 1990                   ATARI DEBUGGER                              DB







      DB                              ATARI DEBUGGER                   JANUARY, 1990


          7-b56N5

              Use the BIOS to access the ST screen  and  keyboard.   Sometimes  this
              helps  when  debugging  a  program which itself does BIOS I/O, because
              using GEMDOS calls can mess up type-ahead and the like.

              You can (optionally) specify which BIOS device to use by  placing  the
              BIOS device number after the 7-b5: "-b3" means "use BIOS calls for input
              and output, and use BIOS device number 3 (the MIDI port).   The  argu-
              ment  is  in  decimal.  Any  number at all may be used here, including
              numbers which are not in fact BIOS device numbers; in this  case,  the
              debugger  will  probably crash, and it is likely that you will have to
              reset your machine.


          7-s

              5Use the serial (RS232) port.  A terminal or an ST running  a  terminal
              program  must  be connected via a "null modem" cable, and its keyboard
              and screen are used for communicating with  the  debugger.   (You  can
              even  use  a  modem  connection to a terminal or computer, but this is
              extreme.)  The baud rate, parity, etc. for the serial port must be set
              before starting the debugger in this mode.


          7-m

              5Use the MIDI port.  An ST running a terminal program  which  uses  the
              MIDI port must be connected with a double-MIDI cable (i.e. MIDI OUT ->
              MIDI IN and MIDI IN -> MIDI  OUT).   One  such  program  is  7miditerm5,
              included  on the distribution disk with the debugger.  It is a minimal
              terminal emulator program, but it gets the job done.

U          In the last two modes, the debugger  controls  the  serial  or  midi  port
          hardware  directly, without going through GEMDOS or the BIOS, so there are
          fewer limitations on debugging programs which  use  GEMDOS  or  the  BIOS.
          However,  the  the limitations with respect to the operating system always
          apply, except when remote debugging.  See the section 7DB AND GEMDOS 5in the
          chapter  7OPERATING  SYSTEM CONSIDERATIONS 5for more information.  Also, see
          7iodev 5and 7bdev 5in the section on debugger variables.


          Each of the options 7-g5, 7-b5, 7-s5, and 7-m 5can be followed by  the  letter  7x5:
          this  controls  the  printing  of non-standard characters when using the 7d
          5(dump) command. Non-standard characters are those with ASCII codes 128 and
          up.  Normally,  these  are printed in the ASCII part of the dump command's
          output.  When 7-s5, 7-m5, or 7-b 5with a device-number code is used, printing of
          these  characters is suppressed, because they confuse most terminals.  The
          presence of the letter 7x 5(e.g.  7-sx 5or 7-bx15) re-enables printing of  these
          characters,  which can be useful if your terminal is in fact another Atari
          computer with the same extended character set.  The 7x 5modifier  also  con-
          trols  the  use  of  inverse  video  for  error  messages: if the Atari ST


U      2                                                      "189  1988,1990 Atari Corp.







            JANUARY, 1990                   ATARI DEBUGGER                              DB


                extended character set is used, the VT52 code for inverse  video  will  be
                used too.

                In addition, the following 6option5 controls loading of  the  initialization
                script:


                7-i56file5

                    The debugger normally searches for and executes a startup file when it
                    is  run.   The  7-i 5option disables this.  With the optional 6file5 argu-
                    ment, the normal startup file is not loaded, and 6file5 is loaded in its
                    place.   There  must not be a space between the 7-i 5option and the 6file5
                    argument: "7-imyfile5".  See the section  7USING  THE  DEBUGGER  5in  this
                    chapter for more information.

D3


4                    _______________________________________________________________
U                     Usage examples:

                     db                    start the debugger; use GEMDOS for I/O.
                     db -s myprog.prg -z

                                           use  the  serial  port  for  I/O;  load
                                           myprog.prg   for  execution,  with  the
                                           command-line argument -z.
D3


4                    _______________________________________________________________

                   3  4|D3
4|
|
|
|
|
|




U3
4                                                                                  3  4|D3
4|
|
|
|
|
|






U3
4

            7TERMS

                5Several terms are used throughout this  document  which  must  be  defined
                here.

                The 6client5 is the program you are debugging.

                The 6head5 is the part of the debugger which handles all the user input  and
                output.   The  commands  you type are translated by the head into commands
                for the 6stub5.  It is the stub which causes the client  to  run,  processes
                breakpoints,  and  catches  exceptions  like  bus error.  The stub reports
                these events to the head, which reports them to you.

                When you are 6remote5 6debugging5, the head runs on the  6master5  machine,  and
                the  stub and client run on the 6slave5 machine.  The head gives commands to
                the stub and receives the  stub's  responses  through  the  6communications5
                layer, which actually talks over a MIDI cable.

                The term 6debugger5 is used to refer to the head, stub, and  communications;
                in short, everything but the client (program) and the user (human).

                You cause the client to execute instructions with the 7g 5(go), 7t 5(trace), 7u
                5(untrace),  and 7v 5(verbose-trace) commands, collectively known as 6trace5/6go5
                commands.  A 6stop5 is anything which causes  a  trace/go  to  stop:  a  bus
                error,  address  error,  or  other processor 6exception5, a breakpoint whose
                count has reached zero, or a memory checkpoint which becomes true.  Memory
                checkpoints  are evaluated at times called 6opportunities5, which occur when


3

4            "189  1988,1990 Atari Corp.                                                      3







      DB                              ATARI DEBUGGER                   JANUARY, 1990


          processing exceptions, including the illegal-instruction exception  caused
          by  breakpoints and the trace exception which happens between instructions
          of a trace.

          You can put a list of commands to be executed in a file, and  cause  those
          commands  to  be  executed  by  the debugger using the 7load 5command.  Such
          files are called 6scripts5.  Also, 6procedures5 consisting  of  debugger  com-
          mands, arguments, and local variables are available.


      7USING THE DEBUGGER

          5When the debugger is started, it processes its GEMDOS command line  first.
          If  there are any 6options5 (like 7-m 5or 7-s5) they are checked and dealt with.
          Then, if there is a 6program5 argument, that program is loaded  and  set  up
          for  executing.   It  becomes  the client.  If there are any 6args5 they are
          placed in the client's basepage, as GEMDOS command-line arguments  to  it.
          When the client is completely set up and ready to run, the debugger prints
          out its basepage information (text size, environment pointer, etc.).  This
          client set-up amounts to the same thing as using the 7exec 5command.

          The debugger then looks for and loads your configuration file (that is, it
          executes  the  commands  found there; such files are called 6scripts5).  The
          first place it looks is the current directory, for a  file  called  7db.rc5.
          If that file doesn't exist, it looks for the file named in the environment
          variable DBRC.  If there is no such environment variable, it looks for the
          file  7db.rc  5in  the directory named by the environment variable HOME.  If
          none of these files exists, the debugger simply continues with the  start-
          up procedure.

          When remote debugging, the autoload procedure is the same, except that the
          debugger looks for 7rdb.rc5, then the file named in the environment variable
          RDBRC, followed by 7rdb.rc 5in the HOME directory.

          In either case, the 7-i 5option on the debugger's command line inhibits  the
          loading  of  a  startup  file.  If the 7-i 5option has a 6file5 argument, that
          file is loaded instead.  The debugger searches for the 6file5 in the current
          directory first, then in the HOME directory.

          Whether or not there was a 6program5 argument to execute  and/or  a  startup
          file,  the  debugger  ultimately  displays its prompt, a colon (":").  Any
          time you see the colon prompt, the debugger is waiting for you to  type  a
          command  line.   Command  lines  consist  of commands and their arguments.
          Multiple commands on one command line are separated by  semicolons  (";").
          Multiple-letter commands must be separated from their arguments by a space
          (e.g.  "7where 512322"), while single-letter commands  don't  need  a  space
          (e.g.  "d12322" or "d 12322").

          You can always use ^S (control-S) to stop the debugger's output and ^Q  to
          start  it  again.   You  can usually use ^C to abort a command, especially
          commands which generate long listings.

          All numbers printed by the debugger are in hex.  All numbers you type  are


      4                                                      "189  1988,1990 Atari Corp.







            JANUARY, 1990                   ATARI DEBUGGER                              DB


                assumed  to  be  hex,  unless  prefixed  with 7@ 5(decimal), 7^ 5(octal), or 7%
                5(binary).

                When debugging programs compiled under Mark Williams C, you need to play a
                trick before you start the program. See the section 7DB AND MARK WILLIAMS C
                5in the chapter 7OPERATING SYSTEM CONSIDERATIONS 5for more information.

                When 7remote debugging5, the debugger will display its version number,  then
                wait for the stub to respond before loading the configuration script.











































U

U            "189  1988,1990 Atari Corp.                                                      5







      DB                              ATARI DEBUGGER                   JANUARY, 1990






















































U

U      6                                                      "189  1988,1990 Atari Corp.










                                                7CHAPTER  2


                                     EXPRESSIONS, RANGES, AND STRINGS



            5This chapter describes how values are entered into  the  debugger,  mostly  as
            arguments  to commands.  An 6expression5 is something which boils down to a sin-
            gle numeric value.  A 6range5 is  something  which  boils  down  to  a  starting
            address  and a length: a range of addresses. A 6string5 is something which boils
            down to a series of single-byte values.  A section on each follows.


            7EXPRESSIONS

                5An 6expression5 can be used any time a numeric value  (like  an  address  or
                count) is expected. All expressions evaluate to 32-bit integers.  Overflow
                is checked when reading a constant (so the hex constant  $FFFFFFFF0  would
                cause  and error because it requires 36 bits).  Overflow is not checked in
                any other situation.  There are two kinds of expressions:  6simple5  expres-
                sions and 6complex5 expressions.


                7SIMPLE EXPRESSIONS

                    5Simple expressions contain  no  operators  and  are  not  enclosed  in
                    parentheses.   There  may  not  be  any spaces in a simple expression.
                    Simple expressions take one of the following forms:


                    6hex5 6constant5
                    7$56hex5 6constant5
                        A hex  constant  has  the  obvious  value.   The  leading  '7$5'  is
                        optional:  with  no prefix, a number is assumed to be hexadecimal.
                        Hex constants consist of an optional sign (+ or -) followed by one
                        or more of the digits 705-795, 7A5-7F5, and 7a5-7f5.

                        Examples: 0, 1, 3FA, 13aD4, $ffffa4d0, $-5b30 (same as $ffffa4d0).


                    7@56decimal5 6constant5
                        A decimal constant begins with an at-sign ("7@5"), then an  optional
                        sign  (+  or  -), then one or more digits 705-795.  It has the obvious
                        value.

                        Examples: @0, @99, @-32768 (same as ffff8000).


                    7^56octal5 6constant5
                        An octal constant begins with a circumflex (up-arrow,  "7^5"),  then
                        an  optional  sign  (+ or -), then one or more digits 705-775.  It has
                        the obvious value.


            JANUARY, 1990                   ATARI DEBUGGER                              DB







      DB                              ATARI DEBUGGER                   JANUARY, 1990


                  Examples: ^0, ^77, ^20000000000 (same as 80000000).


              7%56binary5 6constant5
                  A binary constant  begins  with  a  percent-sign  ("7%5"),  then  an
                  optional  sign  (+ or -), then one or more digits 705-715.  It has the
                  obvious value.

                  Examples: %0, %1010, %1000000000000000 (same as 00008000).


              7.56symbol5
                  A leading period ('7.5') indicates that what  follows  is  a  symbol
                  specification.  The value of the expression is the 32-bit value in
                  the symbol's value field.  A symbol specification  can  simply  be
                  the name of the symbol (e.g.  ".start") or something more complex.
                  See the chapter 7SYMBOLS AND DEBUGGER VARIABLES 5for  more  informa-
                  tion.

                  Examples: .main, .gemlib:xmain:__main:L3


              7`56variable5
                  A leading  backquote  ('7`5')  indicates  that  what  follows  is  a
                  debugger  variable name. The value of this expression is the value
                  in the corresponding debugger variable. See  the  chapter  7SYMBOLS
                  AND DEBUGGER VARIABLES 5for more information.

                  Examples: `d0, `clientbp, `mtype


              7&56variable5
                  A leading  ampersand  ('7&5')  indicates  that  what  follows  is  a
                  debugger  variable  name,  and the value of this expression is the
                  6address5 of the  storage  for  indicated  variable  6in5  6the5  6stub5'6s5
                  6memory5.    These  variables  should  not  be  changed,  since  the
                  debugger's local copy of the variable might overwrite your change.
                  However,  these  addresses  can  be  used  in memory checks to set
                  checkpoints on the values in registers.

                  See the section 7DEBUGGER VARIABLES  5in  the  chapter  7SYMBOLS  AND
                  DEBUGGER  VARIABLES  5(especially the subsection 7Client Registers5),
                  and the section 7MEMORY CHECKPOINTS ON VALUES IN REGISTERS  5in  the
                  chapter  7THE  CLIENT, BREAKPOINTS AND CHECKPOINTS: DETAIL 5for more
                  information.

                  Examples: &d1, &pc, &sr


              7$
                  5The dollar-sign alone is short for 7`$5.  This temporary variable is
                  set  to  the  result  of  the  last math command (that is, just an
                  expression on the  command  line).   In  addition,  the  7f  5(find)


      8                                                      "189  1988,1990 Atari Corp.







            JANUARY, 1990                   ATARI DEBUGGER                              DB


                        command sets 7$ 5to the address of the start of the first match.

                        Example: $


                7COMPLEX EXPRESSIONS

                    5A 6complex5 6expression5 is a LISP-like expression containing parentheses,
                    operators  and operands in prefix notation. Unlike simple expressions,
                    there may be spaces in a complex expression.

                    The first element within the parentheses of a complex expression  must
                    be  an  operator.   The second and subsequent elements must be expres-
                    sions (simple or complex) which are used as operands for  that  opera-
                    tor.

                    In the following table of operators, "exp  ..."  means  "one  or  more
                    expressions."  For the logical operators (and the 7if 5command), zero is
                    "false" and anything nonzero is "true."  The logical  operators  them-
                    selves all return the number 1 if the expression is TRUE.
































U

U            "189  1988,1990 Atari Corp.                                                      9







      DB                              ATARI DEBUGGER                   JANUARY, 1990


D3


4              ______________________________________________________________
U               FORMAT           COMMENTS

               7MATH
               5(+ exp ...)      Add the expressions together
               (- exp1 exp2)    Subtract exp2 from exp1
               (* exp ...)      Multiply the expressions together
               (/ exp1 exp2)    Divide exp1 by exp2
               (% exp1 exp2)    Return exp1 modulo exp2

               7BITWISE
               5(& exp ...)      Bitwise AND the expressions together
               (| exp ...)      Bitwise OR the expressions together
               (^ exp ...)      Bitwise EXCLUSIVE OR the expressions
               (~ exp)          Bitwise NOT (invert) the expression
               (>> exp1 exp2)

                                exp1 >> exp2 (that is, exp1  shifted  right
                                by exp2 bits (zero fill))
               (<< exp1 exp2)

                                exp1 << exp2 (that is, exp1 shifted left by
                                exp2 bits)

               7LOGICAL
               5(= exp1 exp2)    TRUE if the expressions are equal (also ==)
               (&& exp1 exp2)   Logical AND of the two expressions
               (|| exp1 exp2)   Logical OR of the two expressions
               (^^ exp1 exp2)   Logical EXCLUSIVE OR of the two expressions
               (! exp)          Logical NOT of the expression
               (> exp1 exp2)    TRUE if exp1 > exp2 (unsigned)
               (< exp1 exp2)    TRUE if exp1 < exp2 (unsigned)
               (s> exp1 exp2)   TRUE if exp1 > exp2 (signed)
               (s< exp1 exp2)   TRUE if exp1 < exp2 (signed)

               7MEMORY
               5(lpeek exp)      Returns the longword at address exp
               (wpeek exp)      Returns the word at address exp
               (peek exp)       Returns the byte at address exp
D3


4              ______________________________________________________________

             3  4|D3
4|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
































U3
4                                                                           3  4|D3
4|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|


































U3
4
              Here are some examples of complex expressions and how they evaluate:














U3

4

U      10                                                     "189  1988,1990 Atari Corp.







            JANUARY, 1990                   ATARI DEBUGGER                              DB


D3


4                    ________________________________________________________________
U                     EXPRESSION              VALUE   COMMENTS

                     (+ 2 3 3)                   8   simple addition
                     (- 7 5)                     2   simple subtraction
                     (* (+ 2 1) 3)               9   nested complex expressions
                     (+ `clientbp 100)               gives the client's text base
                     (lpeek (+ 4 `d0 `a0))           the addressing mode 4(a0,d0.l)
                                                 8

                     (+ (+ 3 1) (/ (* 2 8)
                     4))


                                                     in     algebraic     notation:
                                                     (3 + 1) + ((2 x 8) / 4)
D3


4                    ________________________________________________________________

                   3  4|D3
4|
|
|
|
|
|
|
|
|







U3
4                                                                                   3  4|D3
4|
|
|
|
|
|
|
|
|









U3
4

            7RANGES

                5A 6range5 is a way to specify a block of memory.   A  range  consists  of  a
                start  address  and  either  an end address or a count.  For most commands
                which take a range, the start and count values have defaults, so  not  all
                parts of the range need to be typed in.

                A fully-specified range can look like "6start57,56end5" or "6start57[56count57]5" (where
                6start5, 6end5, and 6count5 are expressions, and the brackets and commas must be
                typed as shown). If the 6end5 address is present, it is  the  first  address
                6not5  included  in the range: 7100,200 5specifies the range of addresses from
                100 to 1FF, inclusive.

                Various parts of the full specification can be  omitted.   A  range  which
                uses  the default start address looks like "7,56end5" (note the leading comma,
                showing that 6start5 was omitted) or "7[56count57]5" (the brackets set  off  6count5
                and show that 6start5 was omitted).  If you want the default 6count5 the range
                just looks like "6start5" (which also looks like any other expression).

                Here are some examples and the ranges they specify, assuming  the  default
                start is 100 and the default count is 80 (all numbers are hex):

D3


4                _________________________________________________________
U                 RANGE     FIRST   LAST   COMMENTS

                 200[70]     200    26F   no defaults; 6start57[56count57] 5form
                 200         200    27F   default count of 80
                 [70]        100    16F   default start; 7[56count57] 5form
                 80,100       80     FF   no defaults; 6start57,56end5 form
                 ,200        100    1FF   default start; 7,56end5 form
D3


4                _________________________________________________________

               3  4|D3
4|
|
|
|
|
|
|





U3
4                                                                        3  4|D3
4|
|
|
|
|
|
|







U3
4
                Sometimes the start and/or count fields have no defaults; in these  cases,
                they  must  be  specified.   Also,  the  6start57[56count57]  5form  is not always
                allowed.  This is the case for the 7g 5(go) command, where a count of  bytes
                to execute does not make sense.

                The default start and count values are listed in the descriptions for  all
                commands which take a range argument.



U            "189  1988,1990 Atari Corp.                                                     11







      DB                              ATARI DEBUGGER                   JANUARY, 1990


      7STRINGS

          56Strings5 are used mainly by the 7f 5(find) and 7s  5(memory  set)  commands.  A
          string  consists  of characters surrounded by double-quotes  (7"56string57"5) or
          single-quotes (7'56string57'5). The string  acts  like  the  sequence  of  bytes
          represented  by  the  characters  between  the  quotes, with the following
          escapes:

D3


4          ___________________________________________________
U           ESCAPE   MEANING

           \b       backspace ($08)
           \e       escape ($1B)
           \f       formfeed ($0C)
           \n       linefeed ($0A)
           \r       carriage return ($0D)
           \t       tab ($09)
           \\       the single character backslash ($5C)
           \?       the special "wildcard" escape (see 7find5)
           \xXX     the byte $XX where XX is two hex digits
D3


4          ___________________________________________________

         3  4|D3
4|
|
|
|
|
|
|
|
|
|
|









U3
4                                                            3  4|D3
4|
|
|
|
|
|
|
|
|
|
|











U3
4
          Quotation marks are also used to set off parts of commands and keep  semi-
          colons from splitting up a command.  See the chapter 7PROCEDURES, IF, GOTO,
          DEFER, AND ALIAS 5for more information.



























U3

4

U      12                                                     "189  1988,1990 Atari Corp.










                                                7CHAPTER  3


                          3  4THE CLIENT, BREAKPOINTS, AND CHECKPOINTS: AN OVERVIEW





            RUNNING THE CLIENT PROGRAM

                5Once there is a client ready to run (loaded with the 7exec 5command or  with
                a  6program5  argument  on the debugger's command line), you can cause it to
                run with the 7g 5(go), 7t 5(trace), 7u 5(untrace), and  7v  5(verbose-trace)  com-
                mands.   Collectively,  these  are called trace/go commands.  What follows
                are cursory descriptions.  See the chapter  7THE  CLIENT,  BREAKPOINTS  AND
                CHECKPOINTS: DETAIL 5for more information.

                The 7g 5(go) command runs the client at full speed.  It will only stop  when
                something  exceptional happens, like hitting a breakpoint or causing a bus
                error.  You can also stop it by hitting the stop button, if you have  one.
                See  the  section  7STOP  BUTTONS  5in the chapter 7REMOTE DEBUGGING 5for more
                information.

                The 7t 5(trace) and 7u 5(untrace) commands cause the client to execute just  a
                few instructions (sometimes just one) and then stop and display the regis