               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.

   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.

