
                     THE  DOS32  DEBUGGER


                  Copyright (c) , 1995, 1996

                         Adam Seychell
                               &
                        James Bundiono



                           COPYRIGHT

     This software is under copyright and may only be
distributed under the terms and conditions stated in the
General Public Licence. A copy of the licence is distibuted
with this software under the file name GPL.DOC



                              The debugger


     This DOS extender comes with a complete debugger for the
debugging your 32bit protected mode programs. The whole
debugger is the file DEBUG.LIB and must be to be linked in
with the program that you wish to debug. The debugger is
started by executing a near call to the external procedure
named "Debug" or "Debug_Run". Calling "Debug" will immediately
start the debugger directly after this call. Calling
"Debug_Run" will only initialise the debugger and return to
the program as normal. With this later call the debugger will
only come into action when a CPU exception occurs (such as a
Page Fault, General Protection, breakpoint) or if CTRL+BREAK
keys are pressed. In effect, this call is identical as calling
'Debug' and pressing the F9 key to continue executing.
    You have probably already ran the debugger example
program, debug\example.exe . You will find that it's similar
to a conventional debugger except it's for 32bit protected
mode. The debugger will not debug when in V86 mode or in real
mode. Whenever your program calls real mode (or V86) then the
debugger will be disabled until it returns to the program in
protected mode.
     The main feature of the debugger is single-stepping.
Single-stepping allows the user to execute one instruction at
time and able to see the values of each register. There are
two types of stepping available. Pressing the F7 key will step
on every instruction except for INT xx. Pressing the F8 key
will step on all instructions except for CALL, INT xx, LOOP
and instructions with the REP prefix. For these instructions
that are not stepped through, the debugger will begin normal
execution of the instruction and return back to debugging mode
on the following instruction. 
     When stepping through, the debugger saves the value of
each register. The debugger has back stepping feature, which
allows the user to load every register to the same values as
in the previous step. The back stepping keys are ALT+F4 and
can only go back up to 40 times.  
     You can also insert breakpoints anywhere in the code
simply by pressing F2. This will insert (or delete) an opcode
0CCh which is an single byte to cause an interrupt 3. You will
see the instruction highlighted red. When the program is run (
F9 key ), it will stop at the breakpoint instruction and
return to the debugger. You can also assemble your programs
with an INT 3 instruction at any locations you wish to break.
For example, if you have a procedure that hangs the system,
you could assemble the program with an INT 3 somewhere inside
the procedure. The program may then simply be executed ( F9)
and the debugger will take charge soon as the INT 3 is
executed.
     Another feature of the debugger is toggling between the
user screen and debuggers screen by ALT+F5. When switching to
the users screens, the video mode, palette, cursor location,
font memory, text mode screen memory, and all of the
_standard_ VGA registers are restored. Non standard VGA
registers are not restored so you may have some problems in
SVGA modes.
     When stepping through certain instructions a temporary
switch to the users screen is made. The instructions that will
cause a video switch include,  LOOP, INT xx ,CALL, REP prefix,
and any access to the VGA ports. This makes sure that the VGA
card is properly programmed  while debugging.




                      Advanced Debugging

    As well as software breakpoints ( opcode 0CCh) and single
stepping, the 386 has a set of special debug registers. There
are four breakpoint registers each of which hold a 32bit
linear breakpoint address ( registers DR0..DR3 ). Another
debug register ( DR7 ) sets the type of breakpoint for each of
the four breakpoint addresses. There is also a debug status
register ( DR6 ) which contains information for the exception
1 handler.  See the Intel documentation for a complete
description of the debug registers.
      The debuggers exception 1 handler will read DR6 to see
what was the caused of the exception.  If the exception was
caused from one of the four breakpoint addresses then a
message will be displayed on the screen telling you which
breakpoint it was and if it was an instruction or data
breakpoint. At any time the user can hold down the CONTROL key
to display the values of the four linear breakpoint addresses
and the W, R, and LEN fields from DR7. 
     The debugger does not set any of the debug registers
however the program that you are debugging can.  Your program
can load any of the breakpoint addresses and control fields
(e.g.  Ri,Ei,LENi & Gi ) and the debugger will report the
breakpoint so you can then analyse the program.


                           Using it

     The debugger also has it's own keyboard handler. This
means the debugger is independent of the BIOS's keyboard
handler. Programs can grab IRQ 1 for their own keyboard
handlers and do not need to be redirect back to the BIOS. At
any time the program is running you may return to the debugger
by pressing CTRL+BREAK keys.

     Since the improvment to debug.asm made by James Budiono
succeeding DOS32 release V3.3 there are many new features such
as editors for registers, stack, and data. The debugger user
screen lists all the operating keys, so with a little playing
around you shouldn't have too much trouble driving it. 





