b r a n d X S Y M B O L I C D E B U G G E R
version 2.6

by Sonam G. Gyato

What is bXd:

This software is a full-screen debugger for the IBM series of
personal computers and very close compatibles. The major feature
of bXd is its ability to run without disturbing the display
screen of the program being debugged. It supports both the MDA
and CGA boards (also CGA specific modes of EGA).

Some of the other features are:
- Support for Symbol Files
With this feature code will be disassembled using label
names and addresses can be specified using label names.
Two symbol file formats are supported; including the
format generated by the widely used MicroSoft linker.

- NMI Reset Switch
This requires a hardware switch and gives a user the
ability to trap any program at the press of a button
(even if interrupts are off).
By default, this trap is disabled because it causes
problems with some EGA boards.

- Conditional Breakpoints
Users can set up to 10 breakpoints that can be triggered
when user-set conditions are satisfied. For example, a
breakpoint can be enabled only when AX register is
greater than 10 and when the Zero-bit of the flag
register is set.

- Online Help
Detailed descriptions on all the available commands.
First time users are encouraged to go through them all at
least once.


Design Philosophy:

Simple, but can also cut the mustard.

During the design phase of this software, the user and his
goal when running any debugger was kept very much in mind.
Together, the command set, screen design and the user-interface
enable any program to be debugged effectively and transparently.

After a few debugging sessions, you won't have to worry about
how to use bXd and can instead concentrate on your goal -
debugging your code.


Software for Bacon Deal:

bXd is a "shareware" software. You most probably got it from a
bulletin board or a friend at no cost to you. After using it for
sometime, I'm sure you'll appreciate not only the capability but
also the overall design of this software. You are invited to use
and distribute it to whomever you wish. This is my contribution
to the "shareware" concept.

You must understand that someone, namely yours truly, spent
quite a few hours on this software's development. It seems only
natural that I, like other independent software developers, be
encouraged so that users like you continue to have access to good
software at a reasonable cost. This encouragement and your
contribution to the "shareware" concept takes in the form of the
user sending in a registration fee.

Sending in of this contribution is usually the end of most
"software for bacon" deals - not so this one. If you send the
contribution, you will receive a copy of the non-shareware
version of bXd (bXd3). The '3' at the end of bXd is fully
warranted. There are two major additions and they are -

- Source-Code Debugging
This option will support all the compilers that generate
source-information and that can be linked using MS linker.
This includes MicroSoft C and Turbo C (other languages ok
also). It will -
- display in src or src/asm mode
- auto-sync of code and source information
- unlimited number of source files

- Dual Monitor Display
One disadvantage using a full-screen debugger to debug
graphics program with one monitor, is that the target program
cannot access the screen directly. With this new dual-monitor
debugging ability (two monitors with different adapters
required) there is no such restriction. Your program can
access the video screen and the adaptor board directly.

I hope that the addition of these two extra features, a
printed manual and a guarantee of a better product will urge you
to keep your part of the "shareware" bargain (pun intended) and
send in the bacon.

Please send your contribution of $35 to:
Sonam G. Gyato
240, 76th Street
North Bergen, NJ 07047


bXd AND YOUR PROGRAM:

Below is the format of invoking bXd from the DOS prompt.

A>bXd userprog [user_arguments] [
1. The first argument is the name of the file to be debugged
(target prog). If no extension is given, bXd tries first to
load a COM and then an EXE file. The status of the loading
will be displayed.

If a program is loaded, then bXd tries to load the symbol file
associated it. First a SYM and then a MAP format file. More on
the formats later.

2. The second set of arguments is what will be passed to your
program in a buffer as its command line input. When the main
bXd screen is displayed initially, this buffer (DS:80) is
displayed in the data window.

3. bXd does not use DOS for its console i/o. So if the target
prog expects a constant sequence of chars, it could be
redirected from a file. You can also redirect the DOS output.


SCREEN FORMAT:

The bXd screen is divided into six different windows.

USER
This is the window from which all comds are issued. There are
two ways of doing it
- Line-Input Command (LIC)
This is the method used by most debuggers. You type a
command id followed by optional arguments.
- Special-Key Command (SKC)
The second method is through using a single key, like the
function or the cursor keys. You can invoke these even
when you're in the middle of a LIC.

CODE
The program code is unassembled in this window. If a symbol
file was loaded, defined addressed will be displayed using
their variable equivalent. You can scroll the info from the
USER window using the cursor keys.

REGISTER
The user register values are displayed in this window. You can
edit the values using the 'R' Line-Input command.

DATA
Memory is displayed in this section in both hex and ascii
formats. Using the FK3 and FK4, you can select which of the
two available windows will be primary.
You can scroll the info in the primary data window from the
USER window with the and keys.

STACK
The current value pointed to by the stack pointer (SS:SP) is
displayed at the bottom of the window. The values displayed
above it are the subsequent memory locations.

CURRENT WINDOW HELP
You can move the cursor to other windows besides the USER.
This window displays a brief help text on the window the
cursor is in.


COMMANDS

Single-Input Commands:

FK1 Display the online help menu.
You can choose a command by pressing the hi-lighted
letter in each topic header. You can also accomplish the
same by moving the topic-selector bar with the cursor
keys and then pressing RETURN when the bar is over the
topic header.
Press ESC to quit.

FK2 Display the target program's display.
Once displayed, press any key to return to bXd screen.

TECHNICAL:
Since there is a limited amount of video memory present
and both the target and bXd's display has to co-exist,
there are restrictions to how the target program accesses
the display.
MDA There is only one display page in monochrome mode,
therefore the target program cannot access the video
RAM directly. It must go through DOS or BIOS level
routines.
CGA In CGA equipped pc's, bXd uses the last of the four
text pages (BB00:0). This means that in text modes,
target programs can write directly to the screen for
the first three pages. It will have to go though DOS
or BIOS level routines for the fourth page.

In graphics modes, CGA needs all of the 16K
available. Therefore, all plots must go through BIOS
level routines. Most probably, this will be too
slow...but you can write directly to screen once the
program is fully debugged.

FK3 Toggle the mode of the data window.
There are two modes for display
- single: one window of 6 data lines are displayed.
The window displayed is primary.
- dual: two windows of 3 lines each are displayed. The
primary window is pointed to by an arrow on the line
between the two windows.
See FK4

FK4 Toggle primary window.
Primary window is the one to which all data related
commands are acted on. For example, 'display data' and
'edit data' comds act on the primary window.
See FK3.

FK5 Toggle the trace condition for the CALL instruction
(default: ON).
See FK7.

FK6 Toggle the trace condition for the INT and REPx
instructions (default: OFF).
See FK7.

FK7 Trace one instruction.
A single instruction at the current pointer (CS:IP) is
executed. Once executed, if any registers changed it will
flash on the bXd screen; also if any of the bytes in the
data window changed it will be displayed in red. Both
these conditions will be reset when the next command is
given.

The INT, REPx and the CALL instructions are treated in
a special way. The current trace conditions for these
instructions are displayed at the bottom of the bXd
screen. The condition for the INT and REPx instructions
are linked (meaning that one condition controls both
instructions). If the condition is YES, then the
instructions will be traced through. If the condition is
NO, then the instructions are executed in one shot.
See FK5, FK6.

FK9 Set/Reset Breakpoint.
In the CODE window there is always one instruction that
is hi-lighted. You can select which line gets hilighted
by using the cursor up/down keys. Pressing FK9 toggles a
brkpt at the currently hilighted instruction. An enabled
brkpt is marked by an asterisk before the instruction.

FK10 Edit breakpoints.
Once pressed, the brkpt window will be displayed. There
are 10 breakpoints available. You can select a particular
brkpt to edit using the cursor keys.
Press ESC to quit.

There are 5 fields for each brkpt. You can select a
particular field by pressing TAB (next field) and the
shift-TAB (previous field) keys.
ON/OFF Press the SPACE key to toggle the current
state.
SEGMENT Segment value of the brkpt.
Default is the current code segment.
OFFSET Offset value.
HIT Number of times the above address is executed
before the brkpt is signalled.
Default is 1.
CONTROL One or two conditions can also be set before a
brkpt is signalled. A condition consists of one
of the eight binary operators allowed. The
operands can be either register names or hex
constants. If both the conditions specified,
then BOTH have to be satisfied for the brkpt to
be signalled.
Default is "no conditions".


Line-Input Commands:

This is the format most are familiar with. It consists of a
command followed by optional arguments. There are four types of
arguments
- address...you can specify a segment and offset or just offset.
- byte...a value less than 256 decimal.
- string...a set of ascii letters in quotes (ex: "str").

The values that are required for the above fields can also be
specified in different ways. They can be hex constants, register
names or symbolic names (provided a symbol file has been read).
Values can also be formed using the binary operators +,-,* and /
(precedence is left to right).

Below are few examples using the Display command.

- d ds:100
- d ds:MAIN
- d es-1:
- d bp+si

There is extensive online help facility on all the commands.
Refer to it (pressing FK1) to get the details on individual
commands.


Symbol File Format:

Debugging in hexadecimal is not only dreary but also tends to
waste development time. Searching for particular procedures is
time that you waste and does not bring you any closer to finding
your bugs. This difficulty is greatly alleviated if you can debug
using symbolic variables...and this is exactly what bXd allows
you to do. It gets the variable/address information from files
generated by program linkers and supports two different types.


- The first is a file having the same name as the program
but with the extension SYM. For example, if the program
name is PROG.EXE, then the symbol file associated with it
would be PROG.SYM.

The format of the file is lines consisting of hex
constants, space and the ascii symbolic name associated
with it. Below is such an example. Note that underscore
and dollar characters are valid.

034F nmi_
03C7 wrt_reg
04DB continue
046C wrt$hex

- The second format is the file that is generated by the MS
linker and assumes the file extension MAP. This will be
of use to many users because this linker comes free with
your DOS disk and is used by many compilers and
assemblers.

The format if the map file is very important and this
version has been tested with MASM 4.0. For the debugger
to differentiate between data and code variables, you
must put the variables in their proper class (code or
data). The name of the segment is not important, but the
class is. If the class is 'code','rom' or 'static' it is
considered to be a code segment, else data.
Classes are set when you define a segment. For example to
define a code segment you would write.

codeseg segment 'code'

bXd will try to load a file of the SYM format file first. If that
is not found then it tries the MAP format file. Symbols are
stored dynamically...therefore you can store in excess of a
thousand variables.


End Note to all Users:

I hope that this document and more importantly the bXd program
will be of help to you and other PC users. This version has been
tested thoroughly (a major portion of bXd was debugged with bXd)
and right now I feel that it is bugfree. But if someone does find
one or has suggestions for improvements, let me know.

Thank you for taking an interest in this product and until the
next release of bXd3...keep spreading the good word about bXd.

[SGG 08/21/87]