GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


archive:programming:softice.manual

CHAPTER 1 - Introduction

   01.01 Product Description
   01.02 Using This Manual
   01.03 System Requirements

01.01 Product Description

   Soft-ICE is a software debugging tool that provides hardware-level
   debugging capabilities to PCDOS and MSDOS debuggers.
   Soft-ICE uses 80386 protected mode to run DOS in a virtual machine.
   This gives Soft-ICE complete control of the DOS environment. Soft-ICE
   uses 80386 protected mode features, such as paging, I/O privilege
   level, and break point registers, to add hardware-level break points
   your existing DOS debugger.
   Soft-ICE was designed with three goals in mind:
  • To utilize the 80386 virtual machine capability to debugging

features that are impossible or prohibitively slow with

        software-only debuggers (e.g., real time hardware-level break
        points, memory protection, breaking out of hung programs, etc.).
      * To work with existing debuggers. We wanted to provide a tool that
        worked with existing tools. We designed Soft-ICE in such a way
        that you don't have to learn a new debugger to get powerful
        hardware debugging capabilities.
      * To be a user-friendly program with a window that pops up
        instantly and does not get in the way. All of the Soft-ICE
        commands were designed to fit in a small window so that
        information on the screen behind Soft-ICE could still be viewed.
        Dynamic on-line help assists users who only use Soft-ICE
        occasionally.
   The Soft-ICE program features:
  • real time break points on memory reads/writes, port reads/writes,

memory ranges, and interrupts

  • back trace history ranges
  • symbolic and source level debugging
  • an environment that works with existing debuggers
  • full EMM 4.0 support
  • backfilling to raise base memory past 640K for monochrome systems
  • a window that can pop up at any time
  • the ability to break out by keystroke even if interrupts are

disabled

  • debugger code that is isolated by 80386 protected mode. This

prevents an errant program from modifying or destroying Soft-ICE;

        even if DOS clobbered, Soft-ICE will still work
      * the ability to configure Soft-ICE to use no memory in the lower
        640K if the system has more than 640K
      * user-friendly dynamic help
      * the ability to be used as a stand-alone debugger. This ability is
        useful if you are debugging loadable device drivers, interrupt
        handlers, or boot sequences where traditional debuggers can't go,
        if your debugger suffers from re-entrancy problems
      * a soft boot capability that allows debugging with non-DOS
        operating systems or self-booting programs
      * a simple installation, with no DIP switches to set no I/O ports
        taken up, and no memory address space conflicts
   NOTE : Soft-ICE will work with real address mode programs only. It
   will not work with programs that use 80286 or 80386 protected mode
   instructions.

01.02 Using This Manual

   The Soft-ICE manual is divided into four main sections:
  • Learning Soft-ICE (Section I)
  • Commands (Section II)
  • Support Features (Section lII)
  • Advanced Topics (Section IV)
   Soft-ICE can be used for most debugging problems after reading Section
   I, Learning Soft-ICE, and a little experimentation. Soft-ICE's
   user-friendly on-line help can be used to reference command
   descriptions and syntax.
   The Learning Soft-ICE section contains installation instructions, a
   description of the user interface, and a tutorial. The tutorial is
   designed to get you up and running quickly.
   The Commands section describes all of the Soft-ICE commands. The
   command descriptions are organized by functional group with an
   alphabetic index for reference.
   The Support Features section covers advanced loading options, symbolic
   and source level debugging, and EMM 4.0 capability.
   The Advanced Topics section covers topics such as using Soft-ICE with
   DOS loadable drivers and using Soft-ICE with non-DOS operating
   systems.
   Throughout the manual, especially in the tutorial and the command
   section, examples are given that require you to give data to Soft-ICE.
   When the directions specify that you "press" a key, such as the key,
   you should press the key labelled. When the directions tell you to
   "enter" a phrase, such as WIN, you should type in the specified
   letters, then press the ENTER key.

01.03 System Requirements

   Soft-ICE works with the IBM Series II Model 70 and 80, Compaq 80386
   and 80386SX computers, AT compatible and 80386 co-processor cards.
   Soft-ICE will only work with 80386 XT co-processors if they are AT
   compatible.
   Soft-ICE works best with extended memory, but works fine with
   conventional memory systems.
   Soft-ICE does not use DOS or ROM BIOS for its video output and
   keystroke input. Therefore the video must be compatible with one of
   the following: MDA, Hercules, CGA, EGA, or VGA. Soft-ICE also has
   support for a two- monitor configuration, which can be very helpful
   when debugging video- intensive programs.

CHAPTER 2 - Getting Started

   02.01 The Diskettes
   02.02 Loading Soft-ICE
   02.02.01 Loading Without Extended Memory
   02.02.02 Loading With Extended Memory
   02.02.03 Configuring Soft-ICE for a Customized Installation
   02.03 Unloading Soft-ICE
   02.04 Reloading Soft-ICE

02.01 The Diskettes

   Soft-ICE comes on either a 5 1/4" diskette or a 3 1/2" diskette.
   When you run Soft-ICE, the name of the person that your copy of
   Soft-ICE is licensed to is displayed on the screen as a deterrent to
   software pirates. The Soft-ICE diskette is not physically
   copy-protected for your convenience. For our convenience, we
   appreciate your high regard for our licensing agreement. It is
   important to make a duplicate copy to be used only for backup in case
   the original diskette is damaged.
   A directory of a Soft-ICE diskette will show the following files:
    S-ICE.EXE    is the Soft-ICE program.
    S-ICE.DAT    is the Soft-ICE initialization file.
    LDR.EXE      is the Soft-ICE program and symbol file loader.
    MSYM.EXE     is the Soft-ICE symbol file creation program.
    EMMSETUP.EXE is a program that allows you to customize the way your
                 system uses expanded memory.
    UPTIME.EXE   sets the time to that of the real time clock.
    README.SI    is a text file containing information about Soft-ICE
                 that did not make it into this manual.
    SAMPLE.EXE   is a short demonstration program that is used with the
                 tutorial.
    SAMPLE.ASM   is the assembly language source file for the
                 demonstration program.
    SAMPLE.SYM   is the symbol file for the demonstration program.

02.02 Loading Soft-ICE

   Before running Soft-ICE, copy all of the files on the distribution
   diskette to your hard disk.
   These files should be placed in a directory that is accessible through
   your alternate path list.
   S-ICE.EXE can be loaded as a device driver in CONFIG.SYS or can be run
   as a program from the command line. To use many of Soft-ICE's
   features, S- ICE.EXE must be loaded as a device driver in CONFIG.SYS.
   Note : If you do not have extended memory, Soft-ICE can NOT loaded as
   a device driver. Instead, it must be run from the DOS prompt.

02.02.01 Loading Without Extended Memory

   When no extended memory is present, Soft-ICE loads it at the highest
   memory location possible. The memory used by Soft-ICE is then 'mapped
   out', making it invisible to DOS programs. Since the total memory
   visible to DOS its programs is less after Soft-ICE loads, it is
   recommended that you load Soft-ICE before any TSR's or control
   programs.
   If you do not have extended memory, simply enter: S-ICE

02.02.02 Loading With Extended Memory

   Loading Soft-ICE with extended memory can be done in one of two ways:
   1. Install S-ICE,EXE as a driver in CONFIG,SYS, This method is
   necessary if you will be using one the following capabilities:
  • Sharing memory with program that use extended memory by using ROM

BIOS calls (VDISK.SYS, RAMDRIVE.SYS, HIMEM.SYS, cache programs,

        etc.)
      * Using Soft-ICE's EMM 4,0 capability,
      * Using Soft-ICE for symbolic or source level debugging.
      * Using back trace ranges.
      * Using Soft-ICE with other Nu-Mega products such as Magic CV.
   When loaded as a driver, Soft-ICE allocates a portion of extended
   memory for itself and its associated components so there can be no
   memory conflicts. S-ICE.EXE must be loaded in CONFIG.SYS before any
   other driver that allocates extended memory is loaded (e.g.,
   VDISK.SYS, RAMDRIVE.SYS). Generally Soft-ICE works best if it is the
   first loadable device driver installed in CONFIG.SYS. For users that
   are new to Soft-ICE it is advisable to load Soft-ICE as the first
   driver in CONFIG.SYS with the following statement:
   device=drive:\path\S-ICE.EXE /SYM 50
   Drive and path specify the directory where S-ICE.EXE is located. This
   statement will load Soft-ICE at system initialization and will be
   adequate for the tutorial. However, Soft-ICE will not be installed for
   some of its more powerful features such as EMM 4.0. You can
   reconfigure Soft-ICE with those features enabled after you have
   experimented a bit. If you already have experience with Soft-ICE or
   would like to set up Soft-ICE with those features immediately, please
   read chapter 6 (Soft-ICE Initialization Options).
   Caution : When installing any new device driver for the first time on
   your system, it is advisable to have a boot diskette available This
   precautionary measure is for the unlikely event that The default setup
   of the device driver is not compatible with your system.
   If you are not sure how to edit your CONFIG.SYS file, refer to your
   system user's guide or your text editor user's guide for instructions.
   After you have modified your CONFIG.SYS file, you must reboot your
   system to have the changes take effect.
   2. Run Soft-ICE from the DOS Prompt by typing S-ICE. Before actually
   loading, Soft-ICE will display a loading message and prompt. To
   prevent this prompt, place the word EXTENDED in the S-ICE.DAT file.
   See section 6.4 for more information on the S-ICE.DAT file. Using this
   method, S-ICE.EXE is automatically loaded into the top of extended
   memory, whether or not anything else is already there. If you know you
   will not have any other programs using extended memory, this method is
   acceptable. When loaded with this method, Soft-ICE occupies ZERO bytes
   of conventional memory. The command you use is:
   S-ICE
   Notes : You can NOT enable all of Soft-ICE's features when Loading
   from the command line. If you will be using Soft-ICE as a stand-alone
   debugger, it is recommended to Load Soft-ICE from CONFIG.SYS.
   If you want to load Soft-ICE as a device driver, but don't want
   Soft-ICE to be resident all of the time, you should use the /UN
   loading switch. Refer to section 6.3.1 for more information.

02.02.03 Configuring Soft-ICE for a Customized Installation

   You can customize Soft-ICE with Soft-ICE loading switches in
   CONFIG.SYS and with the Soft-ICE initialization file S-ICE.DAT. The
   CONFIG.SYS loading switches allow you to customize how the extended
   memory will be reserved by Soft-ICE. The initialization file S-ICE.DAT
   allows you to specify configuration options, assign commands to
   function keys, and define an auto-start string. An auto-start string
   is used to execute a series of commands that you use every time you
   install Soft-ICE. for more information about customizing Soft-ICE,
   refer to chapter 6.

02.03 Unloading Soft-ICE

   Occasionally you may need to unload Soft-ICE. A typical reason for
   unloading Soft-ICE is to run a program that uses 80286 or 80386
   protected mode instructions. To unload Soft-ICE, enter:
   S-ICE /U
   This command places the machine back in real address mode. If Soft-ICE
   was initially loaded from CONFIG.SYS When the memory is still reserved
   for Soft-ICE and can not be used by other software. If Soft-ICE was
   initially loaded from the command line, unloading frees up the memory
   consumed by S- ICE.EXE.
   Caution : If you have any backfilled memory in your system, or if
   expanded memory is currently being used, unloading Soft-ICE could
   crash your system.

02.04 Reloading Soft-ICE

   Soft-ICE can be re-loaded at any time even if it had initially been
   loaded in CONFIG.SYS. If Soft-ICE had initially been loaded in
   CONFIG.SYS then the original configuration options (EMM 4.0, symbols
   and source...) are still in effect. To reload Soft-ICE, enter:
   S-ICE

CHAPTER 3 - Debugging In 30 Minutes

   03.01 Introduction
   03.02 Popping Up the Window
   03.03 Returning From the Window
   03.04 Changing the Window Size
   03.05 Moving the Window
   03.06 Line Editing Keystrokes
   03.07 Interactive Status Line
   03.08 Command Syntax
   03.08.01 Specifying Memory Addresses
   03.09 Function Keys
   03.10 Help
   03.11 Tutorial

03.01 Introduction

   All interaction with Soft-ICE takes place through a window that can be
   popped up at any time. All Soft-ICE commands fit in a small window,
   but the window can be enlarged to full screen. You will typically use
   the small window when using Soft-ICE as an assistant to another
   debugger, and the large window when using Soft-ICE in stand-alone
   mode.
   The window initially comes up in full screen mode if you are using the
   Soft-ICE configuration file (S-ICE DAT) that was included on the
   distribution diskette.

03.02 Popping Up the Window

   You can bring up the window at any time after installing Soft-ICE. You
   initially bring up Soft-ICE by pressing the CTRL D keys. However, this
   sequence can be changed by using the ALTKEY command (see section 5.8).

03.03 Returning From the Window

   Return to the original display by using the X command or the key
   sequence that you used to invoke Soft-ICE. Any break points that you
   set while working in Soft-ICE will be armed at this point.

03.04 Changing the Window Size

   You can modify both the width and the height of the Soft-ICE window.
   Changing the window size is particularly useful in stand-alone mode
   when you are displaying code memory.
   The window height can vary from 8 to 25 lines tall. To change the
   window height, use the following key sequences:
   ALT UP      : makes the window taller
   ALT DOWN    : makes the window shorter
   To change the window width, use the WIN command (see section 5.9).
   Entering WIN with no parameters toggles between the following two
   modes:
   WIDE mode   : full screen width
   NARROW mode : 46 characters wide
   Some commands (D, E, R, U) take advantage of the extra width by
   displaying more information when the window is in wide mode.

03.05 Moving the Window

   The Soft-ICE window is movable and can be positioned anywhere on the
   screen. This is particularly useful when the window is in narrow mode.
   Move the window anytime you need to view information on the screen
   behind the window. The following key sequences move the window:
   CTRL UP     : moves the window one row up
   CTRL DOWN   : moves the window one row down
   CTRL RIGHT  : moves the window one column right
   CTRL LEFT   : moves the window one column left

03.06 Line Editing Keystrokes

   Soft-ICE's easy-to-use line editor allows you to recall and edit
   previous commands. The line editor functions are similar to those of
   the popular CED line editor. The following key sequences help you edit
   commands in the command window :
   LEFT        : moves the cursor to the right
   RIGHT       : moves the cursor to the left
   INS         : toggles insert mode
   DEL         : deletes the current character
   HOME        : moves the cursor to start of the line
   END         : moves the cursor to the end of the line
   UP          : displays the previous command
   DOWN        : displays the next command
   SHIFT       : scroll one line up in display
   SHIFT       : scroll one line down in display
   PAGE UP     : scroll one page up in display
   PAGE DN     : scroll one page down in display
   BKSP        : deletes the previous character
   ESC         : cancels the current command
   There are special key assignments when the cursor is in the data
   window or the code window. These are described in the sections for the
   E and EC command respectively. One special assignment of note is the
   SHIFT UP and SHIFT DOWN keys while the cursor is in the code window.
   These keys are re-assigned so they have the functions that UP and DOWN
   normally have. This way you can recall previous commands while the
   cursor is in the code window.

03.07 Interactive Status Line

   A status line at the bottom of the window provides interactive help
   with command syntax.

03.08 Command Syntax

   Soft-ICE is a command-driven debugging tool. To interact with
   Soft-ICE, you enter commands, which can optionally be modified by
   parameters.
   All commands are text strings that are one to six characters in length
   and are case insensitive. AlI parameters are either ASCII strings or
   expressions.
   Expressions are typically numbers, but can also be combinations of
   numbers and operators (e.g., + - / *). All numbers are displayed in
   hexadecimal format. Byte parameters are 2 digits long, word parameters
   are 4, and double word parameters are 2 word parameters separated by a
   colon (:). Here are some examples of parameters:
   12          : byte parameter
   10FF        : word parameter
   E000:0100   : double word parameter
   Registers can be used in place of bytes or words in an expression. For
   example, the command 'U CS:IP-10' will start unassembling instructions
   ten bytes before the current instruction pointer address. The
   following register name may be used in an expression: AL, AH, AX, BL,
   BH, BX, CL, CH, CX, DL, DH, DX, DI, SI, BP, SP, IP, CS, DS, ES, SS, or
   FL

03.08.01 Specifying Memory Addresses

   Many Soft-ICE commands require memory addresses as parameters. A
   memory address is a value that is made of two 16-bit words, separated
   by a colon. The first word is the segment address, and the second word
   is the segment offset.
   Public symbols can be used in place of an address in any Soft-ICE
   command. The public symbols must have been loaded with the Soft-ICE
   program loader (LDR.EXE). See chapter 7 (Symbols and Source) for a
   complete description of using public symbols.
   The Soft-ICE expression evaluator recognizes several special
   characters in conjunction with addresses. These special characters
   are:
   $           : Current CS:IP.
   @address    : Double Word Indirection
   .number     : Source Line Number
   The $ character can be used in place of CS:IP when typing the address
   of the current instruction pointer.
   The @ character allows you to refer to the double word pointed to by
   the address. You can have multiple levels of @'s.
   If the . character precedes an address, the address will be
   interpreted as a source line number in the current file, rather than
   an actual address. This is only valid when source files are loaded.
   The address is interpreted as a decimal number in this case. Examples:
   U.1234      : This command starts unassembling instructions at source
                 line 1234 decimal.
   U $-10      : This command unassembles instructions starting 10 bytes
                 prior to the current instruction pointer.
   G @SS:SP    : Assume you are at the first instruction of an interrupt
                 routine. Entering this command will set a temporary break
                 point at the return address on the stack and skip the
                 interrupt routine.

03.09 Function Keys

   Function keys can be assigned to any command string that can be typed
   into Soft-ICE. Function keys can be assigned from the command line or
   pre-initialized through the Soft-ICE definition file S-ICE.DAT.
   The default S-ICE.DAT that comes on the Soft-ICE distribution diskette
   has definitions for all 12 function keys. You can change any of these
   definitions at any time. They are intended as examples, but they are
   designed to make easy for users of Microsoft's CodeView, Thee default
   assignments are:
   F1  : Displays general help                             "^H;"
   F2  : Toggles the register window                       "^WR;"
   F3  : Changes current source mode                       "^SRC;"
   F4  : Restores screen                                   "^RS;"
   F5  : Returns to your program                           "^X;"
   F6  : Toggles cursor between command window code window "^EC;"
   F7  : Goes to current cursor line                       "^HERE;"
   F8  : Single steps                                      "^T;"
   F9  : Sets break point at current cursor line           "^BPX;"
   F10 : Program steps                                     "^P;"
   F11 : Go to return address (large model)                "^G @SS:SP;"
   F12 : Displays Soft-ICE version number                  "^VER;"
   A caret (^) preceding a command makes it invisible, a semi-colon (;)
   following a command represents a carriage return. You can display the
   current function key assignments by entering the command:
   FKEY
   To use a function key simply press the function key instead of
   entering the command. To program function keys see section 5.8 for a
   description of the FKEY command, or chapter 6 for a description of
   pre-initializing function keys in S-ICE.DAT.

03.10 Help

   The help command displays a short description, a syntax expression,
   and an example of each command. To display help information, enter:
   ? or H : displays short descriptions of all commands and operators
   ? command or H command : displays more detailed information on the
                            specified command, syntax, and an example
   ? expression or H expression : displays the value of the expression
                                  in hexadecimal, decimal and ASCII

03.11 Tutorial

   The following tutorial demonstrates a few of the features Soft-ICE and
   gives you the opportunity to try using Soft-ICE. Soft-ICE can be used
   in conjunction with another debugger or as a stand-alone debugger. The
   tutorial demonstrates using Soft-ICE as an assistant to the DOS
   debugger, DEBUG, and then shows how Soft-ICE can be used as a
   stand-alone debugger with source and symbols loaded. DEBUG can be
   found on the PCDOS or MSDOS system diskette. If you do not have DEBUG,
   you can use another debugger in its place, or Soft-ICE can be used as
   a stand-alone debugger.
   Users who need to use Soft-ICE for a reverse engineering project, or
   for debugging DOS loadable device drivers or Terminate and Stay
   Resident programs should go through this tutorial too. Even though
   examples of these types of programs are not demonstrated directly, you
   will get an overview of debugging with Soft-ICE. It is recommended
   that you experiment with Soft-ICE and your particular environment
   before beginning a real project.
   A short assembly language program with a subtle flaw is used to
   demonstrate hardware-style break points. The sample program has been
   kept intentionally short and to-the-point for those not very familiar
   with assembly language. The tutorial is designed to give you a peek at
   Soft-ICE features. Feel free to experiment on your own after going
   through the tutorial.
   Since Soft-ICE is very flexible, it allows you to load in the way that
   is best for your system. Go through the installation procedures in
   section 2.2 before continuing with the tutorial.
   If you do not have extended memory on your system, you must load
   Soft-ICE from the command line. When loading Soft-ICE from the command
   line you can not load symbols or source files. In this case you must
   improvise in the last section of the tutorial where Soft-ICE is used
   as a stand-alone debugger.
   Soft-ICE can be loaded from the DOS prompt or loaded as a device
   driver in CONFIG.SYS. For the purpose of this tutorial you should
   install Soft-ICE in CONFIG.SYS with at least 50K of extended memory
   reserved for symbols and source files. Soft-ICE should be the first
   device driver installed in CONFIG.SYS. The device installation line
   should look like:
   DEVICE = drive: path\S -ICE.EXE /SYM 50
   The /SYM 50 parameter instructs Soft-ICE to reserve 50 kilobytes of
   extended memory for symbols and source file This is not enough to
   solve most real world problems, but will work for our sample program.
   You must re-boot your system after placing this line in CONFIG.SYS.
   When you re-boot your system Soft-ICE displays a copyright notice, a
   registration number, the name of the person who owns this copy of
   Soft-ICE, and the amount a extended memory reserved for each Soft-ICE
   component. On a system with 384K of extended memory the initial screen
   looks like:
    Soft-ICE Exact /Out Rage Pirates Registration # SI123456
    (C) Nu-Mega Technologies 1987-1989 All Rights Reserved.
    Soft-ICE Version 2.00
    Soft-ICE is loaded from 00132000H up to 00160000H.
    50K of symbol space reserved.
    10K of back trace space reserved.
    200 K of extended memory available.
   The "Soft-ICE is loaded ..." message tells you the exact area of
   memory that Soft-ICE and its components are occupying. If you are on a
   Compaq or Compaq clone and have included the word COMPAQ in your
   S-ICE.DAT file you would also see a message saying "Using high memory
   from XXXXXXXX to 00FE0000H".
   The next line tells you how much symbol space has been reserved. This
   space is used for both symbols and source files.
   The next line tells you how much memory has been reserved for back
   trace history. This amount defaults to 10K. This memory area is used
   by the SNAP command and the BPR command with the T or TW options.
   The last line tells you how much memory is left for regular extended
   memory. This memory can be used by other programs, such as HIMEM,
   SMARTDRIVE, VDISK, etc.
   Change directories to the hard drive directory where you loaded all
   the files from your distribution diskette. Remember, this directory
   must be accessible from your alternate path list.
   Before we get into heavy debugging, let's bring the Soft-ICE window up
   and give it a test drive. Clear the screen by entering : CLS and bring
   up the Soft-ICE window by pressing : CTRL D.
   The Soft-ICE window is now on the screen. If you have file S-ICE.DAT
   accessible from your path then the Soft-ICE window will occupy the
   entire screen. It will be divided into four sections. From top to
   bottom, these sections are the register window, the data window, the
   code window, and the command window. If S-ICE.DAT was not found then
   you will have a small window in the center of the screen. This also
   means that other components needed for the tutorial have not been
   loaded.
   If the small window is visible you should:
   1. Exit from Soft-ICE by entering X.
   2. Unload Soft-ICE by entering S-ICE /U.
   3. Copy the file S-ICE.DAT from the distribution diskette to a
   directory accessible from your current path.
   4. Restart the demo.
   We will now switch to the small window. The small window is very
   convenient for using Soft-ICE as an assistant to another debugger.
   Enter : WIN
   This will make a small command window in the center of the screen.
   Several Soft-ICE commands are visible on this screen. These are
   remnants of the initialization string in S-ICE.DAT that originally set
   up Soft-ICE in the full screen mode. You will notice a prompt symbol
   (:) and a status line at the bottom of the window.
   The Soft-ICE window can be moved around on the screen, and the window
   size can be adjusted. Move the window around the screen by pressing:
   CTRL UP     : moves the window one row up
   CTRL DOWN   : moves the window one row down
   CTRL RIGHT  : moves the window one column right
   CTRL LEFT   : moves the window one column left
   Change the window size so that it fills the whole screen by entering :
   WIN. You will notice that the original screen is back. Change back to
   the small window by entering WIN again. Make the window taller or
   shorter by pressing :
   ALT UP      : makes the window taller
   ALT DOWN    : makes the window shorter
   Now try what comes naturally when you're in front of a new program and
   you don't have the foggiest notion of what to do next, ask for help.
   Get a help display by entering : ?
   Notice how the display stops and waits for a keystroke before
   scrolling any information off the screen. Look at the status line at
   the bottom of the window. The status line displays the instructions:
   "Any Key To Continue, ESC to Cancel ". Now press any key to continue
   displaying more the help information. Continue pressing the key until
   the prompt (:) reappears.
   Scroll back through the help information by pressing : SHIFT.
   Previously displayed information in the command window can be scrolled
   with the shift up, shift down, page up and page down keys. Try a
   variety of these keys to scroll through the help information.
   The Soft-ICE help facility gives you an overview of each command. If
   you enter a question mark (?) followed by a command name, you see a
   display showing the command syntax, a short description of the
   command, and an example. Try experimenting with help by entering
   commands in this format: ? command.
   For example, ? ALTKEY. Pay attention to the status line prompts on the
   bottom line of the screen if you get confused.
   The help command also allows you to evaluate hexadecimal expressions.
   For example, enter : ? 10*2+42. The resulting display shows you the
   value of the expression, first in hexadecimal, then decimal, then in
   ASCII representation : 0062 00098 "b"
   We brought up the window with the CTRL D key sequence. That's all
   right for some, but you may prefer to use another key sequence. We are
   now going to enter a command to change the key sequence required to
   bring up the window. We'll do this one step at a time, so you can get
   used to the status line at the bottom of the window.
   Type the letter 'A'. The status line displays a list of all the
   commands starting with the letter 'A'. Finish typing the word
   'ALTKEY'. The status line now displays a short description of the
   /ALTKEY command Press the space bar. The status line now shows the
   required syntax for the /ALTKEY command. Type the letters 'ALT D' then
   press ENTER to enter the entire command : ALTKEY ALTD
   You just changed the window pop up key sequence to ALT D. From now on,
   you must press the ALT D key sequence to pop up the window. This is
   assumed throughout the remainder of the tutorial. Now let's test the
   previous command. To exit from the window, press : ALT D
   The Soft-ICE window just disappeared. To return to the Soft-ICE
   window, release the ALT key, then press: ALT D The window returned.
   To see some previous commands, press: the UP key a few times. Notice
   that Soft-ICE remembers commands that have been entered. Try editing
   one just for fun. Some of the editing keys are:
   INS         : toggles insert mode
   DEL         : deletes the current character
   HOME        : moves the cursor to start of the line
   END         : moves the cursor to the end of the line
   LEFT        : Moves the cursor one column to the right
   RIGHT       : Moves the cursor one column to the left
   When insert mode is on, notice that the cursor is in a block shape.
   Now that you are somewhat familiar with the environment let's try some
   more commands. Erase the command you were editing by pressing the HOME
   key, then pressing the DEL key until the command is gone. Enter : WR.
   The WR command makes the register window visible. The register window
   displays the contents of the 8086 registers. Notice that the register
   values reflect the location where the code was executing when you
   invoked Soft-ICE.
   The WR command is assigned to the function key F2 in the Soft-ICE
   initialization file S-ICE.DAT. Press the F2 key several times and you
   will see the register window toggle on and off. Leave the register
   window visible.
   Extend the vertical size of the Soft-ICE window by holding down the
   ALT and the until the window is the entire length of the screen.
   Notice the values of the CS and IP registers in the register window,
   then enter : MAP
   The MAP command displays a system memory map. The area of the current
   instruction pointer (CS:IP) is highlighted. If you have a complex
   memory map you may have to press a key a few times until the until the
   prompt reappears.
   Now try the following sequence a few times, noticing the (CS:IP)
   registers in the register window. ALT D, release ALT and D, ALT D
   Each time you bring the Soft-ICE window back up you will notice that
   the CS and IP registers have changed. When CS and IP change you can
   enter the MAP command again to see if the instruction pointer now
   points to a different area. This little exercise demonstrates that
   Soft-ICE is a system level debugger that pops up wherever the
   instruction pointer happens to be when you press the Soft-ICE hot key
   sequence. The instruction pointer is continuously changing because
   there is a lot of activity happening behind the scenes even when you
   are at the DOS prompt, such as timer interrupts, DOS device driver
   polling, DOS busy waiting other interrupts, etc.
   Press the F12 function key. The F12 function key defaults to be
   assigned to the Soft-ICE VER command. It displays the Soft-ICE
   copyright message and the version number.
   We will now assign the F12 function key to the Soft-ICE RS command.
   Enter : RS. This will temporarily show the program screen without the
   Soft-ICE window. Press the space bar to get back to get back the
   Soft-ICE window. Enter : FKEY F12 RS;
   This assigns the RS command to the F12 key. The semi-colon represents
   the ENTER key. Press the F12 key. Repeat this a few times to toggle
   between the Soft-ICE window and the program screen. Now make sure the
   Soft-ICE window is displayed, by pressing the F12 key if necessary.
   You will notice RS displayed several times in the window. There is one
   occurrence for each time you pressed the F12 key to show the program
   screen.
   Clear the Soft-ICE window by entering : CLS. Enter : FKEY F12 ^RS;.
   The ^ symbol assigns the RS command to the F12 key, but makes it an
   invisible command. Press the F12 key several times. Notice that the RS
   command no longer displays in the Soft-ICE window. You can also assign
   a sequence of Soft-ICE commands to a function key. Remember to place a
   carriage return between each command.
   Now let's prepare to use Soft-ICE as an assistant to the MSDOS DEBUG
   utility. Get rid of the register window by pressing the F2 then shrink
   the window size down to about 6 lines by Using ALT. Enter : ACTION
   INT3
   This command tells Soft-ICE to generate interrupt 3's when break point
   conditions are met. That's how Soft-ICE will communicate with DEBUG.
   The default setting is HERE. ACTION HERE will cause control to return
   directly to Soft-ICE. Use ACTION HERE when using Soft-ICE as a
   stand-alone debugger.
   For those of you not using DEBUG with this tutorial you might have to
   improvise now. CODEVIEW works with ACTION NMI. Most other debuggers
   will work with ACTION set to INT3. If your debugger doesn't, and you
   need help improvising, refer to the complete description ACTION (see
   section 5.4).
   To make the Soft-ICE window disappear again, enter : X. This is an
   alternative method to exit from Soft-ICE. This especially useful in
   function key definitions.
   Now that you are familiar with some of the basics of using Soft-ICE,
   let's learn some details by debugging the sample program (SAMPLE.ASM).
   SAMPLE.ASM is a simple program written in assembly language by a
   programmer named Jed. The program reads a keystroke from DOS and
   displays a message telling whether the keystroke was a space.
   To run the program SAMPLE, at the DOS prompt, enter : SAMPLE
   Now press the space bar. Press several keys. Jed's program obviously
   has a problem! Jed has spent hours studying this source code and is
   certain there are no flaws in his logic. However, Jed borrowed some
   'helper' routines from his friend Jake (get_key, is_space?). Jed is
   somewhat suspect these routines but he cannot find the bug. The source
   code for Jed's program looks like this:
           Page    55,80
           Title   Sample
   DATA Segment Public 'Data'
   pad             db      12H dup(O)
   char            db      0
   answer          db      0
   space_msg       db      'The Character is a SPACE',0DH,0AH,'$'
   no_space_msg    db      'The Character is NOT a'
                   db      'SPACE',0DH,0AH,'$'
   DATA Ends
   STACK Segment Stack 'Stack'
           Dw          128 Dup (?)                         ;Program stack
   STACK Ends
   CODE Segment Public 'Code'
           Assume CS:CODE,DS:DATA,ES:Nothing,SS:STACK
   start:
           mov     ax,DATA                                 ; Set up segments
           mov     es,ax
           mov     ds,ax
   main_loop:                                              ; Main Program Loop
           call    get_key
           call    is_space
           cmp     answer,0
           je      no_space
   ; It's a space, so display the space message
           mov     ah,9
           mov     dx,offset space_msg
           int     21H
           jmp     main_loop
   ; It's NOT a space, so display the no space message
   no_space:
           mov     ah,9
           mov     dx,offset no_space_msg
           int     21H
           jmp     main_loop
   ;----------------------------------------------------------;
   ; JAKE'S ROUTINES                                          ;
   ;----------------------------------------------------------;
   ; Get Key Routine (one of Jake's routines)
   get_key proc
           mov     ah,8
           int     21H
           mov     char,al
           ret
   get_key endp
   ; Check if character is a space (one of Jake's routines)
   is_space proc
           cmp     char,20H
           jne     not_space
           mov     answer, 1
           ret
   not_space:
           mov     cs:answer,0
           ret
   is_space endp
   CODE Ends
           End.
   Jed has been using DEBUG but has not been able to pinpoint the
   problem. As a recommendation from his nephew Jethro, Jed has purchased
   Soft-ICE. He was somewhat reluctant to use it because he had tried a
   hardware-assisted debugger but could never get it working quite right.
   He was willing to try Soft-ICE because he could continue to use DEBUG
   -- the only debugger he really understood.
   Press CTRL C to break out of the program. Enter the following
   commands:
   DEBUG drive:\pathname\SAMPLE. EXE
   U
   R
   In the hours Jed has spent trying to find this elusive bug, he has had
   the suspicion that something is overwriting his code in some subtle
   way. With Soft-ICE, Jed decides to set a range break point across his
   code segment. Press : ALT D. The Soft-ICE window is back. Move the
   window (by using CTRL and the Arrow keys) until DEBUG's register
   display is visible.
   It's time to set our first break point. Enter : BPR code-seg:0
   code-seg:25 W
   Code-seg is the value in the CS register as displayed by the DEBUG R
   command.
   The BPR command sets a memory-range break point. The length of Jed's
   code segment is 25H bytes, so the memory range specified goes from the
   beginning of his code segment to the end. The W tells Soft-ICE to
   break on a write. We want to catch any unexpected writes to Jed's
   code.
   Enter : BL
   The BL command displays all break points. The display from BL looks
   similar to the following display :
   0) BPR code-seg:0000 code-seg:0025 W C = 01
   The 0 is the identifier for this break point. The range and W are
   displayed as they were entered, and the count (since none was
   specified) defaults to one. Now comes the moment of truth. Press ALT D
   The window disappears again. To run SAMPLE from DEBUG, enter : G.
   Press the space bar. Ok so far. Now press a non-space key. Our break
   point just woke up DEBUG. The registers and single unassembled
   instruction are displayed. Enter : U cs:address
   Address is the value of the IP register minus 10 hexadecimal. Since
   DEBUG is rather primitive, the value of the IP register minus 10
   hexadecimal must be calculated by hand. The instruction pointer is
   pointing one instruction past the instruction that caused the break
   point. By going back ten hexadecimal instructions, DEBUG should sync
   up. The instruction at offset 3BH is:
   CS:
   MOV BYTE PTR [13],0
   Jed says,"There it is! I just knew Jake's helper routines were the
   problem! His code segment override instruction is writing a zero byte
   right over my code! Who knows what that's doing!". Enter : U 0
   Location 13H happens to be the offset of a conditional jump
   instruction. The relative offset of the conditional jump is being set
   to zero. If you are an 8086 guru, you obviously know that the JE will
   ALWAYS fall through if the relative offset is zero. What a subtle BUG!
   Now we will take a quick look at how this problem would be solved
   using Soft-ICE as a stand-alone debugger. But first we must exit from
   debug.
   Before exiting the debugger, it's always a good idea to disable all
   the break points, unless ACTION is set to HERE. If you do not do this,
   when a break point occurs and ACTION tries to return to a debugger
   that is not loaded, the results are unpredictable. We've changed the
   ACTION to INT3, so we have to disable the break point. To bring up the
   window, press : ALT D. List the break point by entering : BL
   Notice that the break point description line is highlighted. The
   highlighted break point is the last break point that occurred. Notice
   that the break point number is 0. To disable break point zero, enter :
   BD 0
   List the break point again by entering : BL. The asterisk (*) after
   the break point number shows that the break point is disabled. To
   clear the break point, enter : BC 0
   Enter BL again. Notice that there are no break point lines displayed.
   Exit from Soft-ICE, then exit from the debugger, by entering :
   X
   Q
   The next part of the tutorial demonstrates how Soft-ICE can be used to
   find the same problem as a stand-alone debugger. Soft-ICE will be used
   as a source level debugger. To prepare Soft-ICE to debug at source
   level it must have been installed in your CONFIG.SYS file, and
   extended memory allocated for symbols and source files. Soft-ICE can
   only be used as a source level debugger if you have extended memory on
   your system. If you do not have extended memory you may still want to
   read through the rest of the tutorial to see the capabilities of
   Soft-ICE with extended memory. If you have not loaded S-ICE.EXE in
   your CONFIG.SYS file with memory reserved for symbols, do so at this
   time.
   To debug the sample program with Soft-ICE as a stand-alone debugger we
   must use the Soft-ICE program loader (LDR.EXE). To load the sample
   program (SAMPLE.EXE), the symbol file (SAMPLE.SYM) and the source file
   (SAMPLE.ASM) enter at the DOS prompt :LDR SAMPLE
   You are now in Soft-ICE with SAMPLE.EXE loaded into memory. Notice
   that Soft-ICE occupies the full screen. Soft-ICE switches to its wide
   mode whenever a program loaded. The source from SAMPLE.ASM should be
   visible in the code window. In addition, the register window and the
   DATA windows are visible.
   Step through one instruction by pressing F10. Notice that the reverse
   video bar moves to the next instruction to be executed after a program
   step.
   Press F6. This places the cursor in the code window. Now experiment
   with the Up, Down, pageUp, and pageDn keys to move the cursor and
   scroll the source file. Move the cursor down to line 42 with the DOWN
   key. Press F9.
   We have just set an execution break point on line 42. The line should
   be highlighted, showing you that a break point has been set on it.
   Enter : BL. This shows the break point that we have just set.
   Now press ALT D. This exits Soft-ICE, and causes the sample program to
   execute until it encounters the break point on line 42. Soft-ICE
   should immediately come back, with the reverse video bar on line 42.
   Press F6 again. This will bring the cursor back to the command window.
   Now enter : BC *. This will clear all the break points (there should
   only be one set). Now exit from Soft-ICE by pressing ALT D. You are
   back to the sample program. Type a few keys just to make sure it is
   still broken.
   Now pop Soft-ICE back up with ALT D. Since the bug has already
   occurred, we want to restart the program. Enter : EXIT RD. This
   command forces the sample program to exit. The R tells Soft-ICE to
   restore the interrupt vectors to the state they were when the sample
   program was loaded with LDR. The D tells Soft-ICE to delete any
   currently pending break points. The R and the D are not necessary in
   this case, but it is good to get in the habit of specifying them when
   exiting a program that was loaded with LDR.EXE.
   You are now back at the DOS prompt. Reload the program by entering :
   LDR SAMPLE.EXE
   Notice the suffix.EXE was specified this time. When the suffix is
   specified, Soft-ICE does not attempt to load a symbol file or source
   file. In this case the symbol file and source file are already in
   memory. Enter : SYM. This displays the public symbols of the sample
   program. Press Esc to get back to the prompt.
   We will now set a range break point similar to the one we set while
   using Soft-ICE as an assistant to debug. This time we will use symbols
   to set the break point. Enter : BPR START .82 W. This will set a range
   break point in our code segment from the symbol START to line 82 of
   the source file. Enter : BL. You can verify that the break point has
   been set properly.
   Press ALT D. Press a non-space key. We're back in Soft-ICE. Notice
   that the current instruction (the line with the reverse video bar) is
   the instruction after the one that caused the break point.
   To see the actual code press the F3 key. This places Soft-ICE in mixed
   mode. Notice that the reverse video bar covers 2 lines. This is the
   actual code line and the source code line of the current instruction.
   Press the F3 key again. We are now in code mode. No source lines are
   visible. The instruction above the reverse video bar is the
   instruction that caused the range break point to go off. Press the F3
   key again to get back to source mode.
   Now we will fix the bug in the sample program. Exit the sample program
   and go back to the DOS prompt by entering : EXIT RD. Re-load the
   sample program by entering : LDR SAMPLE. EXE. Set the code window in
   code mode by pressing the F3 key twice.
   Un-assemble at the broken routine by entering : U not_space.
   We will now use the Soft-ICE interactive assembler to fix the problem.
   Enter: A not_space. Soft-ICE will prompt you with the address. Enter:
   NOP
   Press ENTER to exit from the assembler. Notice in the code window that
   there is a NOP instruction in place of the CS over-ride at offset
   003BH. Press the F3 key to get back to source mode, (the source code
   of course is not modified). Press ALT D to run the mended sample
   program. Enter spaces and some non-spaces characters. It works! You
   fixed the bug! To get out of Jed's program, and return to DOS, press :
   CTRL C
   Now we're going to demonstrate another feature of Soft-ICE. Enter :
   LDR SAMPLE.EXE. This will load the sample program in one more time.
   Enter : RIP HANG_EXAMPLE
   The first two displayed instructions are:
   CLI
   JMP $
   Notice that the jump instruction jumps to itself. This infinite loop
   would normally hang the system in an unrecoverable fashion. Enter :
   BREAK ON. We have just turned on BREAK mode. BREAK mode will cause the
   system to run slightly slower, but will allow Soft-ICE to come up even
   when the system would normal be hung.
   Exit from Soft-ICE by pressing ALT D. Your system is now hung. For
   those non-believers, press : CTRL ALT DEL
   Nothing happens! It is definitely hung. Now press ALT D. The Soft-ICE
   window is back! To get out of the infinite loop, enter : EXIT RD. You
   are now back at DOS. Try a few directories to get a feel for the
   performance degradation. Many people feel comfortable leaving BREAK ON
   as a configuration default.
   Turn BREAK mode off again by entering : BREAK OFF. Do a few
   directories to get a comparison of the speed. That's it! Have fun!
   It's time to start experimenting and debugging on your own. Browse
   through the rest of the manual and refer to specific sections when
   necessary.

CHAPTER 4 - Using Break Point Commands

   04.00 Notationnal Conventions
   04.01 Introduction
   04.02 Setting Break Points
   04.03 Manipulating Break Points

04.00 Notationnal Conventions

   Section II contains syntax listings for each Soft-ICE command, and
   explanations and examples for each command. All numbers are in
   hexadecimal; any number can be an expression using +,-,/,*, or
   registers. All commands are case-insensitive. Words that are in
   italics the command syntax statements must be replaced by an actual
   value, rather than typing in the italicized word.
   The following notational conventions are used throughout this section
   [ ]
        Brackets enclose an optional syntax item.
   < >
        Angle brackets enclose a list of items or choices.
   x | y
        Vertical bars separate alternatives. Use item x or item y.
   count
        Count is a byte value that specifies the number of time break
        point conditions must be met before the actual break point
        occurs. If no count is specified, the default value is 1. Each
        time the Soft-ICE window is brought up, the counts are reset to
        the values originally specified.
   verb
        Verb is a value that specifies what type access the break point
        will apply to. It can be set to 'R' for reads, 'W' for write RW'
        for reads and writes, or 'X' for execute.
   address
        Address is a value that is made of two 16-bit words, separated by
        a colon. The first word is the segment address, and the second
        word is the segment offset. The addresses can be constructed of
        registers expressions, and symbols. The address may also contain
        the special characters "$", ".", and "@". See section 3-8
        (Command Syntax) for a description of these special characters.
   break-#
        Break-number is an identification number that identifies the
        break point to use when you are manipulating break points e.g.,
        editing, deleting, enabling, or disabling them). The break-number
        can be a hexadecimal digit from 0 to F.
   list
        List is a series of break-# separated by commas or spaces.
   mask
        Mask is a bitmask that is represented as: combination of 1's,
        0's, and X's. X's are don't-care bits.
   GT, LT GT and LT
        Command qualifiers that unsigned comparisons of values.
   Example : BPIO 21 W EQ M 1XXX XXXX
   This command will cause a break point to occur if port 21H is written
   to with the high order bit set.

04.01 Introduction

   Soft-ICE has break point capability that has traditionally only been
   available with hardware debuggers. The power and flexibility of the
   80386 chip allows advanced break point capability without additional
   hardware.
   Break points can be set on memory location reads and writes, memory
   range reads and writes, program execution and port accesses. Soft-ICE
   assigns a one-digit hexadecimal number (0-F) to each break point. This
   break-number is used to identify break points when you set delete,
   disable, enable, or edit them.
   All of Soft-ICE's break points are sticky. That means they don't
   disappear automatically after they've been used; you must
   intentionally clear or disable them using the BC or the BD commands.
   Soft-ICE can handle 16 break points at one time. You can have up to
   ten break points of a single type except for break points on memory
   location (BPMs), of which you can only have four, due to restrictions
   of the 80386 processor.
   Break points can be specified with a count parameter. The count
   parameter tells Soft-ICE how many times the break point should be
   ignored before the break point action occurs.

04.02 Setting Break Points

   BPM, BPMB, BPMW, BPMD Set break point on memory access or execution
   BPR Set break point on memory range
   BPIO Set break point on I/O port access
   BPINT Set break point on interrupt
   BPX Set/clear break point on execution
   CSIP Set CS:IP range qualifier
   BPAND Wait for multiple break points to occur

Set break point on memory access or execution

   Syntax :
        BPM[size]address[verb][qualifier value][C=count]
        Size :
             B(yte), W(ord), D(oubleword)
             The size is actually a range covered by this break point.
             For example, if double word is used, and the third byte of
             the double is modified, then a break point will occur. The
             size is also important if the optional qualifier is
             specified (see below).
        Verb :
             R, W, RW, or X
        Qualifier :
             EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
             M (Mask)
             These qualifiers are only applicable to the read and write
             break points.
        Value
             A byte, word, or double word value, depending on the size
             specified.
   Comments :
        The BPM commands allow you to set a break point on memory reads
        or writes or execution.
        If a verb is not specified, RW is the default. If a size is not
        specified, byte is the default.
        All of the verb types except X cause the program to execute the
        instruction that caused the break point. The current CS:IP will
        be the instruction after the break point. If the verb type is X,
        the current CS:IP will be the instruction where the break point
        was set.
        If R is specified, then the break point will occur on read access
        and on write operations that do not change the value of the
        memory location.
        If the verb type is R, W or RW, executing an instruction at the
        specified address will not cause the break point action to occur.
   Notes :
        If BPMW is used, the specified address must start on a word
        boundary. If BPMD is used, the specified address must point to a
        double word boundary.
   Example :
        BPM 1234:SI W EQ 10 C=3
        This command defines a break point on memory byte access. The
        third time that 10 hexadecimal is written to location 1234:SI,
        the break point action will occur.
        BPM CS:1235 X
        This command defines a break point on execution. The break point
        action will occur the first time that the instruction at address
        CS:1235 is reached. The current CS:IP will be the instruction
        where the break point was set.
        BPMW DS:FOO W EQ M 0XXX XXXX XXXX XXX1
        This command defines a word break point on memory write. The
        break point action will occur the first time that location DS:FOO
        has a value written to it that sets the high order bit to 0 and
        the low order bit to 1. The other bits can be any value.
        BPM DS:1000 W GT 5
        This command defines a byte break point on memory write. The
        break point action will occur the first time that location
        DS:1000 has a value written to it that is greater than 5.

Set break point on memory range

   Syntax :
        BPR start-address end-address [verb] [C=count]
        Start-address, end-address :
             start-address and end-address specify memory range.
        Verb :
             R, W, RW, T or TW
   Comments :
        The BPR command allows you to set a break point across a range of
        memory.
        All of the verb types except T or TW cause the program to execute
        the instruction that caused the break point. The current CS:IP
        will be the instruction after the break point.
        There is no range break point on execution. If a range break
        point is desired on execution, R must be used. An instruction
        fetch is considered a read for range break points.
        If a verb is not specified, W is the default.
        The range break point will degrade system performance in certain
        circumstances. Any read or write within the 4K page that contains
        the break point range is analyzed by Soft-ICE. This performance
        degradation is usually not noticeable, however, degradation could
        be extreme in exception cases.
        The T and TW verbs enable back trace ranges on the specified
        range. They do not cause break points, but instead log
        instruction information that can be displayed later with the SHOW
        or TRACE commands. For more information on back trace ranges, see
        chapter 9.
   Example :
        BPR B000:0 B000:1000 W
        This command defines a break point on memory range. The break
        point will occur if there are any writes to the monochrome
        adapter video memory region.

Set break point on I/O port access

   Syntax :
        BPIO port [verb] [qualifier value] [C=count]
        Port :
             A byte or word value.
        Verb :
             R (IN), W (OUT), or RW
        Qualifier :
             EQ(ual), NE (Not Equal), GT (Greater than), LT (Less Than),
             M (Mask)
   Comments :
        The BPIO command allows you to set a break point on I/O port
        reads or writes.
        If value is specified, it is compared with the actual data value
        read or written by the IN or OUT instruction causing the break
        point. The value may be a byte or a word. If the I/O is to a byte
        port, then the lower 8 bits are used in the comparison.
        The instruction pointer (CS:IP) will point to the instruction
        after the IN or OUT instruction that caused the break point.
        If a verb is not specified, RW is the default.
   Example :
        BPIO 21 W NE FF
        This command defines a break point on I/O port access. The break
        point will occur if the interrupt controller one mask register is
        written with a value other than FFH.
        BPIO 3FE R EQ M 11XX XXXX
        This command defines a byte break point on I/O port read. The
        break point action will occur the first time that I/0 port 3FE is
        read with a value that has the two high order bits set to 1. The
        other bits can be any value.

Set break point on interrupt

   Syntax :
        BPINT int-number [ < AL | AH | AX >= value] [C = count]
        Int-number :
             Interrupt number from 0 - FF hex
        Value :
             A byte or a word value
   Comments :
        The BPINT command allows breaking on the execution of a hardware
        or a software interrupt. By optionally qualifying the AX register
        with a value, specific DOS or BIOS calls can be easily isolated.
        If no value is specified, a break point will occur when the
        interrupt specified by int-number occurs. This interrupt can be a
        hardware, software, or internal interrupt.
        The optional value is compared with the specified register (AH,
        AL, or AX) when the interrupt occurs. If the value matches the
        specified register, then the break point will occur.
        When the break point occurs, if the interrupt was a hardware
        interrupt, the instruction pointer (CS:IP) will point to the
        first instruction within the interrupt routine. The INT? command
        can be used to see where execution was when the interrupt
        occurred. If the interrupt was a software interrupt, when the
        break point occurs, the instruction pointer (CS:IP) will point to
        the INT instruction causing the interrupt.
   Example :
        BPINT 21 AH=4C
        This command defines a break point on interrupt 21H The break
        point will occur when DOS function call 4CH (terminate program)
        is called.

Set/Clear break point on execution

   Syntax :
        BPX [address] [C=count]
   Comments :
        The BPX command allows you to set or clear a point-and-shoot
        execution break point in source. When the cursor is in the code
        window the address is not required. The execution break point is
        set at the address of the current cursor location. If an
        execution break point has already been set at the address of the
        current cursor location, then the break point is cleared.
        If the code window is not visible or the cursor is not in the
        code window then the address must be specified. If an offset only
        is specified then the current CS register value used as the
        segment.
   Technical Note :
        BPX uses an interrupt 3 style of break point unless the specified
        address is ROM. This is used instead of a break point register to
        make more execution break points available. If your circumstances
        require the use of a break point register for some reason (code
        not loaded yet for example) you can set an execution break point
        with the BPM command.
   Example :
        BPX.1234
        This sets an execution break point at source line 1234.

Set CS:IP range qualifier

   Syntax :
        CSIP [OFF | [NOT] start-address end-address]
        NOT :
             When NOT is specified, the break point will only occur if
             the CS:IP pointer is outside the specified range.
        OFF :
             Turns off CS:IP checking
   Comments :
        The CSIP command causes a break point to be dependent upon the
        location of the instruction pointer when the break point
        conditions are met. This function is often useful when a program
        is suspected of accidentally modifying code outside of its
        boundaries.
        When break point conditions are met, the CS:IP registers are
        compared with a specified range. If they are within the range,
        the break point is activated. To activate the break point when
        CS:IP is outside the range, use the NOT parameter.
        When a CSIP range is specified, it applies to ALL break points
        that are currently active.
        If no parameters are specified, the current CSIP range is
        displayed.
   Example :
        CSIP NOT F000:0 FFFF:0
        This command causes the break points to occur only the CS:IP is
        NOT in the ROM BIOS when the break point conditions are met.

Wait for multiple break points to occur

   Syntax :
        BPAND list | * | OFF
        List :
             A series of break-numbers separated by commas or spaces
        * :
             ANDs together all break points
   Comments :
        The BPAND command does a logical AND of two or more break points,
        activating the break point only when conditions for all break
        points are met.
        Sometimes conditions arise when you don't want a break point to
        occur until several different conditions are met. The BPAND
        command allows specifying two or more break points that must
        occur before the action is generated. This function allows more
        complex break point conditions to be set.
        Each time the BPAND command is used, the specified break point
        numbers are added to the list until BPAND OFF is used.
        You can tell which of the break-numbers are ANDed together by
        listing the break points with the BL command. The break points
        that are ANDed together will have an ampersand (&) after their
        break-number.
        Once break points have been ANDed together, each remains ANDed
        until it is cleared, or until BPAND is turned off.
   Example :
        BPAND 0,2,3
        This command causes the conditions of the break points 0, 2, and
        3 to be logically tied together. The break occurs only when the
        conditions of all three are met. For example, if the conditions
        of break points 2 and 3 have both been met at least once, but the
        conditions of break point 0 have not been met at all yet, then
        the action will not occur until break point 0 conditions are met.

04.03 Manipulating Break Points

   Soft-ICE provides several commands for manipulating break points.
   Manipulation commands allow listing, modifying, deleting, enabling,
   and disabling of break points. Break points are identified by
   break-numbers which are hexadecimal digits from 0 to F. The break
   point manipulation commands are:
   BD Disable break points
   BE Enable break points
   BL List break points
   BPE Edit break point
   BPT Use break point as a template
   BC Clear break points

Disable break points

   Syntax :
        BD list | *
        List :
             A series of break-numbers separated by commas or spaces
        * :
             Disables all break points
   Comments :
        The BD command is used to temporarily deactivate break points.
        The break points can be reactivated with the BE (Enable break
        points) command.
        You can tell which of the break-numbers are disabled by listing
        the break points with the BL command. The break points that are
        disabled will have an asterisk (*) after their break-number.
   Example :
        BD 1,3
        This command temporarily disables break points 1 and 3.

Enable break points

   Syntax :
        BE list | *
        List :
             A series of break-numbers separated by commas or spaces
        * :
             Enables all break points
   Comments :
        The BE command is used to reactivate break points that were
        deactivated by the BD (Disable break points) command.
        Note that a break point is automatically enabled when defined.
   Example :
        BE 3 his command enables break point 3.

List break points

   Syntax :
        BL
   Comments :
        The BL command displays all break points that are currently set.
        For each break point, BL lists the break-number, break point
        conditions, break point state, and count.
        The state of a break point is either enabled or disabled. If the
        break point is disabled, an asterisk (*) is displayed after its
        break-number. If an enabled break point was used in a BPAND
        command, an ampersand (&) is displayed after its break-number.
        The break point that most recently caused an action to occur is
        highlighted.
        The BL command has no parameters.
   Example :
        BL
        This command displays all the break points that have been
        defined. A sample display, which shows four break points,
        follows:
         0) BPMB 1234:0000 W EQ 0010 C=03
         1)*BPR B000:0000 B000:1000 W C=01
         2) BPIO 0021 W NE 00FF C=01
         3) BPINT 21 AH=4C C=01
        Note that in this example, break point 1 is preceded with an
        asterisk (*), showing that it has been disabled.

Edit break point

   Syntax :
        BPE break-number
   Comments :
        The BPE command loads the break point description into the edit
        line for modification. The command can then be edited using the
        editing keys, and re-entered by pressing the ENTER . This command
        offers a quick way to modify the parameters of an existing break
        point.
   Example :
        BPE 1
        This command moves a description of break point 1 into the edit
        line and removes break point 1. Pressing the ENTER key will cause
        the break point to be re-entered.

Use break point as a template

   Syntax :
        BPT break-number
   Comments :
        The BPT command uses an existing break point description as a
        template for a new break point.
        A description of the existing break point is loaded into the edit
        line. The break point referenced by break-number is not altered.
        This command offers a quick way to create a new break point that
        is similar to an existing break point.
   Example :
        BPT 3
        This command moves a template of break point 3 into the edit
        line. When the ENTER key is pressed, a new break point is added.

Clear break points

   Syntax :
        BC list | *
        List :
             A series of break-numbers separated by commas or spaces
        * :
             ANDs together all break points
   Comments :
        The BC command is used to permanently delete one or more break
        points.
   Example :
        BC *
        This command clears all break points.

CHAPTER 5 - Using Other Commands

   05.01 Display and Edit Commands
   05.02 I/O Port Commands
   05.03 Transfer Control Commands
   05.04 Debug Mode Commands
   05.05 Utility Commands
   05.06 Specialized Debugging Commands
   05.07 Windowing Commands
   05.08 Debugger Customization Commands
   05.09 Screen Control Commands
   05.10 Symbol and Source Line Commands

05.01 Display and Edit Commands

   U Unassemble instructions or display source
   R Display or change registers
   MAP Display system memory map
   D, DB, DW, DD Display memory
   E, EB, EW, ED Edit memory
   INT? Display last interrupt number
   ? or H Display help information
   VER Display Soft-ICE version number

Unassemble instructions or display source

   Syntax :
        U [address] [L[=]length]
        Length :
             The number of instructions to be unassembled
   Comments :
        The U command displays the instructions of the program being
        debugged.
        If length is not specified, the length defaults to eight lines if
        available, or one less than the screen length.
        If address is not specified, the command unassembles at address
        starting at the first byte after the last byte unassembled by a
        previous unassemble command. If the has been no previous
        unassemble command, the address defaults to the current CS:IP.
        If the code window is visible, the instructions are displayed in
        the code window.
        If source is loaded for the address range specified then source
        lines may be displayed depending on the current source mode.
   Example :
        U $-10
        This command unassembles instructions beginning 10 hexadecimal
        bytes before the current address.
        U .499
        This command displays the current source file starting at line
        499. The code window must be visible and in source mode.

Display or change registers

   Syntax :
        R register-name [ [ = ]value] ]
        Register-name :
             Any register (FL for flags)
        Value :
             If register-name is any name other than FL, value is a hex
             value or an expression. If register-name is FL, value is a
             series of one or more of the following flag symbols, each
             optionally preceded by a plus or minus sign : O (Overflow
             flag), D (Direction flag), I (Interrupt flag), S (Sign
             flag), Z (Zero flag), A (Auxiliary carry flag), P (Parity
             flag), C (Carry flag).
   Comments :
        The R command displays or changes register values.
        If no parameters are supplied, all register and flag value are
        displayed, as well as the instruction at the current CS:IP
        address.
        If register-name is supplied without a value, Soft-ICE displays
        the current value of the specified register and prompts you for a
        new value. If register-name is FL, flags that are set are
        displayed as highlighted uppercase characters; flags that are
        cleared are displayed as non-highlighted lowercase characters. To
        retain the current value of a register, press ENTER.
        If both register-name and value are supplied, the specified
        register's contents are changed to the value.
        To change a flag value, use FL as the register-name, followed by
        the symbols of the flag whose values you want to toggle. To turn
        a flag on, precede the flag symbol with a plus sign. To turn a
        flag off, precede the flag symbol with a minus sign. The flags
        can be listed in any order.
   Examples :
        RAH 5
        This command sets the AH register equal to 5.
        R FL = OZP
        This command toggles the O, Z, and P flag values.
        R FL
        This command displays the current flag values, and allows them to
        be changed.
        RFL O + A-C
        This command toggles the O flag value, turns on the flag value,
        and turns off the C flag value.

Display system memory map

   Syntax :
        MAP
   Comments :
        The MAP command displays the names, locations, and sizes of
        system memory components. The size is displayed in paragraphs.
        One paragraph is equivalent to 10 hexadecimal bytes.
        The component that the CS:IP register currently points to is
        highlighted.
        Use the MAP command when A break point occurs and CS:IP is not in
        a known memory region. You want to get control within a resident
        program or system program. A range break point can be set based
        on the starting address and size reflected by MAP. You suspect a
        program or system component of writing over code outside of its
        memory space. MAP is used to obtain the memory address of the
        region to use with the CSIP command. You need to find out which
        resident program owns certain interrupt vectors.
   Example :
        MAP
        The following is a sample display produced by the command :
         Start Length
         0000:0000 0040 Interrupt Vector Table
         0040:0000 0030 ROM BIOS Variables
         0070:0000 00FE I/O System
         016E:0000 06B7 DOS
         0842:0000 02CE DOS File Table & Buffers
         A000:0000 5E00 System BUS
         F000:0000 1000 ROM BIOS
        Versions of DOS lower than 3.1 display program addresses instead
        of displaying the program names.

Display memory

   Syntax :
        D [size] [address] [L[ = ]length]
        Size :
             B(yte), W(ord), D(ouble)
        Length :
             The number of bytes to be displayed.
   Comments :
        The D command displays the memory contents of the specified
        address.
        The contents are displayed in the format of the size specified.
        If no size is specified, the last size used will be displayed.
        The ASCII representation is also displayed for all forms.
        If address is not specified, the command displays memory at the
        address starting at the first byte after the last byte displayed.
        If length is not specified, it defaults to eight lines, or fewer
        if the window is smaller.
        If the data window is visible, the data is displayed in the data
        window and the length is ignored.
   Example :
        DW DS:00 L=8
        This command displays, in word format and in ASCII format, the
        value of the first eight bytes of the current data segment.

Edit memory

   Syntax :
        D [size] [address] [L[ = ]length]
        Size :
             B(yte), W(ord), D(ouble)
        Data-list :
             list of data objects of the specified size (Bytes, Words or
             Double Words) or quoted strings separated by commas or
             spaces. The quoted string can begin with a single quote or a
             double quote.
   Comments :
        The E commands display the memory contents at the specified
        address, and allow you to edit the values.
        These commands display the memory contents in ASCII format, and
        in the format of the size specified.
        A memory editor is provided for quick memory updates. Memory can
        be edited by typing ASCII characters, or by typing byte, word, or
        double word values. If no size is specified, the last size used
        will be assumed. The memory Editing key strokes are:
        UP            Move cursor up
        DOWN          Move cursor down
        LEFT          Move cursor right
        RIGHT         Move cursor left
        SPACE         Move cursor to next element
        TAB           Toggle between numeric and ASCII areas
        ESC or ENTER  Exit memory editor
        As values are input, the actual memory locations are updated. All
        numeric values are hex numbers. To toggle between the ASCII and
        numeric display areas, press the TAB key.
        If the data window is visible, the data is edited in the data
        window, otherwise the data is edited in the command window.
        The data display length defaults to 8 lines if in the command
        window, or to the size of the data window if it's visible.
        If no parameters are supplied, the cursor moves into the data
        window if the data window if visible. If the data window is not
        visible, the data is edited in the command window at the last
        address displayed or edited.
   Examples :
        EB 1000:0
        This command displays, in byte format, up to six lines containing
        both the numeric and the ASCII representation of the values of
        the data starting at location 1000:0000. Once the lines are
        displayed, you can edit the values.
        EB 8000:0 "Hello",0D
        This command replaces the values starting at location 8000:0000
        with the string "Hello" followed by a carriage return.

Display last interrupt number

   Syntax :
        INT?
   Comments :
        The INT? command displays the address and the number the last
        interrupt that happened.
   Example :
        INT?
        An example of the display produced by the INT? command follows:
         Last Interrupt: 16
         At: 0070:0255
        This example shows that the last interrupt generated in the
        system before the Soft-ICE window was brought up was an interrupt
        16 hexadecimal, at location 0070:0255H. If the last interrupt
        that happened was a software interrupt, unassembling the code at
        0070:0255H will show the interrupt instruction. If it was a
        hardware interrupt, unassembling the code will show the
        instruction that was executing when the hardware interrupt
        occurred.

Display help information

   Syntax :
        < ? | H > [command | expression]
   Comments :
        The ? command and the H command both display help information.
        If no parameters are specified, help displays short descriptions
        of all the commands and operators, one screen at a time. Press
        any key to continue, or press ESC to quit displaying help.
        If command is specified, help displays more detailed information
        on the specified command, including the command syntax and an
        example.
        If expression is specified, the expression is evaluated and the
        result is displayed in hexadecimal, decimal, and ASCII.
   Examples :
        ? ALTKEY
        This command displays information about the ALTKEY command,
        including its syntax and an example.
        H 10 + 14*2
        This command displays: 0038 00056 "8". These are the hexadecimal,
        decimal and ASCII representations of value of the expression "10
        + 14*2".

Display Soft-ICE version number

   Syntax :
        VER
   Example :
        VER
        This command displays the Soft-ICE version and the Nu-Mega
        Technologies copyright message.

05.02 I/O Port Commands

   I, IB or IW Input from I/O port
   O, OB or OW Output to byte I/O port

Input from I/O port

   Syntax :
        I [size] port
        Size :
             B(yte), W(ord), D(ouble)
        Port :
             A byte or word value
   Comments :
        The input from port commands are used to read and display a value
        from a hardware port. Input can be done From byte or word ports.
        If no size is specified, the default is byte.
   Example :
        I 21
        This command displays the mask register for interrupt controller
        one.

Output from I/O port

   Syntax :
        O [size] port
        Size :
             B(yte), W(ord), D(ouble)
        Port :
             A byte or word value
        Value :
             A byte for a byte port or a word for a word port
   Comments :
        The output to port commands are used to write a value to a
        hardware port. Output can be done to byte or word ports If no
        size is specified, the default is byte.
   Example :
        O 21 FF
        This command masks off all the interrupts for interrupt
        controller one.

05.03 Transfer Control Commands

   X Exit from Soft-ICE window
   G Go to address
   T Trace one instruction
   P Program step
   HERE Go to current cursor line
   GENINT Force an interrupt
   EXIT Force exit of current DOS program
   BOOT System boot (retain Soft-ICE)
   HBOOT Hard system boot (total reset)

Exit from Soft-ICE window

   Syntax :
        X
   Comments :
        The X command exits the Soft-ICE window and restores control to
        the program that was interrupted to bring up Soft-ICE. The
        Soft-ICE window disappears. If any break points have been set,
        they become active.
   Example :
        X
        Exits the Soft-ICE window and restores control to the program
        that was interrupted.

Go to address

   Syntax :
        G [=start-address] [break-address]
   Comments :
        The G command exits from the Soft-ICE window with a single
        one-time execution break point set. In addition, all sticky break
        points are armed.
        Execution begins at the current CS:IP unless the start-address
        parameter is supplied. In that case execution begins at
        start-address. Execution continues until break-address is
        encountered, the window pop-up key sequence is used, or a sticky
        break point occurs.
        The break-address must be the first byte of an instruction
        opcode.
        When the specified break-address is reached, the current CS:IP
        will be the instruction where the break point was set.
        The G command with no parameters behaves the same as the X
        command.
        The non-sticky execution break point uses an 80386 break point
        register, unless all break point registers have been allocated to
        sticky break points. In that case, an INT 3 style break point is
        implemented. When this case occurs, the G and P commands will not
        work correctly in ROM. An error message will be displayed if this
        is attempted.
   Example :
        G CS:1234
        This command sets a one time break point at CS:1234

Trace one instruction

   Syntax :
        T [=start-address] [count]
   Comments :
        The T command single steps one instruction by utilizing the
        single step flag.
        Execution begins at the current CS:IP unless the start-address
        parameter is specified. If start-address is specified, CS:IP is
        changed to start- address prior to single stepping.
        If count is specified then Soft-ICE single steps count time The
        TRACE command will continue until the count is exhausted or the
        Esc key is pressed, regardless of which break points are reached.
        In source mode, the T command steps to the next source statement.
        If the current statement is a procedure or function call, and
        source exists for the routine being called, T steps into the
        call. If there is no source available for the called procedure or
        function, T steps over the routine.
   Example :
        T = 1284 3
        This command single steps through three instruction starting at
        memory location 1284.

Program step

   Syntax :
        P
   Comments :
        The P command is a logical program step. One instruction at the
        current CS:IP is executed unless the instruction is a call,
        interrupt, loop, or repeated string instruction. In those cases,
        the entire routine or iteration is completed before control is
        returned to Soft-ICE.
        The P command uses a one-time execution break point. The
        non-sticky execution break point uses an 80386 break point
        register, unless all break point registers have been allocated to
        sticky break points. In that case, an INT3 style break point is
        implemented. When this case occurs, the P and G commands will not
        work correctly in ROM. An error message will be displayed if this
        is attempted.
        In source mode, the P command steps to the next source statement.
        If the current statement is a procedure or function call, the P
        command steps over the it.
   Example :
        P
        This command executes one 'program step'.

Go to current cursor line

   Syntax :
        HERE
   Comments :
        The HERE command executes until the program reaches the current
        cursor line. HERE is only available when the cursor is in the
        code window. If the code window is not visible or the cursor is
        not in the code window, use the G command instead.
        The HERE command exits from Soft-ICE with a single one-time
        execution break point set. In addition, all sticky break points
        are armed.
        Execution begins at the current CS:IP and continues until address
        of the current cursor position in the code window encountered,
        the window pop-up key sequence is used, a sticky break point
        occurs.
        The non-sticky execution break point uses an 80386 break point
        register, unless all break point registers have been allocated to
        sticky break points. In that case, an INT 3 style break point is
        implemented. When this case occurs, the HERE command will not
        work correctly in ROM. An error message will be displayed if this
        is attempted.
   Example :
        HERE
        This example sets an execution break point at the current cursor
        position, then exits from Soft-ICE and begins execution at the
        current CS:IP. Default Function Key: F7

Force an interrupt

   Syntax :
        GENINT INT1 | INT3 | NMI | interrupt-number
        Interrupt-number :
             a number in the range 00 - FF
   Comments :
        The GENINT command forces an interrupt to occur. This function
        can be used to hand off control to another debugger when using
        Soft-ICE with another software debugger. It can also be used to
        test interrupt routines.
        The GENINT command simulates the processing sequence of a
        hardware interrupt or an INT instruction. It pushes the flags,
        the CS register, and the IP register, then changes the value of
        the CS and IP registers to the value of the interrupt vector
        table entry corresponding with the specified interrupt number.
   Example :
        GENINT NMI
        This forces a non-maskable interrupt. This will give control back
        to CodeView if Soft-ICE is being used as an assistant to
        CodeView.

Force exit of current DOS program

   Syntax :
        EXIT [R] [D]
        R :
             Restore the interrupt vector table
        D :
             Delete all break points
   Comments :
        The EXIT command attempts to abort the current program by forcing
        a DOS exit function (INT 21H, function 4CH) This command will
        only work if the DOS is in a state where it is able to accept the
        exit function call. If this call is made from certain interrupt
        routines, or other times when the DOS is not ready, the system
        may behave unpredictably.
        This function does NOT do any system resetting other than the
        interrupt table when the R option is used. This means that BIOS
        variables, video modes and other systems level data are not
        restored.
        Using the R option will cause the interrupt vectors to be
        restored to whatever they were the last time they were saved.
        Soft-ICE saves the interrupt vectors when it is loaded, when a
        program is loaded with LDR.EXE, and when the VECS S command is
        used.
   Note :
        To re-start a program that has been loaded with the Soft-ICE
        program loader (LDR.EXE) do the following:
        EXIT R
        LDR prog.EXE
        The EXIT command will restore the interrupt table to the values
        it contained before the program was loaded, then exit to the
        command processor. By running the LDR utility and specifying the
        .EXE suffix, the program is loaded back in without re-loading
        symbols and source. The symbols and source will remain in memory.
   Caution :
        The EXIT command should be used with care. Since Soft-ICE can be
        popped up at any time, a situation can occur where the DOS is not
        in a state to accept an exit function call. Also, the EXIT
        command does not do any program specific resetting. For instance,
        the EXIT command does not reset the video mode. If your program
        has placed the video BIOS and hardware in a particular video
        mode, it will stay in that mode after the EXIT command.
   Example :
        EXIT R
        Restores the interrupt table and exits the current program. The R
        option should be used if exiting from a program loaded with the
        Soft-ICE program loader LDR.EXE.

System boot (retain Soft-ICE)

   Syntax :
        BOOT
   Comments :
        The BOOT command resets the system and retains Soft-ICE. BOOT is
        required to debug boot sequences, DOS loadable drivers, and
        non-DOS operating systems.
        BOOT is implemented with an Interrupt 19H ROM BIOS call. In some
        instances memory may be corrupted to the point where Interrupt 19
        will not work. If this occurs, bring up Soft-ICE and use the
        HBOOT command.
        For BOOT to work properly, Soft-ICE should be installed as a
        loadable driver in CONFIG.SYS before any other device drivers.
        This is so Soft-ICE can restore the original system state as
        accurately as possible.
   Example :
        BOOT
        This command makes the system reboot. Soft-ICE remains resident.

Hard system boot (total reset)

   Syntax :
        HBOOT
   Comments :
        The HBOOT command resets the entire system. Soft-ICE is not
        retained in the reset process. HBOOT is sufficient unless an
        adapter card requires a power-on reset. In those rare cases, the
        machine power must be recycled.
   Example :
        HBOOT
        This command makes the system reboot. Soft-ICE must be reloaded.

05.04 Debug Mode Commands

   ACTION Set action after break point is reached
   WARN Set DOS/ROM BIOS re-entrancy warning mode
   BREAK Break out any time
   I3HERE Direct Interrupt 3's to Soft-ICE

Set action after break point is reached

   Syntax :
        ACTION [INT1 | INT3 | NMI | HERE | int-number]
        Int-number :
             Any valid interrupt number (0-FFH). Use this option only if
             a user-supplied break point qualification routine has taken
             over that interrupt vector (see section 11.2).
   Comments :
        The ACTION command determines where control is given when break
        point conditions have been met. In most cases, the desired action
        is INT3 or HERE, INT3 is typically used if Soft-ICE is being used
        with a host debugger, HERE is used when it is desired to return
        to Soft-ICE when break point conditions have been met, INT1 and
        NMI are alternatives for certain debuggers that will not work
        with the INT3 option. For instance, CODEVIEW works best with
        ACTION set to NMI.
        Use int-number if there is a user-supplied break point
        qualification routine installed. Using int-number without having
        a user-supplied break point qualification routine installed
        causes an error. For more information, see section
        11.2,'User-Qualified Break Points'.
        If no parameter is supplied with the ACTION command, the current
        action is displayed.
        The default action is HERE.
   Example :
        ACTION HERE
        This command specifies that control will return to Soft-ICE when
        break point conditions have been met.

Set DOS/ROM BIOS re-entrancy warning mode

   Syntax :
        WARN [ON | OFF]
   Comments :
        The WARN command is provided for using Soft-ICE with debuggers
        that use DOS and ROM BIOS. Many debuggers use DOS and ROM BIOS
        for screen output and for receiving keystrokes. Since DOS and ROM
        BIOS are not fully re- entrant, these debuggers may not work
        properly if break point occurs while the DOS or ROM BIOS is
        executing.
        If WARN ON is set, and ACTION is not HERE, then control will come
        to Soft- ICE before the actual action occurs. The system displays
        the current CS:IP and gives you the choice of continuing or
        returning to Soft-ICE. Generally, you should choose to return to
        Soft-ICE to continue your debugging. Only continue with the host
        debugger if you know your debugger will not cause DOS or ROM BIOS
        to be re-entered.
        WARN mode should be turned on to use Soft-ICE with DEBUG, SYMDEB,
        and CODEVIEW.
        If no parameter is specified, the current state of WARN is
        displayed.
        The default is WARN mode OFF.
   Example :
        WARN ON
        This command turns on DOS/ROM BIOS re-entrancy warning mode.

Break out any time

   Syntax :
        BREAK [ON | OFF]
   Comments :
        The BREAK command allows popping up the Soft-ICE window when the
        system is hung with interrupts disabled. Break mode can be used
        for the entire debugging session, or it can be turned on and off
        when it is required.
        Break mode degrades system performance slightly. This performance
        degradation must be weighed against the necessity of breaking out
        of a hung program. A user may want to have break mode on all the
        time, even though performance is degraded, because the program
        could hang at any time.
        Unlike other debuggers that can also be brought up at any time,
        Soft-ICE does not require an external switch. When BREAK is on,
        the Soft-ICE window can be brought up at any time by pressing the
        current key sequence.
        If no parameter is specified, the current state of BREAK is
        displayed
        The default is BREAK mode OFF.
   Example :
        BREAK ON
        This command turns on break mode. This means that the Soft-ICE
        window can be brought up at any time, even if interrupts are
        disabled.

Direct Interrupt 3's to Soft-ICE

   Syntax :
        I3HERE [ON | OFF]
   Comments :
        The I3HERE command lets you specify that any Interrupt 3 will
        bring up the Soft-ICE window. This feature is useful for stopping
        your program in a specific location.
        To use this feature, place an INT 3 into your code at the
        location where you want to stop. When the INT 3 occurs, it will
        bring up the Soft-ICE window. At this point, you can use the R IP
        command to change your instruction pointer to the instruction
        after the INT 3, then you can continue debugging.
        If no parameter is specified, the current state of 13HERE is
        displayed.
        The default is 13HERE mode OFF.
   Example :
        I3HERE ON
        This command turns on 13HERE mode. Any INT 3's generated after
        this point will bring up the Soft-ICE window.

05.05 Utility Commands

   A Assemble code
   S Search for data
   F Fill memory with data
   M Move data
   C Compare two data blocks

Assemble code

   Syntax :
        A [address]
   Comments :
        The Soft-ICE assembler allows you to assemble instructions
        directly into memory. The assembler supports the basic 8086
        instruction set with the 80186 and 80286 real address mode
        extensions. Numeric co-processor instructions and 80386 specific
        instructions, registers and addressing modes can NOT be
        assembled.
        The A command enters the Soft-ICE interactive assembler. An
        address is displayed as a prompt for each assembly line After an
        assembly language instruction is typed in and ENTER is pressed,
        the instructions are assembled into memory at the specified
        address. Instructions must be entered with standard Intel format.
        Press ENTER at an address prompt to exit assembler mode.
        If the address range in which you are assembling instructions is
        visible in the code window, the instructions will change
        interactively as you assemble.
        The Soft-ICE assembler supports the standard 8086 family
        mnemonics, however there are some special additions :
        The DB mnemonic is used to define bytes of data directly into
        memory. The DB command is followed by a list of bytes and/or
        quoted strings separated by spaces or commas.
        The RETF mnemonic represents a far return.
        WORD PTR and BYTE PTR are used to determine data size if there is
        no register argument, for example: MOV BYTE PTR ES:[ 1234],1.
        Use FAR and NEAR to explicitly assemble far and near jumps and
        calls. If FAR or NEAR is not specified then all jumps and calls
        are near.
        Operands referring to memory locations should placed in square
        brackets, for example: MOV AX,[1234].
   Example :
        A CS:1234
        This command prompts you for assembly instruction then assembles
        them beginning at offset 1234H with the current code segment.
        Press ENTER at the address prompt after entering the last
        instruction.

Search for data

   Syntax :
        S address L length data-list
        Data-list :
             list of bytes or quoted strings separated by commas or
             spaces. A quoted string can begin with a single quote or a
             double quote.
        Length :
             length in bytes
   Comments :
        The S command searches memory for a series of bytes or characters
        that matches the data-list. The search begins at the specified
        address and continues for the length specified. The address of
        each occurrence found in the range is displayed.
   Example :
        S DS:SI+10 L CX 'Hello',12,34
        This command searches for the string 'Hello' followed by the
        bytes 12H and 34H starting at offset SI+10 in the current data
        segment and ending CX bytes later.

Fill memory with data

   Syntax :
        F address L length data-list
        Data-list :
             list of bytes or quoted strings separated by commas or
             spaces. A quoted string can begin with a single quote or a
             double quote.
        Length :
             length in bytes
   Comments :
        The F command fills memory with the series of bytes or characters
        specified in the data-list. Memory is filled starting at the
        specified address and continuing for the specified length,
        repeating the data-list if necessary.
   Example :
        F 8000:0 L 100 'Test'
        This command fills memory starting at 8000:0 for a length of 100H
        bytes with the string 'Test'. The string Test' is repeated until
        the fill length is exhausted.

Move data

   Syntax :
        M start-address L length end-address
        Length :
             length in bytes
   Comments :
        The M command moves the specified number of bytes from the
        start-address in memory to the end-address in memory.
   Example :
        M 1000:0 L 200 2000:0
        This command moves 200H bytes from memory location 1000:0 to
        memory location 2000:0.

Compare two data blocks

   Syntax :
        C address1 L length address2
        Length :
             length in bytes
   Comments :
        The C command compares the memory block specified by address1 and
        the length with the memory block specified address2 and the
        length. When a byte from the first data block does not match a
        byte from the second data block, both bytes are displayed, along
        with their addresses.
   Example :
        C 5000:100 L 10 6000:100
        This command compares the 10H bytes starting at memory location
        5000:100 with the 10H bytes starting at memory location 6000:100.

05.06 Specialized Debugging Commands

   SHOW Display instructions from history buffer
   TRACE Enter trace simulation mode
   XT Single step in trace simulation mode
   XP Program step in trace simulation mode
   XG Go to address in trace simulation mode
   XRSET Reset back trace buffer
   VECS Save/restore/compare interrupt vectors
   SNAP Take snap shot of memory block
   EMMMAP Display EMM allocation map

Display instructions from history buffer

   Syntax :
        SHOW [B | start]
        B :
             This tells the show command to start the display with the
             oldest instruction in the back trace buffer.
        start :
             The number of instructions back from the buffer end (last
             instruction captured) to begin display.
   Comments :
        The SHOW command displays instructions from the back trace
        history buffer. If source is available for the instructions then
        the display is in mixed mode, otherwise only code is displayed.
        SHOW allows scrolling through the back trace buffer with the up,
        down, Pageup and PaqeDn keys. To exit from SHOW you must press
        the Esc key.
        Preceding the address of each instruction is the buffer entry
        number. This number shows how deep into the buffer you are
        displaying. The higher the number, the deeper you are into the
        buffer.
   Note :
        Before using the SHOW command, instructions must have been logged
        with a back trace range. See chapter 9 for more information on
        back trace ranges.
   Hints :
        It is often useful to have the code window visible with the
        actual code of the region you are displaying from the back trace
        buffer. When you compare the actual instruction flow to code,
        displayed jumps and calls are usually less confusing.
        Using SHOW in conjunction with the TRACE command will allow you
        to see the instructions in the back trace history buffer from two
        different points of view.
   Example :
        SHOW 40
        This example will displays starting with the 40th instruction
        back in the back trace buffer.

Enter trace simulation mode

   Syntax :
        TRACE [start] | [OFF]
        start :
             The number of instructions back from the buffer end (last
             instruction captured) to begin trace simulation.
        OFF :
             Exit trace simulation mode.
   Comments :
        The TRACE command allows you to replay instructions from the
        instruction back trace history buffer just as if they were being
        executed for the first time. To use trace simulation mode you
        must have the code window visible After entering trace simulation
        mode you use the XT, XP and XG commands to trace through the
        instructions in the buffer.
        To exit trace simulation mode type TRACE OFF.
        TRACE with no parameters specified displays whether trace
        simulation mode is on or off.
   Note :
        Before using the TRACE command, instructions must have been
        logged with a back trace range. See chapter 9 for more
        information on back trace ranges.
   Hints :
        Trace simulation mode is most useful when the code window is
        visible. It is often useful to use TRACE in conjunction with the
        SHOW command. This allows the instructions in the back trace
        history buffer to be viewed simultaneously in two different
        forms.
   Example :
        TRACE 40
        This example enters trace simulation mode starting 40
        instructions back from the last instruction logged. It will
        remain in trace simulation mode until TRACE OFF is entered.

Single step in trace simulation mode

   Syntax :
        XT [R]
        R :
             Single step in reverse direction.
   Comments :
        The XT command single steps through the instruction back trace
        history buffer. This command acts like the T command for normal
        debugging. Note that the registers do NOT change while stepping
        in trace simulation mode except CS and IP.
        The XT instruction allows you to replay instructions from the
        back trace history buffer,
   Note :
        Before using XT you must be in trace simulation mode. See chapter
        9 and the TRACE command in this section for more information on
        back trace ranges.
   Hint :
        If you are using XT frequently, like any other Soft-ICE command
        it can be assigned to a function key.
   Example :
        XT
        This command single steps one instruction in trace simulation
        mode.

Program step in trace simulation mode

   Syntax :
        XP
   Comments :
        The XP command does a logical program step through the
        instruction back trace history buffer. This command acts like the
        P command for normal debugging. Note that the registers do NOT
        change while stepping in trace simulation mode except CS and IP.
        The XP instruction allows you to replay instructions from the
        back trace history buffer.
   Note :
        Before using XP you must be in trace simulation mode. See chapter
        9 and the TRACE command in this section for more information on
        back trace ranges.
   Hint :
        If you are using XP frequently, like any other Soft-ICE command
        it can be assigned to a function key.
   Example :
        XP
        This command executes one program step in trace simulation mode.

Go to an address in trace simulation mode

   Syntax :
        XG [R] address
        R :
             Search for address in reverse direction.
        Address :
             Address to go to in the back trace history buffer.
   Comments :
        The XG command moves the instruction pointer to the next
        occurrence of the specified address in the back trace history
        buffer. If R is specified preceding the address, then the
        instruction pointer is moved to the previous occurrence the
        specified address in the back trace buffer.
        The address must be the first byte of an instruction opcode.
        The XG is analogous to the G command in normal debugging.
        Note :
        Before using XG you must be in trace simulation mode. See chapter
        9 and the TRACE command in this section for more information on
        back trace ranges.
   Example :
        XG 273:1030
        This command moves the instruction pointer to the next instance
        of the instruction at address 273:1030.

Reset back trace history buffer

   Syntax :
        XRSET
   Comments :
        The XRSET command resets the back trace history buffer. This
        command should be executed before setting a back trace range if
        there is unwanted instruction information in the back trace
        buffer.
   Example :
        XRSET
        This command resets the back trace buffer.

Save/restore/compare interrupt vectors

   Syntax :
        VECS [C|S|R]
        C :
             Compare current table with stored table
        S :
             Save current interrupt table to buffer
        R :
             Restore interrupt table from buffer
   Comments :
        The VECS command allows you to save and restore the interrupt
        table to an internal Soft-ICE buffer. The actual table can also
        be compared to the stored table with the differences displayed.
        When the C option is used to compare the current interrupt vector
        table with the stored copy the output is in the following format:
        address old-vector new-vector
        Each vector that has changed is displayed.
        The interrupt vector table is initially stored when Soft-ICE is
        loaded. It is also automatically stored when a program loaded
        with LDR.EXE. Only one copy of the interrupt vector table is
        stored, so each time VECS S is executed, previous copy of the
        interrupt table is overwritten.
        If no parameters are specified, the entire interrupt vector table
        is displayed.
   Example :
        VECS C
        This command compares the actual interrupt vector table with one
        that had been previously stored in the Soft-ICE internal VECS
        buffer.

Take snap shot of memory block

   Syntax :
        SNAP [C | S | R] address1 address2
        C :
             Compare buffer with address range
        S :
             Save address range to buffer
        R :
             Restore buffer to address range
   Comments :
        The SNAP command takes a snap shot of a memory block for later
        comparison. The S option copies a block of memory to a buffer in
        extended memory. The C option displays differences between the
        buffer in extended memory and the actual memory specified by the
        address range. The R option copies the buffer in extended memory
        to the address range in conventional memory.
        When the C option is used to compare the buffer with the address
        range the output is in the following format :
        address old-data new-data
        Each byte that has changed is displayed.
        The address is usually not necessary for the C and R options. If
        the address is not specified, the address from the last time SNAP
        was entered with a specified address used.
   Notes :
        To use the SNAP command you must have specified the /TRA XXXX
        switch on the S-ICE.EXE line in CONFIG.SYS.
        The SNAP command saves data in the back trace history buffer. If
        you are using back trace then you will have a conflict with SNAP.
        Specifically, SNAP will overwrite back trace information if you
        do a SNAP S when instruction history is in the back trace buffer.
        Conversely, if you have saved a region with SNAP, then enabling a
        back trace range will overwrite the SNAP buffer.
   Example :
        SNAP S 2000:0 4000:0
        This command stores the data block from 2000:0 to 4000:0 in the
        Soft-ICE back trace buffer.

Display EMM allocation map

   Syntax :
        EMMMAP
   Comments :
        The EMMMAP command displays each physical page that is available
        for EMM memory and the pages that are currently mapped in.
        Note :
        The Soft-ICE EMM feature must be enabled to use this function.
        See chapter 8 for more information on enabling EMM capability.
   Example :
        EMMMAP
        This example displays the current EMM allocation in in the
        following form.
         Phy page Seg address Handle/Page
         00 D000 FFFF
         01 D400 0001/0000
         02 D800 0001/0001
         03 DC00 0001/0002
        In this example, physical page 0 is located at D000 and is
        unmapped. Physical page 1 is located at D400 and has handle 1,
        page 0 mapped into it. Physical page 2 is located at D800 and has
        handle 1, page I mapped into it. Physical page 3 is located at
        DC00 and has handle page 2 mapped into it.

05.07 Windowing Commands

   WR Toggle register window
   WC Toggle/set size of code window
   WD Toggle/set size of data window
   EC Enter/exit code window
   . Locate current instruction
   Three window types may be created with Soft-ICE: register, data, and
   code. Any of these windows can be toggled on or off at any time. The
   data and code windows can be of variable size; the register window is
   fixed in size. The windows always remain in a fixed order. Starting
   from the top of the screen, the order is register window, data window,
   then code window.

Toggle register window

   Syntax :
        WR
   Comments :
        The command makes the register window visible if not currently
        visible. If the register window is currently visible, WR removes
        the register window.
        The register window displays the 8086 register set and the
        processor flags. Default Function: F2

Toggle/set size of code window

   Syntax :
        WC [window-size]
        Window-size :
             a decimal number between one and 21.
   Comments :
        If window-size is not specified, this command toggles the code
        window. If it was not visible it is made visible, and if it was
        visible it is removed.
        If window-size is specified the code window is resized, or it was
        not visible it is made visible with the specified size.
   Note :
        If you wish to move the cursor to the code window use the EC
        command. See description of the EC command for more details.
   Example :
        WC 12
        If no code window is present, then a code window 12 lines in
        length is created. If the code window is currently on the screen,
        it is resized to 12 lines.

Toggle/set size of data window

   Syntax :
        WD [window-size]
        Window-size :
             a decimal number between one and 21.
   Comments :
        If window-size is not specified, this command toggles the data
        window. If it was not visible it is made visible, and if it was
        visible it is removed.
        If window-size is specified the data window is resized, or it was
        not visible it is made visible with the specified size.
   Example :
        WD 1
        If no data window is present then a data window of one line is
        created. If the data window is currently on the screen, it is
        resized to one line.

Enter/exit code window

   Syntax :
        EC
   Comments :
        The EC command toggles the cursor location between the code
        window and the command window. If the cursor was in the command
        window it is moved to the code window, and if the cursor was in
        the code window it is moved to the command window.
        When the cursor is in the code window several options become
        available that make debugging much easier. The options are:
        Point-and-shoot break points.Point-and-shoot break points are set
        with the BP command. If no parameters are specified with the BPX
        command an execution break point is set at the location of the
        cursor position in the code window. The cursor must be on a line
        that contains code (place the code window in mixed mode if you
        are unsure). The default function key assignment for BPX is F9.
        Go to cursor line.You can set a temporary break point at the
        cursor and go with the HERE command. The cursor must be on a line
        that contains code (place the code window in mixed mode if you
        are unsure). The default function key assignment for HERE is F7.
        Scrolling the code window.The code window can be scrolled only
        while the cursor is in the code window. The scrolling keys (UP
        arrow, DOWN arrow, PageUp and PageDown) are redefined while the
        cursor is in code window. When the cursor is in the code window
        the scrolling keys do the following:
        up        Scroll code window up one line
        down      Scroll code window down one
        pageup    Scroll code window up one window
        pageDn    Scroll code window down one window<
   Note :
        The code window must be visible for the EC command to work.
        Default Function Key: F6

Locate current instruction

   Syntax :
        .
   Comments :
        When the code window is visible, the . command makes the current
        source line or current instruction visible.

05.08 Debugger Customization Commands

   PAUSE Pause after each screen
   ALTKEY Set alternate key sequence to invoke Soft-ICE
   FKEY Show and edit function keys
   BASE Set/display current radix
   CTRL-P Toggle log session to printer
   Print-Screen Print contents of screen
   PRN Set printer output port

Pause after each screen

   Syntax :
        PAUSE [ON | OFF]
   Comments :
        PAUSE controls screen pause at the end of each page. If PAUSE is
        ON, you are prompted to press any key before information is
        scrolled off the window. The prompt is displayed in the status
        line at the bottom of the window.
        If noparameter is specified, the current state of PAUSE is
        displayed.
        The default is PAUSE mode ON.
   Example :
        PAUSE ON
        This command specifies that subsequent window display commands
        will cause the screen to wait for you to press a key before
        scrolling new information off the window.

Set alternate key sequence to invoke Soft-ICE

   Syntax :
        ALTKEY [ALTletter] | [CTRLletter] | [SYSREQ]
        Letter :
             Any letter (A - Z)
   Comments :
        The ALTKEY command allows the key sequence for popping up
        Soft-ICE to be changed. The key sequence be changed to CTRL +
        letter, ALT + letter, or the SysRq key.
        Occasionally you may be using a program that conflicts with the
        CTRL D key sequence that brings up the Soft-ICE window. One way
        to circumvent this possible problem is to use the ALTKEY command
        to change the key sequence. Another way is to add the SHIFT key
        to the current sequence. Soft-ICE does not respond to this key
        sequence and allows it to go through to your program. For example
        if a resident program you are using is brought up with the CTRL D
        key sequence, try using the key sequence CTRL SHIFT D to bring up
        your resident program. On some keyboards, you must press ALT and
        the prtsc key simultaneously to generate a system request. Care
        must be taken so the screen is not printed accidentally.
        If no parameter is specified, the current key sequence state is
        displayed. The default key sequence is CTRL D.
   Example :
        ALTKEY ALT Z
        This command specifies that the key sequence ALT Z will now be
        used to pop up the Soft-ICE window.

Show and edit function keys

   Syntax :
        FKEY [function-key-name string]
        function-key-name :
             F1, F2... F12
        string :
             The string consists of any valid Soft-ICE commands and the
             special character ^ (caret) and ; (semicolon). A ^ is placed
             in the string to make a command invisible. A ; is placed in
             the string to denote a carriage return.
   Comments :
        The FKEY command is used from the command line to assign a
        function key to a command string. Function key can be assigned to
        any command string that can be typed into Soft-ICE.
        If no parameters are specified, then the current function key
        assignments are displayed.
        To unassign a specified function key, use the FKEY command with
        these parameters: a function-key-name followed by a null string.
        The function keys can also be pre-initialized in the definition
        file S-ICE.DAT. For more information on function key definitions
        in the definition file, refer to section 6.4.
        Using carriage return symbols in a function key assignment string
        allows you to assign a function key a series of commands. A
        carriage return is represented by a ; (semicolon).
        If you put ^ (shift 6) in front of a function key definition, the
        subsequent command will be invisible. The command will function
        as normal, but all information displayed in the command window
        (including error messages) is suppressed. The invisible mode is
        useful when a command changes information in a window (code,
        register or data) but you do not want to clutter the command
        window, when a function key is made invisible with ^, the
        function key can be used in the middle of typing in other command
        without affecting their operation. For example, if you are using
        the default assignment for F2, you can toggle the register window
        with F2 even if you are partially through typing in your next
        command.
   Note :
        Soft-ICE now has a definition file named S-ICE.DAT. You can place
        function key assignments in this file so that function keys will
        be automatically assigned when Soft-ICE is loaded. The syntax for
        assigning a function key in the configuration file is:
        function-key-name = "string"
        When assigning function keys to a command string in S-ICE.DAT,
        the string must be enclosed in double quotes.
   Command line examples :
        FKEY F2 ^WR;
        This example will assign the toggle register window command to
        the F2 key. The ^ makes the function invisible, and the ; ends
        the function with a carriage return. The F2 key will toggle the
        register window on or off, and can even be evoked while typing in
        another command.
        FKEY F1 "G CS:120; R; G CS:"
        This example shows that multiple commands can be assigned to a
        single function key and that partial commands can be assigned for
        the user to complete. After this command is entered, pressing the
        F1 key will cause the program to execute until location CS:120 is
        reached, display the registers, then start the G command for the
        user to complete.
        FKEY F1 WD 3;D DS:100;
        This example will assign a series of commands to the F1 key. The
        function is visible, and ends with a carriage return. The F1 key
        will make the data window three lines long and dump data starting
        at DS:100.
   S-ICE.DAT example:
        F1 = "WR;WD 2;WC 10;"
        If this line is placed in S-ICE.DAT, when Soft-ICE is loaded it
        will assign the string to the F1 key. When F1 is pressed while in
        Soft-ICE, it will toggle the register window, create a data
        window of length 2 and a code window of length 10. For more
        information about assigning function key definitions in
        S-ICE.DAT, refer to chapter 6.

Set/display current radix

   Syntax :
        BASE [10 | 16]
   Comments :
        The BASE command sets the current radix to base 10 or base 16.
        Base 10 is of limited use in the narrow window because of window
        width limitations. It also limits the amount of information
        displayed in some commands in the wide mode.
        When the current radix is base 10, all numbers and addresses
        typed into and displayed by Soft-ICE are in decimal, When the
        current radix is base 16, all numbers and addresses typed into
        Soft-ICE are in hexadecimal except for the source line numbers
        and the screen coordinates and sizes in the WIN command
        These exceptions are always typed in and displayed as decimal
        numbers. The default radix is base 16.
   Example :
        BASE 16
        This example sets the current radix to base 16.

Toggle log session to printer

   Syntax :
        CTRL-P
   Comments :
        When the CTRL key followed by the P key is pressed, all
        subsequent information displayed in the command window is also
        sent to the printer. To turn the log to printer mode off, type
        CTRL followed by P again.
        When you are sending a lot of information to the printer using
        CTRL-P, you may want to turn the PAUSE command OFF to allow
        information to scroll off the window without pressing a key.

Print contents of screen

   Syntax :
        Print-Screen
   Comments :
        Depressing the print-screen key does a screen dump to printer.
        All information from the screen is sent the printer.
        If you wish to print the memory map or help information is
        usually much faster to use CTRL-P than Print-Screen. This is
        because Print-Screen prints every character on the screen
        including borders.

Set printer output port

   Syntax :
        PRN [LPTx | COMx]
        x :
             a decimal number between 1 and 4.
   Comments :
        The PRN command allows you to send output from the CTRL-P and
        Print-Screen commands to a different printer port.
        If no parameters are supplied, PRN displays the currently
        assigned printer port.
   Example :
        PRN COM 1
        This command causes the CTRL-P and Print-Screen command output to
        go to the COM 1 port.

05.09 Screen Control Commands

   FLASH Restore screen during P and T
   FLICK Screen flicker reduction
   WATCHV Set watch video mode
   RS Restore program screen
   CLS Clear window
   ALTSCR Change to alternate screen
   WIN Change size of Soft-ICE window

Restore screen during P and T

   Syntax :
        FLASH [ON | OFF]
   Comments :
        The FLASH command lets you specify whether the screen will be
        restored during any Trace and Program step commands. If you
        specify that the screen is to be restored it is restored for the
        brief time period that the P or T command is executing. This
        feature is needed to debug sections of code that access video
        memory.
        If the P command executes across a call or an interrupt, the
        screen will always be restored, because the routine being called
        may write to the screen.
        If no parameter is specified, the current state of FLASH is
        displayed.
        The default is FLASH mode OFF.
   Example :
        FLASH ON
        This command turns on FLASH mode. The screen will be restored
        during any subsequent P or T commands.

Screen flicker reduction

   Syntax :
        FLICK [ON | OFF]
   Comments :
        Certain types of video cards require waiting for horizontal or
        vertical retrace before outputting characters. If the video
        writes are made arbitrarily, flickering will appear while
        displaying characters. If flickering occurs on your screen while
        using the Soft-ICE window, you should turn FLICK on.
        With some EGA cards, colors will not be restored properly when
        you exit from Soft-ICE. This is a problem with virtualizing EGA
        video. The port 3DA is a video port used for two purposes. The
        first is old CGA software polling 3DA for hsync and vsync. This
        allows them to have flicker free output on some old CGA
        controller cards. The second is that it is used to reset a
        palette latch on EGA cards. Soft-ICE has an algorithm to avoid
        having to constantly watch this port, which would slow down old
        programs that think they are on a CGA. However, there can
        occasional be circumstances where this algorithm does not work.
        If you are using Soft- ICE on an EGA screen and you notice that
        the colors are not restored correctly, then turn FLICK ON and
        Soft-ICE will watch the 3DA port, fixing the problem.
        When FLICK mode is ON, screen update will be slower.
        If no parameter is specified, the current state of FLICK is
        displayed.
        The default is FLICK mode OFF.
   Example :
        FLICK ON
        This command turns on FLICK mode. This causes Soft-ICE to wait
        for the horizontal or vertical retrace before outputting
        characters.

Set watch video mode

   Syntax :
        WATCHV [ON | OFF]
   Comments :
        The WATCHV command allows you to specify how Soft-ICE should
        watch the video ports. Normally, Soft-ICE only watches video
        ports after an INT 10 instruction has been executed that switches
        to a non-character video mode. Some programs do not use INT 10 to
        switch modes. In these cases, if WATCHV is OFF, Soft-ICE may have
        trouble saving and restoring the screen properly. Turning WATCHV
        ON will cause Soft-ICE to watch the video ports all the time.
        Turn WATCHV ON if you notice that Soft-ICE is not handling your
        screen properly, or if the cursor is not being restored properly.
        Turning WATCHV ON may have a performance impact in certain video
        modes.
        If no parameter is specified, the current state of WATCHV is
        displayed.
        The default is WATCHV mode OFF.
   Example :
        WATCHV ON
        This command turns on WATCHV mode. This causes Soft-ICE to watch
        additional video ports for the purpose of virtualization.

Restore program screen

   Syntax :
        RS
   Comments :
        The RS command allows you to restore the program screen
        temporarily. The Soft-ICE window disappears until any key is
        pressed.
        This feature is useful when debugging graphic programs that
        update the screen frequently. When Soft-ICE is brought up, it
        returns to text mode. Using the RS command temporarily restores
        the graphics screen.
   Example :
        RS

Clear window

   Syntax :
        CLS
   Comments :
        The CLS command clears the Soft-ICE window and moves the prompt
        and the cursor to the upper left-hand corner the window.
   Example :
        CLS

Change to alternate screen

   Syntax :
        ALTSCR [ON | OFF]
   Comments :
        The ALTSCR command allows you to redirect the Soft-ICE output
        from your default screen to the alternate screen. This feature is
        useful, for instance, when you want to debug a graphics program
        without having to switch between the Soft-ICE window and the
        graphics display.
        ALTSCR requires the system to have two monitors attached. The
        alternate monitor should be in a character mode, which is the
        default mode for monitors.
        The default is ALTSCR mode OFF.
   Example :
        ALTSCR ON
        This command redirects screen output to the alternate monitor.

Change size of Soft-ICE window

   Syntax :
        N :
             When N is specified, the window will be set to the narrow
             width : 46 characters.
        W :
             When W is specified, the window will be set to full screen
             width
        start-row :
             Number from 0 to 17 specifying row where window display
             starts.
        length :
             Number from 8 to 25 specifying how many lines tall you want
             the window to be.
        start-column :
             Column position of the left side of narrow window. The
             start-row and start-column specify the upper left hand
             corner of the narrow window. The start-column is ignored if
             applied to the wide window.
   Comments :
        The WIN command allows you to modify the width and height of the
        Soft-ICE display window.
        If no parameters are specified, this command toggles the window
        between wide and narrow screen display modes.
        If the WIN command is specified with only the N or the W
        parameter, the window size will be changed to the requested width
        at the current height.
        If the number of lines plus the starting row number is larger
        than25, the window length goes to the bottom of the screen.
        The default is WIN mode narrow.
   Examples :
        WIN N 4 9 30
        This command causes the window display to start at row 4 and
        column 30, and to be 9 rows tall and 46 characters wide.
        WIN
        This command toggles the window display width from its current
        state (either wide or narrow) to the opposite state.
        WIN W 10 8
        This command causes the window display to start at row 10, and to
        be 8 rows tall and go the width of the screen.

05.10 Symbol and Source Line Commands

   SYM Display/set symbol
   SYMLOC Relocate symbol base
   SRC Toggle between source, mixed and code
   FILE Change/display current source
   SS Search current source file for string

Display/set symbol

   Syntax :
        SYM [symbol-name [value]]
        symbol-name :
             A valid symbol name. The symbol name can end with an *
             (asterisk). This allows searching if only the first part of
             the symbol name is known. The , (comma) character can be
             used as a wild card character in place of character in the
             symbol-name.
        value :
             This is a word value that is used if you want to set a
             symbol to a specific value.
   Comments :
        The SYM command allows displaying and setting of symbols. If SYM
        is entered with no parameters all symbols are displayed. The
        value of each symbol is displayed next to the symbol name.
        If a symbol name is specified with no value then the symbol name
        and value are displayed. If the symbol name was not found then
        nothing is displayed.
        The SYM command is often useful for finding a symbol name when
        you can only remember a portion of the name Two wild card methods
        are available for locating symbols. If symbol-name ends with an
        *, then all symbols that match the actual characters typed prior
        to the * will be displayed regardless of their ending characters.
        If a , is used in place of a specific character in symbol-name,
        that character is a wild card character.
        If value is specified, all symbols that match symbol-name are set
        to the value. All symbols have word values.
   Examples :
        SYM FOO*
        All symbols that start with FOO are displayed.
        SYM FOO* 6000
        All symbols that start with FOO are given the value 6000.

Relocate symbol base

   Syntax :
        SYMLOC segment-address
   Comments :
        The SYMLOC command relocates the segment components of all
        symbols relative to the specified segment address. This function
        is necessary when debugging loadable device drivers or other
        programs that can not be loaded directly with LDR.EXE.
        When relocating for a loadable device driver, use the value of
        the base address of the driver as found in the MAP command. When
        relocating for an .EXE program, the value is 10H greater than
        that found as the base in the MAP command. When relocating for a
        .COM program, use the base segment address that is found in the
        MAP command.
        The MAP command will display at least two entries for each
        program. The first is typically the environment and the second is
        typically the program. The base address of the program is the
        relocation value.
   Example :
        SYMLOC 1244 + 10
        This will relocate all segments in the symbol table relative to
        1244. The + 10 is used to relocate a TSR that was originally a
        .EXE file. If it is a .COM file the + 10 is not necessary.

Toggle between source, mixed and code

   Syntax :
        SRC [?]
   Comments :
        The SRC command toggles between source mode, mixed mode and code
        mode in the code window.
        If SRC ? is entered, the current state is displayed.
   Example :
        SRC
        This command changes the current mode of the code window. If the
        mode was source, it becomes mixed. the mode was mixed, it becomes
        code. If the mode was code, it becomes source. Default-Function
        Key: F3

Change/display current source file

   Syntax :
        FILE [file-name]
   Comments :
        If a file-name is specified, that file becomes the current file
        and the start of the file is displayed in the code window. If no
        name is specified, the name of the current source file (if any)
        is displayed.
        The FILE command is often useful when setting a break point on a
        line that has no associated public symbol. Use file to bring the
        desired file into the code window, use the SS command to locate
        the specific line, move the cursor the specific line, then type
        BPX to set the break point.
   Note :
        Only source files that have been loaded into extended memory with
        LDR.EXE are available with the FILE command.
   Example :
        FILE MAIN.C
        If MAIN.C had been loaded with LDR.EXE, this command brings it up
        in the code window starting with line 1.

Search current source file for string

   Syntax :
        SS [line-number] [' string']
        Line-number :
             a decimal number
        String :
             a character string surrounded by quotes. The quotes can be
             either single quotes or double quotes.
   Comments :
        The SS command searches the current source file for the specified
        character string. If there is a match, the line that the string
        was located in will be displayed as the top line in the code
        window.
        The search starts at the specified line number. If no line number
        is specified the search starts at the top line displayed in the
        code window.
        If no parameters are specified, the search continues for the
        previously specified string.
   Note :
        The code window must be visible and in source mode before using
        the SS command.
   Example :
        SS 1 'if (i = = 3)'
        The current source file is searched starting at line 1 for the
        string 'if (i = = 3)'. The line containing the next occurrence of
        the string becomes the top line displayed in the code window.

CHAPTER 6 - Soft-ICE Initialization Options

   06.01 Introduction
   06.02 Loading Soft-ICE from the DOS Prompt
   06.03 Loading Soft-ICE as a Loadable Device Driver
   06.03.01 Soft-ICE Loading Switches
   06.04 The Soft-ICE Initialization File S-ICE.DAT
   06.04.01 Special Configuration Options
   06.04.02 Function Key Assignments
   06.04.03 Initialization Command Sequence

06.01 Introduction

   The Soft-ICE program file (S-ICE.EXE) can be loaded as a loadable
   device driver in CONFIG.SYS or as a program from the DOS command line.
   To get the full power of Soft-ICE, it must be initially loaded as a
   device driver in CONFIG.SYS. However, there may be circumstances when
   you might want to run Soft-ICE from the DOS prompt or a batch file,
   such as:
  • You do not have extended memory in your system Soft-ICE can only

load as a loadable device driver if you have extended memory.

  • You want to take up ZERO bytes of conventional memory. When

loaded as a device driver, Soft-ICE occupies approximately 2K of

        conventional memory.
  • You only need to use Soft-ICE occasionally and there are no other

programs using extended memory. In some cases you may need some

        of the features that require Soft-ICE to be loaded in CONFIG.SYS
        but do not want Soft-ICE to be resident all of the time. In this
        case Soft-ICE can be loaded in CONFIG.SYS to reserve extended
        memory, and then disabled, by using the /UN switch, until Soft-
        ICE is required. See section 6.3.1 for more information about the
        /UN switch.

06.02 Loading Soft-ICE from the DOS Prompt

   You can NOT enable all of Soft-ICE's features when loading from the
   DOS prompt. If you will be using Soft-ICE as a stand-alone debugger,
   it is recommended you load Soft-ICE in the CONFIG.SYS file.
   To load Soft-ICE from the DOS prompt type:
   S-ICE
   In systems with no extended memory present, Soft-ICE loads itself at
   the highest memory location possible. The memory used by Soft-ICE is
   then 'mapped out', making it invisible to DOS programs. Since the
   total memory visible to DOS and its programs is less after Soft-ICE
   loads, it is recommended that you load Soft-ICE before any TSR's
   control programs.
   In systems with extended memory, you should only load Soft-ICE from
   the DOS prompt if you are not using extended memory for anything else
   (e.g., VDISK, CACHE, HIMEM...). When you initially load Soft-ICE from
   the command line or from a batch file, Soft-ICE will prompt you with a
   warning message. This warning message is just to remind you that
   Soft-ICE will overwrite the highest portion of extended memory when it
   loads. You can suppress this warning prompt with the EXTENDED option
   in the Soft-ICE configuration file S-ICE.DAT. For more information
   about the EXTENDED option, see section 6.4.1.

06.03 Loading Soft-ICE as a Loadable Device Driver

   In order to use all of the Soft-ICE features, you must first load
   Soft-ICE as a loadable device driver in your CONFIG.SYS file. The
   features this makes possible are:
  • Coexisting with other software that uses extended memory. Loading

as a device driver allows Soft-ICE to manage extended memory so

        you can run Soft-ICE with programs that use extended memory, such
        VDISK, CACHE and HIMEM.
  • Symbolic and source level debugging Loading as a device driver

allows Soft-ICE to allocate an extended memory buffer for symbols

        and source information.
  • Back trace ranges and the SNAP command Loading as a device driver

allows Soft-ICE to allocate an extended memory buffer for a back

        trace buffer. This buffer is also used for the Soft-ICE SNAP
        command.
  • Enabling Soft-ICE's EMM 4.0 capability
  • Running Soft-ICE with MagicCV or MagicCVW
   Note : When loaded as a device driver in CONFIG.SYS, Soft-ICE
   allocates the highest portion of extended memory for itself and its
   associated components, so there can be no memory conflicts. S-ICE.EXE
   must be loaded in CONFIG.SYS before any other driver that allocates
   extended memory loaded (e.g., VDISK.SYS, RAMDRIVE.SYS). Generally
   Soft-ICE works best if it is the first loadable device driver
   installed in CONFIG.SYS.

06.03.01 Soft-ICE Loading Switches

   One or more loading switches can follow S-ICE.EXE in CONFIG.SYS. These
   switches allow you to customize the way extended memory will be
   reserved by Soft-ICE. The switches all must begin with a / character.
   The loading switches are:
  • /EXT XXXX: Informs S-ICE.EXE to reserve XXXX Kilobytes of

extended memory for other DOS programs that use extended memory

        (e.g., VDISK, CACHE, HIMEM,...). If the /EXT switch is not
        present, then any extended memory not used by Soft-ICE and its
        associated components will be left as standard extended memory,
        but the amount can not be guaranteed. The /EXT switch is useful
        because it is sometimes difficult to determine exactly how much
        memory being used by Soft-ICE and its associated components.
        Using the /EXT switch will guarantee a specified amount is
        available for other programs that use extended memory.
  • /SYM XXXX: Informs S-ICE.EXE to reserve XXXX Kilobytes of

extended memory for symbols and source usage. If XXXX is not

        specified, then all remaining extended memory is used for
        symbols. Enough memory must be allocated for your .SYM file and
        all source files. For more information about using symbols and
        source, see chapter 7.
  • /TRA XXXX: Informs S-ICE.EXE to reserve XXXX Kilobytes of

extended memory for a back trace history buffer. This buffer is

        used for back trace ranges and for the SNAP command. If XXXX is
        not specified, then 10K of extended memory is automatically
        reserved for the buffer. If you do not want any memory reserved
        for a back trace buffer, use /TRA 0. For more information about
        using back trace ranges, see chapter 9.
  • /MCV XXX: Informs S-ICE.EXE to reserve XXX Kilobytes of extended

memory for MagicCV or MagicCVW. The minimum amount of extended

        memory you can specify is 280K and the maximum is 620K. If XXX is
        not specified, S-ICE.EXE will reserve the remaining memory,
        between 280K and 620K. See chapter 10 for more information about
        running Soft-ICE with MagicCV or MagicCVW.
  • /EMM XXXX: Informs S-ICE.EXE to turn XXXX Kilobytes of extended

memory into EMM 4.0 conforming expanded memory. If XXXX is

        specified, then all remaining memory is used as expanded. See
        chapter 8 for more information about expanded memory support.
  • /UN: Informs S-ICE.EXE to enter protected mode, reserve any

needed extended memory, then exit protected mode and unload

        itself. This switch should be used when you are loading S-ICE.EXE
        as a loadable device driver, but you don't want your system to
        remain in protected mode. This switch will reserve memory for
        Soft-ICE, and you must execute S-ICE.EXE from the DOS prompt when
        you are ready to use Soft-ICE.
   Soft-ICE reserves extended memory in the following order, regardless
   of the order the switches are specified:
  • Reserve approximately 120K for S-ICE.EXE.
  • Reserve memory for the /EXT switch if present.
  • Reserve memory for the /SYM switch if present.
  • Reserve memory for the /TRA switch if present. If it is not

present, default to reserve 10K for the back trace buffer.

  • Reserve memory for the /MCV switch if present.
  • Reserve memory for the /EMM switch if present.
   If available memory runs out while trying to reserve memory for a
   switch in the above sequence, then S-ICE.EXE does the following:
   1. The remaining extended memory is allocated to switch being
   processed when memory runs out.
   2. No memory will be reserved for the remaining switches.
   Note : If the /MCV or /EMM switch is present, a additional 64K of
   extended memory is reserved for a DMA holding buffer.
   The switches can be placed in any order following DEVICE = S-ICE.EXE.
   example is:
   DEVICE = S-ICE.EXE /TRA50 /EMM 500 /SYM 2048
   If four megabytes of extended memory are available, this example will
   reserve approximately 120K for Soft-ICE, 2 megabytes for symbols, 50K
   for a back trace history buffer, 500K for expanded memory and leave
   approximately 1.3 megabytes for other extended memory programs. Note
   that Soft-ICE will load into the highest portion of extended memory,
   leaving the remaining memory starting at 100000H (one megabyte mark).

06.04 The Soft-ICE Initialization File S-ICE.DAT

   Soft-ICE has several load options. These options are specified by
   placing special commands in an initialization file named S-ICE.DAT.
   S-ICE.DAT is an ASCII text file that Soft-ICE parses at load time.
   This file can contain function key assignment an auto-start string and
   various configuration options. The file can be created and edited with
   any DOS text editor. When loading Soft-ICE from the command line,
   S-ICE.DAT must be placed in the current directory or in a directory
   that is accessible through your current PATH. When Soft-ICE is loaded
   as a device driver in CONFIG.SYS, S-ICE.DAT must be in the same
   directory where S-ICE.EXE is located.
   There are three categories of commands that can be included in the
   S-ICE.DAT initialization file:
  • Special configuration options
  • Function key assignments
  • Initialization command sequence

06.04.01 Special Configuration Options

   Any of the following configuration options that are needed should each
   be placed on a separate line in the S-ICE.DAT file.
  • COMPAQ: Compaq 386 and 386SX computer and some Compaq compatible

computers (including computers containing Micronix motherboards)

        have 384K of non-contiguous extended memory. The COMPAQ option is
        necessary if you want Soft-ICE to use this memory. Note that the
        COMPAQ option is the same as the /C command line parameter in
        Soft-ICE 1.X.
  • NOLEDS: The NOLEDS option tells Soft-ICE not to set and clear the

keyboard LEDs while the Soft-ICE window is up. On some keyboards

        the are timing problems that will cause Soft-ICE to lose
        synchronization with the keyboard. If Soft-ICE hangs when you are
        in the Soft-ICE window use this option. Note that the NOLEDS
        option is the same as the /L command line parameter in Soft-ICE
        1.X.
  • NOTVGA: The NOTVGA option allows Soft-ICE to run on BIOS

compatible VGA cards. Many VGA cards are not compatible with IBM

        VGA at the hardware level. These cards support VGA at the BIOS
        level only. Use this switch if you have one of those video
        adapters. Note that the NOTVGA option is the same as the /V
        command line parameter in Soft-ICE 1.X.
  • EXTENDED: The EXTENDED option causes Soft-ICE to load directly

into extended memory without prompting the user with a warning

        message. It should be used if you are loading Soft-ICE initially
        from the DOS prompt and do want to be prompted, and you know
        nothing else using extended memory. Note that the EXTENDED option
        is the same as the /E command line parameter in Soft-ICE 1.X.

06.04.02 Function Key Assignments

   One or more Soft-ICE commands can be assigned to any function key at
   load time. See the description of the FKEY command in section 5.8
   (Debugger Customization Commands) for a description of assigning
   function keys from the Soft-ICE command line.
   The syntax for assigning a function key name in S-ICE.DAT is :
   Function-key-name = "string"
   Function-key-name : F1, F2... F12.
   String : The string may consist of any valid Soft-ICE commands and the
   special characters ^ and ;. A ^ is placed in the string to make a
   command invisible. A ; is placed in the string denote a carriage
   return. The string must be enclosed in double quotes.
   An example function key assignment in S-ICE.DAT is:
   F12 = "D 100;"
   This will assign the Soft-ICE dump command to function key 12. When
   F12 is pressed Soft-ICE will dump at offset 100H in the current data
   segment. The semi-colon following the 100 represents the ENTER key.

06.04.03 Initialization Command Sequence

   A sequence of commands can be automatically executed when Soft-ICE
   loads. This is useful for customizing Soft-ICE to meet your needs. For
   example, you might set up windows and change the default hot key
   sequence. The syntax for setting up an initialization command sequence
   in S-ICE.DAT is:
   INIT = "assignment-string"
   Assignment string : The string consists of any valid SoftICE cmd and
   the special characters ^ and ;. A ^ is placed in the string to make a
   command invisible. A; is placed in the string denote a carriage
   return. The string must be enclosed in double quotes.
   An example initialization command sequence in S-ICE.DAT is:
   INIT = "WIN; WR; WD 1; WC 12; ALTKEY CTRL X;"
   This example will put the Soft-ICE window in full screen mode, create
   a register window, create a data window one line long, create a code
   window 12 lines long, and change the hot key sequence to CTRL X.
   Sample S-ICE.DAT : A sample S-ICE.DAT initialization file is included
   on the distribution diskette. This sample assigns the function keys so
   they are used in a similar manner as the function keys in Microsoft's
   CodeView debugger. This sample S-ICE.DAT should also be used as is for
   the tutorial in chapter 3.

CHAPTER 7 - Symbolic and Source Level Debugging

   07.01 Introduction
   07.02 Preparing for Symbolic or Source Debugging
   07.02.01 Preparing for Symbolic Debugging Only
   07.02.02 Preparing for Symbolic and Source Level Debugging
   07.03 Reserving Memory for Symbols and Source Files
   07.04 Loading Programs and Symbol Files
   07.04.01 Loading Program, Symbols and Source
   07.04.02 Loading Only Symbols and Source Files
   07.04.03 Loading a Program With No Symbols or Source
   07.05 Debugging With Symbols
   07.06 Debugging With Source
   07.06.01 Using Line Numbers
   07.06.02 Using Source Mode in the Code Window

07.01 Introduction

   Soft-ICE can load programs, symbol tables and source files for
   enhanced debugging. Symbolic debugging allows you to set break points
   and reference variables with symbol names rather than specifying
   numeric addresses. Source level debugging allows you to step through
   your program at the source code level rather than assembly code level.
   Symbol and source line number information is extracted from the link
   map file. The link map must be compatible with Microsoft's linker
   version 3.60 or greater.
   Symbols and source files reside in extended memory. You must have
   sufficient extended memory for the symbols and source files. Source
   files are not paged from the disk as in many debuggers. This allows
   Soft-ICE to provide complete system debugging in source level, You can
   debug T&SR's interrupt routines and other systems level code at the
   source level.
   Note : You cannot use symbolic or source level debugging unless
   Soft-ICE has been loaded as a device driver in CONFIG.SYS.

07.02 Preparing for Symbolic or Source Debugging

   Before debugging a program with symbols or source you must create a
   symbol file. This is a binary file that contains symbol and line
   number information in a format that Soft-ICE can understand. This file
   is created with the utility MSYM.EXE. MSYM.EXE reads in your link map
   to create a symbol file with the extension (.SYM).

07.02.01 Preparing for Symbolic Debugging Only

   To prepare a program for symbolic debugging only, you must do the
   following steps:
   1. Compile or assemble your program.
   2. Link your program with the proper switches to create a .MAP file
   that contains a list of public symbols. If you are using Microsoft's
   linker, the /MA switch is the proper switch to use. This .MAP file
   must be identical to the .MAP file produced by Microsoft's linker,
   version 3.60 or greater.
   3. Create a.SYM file by running MSYM.EXE. The syntax for using
   MSYM.EXE is:
   MSYM program-name [.extension]
   If the extension is not supplied MSYM assumes the extension is .MAP.
   MSYM reads in a map file as in and writes out a symbol file as output.
   The symbol has the name program-name.SYM.
   Note : Before compiling or assembling your program you may want to
   make some additional symbols public. Only public symbols are supported
   with Soft-ICE symbolic debugging. The way to make a variable or a
   label public varies, depending upon which language you are using.
   In 8086 assembly language, simply use the PUBLIC directive followed by
   the locally defined symbols you wish to make public. For example:
   PUBLIC FOO, LOOP1, STATUS
   In C language, all procedure names and static variables are defined
   outside a block are public.
   For other languages, refer to your language manual for details.

07.02.02 Preparing for Symbolic and Source Level Debugging

   To prepare a program for both symbolic and source debugging, you must
   do the following steps:
   1. Compile or assemble each module that you wish debug at the source
   level with the appropriate switch to put line number information into
   the object files. With Microsoft languages you can use either the /Zi
   or the /Zd switches. You may not want to do this with all files,
   because the combined file sizes of the symbol file and all the source
   files compiled with these switches must fit into the amount of
   extended memory you have reserved with the /SYM loading switch in
   CONFIG.SYS.
   2. Link your program with the proper switches to create a .MAP file
   that contains source line numbers and a list of public symbols. If you
   are using Microsoft's linker, the /LI and /MA switches are the proper
   switches to use. This .MAP file must be identical to the.MAP file
   produced by Microsoft's linker, version 3.60 or greater.
   3. Create a.SYM file by running MSYM.EXE. The syntax for using
   MSYM.EXE is :
   MSYM program-name [.extension]
   If the extension is not supplied MSYM assumes the extension is.MAP.
   MSYM reads in a map file as input and writes out a symbol file as
   output. The symbol file has the name program-name.SYM.

07.03 Reserving Memory for Symbols and Source Files

   Before loading programs, symbol files and source files you must
   reserve extended memory for them. Extended memory is reserved when you
   load Soft- ICE in CONFIG.SYS. Before reserving extended memory you may
   want to add up the file sizes of the .SYM file and all of the source
   files that you want to load. You must reserve at least this much
   extended memory. You must use the
   /SYM loading switch when loading S-ICE.EXE. A sample line in
   CONFIG.SYS for loading Soft-ICE and reserving space for symbols and
   source files is:
   DEVICE = S-ICE.EXE /SYM 1024
   This example loads Soft-ICE into extended memory and reserves 1
   megabyte of memory for symbols and source files. See section 6.3
   (Loading Soft-ICE as a Loadable Device Driver) for more details on
   reserving memory.

07.04 Loading Programs and Symbol Files

   The Soft-ICE utility LDR.EXE is used for loading programs, symbol
   files and source files. For symbolically debugging application
   programs and T&SR programs you will typically use LDR.EXE to load the
   program, symbols and source files in one step. For debugging loadable
   device drivers, ROMs and other system components you will typically
   use LDR.EXE to load the symbol file and source files only. The syntax
   for LDR.EXE is :
   LDR program-name | program-name.SYM | program-name.extension

07.04.01 Loading Program, Symbols and Source

   To load your program, symbols and source files in one step, you must
   use LDR.EXE in the form:
   LDR program-name
   Notice that program-name does not have a file extension. If no file
   extension is supplied, then LDR.EXE will do the following:
   1. Load program-name.SYM into extended memory
   2. Load source files into extended memory. This step is done only if
   source records exist in the .SYM file.
   3. Load program-name.EXE into memory at the location it would have
   loaded if it had been loaded directly from the DOS prompt.
   4. Bring up Soft-ICE with the instruction pointer at first instruction
   of your program. If it is a C program and source is loaded for the
   file containing , _MAIN, then the source for that file will be visible
   in the code window.

07.04.02 Loading Only Symbols and Source Files

   If you wish to load only symbols and source files (for debugging a
   loadable device driver for example) you must use LDR.EXE in the form:
   LDR program-name.SYM
   Notice that the.SYM extension is specified. This will load the .SYM
   file and source files into extended memory. When symbols are loaded by
   this method your program or device driver symbols are assumed to be
   referenced from 0:0. Since this is rarely the case you will need to
   use the Soft-ICE command SYMLOC to locate the symbols. See the
   description of the SYMLOC command in section 5.10 for a complete
   description. An example of loading a symbol file called DRIVER.SYM is:
   LDR DRIVER.SYM

07.04.03 Loading a Program With No Symbols or Source

   To load a program file without loading the associated symbol file you
   must use LDR.EXE in the form:
   LDR program-name.extension
   Notice that the file extension is present. Typically the file
   extension will be.EXE or.COM. When a file extension specified LDR.EXE
   will load the program and bring up Soft-ICE with the instruction
   pointer at the first instruction of the program. An example of loading
   a program with symbols and source is:
   LDR TEST.EXE
   Notes : LDR.EXE saves a copy of the interrupt vector table
   automatically when it loads your program. This is equivalent to doing
   a VECS S command. If you are going to exit your program before it runs
   to completion, you can do an EXIT R to exit the program and restore
   the interrupt vector table.
   Using LDR.EXE to load only the program-name.EXE is often useful for
   restarting your program while in the middle of a source level
   debugging session. To restart, the EXIT R command to abort the current
   session. Then use LDR.EXE to reload your.EXE file. The symbols: source
   do not have to be loaded since they remain in extended memory.
   If LDR.EXE gives you the message "Out of space loading symbol
   information", this means that you did not reserve enough extended
   memory with the /SYM loading switch in CONFIG.SYS.
   If LDR.EXE does not find your source files on the same directory as
   the program you are loading, LDR.EXE will prompt you for the path
   names where it can find the source files. If you have source files on
   several directories or are loading a program frequently this becomes
   cumbersome. You can eliminate the need for prompting by using the DOS
   environment variable SRC. LDR.EXE uses this environment variable to
   find source files before prompting the user. The syntax for setting
   the environment variable from the DOS prompt is:
   SET SRC = directory;directory;...;directory
   Each of the specified directories will be searched before the user is
   prompted.
   Limitations : Soft-ICE supports symbols for only one program at a
   time. If you load a new .SYM file, the existing one is overwritten.
   Soft-ICE does not follow overlays or Microsoft Windows segment
   movement. Soft-ICE recognizes public symbols and line numbers only. It
   does not support local variables.

07.05 Debugging With Symbols

   After you have loaded your program and.SYM file you can begin
   debugging your program symbolically. In general a symbol can be used
   in any command in place of an address.
   Symbols are also used by several Soft-ICE commands when addresses are
   displayed. For example, the U command displays symbol names of labels
   and procedures as it encounters them. There are two commands that are
   helpful when you are symbolically debugging:
   SYM: Use the SYM command to get a listing of symbol names and values,
   or to change the value a symbol.
   SYMLOC: Use the SYMLOC command to relocate the base of all of your
   symbols. You would need to use the SYMLOC command when:
   1. Loading symbols for a loadable device driver
   2. Loading symbols for a T&SR that has already been loaded
   3. Your program moves itself to a location other than it original
   location.
   See section 5. 10 for a complete description of these commands.

07.06 Debugging With Source

   When source files are loaded, Soft-ICE allows you to view and step
   through your source code as you are debugging. Soft-ICE offers two
   different modes of source level debugging: mixed mode and source mode.
   Use the SRC command to switch between modes.
   Mixed mode shows source lines and the assembly language produced by
   those source lines intermixed on the display. Mixed mode is useful
   when you must debug at the assembly level, but use the source lines
   for reference. Mixed mode is allowed whether the code window visible
   or not.
   Source mode strictly shows source lines on the display. Source level
   debugging requires the code window to be visible.

07.06.01 Using Line Numbers

   Line numbers can be used in place of addresses in several commands. To
   differentiate a line number from an actual address, place a . (period)
   in front of the number. For example, to set an execution break point
   at source line 45 type:
   BPX .450

07.06.02 Using Source Mode in the Code Window

   The code window must be visible to enter source mode. If not visible,
   use the WC command to make it visible. Once you are in source mode you
   can use Soft-ICE commands switch to a different source file, view
   source at any location in the file, scroll through the file, search
   for strings in the file, and set break points in the file. For a
   complete description of the following commands see their command
   descriptions in chapters 4 and 5. The following list is a brief
   overview of commands that are useful when debugging source code:
   Make the code window visible (if it is not already) with WC command.
   Toggle between source, mixed, and code modes with the SRC command.
   Place a source file in the code window with the FILE command. For
   example change from the current file to file MAIN.C enter:
   FILE MAIN.C
   Display source at a specific location within the source file with the
   U command. To change the view to a specific line number or memory
   address use the U command. You can specify actual addresses or line
   numbers as a parameter to the command. For example, to view source in
   the code window starting at source line 450 enter:
   U .450
   Locate the current instruction in the code window with the . (period)
   command.
   Search for a specific character string with the S command. For
   example, to search for the string "Hello World" starting at line 100
   in the current source file enter:
   SS 100 "Hello World"
   Move the cursor to the code window (if it is not) with the EC command.
   Scroll the source with the keys up, down, PaqeUp, PageDn.
   Set point-and-shoot break points with the BPX command. Simply place
   the cursor on the source line that you wish to break on, then enter:
   BPX

CHAPTER 8 - Expanded Memory Support

   08.01 Introduction
   08.02 Configuring the EMM Environment
   08.02.01 Default EMM Pages
   08.02.02 Customizing the EMM Page Map
   08.02.02.01 Including and Excluding Areas from EMM
   08.03 Other EMM Features
   08.03.01 Increasing Conventional Memory
   08.03.02 Automatic Page Frame Locating
   08.04 EMM Debugging

08.01 Introduction

   Soft-ICE has an expanded memory manager built into its kernel. The
   Soft- ICE expanded memory manager supports the Lotus-Intel-Microsoft
   4.0 specification. This Soft-ICE feature is useful if you are using
   programs that support the EMM specification, or if you must backfill
   your conventional memory to extend your conventional memory to 640K or
   more.
   Other 386 control programs that provide EMM capability (such as QEMM
   or 386-to-the-MAX) will not co-exist with Soft-ICE. If you are using
   those programs for EMM capability or backfilling, you can use the
   Soft-ICE EMM manager in their place.
   Enabling EMM capability in Soft-ICE involves the following steps :
   1. Configure the expanded memory environment with the utility
   EMMSETUP.EXE. This utility modifies S-ICE.EXE with the desired EMM
   page map.
   2. Add the /EMM switch to your S-ICE.EXE line CONFIG.SYS. This
   reserves a portion of extended memory for expanded memory. An example
   line in CONFIG.SYS that reserves memory for EMM is:
   DEVICE = S-ICE.EXE /EMM 2048
   This will reserve 2 megabytes of extended memory for EMM use. See
   section 6.3 (Loading Soft-ICE as a Loadable Device Driver) for details
   of installing Soft-ICE in CONFIG.SYS.
   3. Reboot your system.

08.02 Configuring The EMM Environment

   Before installing S-ICE.EXE with the /EMM switch in CONFIG.SYS file,
   you may have to run EMMSETUP.EXE to configure the EMM 4.0 environment.
   This configuration process allows you to select which portions of
   memory you would like to make available as EMM 4.0 pages. Running
   EMMSETUP.EXE is highly recommended if you are using programs that take
   full advantage of the EMM 4.0 specification.

08.02.01 Default EMM Pages

   By default, S-ICE.EXE with the /EMM switch is pre-configured to allow
   EMM 4.0 pages in the following areas:
  • The lower 640K (except for the 1st 64K)
  • 64K starting at DDH
   You may want to reconfigure for the following reasons:
  • You may have a device such as a network that I the D000H area of

memory.

  • You may want to fill more holes above 640K with EMM pages. This will

increase performance and usability of programs like Microsoft Windows.

   To get maximum performance from Microsoft Windows you should fill
   every available page with expanded memory.

08.02.02 Customizing the EMM Page Map

   To configure the EMM map you must use the utility EMMSETUP.EXE.
   EMMSETUP.EXE allows the page map to be altered, then modifies
   S-ICE.EXE with the changes. EMMSETUP makes its best guess on
   automatically configuring the EMM map. EMMSETUP will try to fill much
   of the address space as possible with mappable pages while working
   around video cards and ROMS. If its guess is not good enough or not to
   your liking you can override it. Overriding may be necessary if you
   have a network, a special video adapter or a memory-mapped option
   adapter. To configurethe EMM map enter :
   EMMSETUP
   EMMSETUP displays a matrix of 16K memory pages available in the lower
   1 megabyte region. The matrix is divided into 16 columns each
   representing 64K (from 0 to 10000H). There are 4 rows representing the
   four 16K pages in each 64K region.
   Each block of the matrix can contain an E, X, R or V. Blocks that
   contain an E are available as EMM pages; blocks that contain an X are
   not. Blocks that contain an R are memory areas that have been
   identified by EMMSETUP as ROM areas. You can override these areas with
   an E if desired, however, this should only be done if the ROM is never
   accessed. Blocks that contain V are identified as video memory. We
   have made worst case assumptions on video memory. Your particular
   video card may not take up as much as we have 'guessed'. You can
   override the memory blocks that contain unnecessary V's if desired.
   If you are satisfied with EMMSETUP's guesses, press the F10 key and S-
   ICE.EXE will be modified with these parameters. You must reboot before
   any changes made to S-ICE.EXE will take effect. If you wish to
   override EMMSETUP's guesses, do so at this time.

08.02.02.01 Including and Excluding Areas from EMM

   To include an area as EMM 4.0 memory simply guide the cursor to the
   desired block, then type E. Conversely, to exclude an area from EMM
   4.0 memory, guide the cursor to the block and type X. When you are
   satisfied with your changes, press F10 to exit the program. All
   changes are automatically stored in the S-ICE.EXE file. If you wish to
   exit without modifying S-ICE.EXE press ESC. You must reboot before any
   changes made to S-ICE.EXE will take effect.
   When including upper memory blocks keep in mind the following:
  • CGA occupies from B800H to C000H.
  • MDA occupies from B000H to B100H.
  • Most Hercules cards occupy from B000 to C000H.
  • EGA occupies from A000H to C000H and from C000H to C400H.
  • VGA (mother board) occupies from A000H to C000H.
  • VGA (option card) occupies from A000H to C000H and C000H to C800H.
  • PS/2 System ROM occupies from E000H to 10000H.
  • PS/2 ESDI ROM occupies from CC00H to D000H
  • Most AT Compatible Roms occupy from F000H to 10000H.
  • Compaq systems, Micronix motherboard systems, and most Chips and

Technologies motherboard systems move the EGA/VGA ROM to E000H.

   However they still occupy the C000H region as well.
 * Token Ring Networks usually occupy from CC00H to E000H.
 * Many Networks occupy memory regions in the D000H area.
   The above guidelines are for 'generic' devices, Many implementations
   by different computer vendors and adapter card vendors will vary.

08.03 Other EMM Features

   S-ICE.EXE with the /EMM switch has two features that are automatically
   enabled depending on your system configuration. These features are
   backfilling and relocating the page frame.

08.03.01 Increasing Conventional Memory

   System memory will automatically be backfilled up to the first
   non-mappable page. This means it starts looking at contiguous E's at
   location 1000, and continues until it finds the first non-contiguous
   E. If the contiguous E's go beyond the amount of your system's base
   memory, memory will backfilled up to the first R, V, or X that is
   found.
   The benefit of backfilling is that you can increase the amount of
   usable system memory to greater than 640K. The backfilled memory is
   available within DOS. If you do not want memory backfilled, use
   EMMSETUP to make page non-mappable (X) at the point you wish system
   memory to end.
   Note : Monochrome-only systems (MDA) can backfill up to B000H to add
   an additional 64K to conventional memory CGA systems can be backfilled
   up to B800, adding an additional 96K to conventional memory. EGA and
   VGA systems can be backfilled only if no graphics programs will be
   run. You can backfill an EGA or a VGA system up to B800:0 if no
   graphics programs will be run.
   Warning : If memory is backfilled,DO NOT UNLOAD Soft-ICE. Doing so
   will cause your system to crash.

08.03.02 Automatic Page Frame Locating

   Most EMM-knowledgeable programs require a 64K page frame that is not
   used as normal DOS memory. This is normally located above the video
   device area. However in some systems there is no 64K contiguous region
   to place the page frame. In these instances S-ICE.EXE 'steals' top 4
   mappable pages of lower memory. The net result that lower DOS memory
   shrinks by 64K.

08.04 EMM Debugging

   A range break point or a break point on memory that is in an EMM
   mappable area will stay at that address no matter which EMM page is
   mapped in.
   When debugging EMM programs, the EMMMAP command may also be very
   useful. See section 5.6 for more information.
   The D, E, S, F, and C commands can be used to view or modify any
   allocated EMM handle page. The page does not have to be currently
   mapped in. The syntax of these commands is similar to that of the
   commands when being used for non-EMM pages, except for the following:
  • In the D, E, S, and F commands, the address portion of the command

must be specified in the following way: Hhandle# Ppage# offset where

   handle is a number specifying which EMM handle to use, page is a
   number specifying which EMM page to use, and offset is a number from 0
   to 4000H, specifying the offset from the beginning the page. Example:
   DB H1 P3 0
   This command will dump bytes from page 3 of handle 1, starting at
   offset 0.
  • The C command must be specified in the following way:
   C Hhandle# Ppage# offset1 Llength offset2
   where handle and page are the same as above. offset1 is a number from
   0 to 4000H, specifying the offset from the beginning of the page,
   where the first data block to be compared is located. offset2 is a
   number from 0 to 4000H, specifying the offset from the beginning of
   the page, where the second data block to be compared is located.
   Example:
   C H2 P4 00 L10 1000
   This command will compare the first 10 bytes of memory located at
   offset 0 of page 4 of handle 2 with the first 10 bytes of memory
   located at offset 1000 of page 4 of handle 2.
   Note: Subsequent uses of the D, E, S, F, and C commands will continue
   to use the handle and page last specified. To get back to conventional
   memory, use one of the above commands with a segment specified in the
   address field, for example:
   D 0:0

CHAPTER 9 - Back Trace Ranges

   09.01 Introduction
   09.02 Using Back Trace Ranges
   09.03 Special Notes

09.01 Introduction

   Soft-ICE can collect instruction information in a back trace history
   buffer as your program executes. These instructions can then be
   displayed after a bug has occurred. This allows you to go back and
   retrace a program's action to determine the actual flow of
   instructions preceding a break point.
   Instruction information is collected on accesses within a specified
   address range, rather than system wide. The ranges can be from 1 byte
   to 1 megabyte, so if desired, complete system information can be
   obtained. Using specific ranges rather than collecting all
   instructions is useful for two reasons:
   1. The back trace history buffer is not cluttered by extraneous
   information that you are not interested in. For example, you may not
   be interested in interrupt activity and execution within MSDOS.
   2. Back trace ranges degrade system performance while they are active.
   By limiting the range to an area that you are interested in, you can
   improve system performance greatly.
   Soft-ICE has two methods of utilizing the instructions in the back
   trace history buffer:
   1. The SHOW command allows you to display instructions from the back
   trace history buffer. You must specify how many instructions you wish
   to go back in the buffer.
   2. The TRACE command allows you to go back and replay instructions
   from the back trace history buffer, This way you can see the
   instruction flow within the context of the surrounding program code or
   source code.

09.02 Using Back Trace Ranges

   To use back trace ranges you must do the following:
   1. Allocate a back trace history buffer of the desired size by
   inserting the /TRA switch on the S-ICE.EXE line in CONFIG.SYS. For
   example, to create a back trace buffer of 100K you might have the
   following line in your CONFIG.SYS file:
   DEVICE = S-ICE.EXE 100
   A back trace history buffer of 10K is allocated by default. If this is
   suitable for your needs you do not have to allocate a larger buffer.
   The history buffer size is only limited by the amount of extended
   memory available.
   2. Enable back trace ranges by creating a memory range break point
   with the T or TW verb. For example:
   BPR 1000:0 2000:0 T
   The T and TW verbs do not cause break points instead they log
   instruction information that can be displayed later with the SHOW or
   TRACE commands.
   3. Set any other break points if desired.
   4. Exit from Soft-ICE with the X command.
   5. After a break point has occurred, or you have popped Soft-ICE up
   with the hot key, you can display instructions in the buffer with the
   SHOW command. For example, to go back 50 instructions in the buffer
   and display instructions type:
   SHOW 50
   6. To replay a series of instructions you must first enter trace
   simulation mode with the TRACE command. To begin replaying the
   sequence of instructions starting back 50 in the buffer type:
   TRACE 50
   7. After you have entered trace simulation mode, you can trace through
   the sequence of instructions by using the XT, XP, or XG commands. This
   allows you to re-enact the program flow. For example, you can single
   step through the sequence of instructions in the buffer, starting at
   the instruction specified by the TRACE command, by typing:
   XT
   XT
   .
   .
   .
   XT
   The XT command single steps through the back trace history buffer.
   The XP command program steps through the back trace history buffer.
   The XG command goes to an address in the back trace history buffer.
   8. To exit from trace simulation mode type:
   TRACE OFF
   9. To reset the back trace history buffer, use the X command.

09.03 Special Notes

   While in trace simulation mode, most Soft-ICE commands work as normal,
   including displaying the memory map, and displaying and editing data.
   The exceptions are:
   1. Register information is not logged in the back trace history
   buffer, so the register values do not change as you trace through the
   buffer, except for CS and IP.
   2. Commands that normally exit from Soft-ICE do not work while in
   trace simulation mode. These are X, T, P, G, EXIT.
   As you peruse instructions from the back trace history buffer with the
   SHOW and TRACE commands, you may notice peculiarities in instruction
   execution. These are caused by jumps in and out of the specified
   range. These usually occur at jumps, calls, returns and entry points.
   When you have a hang problem or other difficult bug that requires back
   trace ranges, you must often use very large ranges in order to narrow
   the scope of the problem. Once you have a better idea of the specific
   problem area, you go to smaller ranges.
   Large back trace ranges are often very slow. When using large ranges
   you are usually trying to get a general idea where the problem is.
   Soft-ICE has a special 'COARSE' mode for doing large ranges. This
   speeds up the ranges a factor of three or more, but limits the amount
   of instructions in the history buffer.
   Coarse mode only collects instructions that do a memory write within
   the specified range. As you are replaying instructions with trace
   simulation mode after a 'coarse' range you will notice that the flow
   skips around rather than sequentially executing instructions.
   Coarse ranges work best for large ranges and tend to be less effective
   for small ranges.
   To enable a 'coarse' back trace range, use the BPR command with the TW
   verb instead of the T verb. For example:
   BPR 1000:0 2000:0 TW
   For further information on back trace ranges see the command
   descriptions for : SHOW, TRACE, XT, XP, XG, XRSET, BPR

CHAPTER 10 - Using Soft-ICE with MagicCV or MagicCVW

   10.01 Introduction
   10.02 Running Soft-ICE with MagicCV or MagicCVW
   10.03 Special Considerations
   10.04 The Soft-ICE ACTION command

10.01 Introduction

   MagicCV allows you to run Microsoft's CodeView in less than 8K of
   conventional memory on your 80386 machine.
   MagicCVW allows you to run Microsoft's CodeView for Windows in less
   than 8K of conventional memory on your 80386 machine.
   Using Soft-ICE in combination with MagicCV or MagicCVW allows you to
   have the power of Soft-ICE while still having the convenience of using
   the CodeView product that you are familiar with.
   In the rest of this chapter, statements about MCV will apply to both
   MagicCV and MagicCVW, and statements about CV will apply to both
   CodeView and CodeView for Windows.

10.02 Running Soft-ICE with MagicCV or MagicCVW

   To use Soft-ICE 2.0 and MCV together, you must install S-ICE.EXE as a
   loadable device driver. S-ICE.EXE comes on the Soft-ICE diskette. S-
   ICE.EXE replaces NUMEGA.SYS in CONFIG.SYS. Use the /MCV, /EMM, and the
   /EXT switches as if using MagicCV or MagicCVW alone. There are
   additional switches that you may want to use for Soft-ICE. Refer to
   chapter 6 for information about these switches.
   To run MagicCV or MagicCVW after Soft-ICE has been loaded, refer to
   your MagicCV or MagicCVW manual.
   Notes : MagicCVW requires Soft-ICE version 2.00 or greater. MagicCV
   requires Soft-ICE version 1.02 or greater. The S-ICE.SYS and
   NUMEGA.SYS drivers were shipped with some versions of Soft-ICE. The
   S-ICE and NUMEGA drivers must be replaced by S-ICE.EXE before you can
   run MagicCV and Soft- ICE 2.0 together.

10.03 Special Considerations

   Two Virtual Machines : When you are using both Soft-ICE and MCV
   together, you must keep in mind that CV is in a separate virtual
   machine from the target environment. You can pop Soft-ICE up from
   either virtual machine, i.e., when CV is running, or when the target
   program is running.
   If you pop Soft-ICE up while the target program is running everything
   works as defined in the Soft-ICE manual. If you pop Soft-ICE up while
   CV is running (typically done to break points), you must keep a few
   points in mind:
  • The registers are those of CV and they CAN NOT be changed.
  • For convenience, the Soft-ICE MAP command displays the memory map of

the target program virtual machine, not the memory map of the CV

   virtual machine. The highlighted area in the memory map may not be
   correct.
 * Any display or modification of memory occurs in the target program's
   virtual machine.
 * You have no visibility into the CV virtual machine except for the
   display of register values. Remember that when popping up the Soft-ICE
   window while CV is active, the register values are those of CV and
   should not be modified.
 * Instruction and program tracing is disabled from the Soft-ICE window
   when CV is active. This is to prevent confusion, because a trace would
   actually step through CV, not through the target program. If you
   attempt to do a Soft-ICE Trace (T) or Program Step (P) command while
   CV is active, you will get the warning message: "Function not
   available in CV virtual machine." To trace through your target program
   code instead, you can do one of two options:
 * Use the CV trace command. To do this, exit the Soft-ICE window using
   the Soft-ICE X command, then do one or more CV traces to step through
   the target program.
 * Use Soft-ICE to go to the target program address, then use the
   Soft-ICE T or P commands to step through your target program. To do
   this, exit the Soft-ICE window with the Soft-ICE X command, then press
   the 'F3' key until CV is in 'mixed mode'. This allows you to see both
   the source lines and the instruction addresses. Pop up Soft-ICE. If
   the Soft-ICE window is not already in narrow mode, use the Soft-ICE
   WIN command to change the window size. Move the Soft-ICE window so you
   can see the instruction addresses on the left side of the screen. Now
   you can use the Soft-ICE G command to go to one of the addresses. Be
   sure to type in the full address, including the segment and the
   offset. Then enter 'G' in the CV window. At this point, CV is not
   active, so you can use the Soft-ICE T or P commands to step through t
   target program.
   CodeView's SHELL command : If you run the DOS shell from within the
   CodeView virtual machine, the DOS shell is part of the virtual
   machine. Because of this, you should not run any TSRs when you are in
   the DOS shell. If you do, when you exit CodeView the TSRs will
   disappear along with the virtual machine. This is dangerous, because
   any interrupt vectors that were not restored could hang your machine.
   CV's /R switch :Soft-ICE takes advantage of many of the 80386 features
   including the 80386 debug registers. This means that the debug
   registers are not available for CV, so you cannot use the CV /R switch
   when running with Soft-ICE. If you do use the /R switch, Soft-ICE
   gives you a general protection error. At this point, you can press "C"
   to continue, then rerun CV without the /R switch, and use the Soft-ICE
   break points. The CV /R switch works when you are running MCV without
   Soft-ICE.

10.04 The Soft-ICE ACTION Command

   The ACTION command allows three different methods activating CV from a
   Soft-ICE break point. The best choice of action is ACTION NMI. If you
   experience any problems with ACTION set to NMI (usually because an
   adapter card in your system is using NMI), use ACTION INT1.

CHAPTER 11 - Advanced Features

   11.01 Using Soft-ICE with other Debuggers
   11.01.01 Debuggers that Use DOS
   11.01.02 ACTION Command with other Debuggers
   11.01.03 Special Considerations
   11.01.04 Using Soft-ICE with CODEVIEW
   11.01.05 Debuggers that Use 80386 Break Point Registers
   11.02 User-Qualified Break Points
   11.02.01 Example of a User-Qualified Break Point
   11.03 The Window in Graphics Mode
   11.04 Expanded Memory Debugging Features
   11.05 Extended Memory Debugging Features

11.01 Using Soft-ICE with other Debuggers

   Soft-ICE was designed to work well with other debuggers. Each debugger
   offers different features, and therefore can require special
   treatment. This section will describe some ways to use several
   debuggers effectively.

11.01.01 Debuggers that Use DOS

   Many debuggers use DOS and ROM BIOS to perform their display and
   keyboard I/O. Special consideration must be taken when using these
   debuggers with Soft-ICE (e.g., DEBUG, SYMDEB, and CODEVIEW), because
   DOS and ROM BIOS are not fully re-entrant. If a break point occurs
   while code is executing in DOS or BIOS, a re-entrancy problem can
   occur.
   Soft-ICE provides optional re-entrancy warning, which is activated
   with the WARN command. When WARN mode is on, Soft-ICE checks for DOS
   or ROM BIOS re-entrancy before generating the ACTION that wakes up the
   host debugger. When a re-entrancy problem is detected, Soft-ICE
   displays a warning message and offers you the choice of continuing to
   execute the code or returning to Soft-ICE.
   Note that Soft-ICE itself does not use DOS or ROM BIOS calls in its
   debugging commands. This means that you can use Soft-ICE any time,
   without the worry of re-entrancy problems.
   For more information on the WARN command, see section 5.4.

11.01.02 ACTION Command with other Debuggers

   Different debuggers use different methods of activation For a
   description of these methods see section 13.1.
   If you want to return to your debugger after a break point reached,
   you must change the ACTION (see section 5.4) to work with your
   debugger.
   In most cases, the action that should be taken after a break point is
   reached is INT3. For instance, DEBUG and SYMDEB will work best with
   ACTION set to INT3.
   If INT3 doesn't work with your debugger, try INT1 or NMI. CODEVIEW
   works best with ACTION set to NMI.

11.01.03 Special Considerations

   When a break point is set, you must be careful not to set off the
   break point unintentionally. For instance, if you set a memory break
   point at 0:0, then use your debugger to dump memory location 0:0,
   Soft-ICE will be triggered. If ACTION is set to go to your debugger,
   then your debugger will be triggered by itself. Since some debuggers
   cannot be re-entrant, this could be a fatal problem. This problem can
   also occur with other debugging functions, such as editing or
   unassembling.
   For this reason, it is a good practice to disable the Soft-ICE break
   points once Soft-ICE has helped you get to the point where you want to
   look around with your debugger.

11.01.04 Using Soft-ICE with CODEVIEW

   Soft-ICE works best with CODEVIEW when CODEVIEW is either in Assembler
   mode or Mixed mode. When CODEVIEW is in Source mode with higher-level
   languages it does not always break correctly. It is always best to use
   ACTION NMI when you want Soft-ICE to wake up CODEVIEW.

11.01.05 Debuggers that Use 80386 Break Point Registers

   The 80386 has 4 break point registers that are available for use by
   debuggers. Soft-ICE uses these for its memory byte, word and double
   word break points. If the debugger you are using Soft-ICE with uses
   these debug registers there will be a conflict. There are two ways to
   handle this problem.
   1. Disable the use of 80386 break point registers in the debugger you
   are using Soft-ICE with. Check the documentation of your other
   debugger for a description of how to do this.
   2. Some debuggers automatically use the break point registers if they
   detect an 80386 processor with no method of turning them off (some
   versions of SYMDEB do this). For these debuggers do the following:
  • Bring up the Soft-ICE window before you start the other debugger.
  • Turn on Soft-ICE's break mode with the BREAK command (you may want to

do this in the INIT statement of S-ICE.DAT if you are doing this

   frequently).
 * Start up your other debugger.
 * You may now pop up the Soft-ICE window and turn the Soft-ICE break
   mode off if desired.

11.02 User-Qualified Break Points

   Occasionally you may have the need for a very specific set of break
   point conditions. If the special conditions require qualifying
   register values or memory values, you can write a break point
   qualification routine.
   Soft-ICE contains a very general mechanism for calling user-written
   break point qualification routines: the ACTION command. When you use
   the ACTION command, Soft-ICE can route all break points through
   special interrupt vector. However, before break points can be routed,
   the qualification routine must be placed in memory, and the interrupt
   vector must be pointing to the qualification routine.
   All registers are identical to the values when the Soft-ICE break
   point occurred. It is the responsibility of the qualification routine
   to save and restore the registers. If your qualification routine
   detects a match of break point conditions, it can do a variety of
   activities. Some examples of useful activities that a routine can do
   when a match is found are:
  • store information for later
  • send the information directly to a printer or serial terminal
  • issue an INT 3 instruction to bring up Soft-ICE The command 13HERE

must be turned on in order for the INT 3 to bring up Soft-ICE (see

   section 5.4).
   If conditions do not match, the qualification routine in should
   execute an IRET instruction. To summarize:
   1. Create a break point qualification routine in your code space, or
   anywhere in free memory. The routine must preserve registers. After
   comparing the desired conditions, the routine can execute either an
   INT 3 to bring up Soft-ICE, or an IRET to continue.
   2. Point an unused interrupt vector to your qualification routine.
   This can be done either within your code or from Soft-ICE.
   3. In Soft-ICE, set ACTION to the interrupt- number that was used to
   point to your qualification routine.
   4. In Soft-ICE, set 13HERE on. This is necessary to bring up Soft-ICE
   after the conditions have been met.
   5. Set the Soft-ICE general break point conditions. When any of these
   break point conditions are met, your qualification routine will be
   called.

11.02.01 Example of a User-Qualified Break Point

   This section contains an example of a user-qualified break point that
   compares for the conditions of U = 3, BX = 4 and CX = 5 when a break
   point goes off.
   First, we create the qualification routine. For the purposes of this
   example, we will assemble the command directly into memory with the
   Soft- ICE interactive assembler. For this example we will arbitrarily
   assemble the routine at location 9000:0H. The following statements are
   entered into Soft-ICE :
   A 9000:0
    9000:0 CMP AX,3
    9000:3 JNE 10
    9000:5 CMP BX,4
    9000:7 JNE 10
    9000:A CMP CX,5
    9000:D JNE 10
    9000:F INT3
    9000:10 IRET
   Now that the routine is in memory, you must point an interrupt vector
   to the routine. For this example, we arbitrarily pick INT 99H. To
   place 9000:0H in the INT 99H vector enter:
   ED 0:99*4 9000:0
   Set the ACTION command so that Soft-ICE will call your break point
   qualification routine on every break point.
   ACTION 99
   Set I3HERE on so the qualification routine can activate Soft-ICE when
   the conditions occur.
   I3HERE ON
   Now you need to set the break points. For this example, we are just
   interested when the registers are: AX = 3, BX = 4, CX = 5 in a
   specific program, and we do not want any further qualification. To do
   this, use a range break point on memory read :
   BPR segment:starting-offset segment:ending-offset
   This will cause your break point qualification routine to be called
   after every instruction is executed in the specified memory range.
   When the register conditions do not match, then the IRET instruction
   is executed. When the conditions finally match the specified
   qualifications, the INT 3 is executed and Soft-ICE is popped up.
   When Soft-ICE pops up, the instruction pointer will be pointing at the
   INT3 in your qualification routine (9OOO:FH in our example). To get to
   the instruction after the one that caused the break point, you must
   change the instruction pointer to point to the IRET instruction
   (F000:10H in the example) and single step one time. This is
   accomplished with the following Soft-ICE commands
   RIP IP + 1
   T
   After your break conditions have gone off, remember to change the
   ACTION command back to ACTION HERE that subsequent break points do not
   go through your qualification routine.

11.03 The Window in Graphics Mode

   The screen is switched to text mode when Soft-ICE is invoked. If the
   screen was in graphics mode or 40-column mode, the graphics display is
   not visible while the window is up. For users who must see the
   graphics display while debugging, three features are provided. The
   first feature allows the Soft-ICE window to display on a second
   monitor (see the ALTSCR command, section 5.9). The second feature
   allows you to restore the screen while you are doing P or T
   instruction step commands (see the FLASH command, section 5.9). The
   third feature allows you to restore the program screen temporarily
   (see the RS command, section 5.9).
   If Soft-ICE does not seem to be following your program into graphics
   mode, try turning WATCHV on (see section 5.9 for details).

11.04 Expanded Memory Debugging Features

   A range break point or a break point on memory that is set in an EMM
   mappable area will stay at that address no matter which EMM page is
   mapped in.
   When debugging EMM programs, the EMMMAP command may also be very
   useful. See section 5.6 for more information.
   The D, E, S, F, and C commands can be used to view or modify any
   allocated EMM handle page. The page does not have to be currently
   mapped in. The syntax of these commands is similar to that of the
   commands when being used for non-EMM pages, except for the following :
  • In the D, E, S, and F commands, the address portion of the command

must be specified in the following way:

   Hhandle# Ppage# offset
   where handle is a number specifying which EMM handle to use, page is a
   number specifying which EMM page to use, and offset is a number from 0
   to 4000H, specifying the offset from the beginning of the page.
   Example:
   DB H1 P3 0
   This command will dump bytes from page 3 of handle 1, starting at
   offset 0.
  • The C command must be specified in the following way :
   C Hhandle# Ppage# offset1 L length offset2
   where handle and page are the same as above. offset1 is a number from
   0 to 4000H, specifying the offset from the beginning of the page,
   where the first data block to be compared is located. offset2 is a
   number from 0 to 4000H, specifying the offset from the beginning of
   the page, where the second data block to be compared is located.
   Example :
   C H2 P4 00 L10 1000
   This command will compare the first 10 bytes of memory located at
   offset 0 of page 4 of handle 2 with the first 10 bytes of memory
   located at offset 1000 of page 4 of handle 2.
   Note : Subsequent uses of the D, E, S, F, and C commands will continue
   to use the handle and page last specified. To get back to conventional
   memory, use one of the above commands with a segment specified in the
   address field, for example:
   D 0:0

11.05 Extended Memory Debugging Features

   The D, E, S, F, and C commands can be used to view or modify extended
   memory. Extended memory reserved by Soft-ICE can not be displayed. The
   syntax of these commands is similar to that of the commands when being
   used for conventional memory:
  • In the D, E, S, and F commands, the address portion of the command

must be specified in the following way: M megabyte address where

   megabyte is a number specifying which megabyte to use, and address
   specifies the address in the specified megabyte. Example:
   DB M 2 0:0
   This command will dump bytes from start of the megabyte starting at
   linear address 200000H.
  • The C command must be specified in the following way :
   C M megabyte address1 L length address2
   where megabyte and address1 are the same as above. address2 specifies
   the address in the specified megabyte, where the second data block to
   be compared is located.Example:
   C M 3 1000:2000 L10 3000:4000
   This command will compare the first 10 bytes of memory located at
   1000:2000 with the first 10 bytes of memory located at 3000:4000.
   Note : Subsequent uses of the D, E, S, F, and C commands will continue
   to use the last megabyte specified. To get back to megabyte 0
   (conventional memory), use one of the above commands with 0 specified
   as the megabyte, for example:
   D M 0
                              We will now discuss in a little more detail
                                              the struggle for existence.
                                                           Charles Darwin

SoftICE Tutorial

   Introduction
   Loading SoftICE
   Building the GDIDEMO Sample Application
   Loading the GDIDEMO Sample Application
   Controlling the SoftICE Screen
   Tracing and Stepping through Source Code
   Viewing Local Data
   Setting Point-and-Shoot Breakpoints
        Setting a One-Shot Breakpoint
        Setting a Sticky Breakpoint
   Using SoftICE Informational Commands
   Using Symbols and Symbol Tables
   Setting a Conditional Breakpoint
        Setting a BPX Breakpoint
        Editing a Breakpoint
   Setting a Read-Write Memory Breakpoint

Introduction

   This tutorial gives you hands-on experience debugging a Windows
   application to teach you the fundamental steps for debugging
   applications and drivers. During this debugging session, you will
   learn how to do the following:
  • Load SoftICE
  • Build an application
  • Load the application source and symbol files
  • Trace and step through source code and assembly language
  • View local data and structures
  • Set point-and-shoot breakpoints
  • Use SoftICE informational commands to explore the state of the

application

  • Work with symbols and symbol tables
  • Modify a breakpoint to use a conditional expression
   Each section in the tutorial builds upon the previous sections, so you
   should perform them in order.
   This tutorial uses the GDIDEMO application as its basis. GDIDEMO
   provides a demonstration of GDI functionality. GDIDEMO is located in
   the \EXAMPLES\GDIDEMO directory on your CDROM. GDIDEMO is also
   available under \mstools\samples\win32\GDIDEMO. If you use the GDIDEMO
   on the CDROM, copy it to your hard drive.
   You can substitute a different sample application or an application of
   your own design. The debugging principles and features of SoftICE used
   in this tutorial apply to most applications.
   Note: The examples is this tutorial are based on Windows NT. If you
   are using Windows 95, your output may vary slightly.

Loading SoftICE

   If you are running SoftICE under Windows 95 or under Windows NT in
   Boot, System, or Automatic mode, SoftICE automatically loads when you
   start or reboot your PC. If you are running SoftICE in Manual Startup
   mode under Windows NT, SoftICE does not load automatically.
   To load SoftICE for Windows 95, enter the command WINICE. To load
   SoftICE for Windows NT, do one of the following:
  • Select START SOFTICE.
  • Enter the command: NET START NTICE
   Note: Once you load SoftICE, you cannot deactivate it until you reboot
   your PC.
   To verify that SoftICE is loaded, press the SoftICE hot key sequence
   Ctrl-D. The SoftICE screen should appear. To return to the Windows
   operating system, use the X (exit) or G (go to) command (F5).

Building the GDIDEMO Sample Application

   The first step in preparing to debug a Windows application is to build
   it with debug information. The makefile for the sample application
   GDIDEMO is already set up for this purpose.
   To build the sample program, perform the following steps:
   1. Open a DOS shell.
   2. Change to the directory that contains the sample code.
   3. Execute the NMAKE command:
   C:\MSTOOLS\SAMPLES\WIN32\GDIDEMO>NMAKE
   If GDIDEMO is located in another directory, change the path as
   appropriate.

Loading the GDIDEMO Sample Application

   Loading an application entails creating a symbol file from the
   application’s debug information and loading the symbol and source
   files into SoftICE. To Load the GDIDEMO application, perform the
   following steps:
   1. Start Symbol Loader : The Symbol Loader window appears.
   2. Either choose OPEN MODULE from the File menu or click the OPEN
   button : The Open window appears.
   3. Locate GDIDEMO.EXE and click Open.
   4. Either choose LOAD from the Module menu or click the LOAD button to
   load GDIDEMO.
   Symbol Loader translates the debug information into a .NMS symbol
   file, loads the symbol and source files, starts GDIDEMO, pops up the
   SoftICE screen, and displays the source code for the file GDIDEMO.C.

Controlling the SoftICE Screen

   The SoftICE screen is your central location for viewing and debugging
   code. It provides up to seven windows and one help line to let you
   view and control various aspects of your debugging session. By
   default, it displays the following:
   Locals window: Displays and expand variables allocated on the stack.
   Code window: Displays source code or unassembled instructions.
   Command window: Enters user commands and display information.
   Help line: Provides information about SoftICE commands and shows the
   active address context.
   1. Look at the contents of the Code window. Note that SoftICE is
   displaying the WinMain routine at line 34. By default, SoftICE creates
   a breakpoint and stops at the first main module it encounters when
   loading your application.
   2. To see all the source files that SoftICE loaded, enter the FILE
   command with the wild card character:
   :FILE *
   SoftICE displays the source files for GDIDEMO: draw.c, maze.c,
   xform.c, poly.c, wininfo.c, dialog.c, init.c, bounce.c, and gdidemo.c.
   The Command window varies in size depending upon the number of lines
   used by open windows, so you might not see all these file names. To
   display the remaining file names, press any key. (Refer to Chapter 5:
   Navigating Through SoftICE on page 69 for information about resizing
   windows.)
   3. Many SoftICE windows can be scrolled. If you have a mouse, you can
   click on the scroll arrows. If not, SoftICE provides key sequences
   that let you scroll specific windows. Try these methods for scrolling
   the Code window:
    Scroll the Code Window   Key Sequence    Mouse Action
    Scroll to the previous                   Click the innermost up
    page.                    PageUp          scroll arrow
    Scroll to the next                       Click the innermost down
    page.                    PageDown        scroll arrow
    Scroll to the previous                   Click the outermost up
    line.                    UpArrow         scroll arrow
    Scroll to the next                       Click the outermost down
    line.                    DownArrow       scroll arrow
    Scroll left one                          Click the left scroll
    character.               Ctrl-LeftArrow  arrow
    Scroll right one                         Click the right scroll
    character.               Ctrl-RightArrow arrow
   4. Enter the U command followed by EIP to disassemble the instructions
   for the current instruction pointer.
   :U EIP
   You can also use the . (dot) command to accomplish the same thing:
   :.

Tracing and Stepping through Source Code

   The following steps show you how to use SoftICE to trace through
   source code:
   1. Enter the T (trace) command or press the F8 key to trace one
   instruction.
   :T
   The F8 key is the default key for the T (trace) command.
   Execution proceeds to the next source line and highlights it. At this
   point, the following source line should be highlighted:
   if(!hPrevInst)
   2. The Code window is currently displaying source code. However, it
   can also display disassembled code or mixed (both source and
   disassembled) code. To view mixed code, use the SRC command (F3).
   :SRC
   Note that each source line is followed by its assembler instructions.
   3. Press F3 once to see disassembled code, then again to return to
   source code.
   4. Enter the T command (F8) to trace one instruction. Execution
   proceeds until it reaches the line that executes the RegisterAppClass
   function.
   As demonstrated in these steps, the T command executes one source
   statement or assembly language instruction. You can also use the P
   command (F10) to execute one program step. Stepping differs from
   tracing in one crucial way. If you are stepping and the statement or
   instruction is a function call, control is not returned until the
   function call is complete.
   Hint: The T command does not trace into a function call if the source
   code is not available. A good example of this is Win32 API calls. To
   trace into a function call when source code is not available, use the
   SRC command (F3) to switch into mixed or assembly mode.

Viewing Local Data

   The Locals window displays the current stack frame. In this case, it
   contains the local data for the WinMain function. The following steps
   illustrate how to use the Locals window:
   1. Enter the T command to enter the RegisterAppClass function. The
   Locals window is now empty because local data is not yet allocated for
   the function.
   The RegisterAppClass function is implemented in the source file
   INIT.C. SoftICE displays the current source file in the upper left
   corner of the Code window.
   2. Enter the T command again. The Locals window contains the parameter
   passed to the RegisterAppClass (hInstance) and a local structure
   wndClass. The structure tag wndClass is marked with a plus sign (+).
   This plus sign indicates that you can expand the structure to view its
   contents.
   Note: You can also expand character strings and arrays.
   3. If you have a Pentium-class processor and a mouse, double-click the
   structure WNDCLASSA to expand it. To collapse the structure wndClass,
   double-click its contents.
   4. To use the keyboard to expand the structure: press Alt-L to move
   the cursor to the Locals window, use the UpArrow or DownArrow to move
   the highlight bar to the structure, and press Enter. Press Enter again
   to collapse it.

Setting Point-and-Shoot Breakpoints

   This section shows you how to set two handy types of point-and-shoot
   breakpoints: one-shot and sticky breakpoints.

Setting a One-Shot Breakpoint

   The following steps demonstrate how to set a one-shot breakpoint. A
   one-shot breakpoint clears after the breakpoint is triggered.
   1. To shift focus to the Code window, either use your mouse to click
   in the window or press Alt-C.
   If you wanted to shift focus back to the Command window you could
   press Alt-C again. Setting Point-and-Shoot Breakpoints
   2. Either use the Down arrow key, the down scroll arrow, or the U
   command to place the cursor on line 61, the first call to the Win32
   API function RegisterClass. If you use the U command, specify the
   source line 61 as follows:
   :U .61
   SoftICE places source line 61 at the top of the Code window.
   3. Use the HERE command (F7) to execute to line 61. The HERE command
   executes from the current instruction to the instruction that contains
   the cursor. The HERE command sets a one-shot breakpoint on the
   specified address or source line and continues execution until that
   breakpoint triggers. When the breakpoint is triggered, SoftICE
   automatically clears the breakpoint so that it does not trigger again.
   The following current source line should be highlighted:
   if(!RegisterClass(&wndClass))
   Note: You can do the same thing by using the G (go) command and
   specifying the line number or address to which to execute:
   :G .61

Setting a Sticky Breakpoint

   The following steps demonstrate another type of point-and-shoot
   breakpoint: the sticky breakpoint, which does not clear until you
   explicitly clear it.
   The F9 key is the default key for the BPX command.
   1. Find the next call to RegisterClass that appears on source line 74.
   With the cursor on line 74, enter the BPX command (F9) to set an
   execution breakpoint. The BPX command sets an execution breakpoint by
   inserting an INT3 instruction into the code. Note that the line is
   highlighted when you set a breakpoint.
   2. Press the F9 key to clear the breakpoint. If you are using a
   Pentium-class processor and you have a mouse, you can double-click on
   a line in the Code window to set or clear a breakpoint.
   3. Set a breakpoint on line 74, then use the G or X command (F5) to
   execute the instructions until the breakpoint triggers:
   :G
   When the INT3 instruction is executed, SoftICE pops up. Unlike the
   HERE command, which sets a one-shot breakpoint, the BPX command sets a
   sticky breakpoint. A sticky breakpoint remains until you clear it.
   4. To view information about breakpoints that are currently set, use
   the BL command:
   :BL
   00) BPX #0137:00402442
   Note: The address you see might be different.
   From the output of the BL command, one breakpoint is set on code
   address 0x402442. This address equates to source line 74 in the
   current file INIT.C.
   5. You can use the SoftICE expression evaluator to translate a line
   number into an address. To find the address for line 74, use the ?
   command:
   :? .74
   void * = 0x00402442
   6. The RegisterAppClass function has a relatively straightforward
   implementation, so it is unnecessary to trace every single source
   line. Use the P command with the RET parameter (F12) to return to the
   point where this function was called:
   :P RET
   The RET parameter to the P command causes SoftICE to execute
   instructions until the function call returns. Because RegisterAppClass
   was called from within WinMain, SoftICE pops up in WinMain on the
   statement after the RegisterAppClass function call.
   The following source line in WinMain should be highlighted:
   msg.wParam = 1;
   7. Enter the BC command with the wild card parameter to clear all the
   breakpoints:
   BC *

Using SoftICE Informational Commands

   SoftICE provides a wide variety of informational commands that detail
   the state of an application or the system. This section teaches you
   about two of them: H (help) and CLASS.
   1. The H and Class commands work best when you have more room to
   display information, so use the WL command to close the Locals window.
   Closing this window automatically increases the size of the Command
   window.
   2. The H command provides general help on all the SoftICE commands or
   detailed help on a specific command. To view detailed help about the
   CLASS command, enter CLASS as the parameter to the H command.
   :H CLASS
   Display window class information
   CLASS [-x] [process | thread | module | class-name]
   ex: CLASS USER
   The first line of help provides a description of the command. The
   second line is the detailed use, including any options and/or
   parameters the command accepts. The third line is an example of the
   command.
   3. The purpose of the RegisterAppClass function is to register window
   class templates that are used by the GDIDEMO application to create
   windows. Use the CLASS command to examine the classes registered by
   GDIDEMO.
   :CLASS GDIDEMO
   Note: This example shows only those classes specifically registered by
   the GDIDEMO application. Classes registered by other Windows modules,
   such as USER32, are omitted.
   The output of the CLASS command provides summary information for each
   window class registered on behalf of the GDIDEMO process. This
   includes the class name, the address of the internal WINCLASS data
   structure, the module which registered the class, the address of the
   default window procedure for the class, and the value of the class
   style flags.
   Note: For more specific information on window class definitions, use
   the CLASS command with the -X option, as follows:
   :CLASS -X
   Class Name  Handle    Owner    WndwProc  Styles
   ---------------Application Private---------------
   BOUNCEDEMO  A018A3B0  GDIDEMO  004015A4  00000003
   DRAWDEMO    A018A318  GDIDEMO  00403CE4  00000003
   MAZEDEMO    A018A280  GDIDEMO  00403A94  00000003
   XFORMDEMO   A018A1E8  GDIDEMO  00403764  00000003
   POLYDEMO    A018A150  GDIDEMO  00402F34  00000003
   GDIDEMO     A018A0C0  GDIDEMO  004010B5  00000003

Using Symbols and Symbol Tables

   Now that you are familiar with using SoftICE to step, trace, and
   create point-and-shoot style breakpoints, it is time to explore
   symbols and tables. When you load symbols for an application, SoftICE
   creates a symbol table that contains all the symbols defined for that
   module.
   1. Use the TABLE command to see all the symbol tables that are loaded:
   :TABLE
   GDIDEMO [NM32]
   964657 Bytes Of Symbol Memory Available
   The currently active symbol table is listed in bold. This is the
   symbol table used to resolve symbol names. If the current table is not
   the table from which you want to reference symbols, use the TABLE
   command and specify the name of the table to make active:
   :TABLE GDIDEMO
   2. Use the SYM command to display the symbols from the current symbol
   table. With the current table set to GDIDEMO, the SYM command produces
   output similar to the following abbreviated output:
   :SYM
   .text(001B)
   001B:00401000 WinMain
   001B:004010B5 WndProc
   001B:004011DB CreateProc
   001B:00401270 CommandProc
   001B:00401496 PaintProc
   001B:004014D2 DestroyProc
   001B:004014EA lRandom
   001B:00401530 CreateBounceWindow
   001B:004015A4 BounceProc
   001B:004016A6 BounceCreateProc
   001B:00401787 BounceCommandProc
   001B:0040179C BouncePaintProc
   This list of symbol names is from the .text section of the executable.
   The .text section is typically used for procedures and functions. The
   symbols displayed in this example are all functions of GDIDEMO.

Setting a Conditional Breakpoint

   One of the symbols defined for the GDIDEMO application is the
   LockWindowInfo function. The purpose of this routine is to retrieve a
   pointer value that is specific to a particular instance of a window.
   To learn about conditional and memory breakpoints, you will perform
   the following steps:
  • Set a BPX breakpoint on the LockWindowInfo function.
  • Edit the breakpoint to use a conditional expression, thus setting a

conditional breakpoint.

  • Set a memory breakpoint to monitor access to a key piece of

information, as described in Setting a Read-Write Memory Breakpoint on

   page 39.

Setting a BPX Breakpoint

   Before setting the conditional breakpoint, you need to set a BPX-style
   breakpoint on LockWindowInfo.
   1. Set a BPX-style breakpoint on the LockWindowInfo function:
   :BPX LockWindowInfo
   When one of the GDIDEMO windows needs to draw information in its
   client area, it calls the LockWindowInfo function. Every time the
   LockWindowInfo function is called, SoftICE pops up to let you debug
   the function. The GDIDEMO windows continually updates, so this
   breakpoint goes off quite frequently.
   2. Use the BL command to verify that the breakpoint is set.
   3. Use either the X or G command to exit SoftICE. SoftICE should pop
   up almost immediately on the LockWindowInfo function.

Editing a Breakpoint

   From the LockWindowInfo function prototype on source line 47, you can
   see that the function accepts one parameter of type HWND and returns a
   void pointer type. The HWND parameter is the handle to the window that
   is attempting to draw information within its client area. At this
   point, you want to modify the existing breakpoint, adding a
   conditional breakpoint to isolate a specific HWND value.
   1. Before you can set the conditional expression, you need to obtain
   the HWND value for the POLYDEMO window. The HWND command provides
   information about application windows. Use the HWND command and
   specify the GDIDEMO process:
   :HWND GDIDEMO
   The following example illustrates what you should see if you are using
   Windows NT. If you are using Windows 95, your output will vary.
   Handle  Class       WinProc   TID Module
   07019C  GDIDEMO     004010B5  2D  GDIDEMO
   100160  MDIClient   77E7F2F5  2D  GDIDEMO
   09017E  BOUNCEDEMO  004015A4  2D  GDIDEMO
   100172  POLYDEMO    00402F34  2D  GDIDEMO
   11015C  DRAWDEMO    00403CE4  2D  GDIDEMO
   The POLYDEMO window handle is bold and underlined. This is the window
   handle you want to use to form a conditional expression. If the
   POLYDEMO window does not appear in the HWND output, exit SoftICE using
   the G or X commands (F5) and repeat Step 1 until the window is
   created.
   The value used in this example is probably not the same value that
   appears in your output. For the exercise to work correctly, you must
   use the HWND command to obtain the actual HWND value on your system.
   Using the POLYDEMO window handle, you can set a conditional expression
   to monitor calls to LockWindowInfo looking for a matching handle
   value. When the LockWindowInfo function is called with the POLYDEMO
   window handle, SoftICE pops up.
   2. Because you already have a breakpoint set on LockWindowInfo, use
   the BPE command (Breakpoint Edit) to modify the existing breakpoint:
   :BPE 0
   When you use the BPE command to modify an existing breakpoint, SoftICE
   places the definition of that breakpoint onto the command line so that
   it can be easily edited. The output of the BPE command appears:
   :BPX LockWindowInfo
   The cursor appears at the end of the command line and is ready for you
   to type in the conditional expression.
   3. Remember to substitute the POLYDEMO window handle value that you
   found using the HWND command instead of the value (100172) used in
   this example. Your conditional expression should appear similar to the
   following example. The conditional expression appears in bold type.
   :BPX LockWindowInfo IF ESP->4 == 100172
   Note: Win32 applications pass parameters on the stack and at the entry
   point of a function; the first parameter has a positive offset of 4
   from the ESP register. Using the SoftICE expression evaluator, this is
   expressed in the following form: ESP->4. ESP is the CPU stack pointer
   register and the "->" operator causes the lefthand side of the
   expression (ESP) to be indirected at the offset specified on the
   righthand side of the expression (4). For more information on the
   SoftICE expression evaluator refer to Chapter 8: Using Expressions on
   page 125 and for referencing the stack in conditional expressions
   refer to Conditional Breakpoints on page 114.
   4. Verify that the breakpoint and conditional expression are correctly
   set by using the BL command.
   5. Exit SoftICE using the G or X command (F5).
   When SoftICE pops up, the conditional expression will be TRUE.

Setting a Read-Write Memory Breakpoint

   We set the original breakpoint and subsequently the conditional
   expression so that we could obtain the address of a data structure
   specific to this instance of the POLYDEMO window. This value is stored
   in the window’s extra data and is a global handle. The LockWindowInfo
   function retrieves this global handle and uses the Win32 API LocalLock
   to translate it into a pointer that can be used to access the window’s
   instance data.
   1. Obtain the pointer value for the windows instance data by executing
   up to the return statement on source line 57:
   :G .57
   2. Win32 API functions return 32-bit values in the EAX register, so
   you can use the BPMD command and specify the EAX register to set a
   memory breakpoint on the instance data pointer.
   :BPMD EAX
   The BPMD command uses the hardware debug registers provided by Intel
   CPUs to monitor reads and writes to the Dword value at a linear
   address. In this case, you are using BPMD to trap read and write
   accesses to the first Dword of the window instance data.
   3. Use the BL command to verify that the memory breakpoint is set.
   Your output should look similar to the following:
   :BL
   00) BPX LockWindowInfo IF ((ESP->4)==0x100172)
   01) BPMD #0023:001421F8 RW DR3
   Breakpoint index 0 is the execution breakpoint on LockWindowInfo and
   breakpoint index 1 is the BPMD on the window instance data.
   4. Use the BD command to disable the breakpoint on the LockWindowInfo.
   :BD 0
   SoftICE provides the BC (breakpoint clear) and BD (breakpoint disable)
   commands to clear or disable a breakpoint. Disabling a breakpoint is
   useful if you want to re-enable the breakpoint later in your debugging
   session. If you are not interested in using the breakpoint again, then
   it makes more sense to clear it.
   5. Use the BL command to verify that the breakpoint on LockWindowInfo
   is disabled. SoftICE indicates that a breakpoint is disabled by
   placing an asterisk (*) after the breakpoint index. Your output should
   appear similar to the following:
   :BL
   00) * BPX _LockWindowInfo IF ((ESP->4)==0x100172)
   01) BPMD #0023:001421F8 RW DR3
   Note: You can use the BE command to re-enable a breakpoint:
   :BE breakpoint-index-number
   6. Exit SoftICE using the G or X command. When the POLYDEMO window
   accesses the first Dword of its window instance data, the breakpoint
   triggers and SoftICE pops up.
   When SoftICE pops up due to the memory breakpoint, you are in the
   PolyRedraw or PolyDrawBez function. Both functions access the
   nBezTotal field at offset 0 of the POLYDRAW window instance data.
   Note: The Intel CPU architecture defines memory breakpoints as traps,
   which means that the breakpoint triggers after the memory has been
   accessed. In SoftICE, the instruction or source line that is
   highlighted is the one after the instruction or source line that
   accessed the memory.
   7. Clear the breakpoints you set in this section by using the BC
   command:
   :BC *
   Note: You can use the wildcard character (*) with the BC, BD, and BE
   commands to clear, disable, and enable all breakpoints.
   8. Exit SoftICE using the G or X command.
   The operating system terminates the application.
   Congratulations on completing your first SoftICE debugging session. In
   this session, you traced through source code, viewed locals and
   structures, and set point-and-shoot, conditional, and read-write
   memory breakpoints. SoftICE provides many more advanced features. The
   SoftICE commands ADDR, HEAP, LOCALS, QUERY, THREAD, TYPES, WATCH, and
   WHAT are just a few of the many SoftICE commands that help you debug
   smarter and faster. Refer to the SoftICE Command Reference for a
   complete explanation of all the SoftICE commands.
                                         You know my methods. Apply them.
                                                   Sir Arthur Conan Doyle

Using Breakpoints

   Introduction
   Types of Breakpoints Supported by SoftICE
        Breakpoint Options
        Execution Breakpoints
        Memory Breakpoints
        Interrupt Breakpoints
        I/O Breakpoints
        Window Message Breakpoints
   Understanding Breakpoint Contexts
   Virtual Breakpoints
   Setting a Breakpoint Action
   Conditional Breakpoints
        Conditional Breakpoint Count Functions
        Using Local Variables in Conditional Expressions
        Referencing the Stack in Conditional Breakpoints
        Performance
        Duplicate Breakpoints
   Elapsed Time
   Breakpoint Statistics
   Referring to Breakpoints in Expressions
   Manipulating Breakpoints
   Using Embedded Breakpoints

Introduction

   You can use SoftICE to set breakpoints on program execution, memory
   location reads and writes, interrupts, and reads and writes to I/O
   ports. SoftICE assigns a breakpoint index, from 0 to FF, to each
   breakpoint. You can use this breakpoint index to identify breakpoints
   when you set, delete, disable, enable, or edit them.
   All SoftICE breakpoints are sticky, which means that SoftICE tracks
   and maintains a breakpoint until you intentionally clear or disable it
   using the BC or the BD command. After you clear breakpoints, you can
   recall them with the BH command, which displays a breakpoint history.
   You can set up to 256 breakpoints at one time in SoftICE. However, the
   number of breakpoints you can set on memory location (BPMs) and I/O
   ports (BPIOs) is a total of four, due to restrictions of the x86
   processors.
   Where symbol information is available, you can set breakpoints using
   function names. When in source or mixed mode, you can set
   point-and-shoot style breakpoints on any source code line. A valuable
   feature is that you can set point-and-shoot breakpoints in a module
   before it is even loaded.

Types of Breakpoints Supported by SoftICE

   SoftICE provides a powerful array of breakpoint capabilities that take
   full advantage of the x86 architecture, as follows :
  • Execution Breakpoints: SoftICE replaces an existing instruction with

INT 3. You can use the BPX command to set execution breakpoints.

  • Memory Breakpoints: SoftICE uses the x86 debug registers to break when

a certain byte/word/dword of memory is read, written, or executed. You

   can use the BPM command to set memory breakpoints.
  • Interrupt Breakpoints: SoftICE intercepts interrupts by modifying the

IDT (Interrupt Descriptor Table) vectors. You can use the BPINT

   command to set interrupt breakpoints.
  • I/O Breakpoints: SoftICE uses a debug register extension available on

Pentium and Pentium-Pro CPUs to watch for an IN or OUT instruction

   going to a particular port address. You can use the BPIO command to
   set I/O breakpoints.
  • Window Message Breakpoints: SoftICE traps when a particular message or

range of messages arrives at a window. This is not a fundamental

   breakpoint type; it is just a convenient feature built on top of the
   other breakpoint primitives. You can use the BMSG command to set
   window message breakpoints.

Breakpoint Options

   You can qualify each type of breakpoint with the following two
   options:
  • A conditional expression [IF expression]: The expression must evaluate

to non-zero (TRUE) for the breakpoint to trigger. Refer to Conditional

   Breakpoints.
  • A breakpoint action [DO "command1;command2;"]: A series of SoftICE

commands can automatically execute when the breakpoint triggers. You

   can use this feature in concert with user-defined macros to automate
   tasks that would otherwise be tedious. Refer to Setting a Breakpoint
   Action on page 114.
   Note: For complete information on each breakpoint command, refer to
   the SoftICE Command Reference.

Execution Breakpoints

   An execution breakpoint traps executing code such as a function call
   or language statement. This is the most frequently used type of
   breakpoint. By replacing an existing instruction with an INT 3
   instruction, SoftICE takes control when execution reaches the INT 3
   breakpoint.
   SoftICE provides two ways for setting execution breakpoints: using a
   mouse and using the BPX command. The following sections describe how
   to use these methods for setting breakpoints.

Using a Mouse to Set Breakpoints

   If you are using a Pentium processor and a mouse, you can use the
   mouse to set or clear point-and-shoot (sticky) and one-shot
   breakpoints. To set a sticky breakpoint, double-click the line on
   which you want to set the breakpoint. SoftICE highlights the line to
   indicate that you set a breakpoint. Double-click the line again to
   clear the breakpoint. To set a one-shot breakpoint, click the line on
   which you want to set the breakpoint and use the HERE command (F7) to
   execute to that line.

Using the BPX Command to Set Breakpoints

   Use the BPX command with any of the following parameters to set an
   execution breakpoint:
   BPX [address] [IF expression] [DO "command1;command2;"]
   IF expression:
        Refer to Conditional Breakpoints.
   DO "command1;command2;":
        Refer to Setting a Breakpoint Action.
   Example:
        To set a breakpoint on your application's WinMain function, use
        this command:
        BPX WinMain
   Use the BPX command without specifying any parameter to set a
   point-and-shoot execution breakpoint in the source code. Use Alt-C to
   move the cursor into the Code window. Then use the arrow keys to
   position the cursor on the line on which you want to set the
   breakpoint. Finally, use the BPX command (F9). If you prefer to use
   your mouse to set the breakpoint, click the scroll arrows to scroll
   the Code window, then double-click the line on which you want to set
   the breakpoint.

Memory Breakpoints

   A memory breakpoint uses the debug registers found on the 386 CPUs and
   later models to monitor access to a certain memory location. This type
   of breakpoint is extremely useful for finding out when and where a
   program variable is modified, and for setting an execution breakpoint
   in read-only memory. You can only set four memory breakpoints at one
   time, because the CPU contains only four debug registers.
   Use the BPM command to set memory breakpoints:
   BPM[B|W|D] address [R|W|RW|X] [ debug register] [IF expression]
      [DO "command1;command2;"]
   BPM and BPMB:
        Set a byte-size breakpoint.
   BPMW:
        Sets a word (2-byte) size breakpoint.
   BPMD:
        Sets a dword (4-byte) size breakpoint.
   R, W, and RW:
        Break on reads, writes, or both.
   X:
        Breaks on execution; this is more powerful than a BPX-style
        breakpoint because memory does not need to be modified, enabling
        such options as setting breakpoints in ROM or setting breakpoints
        on addresses that are not present.
   debug register:
        Specifies which debug register to use. SoftICE normally manages
        the debug register for you, unless you need to specify it in an
        unusual situation.
   IF expression:
        Refer to Conditional Breakpoints.
   DO "command1;command2;":
        Refer to Setting a Breakpoint Action.
   Example:
        The following example sets a memory breakpoint to trigger when a
        value of 5 is written to the Dword (4-byte) variable
        MyGlobalVariable.
        BPMD MyGlobalVariable W IF MyGlobalVariable==5
   If the target location of a BPM breakpoint is frequently accessed,
   performance can be degraded regardless of whether the conditional
   expression evaluates to FALSE.

Interrupt Breakpoints

   Use an interrupt breakpoint to trap an interrupt through the IDT. The
   breakpoint only triggers when a specified interrupt is dispatched
   through the IDT.
   Use the BPINT command to set interrupt breakpoints:
   BPINT interrupt-number [IF expression] [DO "command1;command2;"]
   interrupt-number:
        Number ranging from 0 to 255 (0 to FF hex).
   IF expression:
        Refer to Conditional Breakpoints.
   DO "command1;command2;":
        Refer to Setting a Breakpoint Action.
   If an interrupt is caused by a software INT instruction, the
   instruction displayed will be the INT instruction. (SoftICE pops up
   when execution reaches the INT instruction responsible for the
   breakpoint, but before the instruction actually executes.) Otherwise,
   the current instruction will be the first instruction of an interrupt
   handler. You can list all interrupts and their handlers by using the
   IDT command.
   Example:
        Use the following command to set a breakpoint to trigger when a
        call to the kernel-mode routine NtCreateProcess is made from user
        mode:
        BPINT 2E IF EAX==1E
        Note: The NtCreateProcess is normally called from ZwCreateProcess
        in the NTDLL.DLL, which is in turn called from CreateProcessW in
        the KERNEL32.DLL. In the conditional expression, 1E is the
        service number for NtCreateProcess. Use the NTCALL command to
        find this value.
   You can use the BPINT command to trap software interrupts, for
   example, INT 21 made by 16-bit Windows programs. Note that software
   interrupts issued from V86 mode do not pass through the IDT vector
   that they specify. INT instructions executed in V86 generate processor
   general protection faults (GPF), which are handled by vector 0xD in
   the IDT. The Windows GPF handler realizes the cause of the fault and
   passes control to a handler dedicated to specific V86 interrupt types.
   The types may end up reflecting the interrupt down to V86 mode by
   calling the interrupt handler entered in the V86 mode Interrupt Vector
   Table (IVT). In some cases, a real-mode interrupt is reflected
   (simulated) by calling the real-mode interrupt vector.
   In the case where the interrupt is reflected, you can trap it by
   placing a BPX breakpoint at the beginning of the real-mode interrupt
   handler.
   Example:
        To set a breakpoint on the real-mode INT 21 handler, use the
        following command:
        BPX *($0:(21*4))

I/O Breakpoints

   An I/O breakpoint monitors reads and writes to a port address. The
   breakpoint traps when an IN or OUT instruction accesses the port.
   SoftICE implements I/O breakpoints by using the debug register
   extensions introduced with the Pentium. As a result, I/O breakpoints
   require a Pentium or Pentium-Pro CPU. A maximum of four I/O
   breakpoints can be set at one time. The I/O breakpoint is effective in
   kernel-level (ring 0) code as well as user (ring 3) code.
   Notes: Under Windows 95, SoftICE relies on the I/O permission bitmap,
   which restricts I/O trapping to ring 3 code.
   Notes: You cannot use I/O breakpoints to trap IN/OUT instructions
   executed by MS-DOS programs. The IN/OUT instructions are trapped and
   emulated by the operating system, and therefore do not generate real
   port I/O, at least not in a 1:1 mapping.
   Use the BPIO command to set I/O breakpoints:
   BPIO port-number [R|W|RW] [IF expression]
      [DO "command1;command2;"]
   R, W, and RW :
        Break on reads (IN instructions), writes (OUT instructions), or
        both, respectively.
   IF expression:
        Refer to Conditional Breakpoints.
   DO "command1;command2;":
        Refer to Setting a Breakpoint Action.
   When an I/O breakpoint triggers and SoftICE pops up, the current
   instruction is the instruction following the IN or OUT that caused the
   breakpoint to trigger. Unlike BPM breakpoints, there is no size
   specification; any access to the port-number, whether byte, word, or
   dword, triggers the breakpoint. Any I/O that spans the I/O breakpoint
   will also trigger the breakpoint. For example, if you set an I/O
   breakpoint on port 2FF, a word I/O to port 2FE would trigger the
   breakpoint.
   Example:
        Use the following command to set a breakpoint to trigger when a
        value is read from port 3FEH with the upper 2 bits set:
        BPIO 3FE R IF (AL & C0)==C0
        The condition is evaluated after the instruction completes. The
        value will be in AL, AX, or EAX because all port I/O, except for
        the string I/O instructions (which are rarely used), use the EAX
        register.

Window Message Breakpoints

   Use a window message breakpoint to trap a certain message or range of
   messages delivered to a window procedure. Although you could implement
   an equivalent breakpoint yourself using BPX with a conditional
   expression, the following BMSG command is easier to use:
   BMSG window-handle [L] [ begin-message [ end-message]]
      [IF expression] [DO "command1;command2;"]
   window-handle:
        Value returned when the window was created; you can use the HWND
        command to get a list of windows with their handles.
   L:
        Signifies that the window message should be printed to the
        Command window without popping into SoftICE.
   begin-message:
        Single Windows message or the lower message number in a range of
        Windows messages. If you do not specify a range with an
        end-message, then only the begin-message will cause a break. For
        both begin-message and end-message, the message numbers can be
        specified either in hexadecimal or by using the actual ASCII
        names of the messages, for example, WM_QUIT.
   end-message:
        Higher message number in a range of Windows messages.
   IF expression:
        Refer to Conditional Breakpoints.
   DO "command1;command2;":
        Refer to Setting a Breakpoint Action.
   When specifying a message or a message range, you can use the symbolic
   name, for example, WM_NCPAINT. Use the WMSG command to get a list of
   the window messages that SoftICE understands. If no message or message
   range is specified, any message will trigger the breakpoint.
   Example:
        To set a window message breakpoint for the window handle 1001E,
        use the following command:
        BMSG 1001E WM_NCPAINT
        SoftICE is smart enough to take into account the address context
        of the process that owns the window, so it does not matter what
        address context you are in when you use BMSG.
        You can construct an equivalent BPX-style breakpoint using a
        conditional expression. Use the HWND command to get the address
        of the window procedure, then use the following BPX command
        (Win32 only):
        BPX 5FEBDD12 IF (esp->8)==WM_NCPAINT
   Warning: When setting a breakpoint using a raw address (not a symbol),
   it is vital to be in the correct address context.

Understanding Breakpoint Contexts

   A breakpoint context consists of the address context in which the
   breakpoint was set and in what code module the breakpoint is in, if
   any. Breakpoint contexts apply to the BPX and BPM commands, and
   breakpoint types based on those commands such as BMSG.
   For Win32 applications, breakpoints set in the upper 2GB of address
   space are global; they break in any context. Breakpoints set in the
   lower 2GB are context-sensitive; they trigger according to the
   following criteria and SoftICE pops up:
  • SoftICE only pops up if the address context matches the context

in which the breakpoint was set.

  • If the breakpoint triggers in the same code module in which the

breakpoint was set, then SoftICE disregards the address context

        and pops up. This means that a breakpoint set in a shared module
        like KERNEL32.DLL breaks in every address context that has the
        module loaded, regardless of what address context was selected
        when the breakpoint was set.
        The exception is if another process mapped the module at a
        different base address than the one in which the breakpoint is
        set. In this case, the breakpoint does not trigger. Avoid this
        situation by basing your DLLs at non-conflicting addresses.
   Breakpoints set on MS-DOS and 16-bit Windows programs are
   context-sensitive too in the sense that the breakpoint only affects
   the NTVDM process in which the breakpoint was set. The breakpoint
   never crosses NTVDMs, even if the same program is run multiple times.
   Breakpoint contexts are more important for BPM-type breakpoints than
   for BPX. BPM sets an x86 hardware breakpoint that triggers on a
   certain virtual address. Because the CPU's breakpoint hardware knows
   nothing of address spaces, it could potentially trigger on an
   unrelated piece of code or data. Breakpoint contexts give SoftICE the
   ability to discriminate between false traps and real ones.

Virtual Breakpoints

   In SoftICE, you can set breakpoints in Windows modules before they
   load, and it is not necessary for a page to be present in physical
   memory for a BPX (INT 3) breakpoint to be set. In such cases, the
   breakpoint is virtual; it will be automatically armed when the module
   loads or the page becomes present. Virtual breakpoints can only be set
   on either symbols or source lines.

Setting a Breakpoint Action

   You can set a breakpoint to execute a series of SoftICE commands,
   including user-defined macros, after the breakpoint is triggered. You
   define these breakpoint actions with the DO option, which is available
   with every breakpoint type:
   DO "command1;command2;"
   The body of a breakpoint action definition is a sequence of SoftICE
   commands or other macros, separated by semicolons. You need not
   terminate the final command with a semicolon.
   Breakpoint actions are closely related to macros. Refer to Working
   with Persistent Macros on page 162 for more information about macros.
   Breakpoint actions are essentially unnamed macros that do not accept
   command-line arguments. Breakpoint actions, like macros, can call upon
   macros. In fact a prime use of macros is to simplify the creation of
   complex breakpoint actions.
   If you need to embed a literal quote character (") or a percent sign
   (%) within the macro (breakpoint) body, precede the character with a
   backslash character (\). To specify a literal backslash character, use
   two consecutive backslashes (\\).
   If a breakpoint is being logged (refer to the built-in function
   BPLOG), the action will not be executed.
   The following examples illustrate the basic use of breakpoint actions:
   BPX EIP DO "dd eax"
   BPX EIP DO "data 1;dd eax"
   BPMB dataaddr if (byte(*dataaddr)==1) do "? IRQL"

Conditional Breakpoints

   Conditional breakpoints provide a fast and easy way to isolate a
   specific condition or state within the system or application you are
   debugging. By setting a breakpoint on an instruction or memory address
   and supplying a conditional expression, SoftICE will only trigger if
   the breakpoint evaluates to non-zero (TRUE). Because the SoftICE
   expression evaluator handles complex expressions easily, conditional
   expressions take you right to the problem or situation you want to
   debug with ease.
   All SoftICE breakpoint commands (BPX, BPM, BPIO, BMSG, and BPINT)
   accept conditional expressions using the following syntax:
   breakpoint-command [ breakpoint options] [IF conditional expression]
      [DO "commands"]
   The IF keyword, when present, is followed by any expression that you
   want to be evaluated when the breakpoint is triggered. The breakpoint
   will be ignored if the conditional expression is FALSE (zero). When
   the conditional expression is TRUE (non-zero), SoftICE pop ups and
   displays the reason for the break, which includes the conditional
   expression.
   The following examples show conditional expressions used during the
   development of SoftICE.
   Note: Most of these examples contain system-specific values that vary
   depending on the exact version of Windows NT you are running.
  • Watch a thread being activated:
        bpx ntoskrnl!SwapContext IF (edi==0xFF8B4020)
  • Watch a thread being deactivated:
        bpx ntoskrnl!SwapContext IF (esi==0xFF8B4020)
  • Watch CSRSS HWND objects (type 1) being created:
        bpx winsrv!HMAllocObject IF (esp->c == 1)
  • Watch CSRSS thread info objects (type 6) being destroyed:
        bpx winsrv!HMFreeObject+0x25 IF (byte(esi->8) == 6)
  • Watch process object-handle-tables being created:
        bpx ntoskrnl!ExAllocatePoolWithTag IF (esp->c == ‘Obtb')
  • Watch a thread state become terminated (enum == 4):
        bpmb _thread->29 IF byte(_thread->29) == 4)
  • Watch a heap block (230CD8) get freed:
        bpx ntddl!RtlFreeHeap IF (esp->c == 230CD8)
  • Watch a specific process make a system call:
        bpint 2E if (process == _process)
   Many of the previous examples use the thread and process intrinsic
   functions provided by SoftICE. These functions refer to the active
   thread or process in the operating system. In some cases, the examples
   precede the function name with an underscore "_". This is a special
   feature that makes it easier to refer to a dynamic value such as a
   register's contents or the currently running thread or process as a
   constant. The following examples should help to clarify this concept:
  • This example sets a conditional breakpoint that will be triggered if

the dynamic (run-time) value of the EAX register equals its current

   value.
        bpx eip IF (eax == _eax)
   This is equivalent to:
        ? EAX
        00010022
        bpx eip IF (eax == 10022)
  • This example sets a conditional breakpoint that will be triggered if

the value of an executing thread's thread-id matches the thread-id of

   the currently executing thread.
        bpx eip IF (tid == _tid)
   This is equivalent to:
        ? tid
        8
        bpx eip IF (tid == 8)
   When you precede a function name or register with an underscore in an
   expression, the function is evaluated immediately and remains constant
   throughout the use of that expression.

Conditional Breakpoint Count Functions

   SoftICE supports the ability to monitor and control breakpoints based
   on the number of times a particular breakpoint has or has not been
   triggered. You can use the following count functions in conditional
   expressions:
  • BPCOUNT
  • BPMISS
  • BPTOTAL
  • BPLOG
  • BPINDEX

BPCOUNT

   The value for the BPCOUNT function is the current number of times that
   the breakpoint has been evaluated as TRUE.
   Use this function to control the point at which a triggered breakpoint
   causes a popup to occur. Each time the breakpoint is triggered, the
   conditional expression associated with the breakpoint is evaluated. If
   the condition evaluates to TRUE, the breakpoint instance count
   (BPCOUNT) increments by one. If the conditional evaluates to FALSE,
   the breakpoint miss instance count (BPMISS) increments by one.
   Example:
        The fifth time the breakpoint triggers, the BPCOUNT equals 5, so
        the conditional expression evaluates to TRUE and SoftICE pops up.
        bpx myaddr IF (bpcount==5)
   Use BPCOUNT only on the righthand side of compound conditional
   expressions for BPCOUNT to increment correctly:
   bpx myaddr if (eax==1) && (bpcount==5)
   Due to the early-out algorithm employed by the expression evaluator,
   the BPCOUNT==5 expression will not be evaluated unless EAX==1. (The C
   language works the same way.) Therefore, by the time BPCOUNT==5 gets
   evaluated, the expression is TRUE. BPCOUNT will be incremented and if
   it equals 5, the full expression evaluates to TRUE and SoftICE pops
   up. If BPCOUNT != 5, the expression fails, BPMISS is incremented and
   SoftICE will not pop up (although BPCOUNT is now 1 greater).
   Once the full expression returns TRUE, SoftICE pops up, and all
   instance counts (BPCOUNT and BPMISS) are reset to 0.
   Note: Do not use BPCOUNT before the conditional expression, otherwise
   BPCOUNT will not increment correctly:
   bpx myaddr if (bpcount==5) && (eax==1)

BPMISS

   The value for the BPMISS expression function is the current number of
   times that the breakpoint was evaluated as FALSE.
   The expression function is similar to the BPCOUNT function. Use it to
   specify that SoftICE pop up in situations where the breakpoint is
   continually evaluating to FALSE. The value of BPMISS will always be
   one less than you expect, because it is not updated until the
   conditional expression is evaluated. You can use the (>=) operator to
   correct this delayed update condition.
   Example:
        bpx myaddr if (eax==43) || (bpmiss>=5)
   Due to the early-out algorithm employed by the expression evaluator,
   if the expression eax==43 is ever TRUE, the conditional evaluates to
   TRUE and SoftICE pops up. Otherwise, BPMISS is updated each time the
   conditional evaluates to FALSE. After 5 consecutive failures, the
   expression evaluates to TRUE and SoftICE pops up.

BPTOTAL

   The value for the BPTOTAL expression function is the total number of
   times that the breakpoint was triggered.
   Use this expression function to control the point at which a triggered
   breakpoint causes a popup to occur. The value of this expression is
   the total number of times the breakpoint was triggered (refer to the
   Hits field in the output of the BSTAT command) over its lifetime. This
   value is never cleared.
   Example:
        The first 50 times this breakpoint is triggered, the condition
        evaluates to FALSE and SoftICE will not pop up. Every time after
        50, the condition evaluates to TRUE, and SoftICE pops up on this
        and every subsequent trap.
        bpx myaddr if (bptotal > 50)
   You can use BPTOTAL to implement functionality identical to that of
   BPCOUNT. Use the modulo "%" operator as follows:
   if (!(bptotal%COUNT))
   The COUNT is the frequency with which you want the breakpoint to
   trigger. If COUNT is 4, SoftICE pops up every fourth time the
   breakpoint triggers.

BPLOG

   Use the BPLOG expression function to log the breakpoint to the history
   buffer. SoftICE does not pop up when logged breakpoints trigger.
   Note: Actions only execute when SoftICE pops up, so using actions with
   the BPLOG function is pointless.
   The BPLOG expression function always returns TRUE. It causes SoftICE
   to log the breakpoint and relevant information about the breakpoint to
   the SoftICE history buffer.
   Example:
        Any time the breakpoint triggers and the value of EAX equals 1,
        SoftICE logs the breakpoint in the history buffer. SoftICE will
        not popup.
        bpx myaddr if ((eax==1) && bplog)

BPINDEX

   Use the BPINDEX expression function to obtain the breakpoint index to
   use with breakpoint actions.
   This expression function returns the index of the breakpoint that
   caused SoftICE to pop up. This index is the same index used by the BL,
   BC, BD, BE, BPE, BPT, and BSTAT commands. You can use this value as a
   parameter to any command that is being executed as an action.
   Example:
        This example of a breakpoint action causes the BSTAT command to
        be executed with the breakpoint that caused the action to be
        executed as its parameter:
        bpx myaddr do "bstat bpindex"
        This example shows a breakpoint that uses an action to create
        another breakpoint:
        bpx myaddr do "t;bpx @esp if(tid==_tid) do \"bc bpindex\";g"
   Note: BPINDEX is intended to be used with breakpoint actions, and
   causes an error if it is used within a conditional expression. Its use
   outside of actions is allowed, but the result is unspecified and you
   should not rely on it.

Using Local Variables in Conditional Expressions

   SoftICE lets you use local variable names in conditional expressions
   as long as the type ofbreakpoint is an execution breakpoint (BPX or
   BPM X). SoftICE does not recognize local symbols in conditional
   expressions for other breakpoint types, such as BPIO or BPMD RW,
   because they require an execution scope. This type of breakpoint is
   not tied to a specific section of executing code, so local variables
   have no meaning.
   When using local variables in conditional expressions, functions
   typically have a prologue where local variables are created and an
   epilogue where they are destroyed. You can access local variables
   after the prologue code completes execution and before the epilogue
   code begins execution. Function parameters are also temporarily
   inaccessible using symbol names during prologue and epilogue
   execution, because of adjustments to the stack frame.
   To avoid these restrictions, set a breakpoint on either the first or
   last source code line within the function body. The following concepts
   use the foobar function to explain this concept.

Foobar Function

   1:DWORD foobar ( DWORD foo )
   2:{
   3: DWORD fooTmp=0;
   4:
   5: if(foo)
   6: {
   7: fooTmp=foo*2;
   8: }else{
   9: fooTmp=1;
   10: }
   11:
   12: return fooTmp;
   13:}
   Source code lines 1 and 2 are outside the function body. These lines
   execute the prologue code. If you use a local variable at this point,
   you receive the following symbol error:
   :BPX foobar if(foo==1)
   error: Undefined Symbol (foo)
   Set the conditional on the source code line 3 where the local variable
   fooTmp is declared and initialized, as follows:
   :BPX .3 if(foo==0)
   Source code line 13 marks the end of the function body. It also begins
   epilogue code execution; thus, local variables and parameters are out
   of scope. To set a conditional at the end of the foobar function, use
   source line 12, as follows:
   :BPX.12 if(fooTmp==1)
   Note: Although it is possible to use local variables as the input to a
   breakpoint command, such as BPMD RW, you should avoid doing this.
   Local variables are relative to the stack, so their absolute address
   changes each time the function scope where the variable is declared
   executes. When the original function scope exits, the address tied to
   the breakpoint no longer refers to the value of the local variable.

Referencing the Stack in Conditional Breakpoints

   If you create your symbol file with full symbol information, you can
   access function parameters and local variables through their symbolic
   names, as described in Using Local Variables in Conditional
   Expressions. If, however, you are debugging without full symbol
   information, you need to reference function parameters and local
   variables on the stack. For example, if you translated a module with
   publics only or you want to debug a function for an operating system,
   reference function parameters and local variables on the stack.
   This section is specific to 32-bit flat application or system code.
   Function parameters are passed on the stack, so you need to
   de-reference these parameters through the ESP or EBP registers. Which
   one you use depends on the function's prologue and where you set the
   actual breakpoint in relation to that prologue.
   Most 32-bit functions have a prologue of the following form:
   PUSH EBP
   MOV EBP,ESP
   SUB ESP,size (locals)
   Which sets up a stack frame as follows:
    Stack Top          PARAM n           ESP+(n*4), or
                                          EBP+(n*4)+4        Pushed by
                       PARAM #2         ESP+8, or EBP+C        Caller
                       PARAM #1         ESP+4, or EBP+8
                       RET EIP         Stack pointer on
                                             Entry
              Current                 Base Pointer (PUSH
                EBP    SAVE EBP        EBP, MOV EBP,ESP)
                       LOCALS+SIZE-1                       Call prologue
                                      Stack Pointer after
                       LOCALS+0       prologue (SUB ESP,
                                         size(locals)
                       SAVE EBX      Optional save of "C"
                                           registers          Register
                       SAVE ESI                               saved by
      Stack   Current                 Stack pointer after     compiler
     Bottom     ESP    SAVE EDI       registers are saved
   Use either the ESP or EBP register to address parameters. Using the
   EBP register is not valid until the PUSH EBP and MOV EBP, ESP
   instructions are executed. Also note that once space for local
   variables is created (SUB ESP,size) the position of the parameters
   relative to ESP needs to be adjusted by the size of the local
   variables and any saved registers.
   Typically you set a breakpoint on the function address, for example:
   BPX IsWindow
   When this breakpoint is triggered, the prologue has not been executed,
   and parameters can easily be accessed through the ESP register. At
   this point, use of EBP is not valid.
   To be sure that de-referencing the stack in a conditional expression
   operates as you would expect, use the following guidelines.
   Note: This assumes a stack-based calling convention with arguments
   pushed right-to-left.
  • If you set a breakpoint at the exact function address, for example,

BPX IsWindow, use ESP+(param# * 4) to address parameters, where param#

   is 1...n.
  • If you set a breakpoint inside a function body (after the full

prologue has been executed), use EBP+(param# * 4)+4 to address

   parameters, where param# is 1...n. Be sure that the routine does not
   use the EBP register for a purpose other than a stack-frame.
  • Functions that are assembly-language based or are optimized for

frame-pointer omission may require that you use the ESP register,

   because EBP may not be set up correctly.
   Note: Once the space for local variables is allocated on the stack,
   the local variables can be addressed using a negative offset from EBP.
   The first local variable is at EBP-4. Simple data types are typically
   Dword sized, so their offset can be calculated in a manner similar to
   function parameters. For example, with two pointer local variables,
   one will be at EBP-4 and the other will be at EBP-8.

Performance

   Conditional breakpoints have some overhead associated with run-time
   evaluation. Under most circumstances you see little or no effect on
   performance when using conditional expressions. In situations where
   you set a conditional breakpoint on a highly accessed data variable or
   code sequence, you may notice slower system performance. This is due
   to the fact that every time the breakpoint is triggered, the
   conditional expression is evaluated. If a routine is executed hundreds
   of times per second (such as ExAllocatePool or SwapContext), the fact
   that any type of breakpoint with or without a conditional is trapped
   and evaluated with this frequency results in some performance
   degradation.

Duplicate Breakpoints

   Once a breakpoint is set on an address, you cannot set another
   breakpoint on the same address. With conditional expressions, however,
   you can create a compound expression using the logical operators (&&)
   or (||) to test more than one condition at the same address.

Elapsed Time

   SoftICE supports using the time stamp counter (RDTSC instruction) on
   all Pentium and Pentium-Pro machines. When SoftICE first starts, it
   displays the clock speed of the machine on which it is running. Every
   time SoftICE pops up due to a breakpoint, the elapsed time displays
   since the last time SoftICE popped up. The time displays after the
   break reason in seconds, milliseconds, or microseconds:
   Break due to G (ET=23.99 microseconds)
   The Pentium cycle counter is highly accurate, but you must keep the
   following two issues in mind:
   1- There is overhead involved in popping SoftICE up and down. On a
   100MHz machine, this takes approximately 5 microseconds. This number
   is slightly variable due to caching and privilege level changes.
   2- If a hardware interrupt occurs before the breakpoint goes off, all
   the interrupt processing time is included. Interrupts are off when
   SoftICE pops up, so a hardware interrupt almost always goes off as
   soon as Windows NT resumes.

Breakpoint Statistics

   SoftICE collects statistical information about each breakpoint,
   including the following:
  • Total number of hits, breaks, misses, and errors
  • Current hits and misses
   Use the BSTAT command to display this information. Refer to the
   SoftICE Command Reference for more information on the BSTAT command.

Referring to Breakpoints in Expressions

   You can combine the prefix "BP" with the breakpoint index to use as a
   symbol in an expression. This works for all BPX and BPM breakpoints.
   SoftICE uses the actual address of the breakpoint.
   Example:
        To disassemble code at the address of the breakpoint with index
        0, use the command:
        U BP0

Manipulating Breakpoints

   SoftICE provides a variety of commands for manipulating breakpoints
   such as listing, modifying, deleting, enabling, disabling, and
   recalling breakpoints. Breakpoints are identified by breakpoint index
   numbers, which are numbers ranging from 0 to FF (hex). Breakpoint
   index numbers are assigned sequentially as breakpoints are added. The
   following table describes the breakpoint manipulation commands:
    BD Disable a breakpoint
    BE Enable a breakpoint
    BL List current breakpoints
    BPEEdit a breakpoint
    BPTUse breakpoint as template
    BC Clear (remove) a breakpoint
    BH Display breakpoint history
   Note: Refer to the SoftICE Command Reference for more information on
   each of these commands.

Using Embedded Breakpoints

   It may be helpful for you to embed a breakpoint in your program source
   rather than setting a breakpoint with SoftICE. To embed a breakpoint
   in your program, do the following:
   1 Place an INT 1 or INT 3 instruction at the desired point in the
   program source.
   2 To enable SoftICE to pop up on such embedded breakpoints, use the
   following command:
   SET I1HERE ON ; for INT 1 breakpoints
   SET I3HERE ON ; for INT 3 breakpoints
/data/webs/external/dokuwiki/data/pages/archive/programming/softice.manual.txt · Last modified: 2001/05/04 05:51 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki