
                    SUNSYS Protected Mode Debugger
                                 and
                SUNSYS Linkable Debugger Module Library
               *****************************************

Requires:
    an 80386SX processor (an 80486 or better recommended)
    a VESA VBE 1.2 compatible video BIOS
    DOS/32 Advanced DOS Extender (this program cannot be run under Windows)


    The SUNSYS Protected Mode Debugger is a stand alone debugger program that
allows the programmers to debug their 32bit protected mode applications. It
supports the LE (Linear Executable) format that is used by WATCOM C/C++ when
creating DOS/4G(W) protected mode applications. The usage of SUNSYS Protected
Mode Debugger is:

	sd myprog.exe

where sd is the name of the debugger executable and myprog.exe is the file
name of the protected mode program that you want to debug.

    The SUNSYS Linkable Debugger Module Library is a powerful tool for the
programmers that allows the Debugger Module to be linked into your application
and debug the program as is at run-time. To link the Debugger Module into
your protected mode application you need to include a C header file debug.h
into your C/C++ source code. To initialize the Debugger you must call a
subroutine Debug_Init(), and to place a break point you need to insert a
subroutine Debug() into your source files.

Exemple:

#include <stdio.h>
#include <debug.h>		// include the Debugger Module


int main(int argc, char *argv[]) {
	int n;

	Debug_Init();		// initialize the debugger
				// needed only once, and can be placed anywhere
				// in your program
	.
	.
	.

	Debug();		// place a breakpoint
				// the program execution will be stopped at
				// this point and the Debugger will be entered

	for(n=0; n<64; n++) printf("Number=%d\n",n);

	return(0);
}

    Please note that you do not have to call the function Debug_Init at the
startup of your program. The debugger can be initialized anywhere, and at
any time. Also note that both Debug_Init and Debug procedures are declared
as void proc(void), that is, they do not take any arguments and do not return
anything. This way, the C/C++ compilator will not modify the code when
a break point (a call to Debug function) is inserted into the source code.

    Tips: it is very easy to examine the code that the compiler had produced
by simply placing a Debug break point between the lines of the source code
that the programmer is interested in. As soon as the break point will be
reached and the debugger will be entered, it will show the assembly code
at that point in your program where the break point was encountered.

    You may place as many Debug break points as you wish, there is no limit,
since these break points are the calls to the debugger library that are
allocated at compile and link time by the compiler and linker.

    Tips: you may call the Debugger library from assembly language as well,
though it is much easier to place a software break points (INT 3) instead.
To call the Debug_Init procedure from assembly language you must include
the following lines into your source code:

extrn	Debug_Init_	: near		; the debugger initialization routine
extrn	Debug_		: near		; the debugger break point routine

    Note that both the Debug_Init and Debug subroutines will not modify any
or all of the registers or flags and are declared the near calls.

Exemple:

.386p
.MODEL	flat

extrn	Debug_Init_	: near
extrn	Debug_		: near


.CODE

create_bit_pattern:
	
	call	Debug_Init_		; initialize the debugger

	push	eax
	push	ecx
	push	esi

	mov	eax,1
	mov	ecx,32
	mov	esi,0
	int	3			; place a break point
					; can be substituted by call to Debug_
@@1:	mov	table[esi*4],eax
	shl	eax,1
	inc	esi
	loop	@@1

	pop	esi
	pop	ecx
	pop	eax

	ret

.DATA

table	dd	32 dup(0)

    Tips: you don't have to step through the WATCOM startup every time you
debug your program. Generate the map file and look for the address of the
subroutine you are interested in (for exemple main_). Remember the address,
start the debugger, switch on unrelocated addresses (keys 4 or '.') and
enter the unrelocated using key ENTER (do not forget the preceeding '.').
Now just press the F4 key and the debugger will do all the rest of the job
for you.

    Remember to include the Linkable Debugger Module library into the list of
the libraries that are to be linked into your protected mode application. The
library file sdebug.lib should be located in DOS32A\L32 and WATCOM\LIB386\L32
directories.



                   Using the SUNSYS Protected Mode Debugger
                  ******************************************

    The stand alone Debugger and the Linkable Debugger Module are completely
identical to each other. They look the same and perform the same functions.
The only major difference between them is that the Linkable Debugger Module
can not show the unrelocated adresses since it is linked into the application
and has no idea of how the objects were loaded into the memory.

    The SUNSYS Protected Mode Debugger has a number of unmovable windows that
will be shown for the first time when the debugger is entered (the debugger
will be initialized and stay active when using Debug_Init with Linkable
Debugger Module, but it will not be entered until a break point or an
exception is encounered in the program).

    Some of the windows can be selected and an action can be performed in
them, other windows are not selectable and will only show the information.
The following is a list of all the windows in SUNSYS Debugger and functions
that can be performed in them:


CPU 80x86/80x87
===============
In this window will be displayed the addresses, processor instruction codes
(in hex) and assembly language code.

Keys:
-----
 ESC - Repaint Screen	- clear and repaint the screen
 TAB - Next Window	- switch to next window
 SHIFT-TAB - Prev Win	- switch to previous window
 PRINT SCREEN - DumpScr	- dump the contents of the screen into file on disk
 ENTER - New Address	- view the disassembled code at specified address,
			  the addreses preceeded by a '.' are treated as
			  unrelocated addresses, you can also specify a
			  general register that contains a new address

 KEY 1			- turn on/off the CPU instruction codes
 KEY 2			- switch between 16- and 32bit instructions
 KEY 3 or ','		- turn on/off the FPU registers shown in Stings Window
 KEY 4 or '.'		- turn on/off the unrelocated addresses

 ARROWS UP and DOWN	- move the cursor up and down
 ARROUS LEFT and RIGHT	- shift the code by one byte
 PAGE UP and PAGE DOWN	- move the cursor one page up or down
 HOME			- move the cursor to EIP address

 '+' and '-' on keypad	- increment/decrement the selector in Memory Window

 F1 - Show Info		- show system information
	Sub-keys:
	---------
	 F1 - DPMI information
		UP, DOWN, PGUP, PGDOWN, - scroll the info in the window
	 F2 - GDT information
		PGUP, PGDOWN, - scroll the info in the window
	 F3 - IDT information
		PGUP, PGDOWN, - scroll the info in the window
	 F4 - EMBs (Extended Memory Blocks) Information
		UP, DOWN, PGUP, PGDOWN, - scroll the info in the window
	 F5 - System Interrupt History
		UP, DOWN, PGUP, PGDOWN, - scroll the info in the window
		1,2,3,0 - select a particular interrupt (0-show all)
		BACKSPACE - reset buffer
	 F6 - Buffered Interrupts Information

 F2 - BreakPoint 	- place a hardware breakpoint at the cursor position
			  maximum of 3 (three) breakpoints can be placed at
			  the same time

 F3 - Return		- return from subroutine, run until a RET, IRET, RETF
			  or an unconditional JMP instructions are encountered

 F4 - Run Here		- run to the address where the cursor is placed

 F5 - User Screen	- switch to user screen

 F6 - New Address	- skip to cursor, place the address value under the
			  cursor in the EIP register

 F7 - Trace Into	- single step through the program, the CALL, LOOP and
			  REP prefixed instructions executed step by step

 F8 - Step Over		- single step through the program, but step over
			  the CALL, LOOP and REP prefixed instruction which
			  are executed as is, ie without stepping into them

 F9 - Run		- continue execution of the program

 F10 - Step Over Jumps	- the same as F8, but step over JUMPS (both conditional
			  and unconditional)

 F11 - Search New	- search for an expression, symbol '*' can be used to
			  indicate wild cards, for exemple: mov ax,[ebx+***]
			  will match any move to ax from the address pointed
			  to by [ebx+ any other general register]

 F12 - Search Next	- continue searching for the previously entered string



CPU Registers Window
====================
In this window will be shown all the general registers, segment registers and
the extended flags.

Keys:
-----
 ESC - Return to CPU	- return to the CPU Window
 TAB - Next Window	- switch to next window
 SHIFT-TAB - Prev Win	- switch to previous window
 PRINT SCREEN - DumpScr	- dump the contents of the screen into file on disk
 ENTER - New Value	- change the value of a register, you can also specify
			  a general register that contains a new value

 KEY 1			- turn on/off the CPU instruction codes
 KEY 2			- switch between 16- and 32bit instructions
 KEY 3 or ','		- turn on/off the FPU registers shown in Stings Window
 KEY 4 or '.'		- turn on/off the unrelocated addresses

 ARROWS UP and DOWN	- move the cursor up and down, select a register
 ARROUS LEFT and RIGHT	- move the cursor left and right, select a register
 PAGE UP and PAGE DOWN	- move the cursor to the next group of registers
 HOME			- move the cursor to the EAX register
 END			- move the cursor to the Carry Flag

 '+' and '-' on keypad	- increment or decrement register's value
 '/' on keypad		- clear the contents of the register (set to 0)
 '*' on keypad		- inverse the contents of the register (NOT reg)



Memory Window
=============
In this window will be displayed the contents of the memory at the specified
addresses.

Keys:
-----
 ESC - Return to CPU	- return to the CPU Window
 TAB - Next Window	- switch to next window
 SHIFT-TAB - Prev Win	- switch to previous window
 PRINT SCREEN - DumpScr	- dump the contents of the screen into file on disk
 ENTER - New Address	- view the memory contents at specified address,
			  the addreses preceeded by a '.' are treated as
			  unrelocated addresses, you can also specify a
			  general register that contains a new address

 KEY 1			- turn on/off the CPU instruction codes
 KEY 2			- switch between 16- and 32bit instructions
 KEY 3 or ','		- turn on/off the FPU registers shown in Stings Window
 KEY 4 or '.'		- turn on/off the unrelocated addresses

 '+' and '-' on keypad	- increment/decrement the selector

 ARROWS UP and DOWN	- move the cursor up and down
 ARROUS LEFT and RIGHT	- move the cursor left and right
 PAGE UP and PAGE DOWN	- move the cursor one page up or down



Stack Window
============
In this window will be displayed the contents of the stack memory at the
addresses specified by SS:ESP registers. The '>' symbol will point to the
address specified by SS:EBP registers.

Keys:
-----
 ESC - Return to CPU	- return to the CPU Window
 TAB - Next Window	- switch to next window
 SHIFT-TAB - Prev Win	- switch to previous window
 PRINT SCREEN - DumpScr	- dump the contents of the screen into file on disk

 ARROWS UP and DOWN	- scroll the contents of the window up and down



Strings Window
==============
In this window will be displayed the contents of the memory pointed to by
registers DS:ESI and ES:EDI. This window cannot be selected and its contents
cannot be modified.



FPU Registers Window
====================
This window will show the contents of the Floating Point Co-processor. This
window cannot be selected and its contents cannot be modified.



    The SUNSYS Debugger will, when entered, switch to its own 32bit stack and
disable all the hardware interrupts (IRQs) except IRQ 1 (keyboard). That will
result in the timer stops, and when you return to DOS the clock will show
the wrong time. The only way to restore the clock will be to reboot the
computer. The mouse will not work when the Debugger is entered an working
either (though the mouse will work fine in the program you are debugging).
    This is done this way to ensure that the debugging of your applications
will proceed as exact as possible. The system will be "frozen" when the
debugger is entered, and restored when the debugger returns to your program.
Note that on some computers the screen in SuperVGA videomodes will not be
restored correctly.

