World of Shareware - Software Farm 2/wosw_2.zip/wosw_2/CPROG/BXD26.ZIP/BXD2.DOC

Text File | 1989-05-28 | 15KB | 374 lines

            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] [<userCON.txt]

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 <cntrl-PgUp> and <cntrl-PgDn> 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]