-=: REBUG 1.0:=-
A Resident Debugging Program For IBM PC Compatible Computers
(C) Copyright 1988 C.Bruce Snow, All rights reserved.





----- FORWARD -----

REBUG can be a very useful debugging tool. Whereas larger
debugging programs such as CODEVIEW get its power from the brute
force of a wide variety functions and options, REBUG's power
comes from its agility in being where you need it whenever you
want it. REBUG was written not to supplant other debugging
programs, but rather to use in conjunction with them. The
combinational effect of REBUG and other programs such as CODEVIEW
or even DOS's DEBUG,is synergistic in that the resulting value is
far greater then the sum of the individual components.

However, useful as REBUG is as a debugging tool its value is
not limited the that objective. A common use of a debugger is to
learn about the the system by poking around examining the various
nooks and crannies that lurk behind the scene, so to speak. A
resident debugger such as REBUG extends this practice to a whole
new dimension as application programs can be interrupted in mid
execution to be turned over and looked into.

Additionally, application programs can often be coaxed into
delivering better performance by making patches while they are
running. For example, few word processors support the use of the
graphics codes such as those which frame REBUG's window.
WORDSTAR 2000, for instance, can be forced into it by searching
out its "replace buffer" (place a unique combination of
characters the with WORDSTAR's locate & replace command and
searching for them with REBUG's F2), then substitute its contents
with the graphics code and then do a global replace. Or for
small modifications, just write directly to WORDSTAR's text
buffer! With a little imagination it possible to tickle almost
any program into doing things that hadn't been written into it.

There are some limitations of REBUG that I am aware of, it
is possible that they may be addressed in future versions.

1) REBUG cannot be used to interrupt a program which is
running in graphics mode. This isn't an oversight but rather
a decision made to try to limit the amount of memory resident
by REBUG. So far I haven't found a need for a graphics
provision. If I find later thet it's worth the space trade
off, I may add it in the future.






1






2) REBUG causes snow to appear on the screen when
refreshing the display on some CGA systems. Again, I was
faced with a performance trade off. To eliminating the snow
requires timing the screen writes to match the screen
retrace; this would seriously slow rewriting the display. I
can tolerate the snow if it means that I can page through
data at a faster rate.

3) The biggest limitation of REBUG is the lack of a
disassembled instruction for the "next-execution-address".
This would make following SINGLESTEP much more effective.
Unfortunately, the amount and complexity of the coding is
daunting. This doesn't mean, however, that I've given up on
it; it just mean it will have to be added later (I hope).

I will be glad to receive suggestions or comments you may
have concerning REBUG. Drop me a line at:

C.Bruce Snow
417 Brentwood Blvd.
Lafayette, LA 70503.


----- SYSTEM REQUIREMENTS -----

REBUG is written for a IBM PC compatible machine with a CGA
monochrome display. By specifying color during installation
color may be added to the window. Unfortunately REBUG does not
support TTL monochrome displays.

REBUG provides for the use of a NMI (non-maskable interrupt)
request. This feature permits REBUG to get into and out of
places that would not be otherwise possible. The hardware
required to utilize this feature is simply a switch which
momentarily grounds the "I/O_CH_CK" line on an I/O slot (see
appendix for additional information). If your system does not
have the NMI hardware or if this use of the NMI conflicts with
another use of the NMI, REBUG's NMI intercept may disabled as
described under the installation section.

----- INSTALLATION -----

REBUG must be installed into resident memory before it is to
be used. Once it is installed it remains resident until the
system is re-booted. Once REBUG is installed, each time the
HOTKEY (alt/left-shift) is pressed the computer will interrupt
whatever it is doing (unless it is in the process of a disk
access) and display the REBUG window. Once in REBUG, pressing
the HOTKEY will return the computer to whatever it was doing
prior to being called.


REBUG defaults to CGA monochrome and NMI intercept. It is
possible to override either or both of these by including a
switch on the command line during installation. The switch is
simply a single letter following the REBUG command. To request
color use "C", to disable the NMI intercept use "N", and for both
use "B". For example: REBUG B will install REBUG

2






in color without an NMI intercept. Note that there is one and
only one space between the command "REBUG" and the switch letter
"B", this is important, it will not see the switch if more than
one space is used.

There may be some instances when it is desirable to install
more than one copy of REBUG. This is possible providing room is
available (each copy requires 11456 bytes of RAM) and as long the
HOTKEY of the first copy is changed before the second copy is
installed. See the appendix for information on patching the
HOTKEY.



----- FUNCTIONS -----

ESC : ADDRESS MODE

ADDRESS MODE is REBUG's primary mode from which SEARCH,
MODIFY, REGISTER MODIFY, BREAKPOINT and SINGLESTEP are called.
It is in ADDRESS MODE where the ADDRESS POINTER is set. The pair
of 4-digit hexidecimal words in the upper left the display is the
ADDRESS POINTER, and describes the segment and offset that is
currently being addressed in memory.

This address can be edited using left and right arrow keys
(or backspace and space bar respectively) and keys 0 through f.
The address is loaded when the "enter", F2 or F3 key is pressed.
In addition each of the segment digits and the left two offset
digits can be incremented(decremented) by placing the cursor at
the respective digit and pressing the +(-) key. If the cursor is
placed at the rightmost digit and the +(-) key pressed, the
ADDRESS POINTER will increment(decrement) by 256 bytes causing
the display to page forward(backward). By placing the cursor at
the next to last digit and pressing +(-), the segment will
increment(decrement) causing the display to scroll one line at a
time.


F1 : HELP WINDOW

Pressing F1 key will temporarily display a summary of these
functions. This window will be cleared by pressing any key.

F2 : SEARCH MODE

SEARCH MODE will permit searching the current 64K segment
for the next occurrence of a string of up to 11 bytes in length.

Pressing F2 key while in ADDRESS MODE will switch REBUG into
SEARCH MODE. SEARCH MODE is indicated by the cursor being in the
data field. REBUG can be in both the SEARCH MODE and MODIFY MODE
concurrently. To leave SEARCH MODE and return to ADDRESS MODE
press the ESC key.

While in SEARCH (or MODIFY) MODE, pressing the F2 key will
produce the SEARCH WINDOW. A search string of up to 11 bytes may
be entered into this window. The string may be edited as needed,

3






pressing the ENTER key will load every byte to the left of the
cursor. REBUG will then search for the next occurrence of that
string contained in the current 64K segment. If found, the
cursor will be positioned at the start of matching string and the
ADDRESS POINTER will show its starting address. Additional
occurrences of the same string may be sought by pressing F2 and
re-entering the un-edited string which remains in the window. If
no match is made, a beep will sound and the window must be
cleared by pressing F2.

If the sought string is a character string, it is more
convenient to enter the bytes in ASCII MODE (see F8).


F3 : MODIFY MODE

MODIFY MODE permits writing data to memory addressed under
the cursor. Care must be exercised in what memory is modified,
especially in the low end of RAM where DOS resides. Also, it may
be important to understand that the hex nybble under the cursor
is written the moment that the key is pressed, and that each byte
is written as two consecutive nybbles.

Pressing F3 while in ADDRESS MODE will switch REBUG into
MODIFY MODE. MODIFY MODE is indicated by the block type cursor.
REBUG may be in both the MODIFY and SEARCH modes concurrently.
To leave MODIFY MODE and return to ADDRESS MODE press the ESC
key.

The cursor arrows are used to position the cursor within the
data field, and the "pg up" and "pg dn" keys will move backward
and forward through the data one page (256 bytes) at a time.

If ascii data is being written to memory, it is more
convenient to use ASCII MODE (see F8).


F4 : DISPLAY REGISTERS

The 13 working CPU registers plus flags may be displayed in
a window at the right side of the screen. The contents of the
registers reflects the state of the CPU at the moment it was
interrupted by HOTKEY.

Pressing F4 will toggle the registers window on and off.


Alt/F4 : MODIFY REGISTERS

Pressing Alt-F4 while in ADDRESS MODE will switch REBUG into
MODIFY REGISTERS MODE. MODIFY REGISTERS MODE is indicated by the
cursor's being in the registers window. The cursor may be moved
from register to register by the up-arrow and down-arrow keys;
the "page-up and page-down keys will move the cursor to the top
and bottom respectively. Editing may be done within an individual
register display but the actual change is not made until the
"enter" key is pressed and the changed register is not
transferred to the CPU until control is returned to the

4






interrupted program by toggling the HOTKEY back. If the cursor
is moved out of the individual register, the pending modification
is aborted.

The flags may be modified by placing the cursor over the
desired flag and pressing "enter". Each time "enter" is pressed
the state of the flag is reversed (set/reset).

Extreme caution is recommended in using this mode. Normally
the registers contain DOS data, since typically REBUG will
interrupt DOS in it "idle" state. Modifying these data can
easily crash the system.


F5 : BREAKPOINT

A breakpoint may be set any where in RAM (but not in ROM) in
order to cause the executing program to jump back to REBUG.

Pressing the F5 key will either set a breakpoint at at the
address pointed to by the ADDRESS POINTER or, if a breakpoint
already exists, will clear that breakpoint. Once the breakpoint
is set control will be returned to the interrupted program when
the HOTKEY is toggled back. The breakpoint remains set until the
program reaches that instruction, at which time REBUG is called.
The breakpoint is not automatically reset when reached, instead
REBUG will ask whether it should be cleared. In almost all cases
it should be reset since it is not possible to execute the next
instruction until it is reset.

If the breakpoint is never reached in the course of program
execution, it will remain embedded in the program code until
reset by pressing the F5 key.


F6 : SWAP WINDOWS

REBUG has two display windows: an active one, which is
visible, and an inactive one, which is in background. At
installation both windows are set to the HOME PAGE (page 1 of the
REBUG segment). Each window is set by entering an address in the
ADDRESS POINTER in ADDRESS MODE.

Pressing the F6 key will swap the active and inactive
windows.

F7 : SINGLESTEP

SINGLESTEP will execute the interrupted program one
instruction at a time. Certain instructions (calls, ints and
loops) may be either entered or stepped across at the operators
option.

Pressing the F8 key will automatically return control back
to the interrupted program for the execution of a single
instruction and then jump back to REBUG. If the next executable
instruction is not in the normal user memory range, REBUG will
warn of this fact and the F7 key will need to be again pressed to

5






execute SINGLESTEP. Care must be exercised in singlestepping in
low memory since that is where DOS resides. It is possible to
singlestep ROM as long as a call, int or loop is not stepped
across. Stepping across requires a breakpoint to be set, which
is not possible in ROM.

Multiple singlestepping is not fully supported in this
version of REBUG, however see the appendix on how to set the
singlestep counter for multiple singlestepping.



F8 : ASCII INPUT

Ascii characters may be inputted directly into memory in the
MODIFY MODE or into the search window when the ascii flag is on.

Pressing the F8 key will toggle the ascii input flag on and
off. When the flag is set a lower case "a" will flash at the top
left of the data field.

Alt/F9 : TAKE SNAPSHOT

In lieu of a true split display, a SNAPSHOT of 128 bytes of
data may be recorded to be displayed whenever desired.

Pressing the Alt and F9 keys together will cause REBUG to
record 8 lines of the display starting with the line pointed to
by the ADDRESS POINTER. If the ADDRESS POINTER is in the lower
half of the page, the SNAPSHOT will extend across the page
boundary into the next page. This feature is sometimes useful in
examining data which extends across the page boundary. Each time
the alt-F9 key is pressed the prior SNAPSHOT is replaced by a new
one at the current ADDRESS POINTER.


F9 : DISPLAY SNAPSHOT

Pressing F9 will toggle the SNAPSHOT on and off. The
SNAPSHOT is displayed in reverse video starting at a location
four lines below the current cursor position (ADDRESS POINTER).
If the cursor is in the lower three quarters of the display the
SNAPSHOT will wrap around to the top of the display.


F10 : ABORT TO DOS


Pressing the F10 key will cause the interrupted program to
be terminated and control passed back to DOS. While this can be
an important way to escape from an errant or locked-up program,
or even a convent way to quickly bail out of a program, it should
be used with discretion. Many programs do important housekeeping
prior to termination, left undone it may produce some unwanted
after effects. Experience will show what programs may be safely
ABORTed and when it may be better to just re-boot.



6











----- APPENDIX -----

HARDWARE FOR NMI INTERCEPT

The hardware to support the NMI intercept need not be
particularly elaborate. It is only necessary to momentarily
ground the I/O channel check line (A1) the system bus. I use a
NO push button such as Radio Shack's 275-1547. Conveniently the
I/O_CH_CK bus line (A1) is directly opposite the ground line
(B1). These two pins are at the rear of the slot with A1 on the
side closest to the power supply. So if you have an open slot
available, a small piece of PC board with a foil trace on either
side may be slid between the two bus connections. A pair of
wires solder to either side of the PC board may bring the signal
lines out to where a push button can be mounted. When the push
button shorts out the two lines an NMI signal is produced which
will summons REBUG.


HOTKEY PATCH

It may be desirable to change the HOTKEY combination from
the normally used alt/left-shift. REBUG checks for the HOTKEY by
reading the BIOS keyboard status flags buffer at 0000:0417. The
useful flags are:
bit 0 - right shift depressed
bit 1 - left shift depressed
bit 2 - ctrl-shift depressed
bit 3 - alt-shift depressed.
A mask byte made up of a combination of those bits determine what
keyboard entry REBUG will respond to. For instance, the mask for
the normal used alt/left-shift is 0AH, and for both shifts is
03H. The mask byte is stored at location 0171H which is on the
HOME PAGE in the REBUG segment. To change the HOTKEY merely
modify that location ,by using F3, to whatever mask is desired.
The new HOTKEY will remain in effect until REBUG is re-installed.


COLOR PATCH

If the colors used in the color installation of REBUG are
unsatisfactory, they may be changed by replacing the color
attribute bytes at the following locations in the REBUG segment:

01B9H - Main display color (0AH : light green)
01BAH - Information window color (0BH : light cyan)
01BBH - Warning color (8CH : flashing red).


MULTIPLE SINGLESTEP PATCH

REBUG does not offer a function for repetitive
singlestepping. However, a counter which was included in the

7






REBUG code for debugging and testing of itself still remains in
the final version. This counter, a 2-byte word, is at location
0103H-0104H in the REBUG segment. This counter may still be used
by placing a number at this location (which is normally 0000).
When SINGLESTEP is initiated, singlestepping will automatically
repeat, decrementing the counter each time, until the counter is
zero or SINGLESTEP is aborted by pressing the ESC key.


















































CBS 1/17/88

8