💾 Archived View for spam.works › mirrors › textfiles › programming › softice.manual.txt captured on 2023-06-16 at 20:12:17.
-=-=-=-=-=-=-
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,'