===============================================================================
                          Ladybug version 1.02
===============================================================================

-------------------------------------------------------------------------------
1. Introduction                               

Derived from Morten Welinder's Sally Full Screen Debugger version 0.91a,
Ladybug is an alternative tool for debugging 32-bit programs running under
go32.

Ladybug and this manual are distributed under the terms of the 
GNU General Public License as specified in the files "fullscr.c" and 
"copying".  You should have received a copy of the GNU General Public 
License together with Ladybug.

Ladybug comes with absolutely no warranty, expressed or implied.
Use it at your own risk.  If you discover any bugs in Ladybug,
please report them to:

        Long Doan
        ld@netrix.com

**** IMPORTANT ******
If the target program being debugged includes a file with a .sym extension,
please read sections 2 and 3.

-------------------------------------------------------------------------------
1.1 Hardware

Ladybug has been tested under the following conditions only, but I
expect no problems in other environments except as noted below:

  - Cpu:
    + 486 DX2 66
    + 386 SX (without fpu, with or without emulator.)
  - Display:
    + Color SVGA card/monitor, text mode.
    + CGA card, Yellow/Black CGA monitor.
    + VT100 terminals
    + HP Apollo Workstation's display
    + Sun SparcStation 5's display
  - Remote debugging terminals:
    + VT100
    + PC's emulators (Procomm Plus, Telemate)
    + HP Apollo's emulator (emt)
    + Sun SparcStation 5's emulator (tip)
  - Memory mode:
    + Vcpi mode of the extender.
    + Raw mode.
    + XMS mode.

Ladybug has also been tested on programs of various sizes, from
a few KB in size (with no symbols) to programs over 10MB in size (with
more than 15000 symbols).

Some features of Ladybug are NOT DPMI (DOS Protected Mode Interface)
compatible and should not be used under DPMI. 

-------------------------------------------------------------------------------
1.2 Display modes

Ladybug works with all text modes having at least 80 columns and 24
rows.  ANSI.SYS is not required to run Ladybug, because Ladybug
writes directly to video memory, and therefore does not work in graphic
modes.  The go32 -topline option should not be used when running the
debugger because then the display will not look pretty.

-------------------------------------------------------------------------------
1.3 Installation

NOTE: $DJGPP means your djgpp directory, for example, C:\DJGPP.

  - In the $DJGPP directory, unzip the file ldgb100.zip, like so:
    (for pkzip, the invocation is pkunzip -d -o ldbg100).  Be sure
    your unzip utility preserves the directory information stored
    in the zip file.

  - Copy the files ladybug and ladydpmi from $DJGPP/go32/fs to
    $DJGPP/bin.

  - IMPORTANT: If this is the FIRST time you are using Ladybug version
    1.00, make sure that you read Sections 2 and 3 of this document
    before continuing!!!!

  - After setting up the LDBG environment variable (as outlined in
    Sections 2 and 3), reboot your computer.

2. Environment

Ladybug uses a environment variable named LDBG.  The syntax for
setting this environment variable is as follows:

set LDBG=value [value ...]

where value can be one of:

value                 meaning
---------------------------------------------------------------
oldgo32               The current go32 does not support remote
                      debugging.  Don't check for the remote
                      debugging command line switch.
remote <com_num>      Use com port number <com_num> to do remote
                      debugging.  <com_num> is a number from 1 to 4.
sympath <path>        Use <path> as the path to the symbol file.
                      The default path is the path to the program
                      being debugged.
symname <name>        Use <name> for symbol file.  The default is
                      the name of the program being debugged.
symext <ext>          Use <ext> as symbol file's extension. 
                      The default extension is ".sym".
startup <file>        Use the startup file <file>. The default is
                      /go32/ldbg.rc

The syntax in the startup file:
  keyword switch value [switch value...]
Where keyword can be:

#            Beginning of a comment, must be at the beginning of a
             line.
bre          Breakpoint.
reg          Debug register.
pa           Perfomance Analyzer settings.
pane         Pane infomation.
 
  Syntax for breakpoint:
  bre -class <class> -type <type> -at <addr> -length <len> [-count
      <count>] [-condition <cond>]
  Where:
  class  (normal, count_down, conditional) is the class of the
         breakpoint.
  type   (code, data_write, data_read) is the type of the breakpoint.
  addr   (expression with no white space) is the location of the
         breakpoint.
  len    (1, 2, 4) is the length of the breakpoint.
  count  (number) is the countdown number (only used for count_down
         breakpoints.)
  cond   (expression) is the condition for the breakpoint. It MUST be
         at the end of the line.

  Syntax for registers:
  reg -number <regnum> -value <exp>
  Where:
  regnum (0..A..Z..a..z) is the register to be used.
  exp    (expression) is the value to be stored to the register.

  Syntax for performace analyzer settings:
  Where:
  pa -start <exp> -stop <exp>
  exp    (expression) is the address of the beginning/ending of
         the area to be analyzed.

  Syntax for pane information:
  pane -toplines <num> -top_left_cols <num> -top_mid_cols <num>
       -bot_left_cols <num>
  Where:
  num    Number of rows/columns to be used for each region.

NOTE: This is also the syntax in which the debugger's context is saved.

If you are not using a version of go32 that supports remote debugging
(the only known versions that do are 1.11maint5n and 1.12maint3)
or if you are not sure if your copy of go32 supports this feature,
add the following into your autoexec.bat file:

  set LDBG=oldgo32

If you wish to do remote debugging with LDBG set to oldgo32, then
add the following to your autoexec.bat file:

  set LDBG=oldgo32 remote <com_num>

where <com_num> is the com port number as described above.

EXAMPLE:

  set LDBG=oldgo32 sympath /djgpp/syms symext sym

which tells Ladybug to use the file

  /djgpp/syms/<program_name>.sym

as the symbol file for

  <program_name>.<whatever>

-------------------------------------------------------------------------------
3. Symbol file

In order to conserve memory, Ladybug stores symbol information in
a .sym file and reads from the file as necessary.  The name of the
file is the same as the name of the program being debugged,
e.g. program.exe will typically accompany a program.sym file 
which contains symbol information.

Ladybug uses timestamp and size information in order to determine if
the .sym file contains the actual symbol information belonging to the
target program being debugged.  However, Ladybug WILL be fooled if
the number of symbols in the target program corresponds to the
number of symbols in the .sym file AND the timestamp of the program
file corresponds to the information stored in the .sym file.  This
is unlikely, but be careful when "touching" the program file.  To
be safe, delete the .sym file every time you recompile.

If reading the symbol file takes too long, defragment the file and
restart Ladybug.

To change the symbol file name, see Section 2 above.

Any file (other than the symbol file itself) that has the same path,
name, and extension as the symbol file WILL be OVERWRITTEN,
therefore it is probably a good idea to set the symbol path to a
seperate symbol directory (like /djgpp/syms) as outlined in Section 2
above.

Ladybug will not delete the symbol file for you.  If you need more
disk space, delete it yourself.

-------------------------------------------------------------------------------
4. New features (new with respect to fsdb091a):
 - Help and Module panes.
 - Remote debugging support, as follows:
     go32 -d ladybug -<device> <program> [args]
     where <device> is one of the following:
         com_one
         com_two
         com_three
         com_four
     or, inside Ladybug, choose <File><Redirect IO> and then
     enter the device name.  The device name can be one of the
     devices above, or it can be
         con
     for local debugging mode.
   (Note that the command line options override
   environment variable settings.)
 - Menus and dialog boxes to simplify user input.
 - External data structure support (activated through the Data pane)
   to allow users to display data in customized format.
     This feature is application-specific, and xsupport.c must be 
     implemented according to the project being debugged.
 - Program animation (running by continuously single-stepping
   at a user-specified speed).
 - Performance analyzer.
 - Access to PC IO ports.
 - Resizable panes/screens.
 - 80387/emulation checking to prevent the user from accessing
   a non-existent 80387 via the NPX pane.
 - Ability to save/load the debugger context, including breakpoints
   and other settings.
 - Address registers for placing "bookmarks" in code or data.
 - A minibuffer for input/output not requiring dialogue boxes.
 - Undo commands.
 - Horizontal scrolling within panes.
 - Memory search.

===============================================================================
5. Enhancements
 - Conditional/count-down data and code breakpoints.
 - New expression parser that allows the use of parentheses and
   memory references.
 - New background and colors (in color mode only!)
 - The active window is now highlighed by a double frame (in local mode)
   and by a different type of frame in remote mode..
 - Less memory usage.

===============================================================================
6. Key bindings

 Since this version of Ladybug is primarily intended
 for use by those whose primary operating system experience
 is with unix, the key bindings have been redefined to
 closely correspond with Gnu Emacs key bindings.  Emacs is
 an editor which is commonly used on unix systems.

 An initial attempt was made to use keystrokes from the
 more-prevalent vi editor, but the resulting interface
 was cumbersome.  It quickly became clear that Emacs was
 better suited to the job.  Thus is the vi/emacs war
 perpetuated.

KEY ABBREVIATIONS USED IN THIS DOCUMENT:

 C      when used as a hyphenated prefix, is the control.
        key.  "C-c" means to press the control key
        simultaneously with the "c" key.
 M      when used as a hyphenated prefix, is the meta key.
        Currently, M is the same as ESC (the Escape key).
        "M-c" means to press the meta key followed by the
        "c" key.
 S      when used as a hyphenated prefix, is the shift key.
        "S-c" means to press the shift key simultaneously
        with the "c" key.
 ESC    is the escape key.
 CR     is the return key.
 TAB    is the tab key.
 DEL    is the delete key.
 BS     is the backspace key.
 LT     is the left arrow key.
 RT     is the right arrow key.
 UP     is the up arrow key.
 DN     is the down arrow key.
 PGUP   is the page up key.
 PGDN   is the page down key.
 HOME   is the home key.
 END    is the end key.

 <n>    denotes any string of numerals.
 <x>    denotes a hexadecimal number, i.e. a string of
        numerals prefixed with 0x.
 <c>    denotes one character.
 <sym>  denotes any string of alphanumeric characters
 <exp>  denotes any C expression, with limitations, as
        specified in the manual section on expressions.

GENERAL NOTES:
 C-c  is used to prefix commands which would change the
      debugger state beyond the reach of an easy undo
      command (and sometimes beyond any possible undo).

DEFINITIONS OF USER INTERFACE ELEMENTS:

 Window        General term for a user interface element.
 Menu          Horizontal list of user-selectable items.
 Pulldown      Vertical list of user-selectable items.
 Pane          Window in which user input is possible but
               not required.
 Dialog Box    Window requiring user input.
 Minibuffer    One-line window used for user input and
               debugger status messages.

----------------------------------------------------------
GLOBAL KEY BINDINGS:

 C-x C-c     Quit debugger.  You will be prompted first.
 C-x C-v     Save or load debugger context.
 C-r         Run program.
 C-h         Make Help pane active.
 BS          Make Help pane active.
 C-x C-w     Write active pane contents to a file.  Only
             the visible portion of the pane is saved.
 C-x C-f     Display contents of log file.
 C-x m       Toggle between color/monochrome mode.
 C-x C-e     Evaluate an expression and display result
             in the minibuffer.
 C-z         Show program output.  Press any key to return
             to the debugger.
 C-l         Redraw the screen.
 ESC C-p <c> Goto pane whose name begins with <c>.
 C-x C-o     Toggle between insert/overstrike mode.

----------------------------------------------------------
MAIN MENU:

 ESC ESC     Quit main menu, go to previously active pane.
 C-g         Quit main menu, go to previously active pane.
 f           Select File pulldown.
 p           Select Pane pulldown.
 l           Select Local pulldown.
 m           Select Miscellaneous pulldown.
 h           Select Help pulldown.
 CR          Select pulldown of highlighted choice.
 DN          Select pulldown of highlighted choice.
 C-n         Select pulldown of highlighted choice.
 C-f         Highlight next choice on main menu.
 TAB         Highlight next choice on main menu.
 RT          Highlight next choice on main menu.
 C-b         Highlight previous choice on main menu.
 S-TAB       Highlight previous choice on main menu.
 LT          Highlight previous choice on main menu.

----------------------------------------------------------
PULLDOWNS:

 ESC ESC     Go to main menu.
 CR          Select currently highlighted pulldown item.
 C-n         Highlight next pulldown item.
 DN          Highlight next pulldown item.
 C-p         Highlight previous pulldown item.
 UP          Highlight previous pulldown item.
 C-f         Show pulldown of next main menu choice.
 RT          Show pulldown of next main menu choice.
 TAB         Show pulldown of next main menu choice.
 C-b         Show pulldown of previous main menu choice.
 LT          Show pulldown of previous main menu choice.
 S-TAB       Show pulldown of previous main menu choice.
 
----------------------------------------------------------
PANES:

 ESC ESC     Go to main menu.
 C-x o       Go forward one pane.
 TAB         Go forward one pane.
 S-TAB       Go backward one pane.
 C-x C-x     Go to previous pane (and again to return).
 C-x ^       Make current pane taller by one line.
 C-x }       Make current pane wider by one line.
 C-x >       Scroll text right (show more of the left).
 C-x <       Scroll text left (show more of the right).
 C-f         Move forward one line/byte/halfword/fullword.
 RT          Move forward one line/byte/halfword/fullword.
 C-b         Move backward one line/byte/halfword/fullword.
 LT          Move backward one line/byte/halfword/fullword.
 C-n         Move forward one line.
 DN          Move forward one line.
 C-p         Move backward one line.
 UP          Move backward one line.
 C-v         Move forward one page.
 PGDN        Move forward one page.
 M-v         Move backward one page.
 PGUP        Move backward one page.
 M-<         Move to beginning of pane.
 HOME        Move to beginning of pane.
 M->         Move to end of pane.
 END         Move to end of pane.

----------------------------------------------------------
DIALOG BOXES:

 ESC ESC     Quit dialog box and discard any changes.
 C-g         Quit dialog box and discard any changes.
 TAB         Move to next field, if applicable.
 C-n         Move to next field, if applicable.
 DN          Move to next field, if applicable.
 S-TAB       Move to previous field, if applicable.
 C-p         Move to previous field, if applicable.
 UP          Move to previous field, if applicable.
 CR          Select highlighted item, if applicable.
 C-f         Move forward one character, if applicable.
 RT          Move forward one character, if applicable.
 C-b         Move backward one character, if applicable.
 LT          Move backward one character, if applicable.
 DEL         Delete character left of cursor.
 C-d         Delete character under cursor.
 CR          Accept input and
               - go to next field (if not on a button), or
               - take action specified by button.

----------------------------------------------------------
MINBUFFER:

 ESC ESC     Quit minibuffer and discard any changes.
 C-g         Quit minibuffer and discard any changes.
 C-f         Move forward one character, if applicable.
 RT          Move forward one character, if applicable.
 C-b         Move backward one character, if applicable.
 LT          Move backward one character, if applicable.
 DEL         Delete character left of cursor.
 C-d         Delete character under cursor.
 CR          Accept input.

==========================================================
 PANE-SPECIFIC HELP
==========================================================
----------------------------------------------------------
HELP PANE:

 CR          Make code pane active.
 C-g         Make code pane active.

----------------------------------------------------------
CODE PANE:

 s           Single step, stepping over function calls.
 S           Single step, stepping into function calls.
 C-c a       Animate - run program by single stepping at
             a user-specified speed.
 b           Toggle breakpoint on/off at current location.
 e           Edit breakpoint via dialog box.
             Breakpoint particulars are:
               Address   - breakpoint location.
               Type      - 0 == Code breakpoint.
                           1 == Data write breakpoint.
                           2 == Data read breakpoint.
               Class     - 0 == Always enabled.
                           1 == Breakpoint enabled only after
                                being reached <count> times.
                           2 == Breakpoint enabled only after
                                <condition> is true (nonzero).
               Count     - Number of hits before a class 1
                           breakpoint activates.
               Condition - Condition to be met before a
                           class 2 breakpoint activates.
                           The condition can be almost any
                           C expression.  For more info on
                           allowable expressions, see the
                           manual section on expressions.
                           Two examples are:
_Odd_num >> 3 == 1 && (_Even_num >> _Shift_val || _Test)
(([%esi + %eax * 4] & 0x5fff) >> 12) & 0x0f == 4
               Size      - The Size parameter allows you
                           to specify the maximum size to
                           be used during evaluation of
                           expressions.
 C-c t       Trace to current address.  Same as toggling
             breakpoint, then running program.
 <n> CR      Disassemble and display memory at specified
             decimal address.
 <x> CR      Disassemble and display memory at specified
             hexadecimal address.
 _<sym> CR   Disassemble and display memory at address
             specified by symbol <sym>.
 %<sym> CR   Disassemble and display memory at address
             specified by value in register denoted by
             symbol <sym>.
 <exp> CR    Disassemble and display memory at address
             specified by value of expression <exp>.
 i           Disassemble and display memory at address
             specified by EIP (current run location).
 C-c i       Set EIP to address of currently highlighted
             instruction.
 p           Modify performance analyzer settings.
 C-c p       Start performance analyzer and run program
             (if performance analyzer timer has been set).
 M-b         Move pane's origin left by one byte.
 M-f         Move pane's origin right by one byte.
 C-x / <c>   Save highlighted location in debugger code
             pane register <c>.
 C-x j <c>   Disassemble and display memory at location
             saved in debugger code pane register <c>.

----------------------------------------------------------
DATA PANE:

 w           Toggle data write breakpoint on/off.
 r           Toggle data read/write breakpoint on/off.
 e           Edit data read or read/write breakpoint.
             Breakpoint particulars are:
               Address   - breakpoint location.
               Type      - 0 == Code breakpoint.
                           1 == Data write breakpoint.
                           2 == Data read breakpoint.
               Class     - 0 == Always enabled.
                           1 == Breakpoint enabled only after
                                being reached <count> times.
                           2 == Breakpoint enabled only after
                                <condition> is true (nonzero).
               Count     - Number of hits before a class 1
                           breakpoint activates.
               Condition - Condition to be met before a
                           class 2 breakpoint activates.
                           The condition can be almost any
                           C expression.  For more info on
                           allowable expressions, see the
                           manual section on expressions.
                           Two examples are:
_Odd_num >> 3 == 1 && (_Even_num >> _Shift_val || _Test)
(([%esi + %eax * 4] & 0x5fff) >> 12) & 0x0f == 4
               Size      - The Size parameter allows you
                           to specify the maximum size to
                           be used during evaluation of
                           expressions.
 b           Display data in byte format.
 h           Display data in halfword (two byte) format.
 f           Display data in fullword (four byte) format.
 <n> CR      Display memory at specified decimal address.
 <x> CR      Display memory at specified hexadecimal
             address.
 _<sym> CR   Display memory at address specified by
             symbol <sym>.
 %<sym> CR   Display memory at address specified by value
             in register denoted by symbol <sym>.
 <exp> CR    Display memory at address specified by value
             of expression <exp>.
 i           Display memory at address specified by EIP
             (current run location).
 s           Display memory at address specified by ESP
             (current stack pointer).
 *           Dereference currently highlighted value.
 @           Retrace steps after a '*' command.  Up to
             five (5) steps back are allowed.
 n           Display data in customized format.
 p           Input/output from/to ports as follows:
               Size - 1 = byte, 2 = word, 3 = dword
               Port - port to access
               Data - data to write
               <In>  button - input from port
               <Out> button - output to port
 M-b         Move pane's origin left by one byte.
 M-f         Move pane's origin right by one byte.
 C-c m       Modify memory at cursor.
 C-c u       Undo last memory modification.  No more than
             five (5) modifications can be undone.
 C-c s       Search memory.
 C-x / <c>   Save highlighted location in debugger data
             pane register <c>.
 C-x j <c>   Display memory at location saved in
             debugger data pane register <c>.

----------------------------------------------------------
REGISTERS PANE:

 C-c m       Modify register at cursor.
 C-c u       Undo last register modification.  No more
             than five (5) modifications can be undone.

----------------------------------------------------------
FLAGS PANE:

 All commands accessed via local menu.

----------------------------------------------------------
BREAKPOINT PANE:

 CR          Goto location of currently highlighted
             breakpoint, in code or data pane, as
             appropriate.
 DEL         Delete currently highlighted breakpoint.
 C-d         Delete currently highlighted breakpoint.
 C-e         Edit currently highlighted breakpoint.
 C-k         Delete from currently highlighted breakpoint
             up to the last breakpoint.
 C-y         Restore from previous deletion.  No more
             than five (5) deletions can be undone.

----------------------------------------------------------
WHEREIS PANE:

 CR          Display data/code at address represented by
             currently highlighted symbol.
 _<sym> CR   Find <sym> in symbol table
             Permissible wildcards are:
               ? - Matches one character
               * - Matches any number of characters

----------------------------------------------------------
MODULE PANE:

 CR          Prompt for a line number, disassemble and
             display code at that location.

----------------------------------------------------------
NPX PANE: 

 C-c e       Empty register.    
 C-c n       Negate register contents.
 C-c z       Zero register.
 C-c m       Modify register contents.
 C-c u       Undo last register modification.  No more
             than five (5) modifications can be undone.

----------------------------------------------------------
PERFORMANCE ANALYZER DATA VIEWER:

 C-x C-w     Log performance analyzer results to file.

----------------------------------------------------------
STACK PANE:

 CR          Select highlighted location and display
             in data pane.

----------------------------------------------------------
INFO PANE:

 No commands available.

==========================================================
SYNTAX AND VALUES
==========================================================
----------------------------------------------------------
C EXPRESSIONS ALLOWED:

   Syntax:
     <expr>  = <l_exp> [<l_op> <l_exp> ...]
     <l_exp> = <a_exp> [<r_op> <a_exp> ...] | 
               (<l_exp>) | !<l_exp>
     <a_exp> = <a_exp>|<identifier> [<a_op> 
               <a_exp>|<identifier> ...] | (<a_exp>)
     <identifier> = <identifier> | <[<a_exp>]><size>
   where
     <l_exp>      is a logical expression.
     <l_op>       is one of: && ||
     <a_exp>      is an arithmetic expression
     <r_op>       is one of: < <= == != >= >
     <a_op>       is one of: + - * / >> << & | ! ~
     <identifier> is an identifiler (a symbol, register) 
                  a [decimal | hexidecimal | octal] number,
                  or a memory reference.

     * <identifier> can be a global variable name,
       symbolic constant, constant value, register name,
       or memory reference (i.e. an expression which
       evaluates to a memory location).
     * All register names must begin with a '%' (percent) 
       character. 
     * All memory references have the structure: 
         [<address expression>]size 
       where size can be b, h, f, or nothing.
       b: 1 byte. h: 2 bytes. f: 4 bytes. Any other
       character immediately following the right square 
       bracket (]) and is not one of the above characters
       will be interpreted as part of the expression.
       By default (if neither b, h, or f follows the
       right square bracket,) the reference will read
       4 bytes from memory.
     * When constructing expressions, be aware that
       the modulo (%) operator is not allowed, since
       it conficts with the register naming scheme.
       To perform a modulo, use divide (/) and
       subtract (-): (a % b) == (a - a / b)
     * When constructing expressions, be wary
       of possible overflow (the debugger uses
       32 bit arithmetic to evaluate expressions).

   Examples of valid expressions: 

     _Odd_num >> 3 == 1 && (_Even_num >> _Shift_val || _Test)
     (([%esi + %eax * 4] & 0x5fff) >> 12) & 0x0f == 4

----------------------------------------------------------
REMOTE DEBUGGING DEVICES
  
    con       : console. 
    com_one   : COM1. 
    com_two   : COM2. 
    com_three : COM3. 
    com_four  : COM4. 

-------------------------------------------------------------------------------
7. Rebuilding instructions:

  In the same directory as the source files, type "make", or whatever
  your make utility name is.

8. Troubleshooting

  8.1 The debugger appears to hang when startup (but numlock/caplock
      still works.)

      Solution:
        1. Try adding "oldgo32" (without the quotation marks) to your
           ldbg environment variable.

  8.2 The debugger is slow

      Solution:
        1. Defrag your hard drive.
        2. Use a disk cache.

  8.3 The debugger displays wrong/mismatched symbols

      Solution:

        1. Delete the symbol file (see section 3) and restart the
           debugger.
===============================================================================

