/* History:133,1 */
This is file debug32.doc


Contents:

* Basic concepts
* Command summary









Basic concepts:

Debug32 is created from the same set of sources as go32, the DOS extender.
However, additional sources are enabled to add in the symbolic debugger
features.  When invoked, debug32 loads the programs symbols (if it can)
and places you at the beginning of execution (*NOT* at main()).  The
debugger allows the following actions:

* step through code
* step across or into function calls
* set 3 independent breakpoints
* go until a certain address
* view and change registers
* view and change memory
* view program code (not source code)
* view the 80387 state
* display a stack trace
* list symbols

The debugger does not allow changing the code, restarting the program, or
changing the 387.

Wherever the commands call for an address, you may specify any of the
following, or combination (use '+' and '-'):

* constants (1024, 0x4F)
* symbols (_main, _valid_mem_used)
* file/line (control#47)
* registers (%edx)
* combinations: (_data2+%edx-4 , traps#4+0x17)

Addresses are displayed in symbolic notation when available.  Code listings
include function, file, and line numbers when available; and give
variable names when it can figure what they are.

Whenever a prompt is displayed, a default command is also displayed.  If
you just hit return, the prompt and default are *erased* and the previous
command is repeated, including any counts specified, as a continuation of
the previous command.  Thus, when stepping through code, enter "step"
once, and just press <return> after that.  When dumping code or data,
each <return> picks up where the last operation left off.

If you include the "ansi" parameter in the GO32 environment variable,
then ANSI color commands will be used to colorize the debugging output:

  set go32=ansi driver c:/drivers/ati.grd
           ----








The commands:


go [v]
g [v]
cont [v]
c [v]

begin/continue execution from the current EIP and continue until the next
breakpoint or exception.  If an address is specified after the "go",
breakpoint number three is temporarily set to this address and enabled.


step [count]
s [count]

Execute one machine instruction, then stop.  If a count is given, steps
that many instructions (displaying each on the screen).  This command
traces *into* function calls.  No debug registers are used by this
routine.  As each instruction is performed, the instruction is displayed
on the screen with the "before" values of the appropriate registers.  You
might see extra registers if a symbol like "pleax" is used (%eax displayed).


next [count]
n [count]

Similar to step, but does not trace into function calls.  Uses breakpoint
number three.


list [address] [count]
l [address] [count]
u [address] [count]

Lists machine-level code (symbolically, if it can), starting at the given
address, or %eip if address not given (unless previous command was a
list, then it picks up after the previous one).  If a count is given,
lists that many lines (defaults to one unless previous was list).
Source lines are listed if the source files are present, and source
debugging information is available.


dump [address] [count]
d

dump memory.  Dumps as 32-bit words, with ASCII to the right.


da [address]

Dump null-terminated ASCII.


where

Give a list of functions currently active, provided the stack hasn't been
trashed.


whereis <wildcard>

give a list of symbols that match <wildcard> and their hexadecimal
values.  Can also be used to evaluate expressions.  Wildcards are "*" for
match zero or more, "?" for match any one.

Examples:    "whereis _foo*" gives _foo, _foo_bar, etc.
             "whereis _main+47" gives 0x452f


break <which> <address>
b <which> <address>

Sets breakpoint <which> to address <address>.  There are four
breakpoints, 0-3, but number three is used by "go" and "next".
To clear a breakpoint, set its address to zero.


status

Lists the breakpoints that are active.


regs
r

Display the 80386 registers and flags.


set <what> <value>

Changes the contents of memory or registers.  To change memory, give any
standard address as <what>.  To change a register, specify and of %eax,
%ax, %ah, %al, %ebx, %bx, %bh, %bl, %ecx, %cx, %ch, %cl, %edx, %dx, %dh,
%dl, %esi, %edi, %ebp, %esi, %esp, %eip, %eflags.


npx

Displays the 80387 contents


cls

Clears the screen


help
h
?

Give help


quit
q

Quit, what else?