What's New in SoftICE 3.

0
Here is a quick tour of the new features in SoftICE 3.0.

SoftICE 3.0 is available separately for Windows 95 and Windows NT. Many enhancements apply to both
versions of SoftICE. In addition, many new features are now available to Windows 95 users that were previously
only available in the Windows NT version of SoftICE.

Contents
What's New For All SoftICE Users
SoftICE Symbol Loader
Quick Start to Debugging
Pre-Loading Symbols and Source Code for Device Driver Debugging
Using Translation Options
Choosing the "Package Source…" Option
Using Symbol Loader from the Command Line
Using NMSYM to Automate Translation and Loading
Locals and Structures Support
Using the Locals Window
Using Local Variables in Conditional Expressions
Using the Watch Window
Mouse Support
New and Enhanced Commands for All Users
What's New For Windows 95 SoftICE Users
New and Enhanced Commands for Windows 95 Users
Using the New Expression Evaluator

What's New For All SoftICE Users

SoftICE 3.0 combines the power you expect with these great new features:

· New Symbol Loader lets you start debugging fast

· Locals and Structures support shows your data the way you understand it

· Mouse support speeds up your debugging session

· New commands provide more system visibility: CPU, FIBER, PCI, PEEK and POKE

· Comprehensive on-line manuals help you take advantage of the power of SoftICE

SoftICE Symbol Loader

Symbol Loader (LOADER32.EXE) replaces all the separate utilities you needed in previous SoftICE versions.
Open your module and press the Load button to start debugging with complete symbol information. There's no
need to run DBG2MAP and MSYM before you can load source and symbols. The new loader makes all the old
utilities obsolete for Windows applications. You still need to use them for MS-DOS applications, and will find
them in the UTIL16 directory.

What's New in SoftICE 3.0 Page 1

Quick Start to Debugging

1) Run Symbol Loader (LOADER32.EXE).

2) Choose File-Open Module, and select the module you want to debug.

3) Choose Module-Load (or click the Load button on the toolbar). SoftICE automatically extracts symbol
information from your module, creates a .NMS file containing the information, loads the symbols and source
code, and, if you are loading an EXE file, loads the EXE and sets a breakpoint. You're ready to start debugging.

Other features to check in the new symbol loader:

* Module-Settings (symbol translation and debug options for your module)

* Module-Translate (creates a .NMS file for pre-loading symbols at start up)

* Edit-SoftICE Initialization Settings (replaces WINICE.DAT)

* File-Load Exports (loads exported symbols for DLLs you select)

* File-Save SoftICE History (replaces WLOG and DLOG)

Pre-Loading Symbols and Source Code for Device Driver Debugging

1) Run Symbol Loader (LOADER32.EXE), and open the module you want to debug.

2) Choose Module-Settings, and select the Translation page. Check "Package source with symbol table."

3) Choose Module-Translate (or click the Translate button) to create a .NMS symbol file.

4) Choose Edit-SoftICE Initialization Settings, and select the Symbols page. Add your .NMS file to the list.

5) Restart your system. Your symbols and source code will automatically be loaded with SoftICE.

SoftICE no longer supports loading .SYM files directly at initialization time. Use Symbol Loader to convert .SYM
files to .NMS format. Your translation options determine if your .NMS file includes source code.

Using Translation Options

Use Translation options on the Module-Settings dialog to select how much information is stored in your .NMS
file. The options are arranged in order of increasing memory requirements.

· Publics only

This option provides public (global) symbol names. Your .NMS file will not include statics, locals, type
information or source code. This option uses the least amount of symbol memory.

· Type information only

What's New in SoftICE 3.0 Page 2

 Only the type information is included. This option is primarily used when advanced type information can
be produced without the original source code or debug information.

· Symbols only (includes locals and structures)

This option includes global, static and local symbols, as well as type information. Source code and line
numbers are not included. This produces smaller symbol tables.

· Symbols and source code

This option includes all available debugging information, include source code and line number information.

Choosing the “Package Source…” Option

There are two primary reasons for choosing to package your source code with the actual NMS symbol table:

· Using NMS symbol information to pre-load symbols and source (i.e. LOAD= ).

SoftICE does not attempt to locate source information at start up. If you need to have source code
loaded for a .VxD or Windows NT device driver, then you must choose the Package Source option.

· Optimization when debugging without recompiling.

· Convenience or efficiency when packaging a module for debugging on a system that does not have access
to your source files, or when you plan to reload frequently between recompiles.

If you use the Package option, your source code is attached to the .NMS file. You probably do not want to
distribute your .NMS file or leave it in a place that is accessible to non-employees of your company.

Using Symbol Loader from the Command Line

Symbol Loader (LOADER32.EXE) supports basic command line arguments to let you create short-cuts for your
most common or repetitive tasks. You might want to place a short-cut on your desktop to save the SoftICE
history to a file, or to load an application you are debugging. LOADER32 is not intended for batch automation,
because it has limited error handling, and uses default settings for translation and loading. A separate utility
(NMSYM.EXE) is provided for batch automation.

The basic command line syntax is as follows:

Loader32 [ [option(s)] file-name]

where options are:

/TRANSLATE · Perform the default translation for the module-type, or if settings exist, use those
settings.
/LOAD · Perform the default translation (if required) and perform the default load for the
module-type. If settings exist, they will be used for both translation and load.
/EXPORTS · Load exports for a file.
/LOGFILE · Create a log file.
/PACKAGE · Turns on source packaging for file-name specified. Ignored if no file-name is used.
/NOPROMPT · Turns off source prompting for file-name specified. Ignored if no file-name is used.

What's New in SoftICE 3.0 Page 3

None of the options are required, and specifying a file name will simply open that file for use inside the GUI.
When an option is specified, the GUI will not appear UNLESS there is an error. In the case of an error, a
message will be displayed in the GUI status pane.

You may specify both TRANSLATE and LOAD as options (only required if you want to *force* a symbol file to
translated), but all other options are mutually exclusive.

Using NMSYM to Automate Translation and Loading

NMSYM is a utility program that allows you to implement batch automation of translating and loading symbol
information for use with SoftICE.

NMSYM provides two complimentary sets of functionality analogous to the SoftICE Symbol Loader
(Loader32.exe). The primary functionality allows you to set all the parameters related to translating and loading
symbol information for an individual module. The secondary functionality allows you to automate the loading or
unloading groups of symbol tables or module exports. Also included is the ability to obtain product version
information and save the SoftICE history log.

Refer to Using SoftICE in the on-line documentation for a full description of NMSYM. For quick help on NMSYM
command syntax and usage, run:

NMSYM /HELP

Locals and Structures Support

Now you can use symbol names to view and manipulate locals and structures in Windows modules. The Locals
Window displays your current stack frame and lets you expand or condense structures and other complex
types. The Watch window supports typed expressions that can be expanded and collapsed. It functions as a
"global watch" window.

The new SoftICE Loader extracts enhanced type information from your module's debug information, creating a
file in NuMega 32 bit symbol format (NM32). Files in this format have the extension .NMS. SoftICE supports the
following debug formats: PDB, 16-bit and 32-bit Codeview, 32-bit Borland (including Delphi), COFF and SYM.

The SoftICE Expression evaluator uses type information to provide enhanced functionality. This includes the
ability to cast to a type, indirect through class and structure types, take the address of a class or structure
member, perform symbol lookups on local and global symbols, and display variables in type format.

Using the Locals Window

When you enter a procedure, the Locals window is empty. After the function's prologue code executes, function
parameters and local variables appear. You can expand or condense items in the Locals window with the
keyboard or the mouse (Pentium only).

TO DO THIS: USE THIS KEY SEQUENCE: OR THIS MOUSE ACTION

Set focus to/from locals window Alt-L click in locals window
Open or close the locals window WL [window-size] not supported
Expand or condense an item Scroll to the item, then press Enter double-click item (Pentium only)
Scroll the locals window one line NORTH | SOUTH click on outermost scroll arrows
Scroll up or down one page Page Up | Page Down click on innermost scroll arrows
Scroll to first or last item HOME | END not supported

What's New in SoftICE 3.0 Page 4

Horizontal scroll EAST | WEST click on horizontal scroll arrows

Using Local Variables in Conditional Expressions

SoftICE allows the use of local variable names in conditional expressions if the type of breakpoint is an
execution breakpoint (BPX or BPM X). In conditional expressions for other breakpoint types (such as BPIO or
BPMD RW), locals symbols are not recognized because their use requires an execution scope. Because these
type of breakpoints are not tied to a specific section of executing code, local variables have no meaning.

When using local variables in conditional expressions, it is important to remember that functions typically have a
prologue where local variables are created, and an epilogue where they are destroyed. Local variables are not
accessible until the prologue code has completed execution, and are also inaccessible once the epilogue code
begins executing. Because of the adjustments to the stack frame during execution of the prologue and epilogue
code, function parameters are also temporarily inaccessible using symbol names.

These issues are easily worked around by setting the breakpoint on the first or last source code line within the
function body.

Example:

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:}

For the function foobar source code lines 1 and 2 are outside the function body. This is where the prologue
code is executed. Attempting to use a local variable or parameter at this point will result in a symbol not found
error as follows:

:BPX foobar if ( foo == 1 )

error: Undefined Symbol (foo)

Instead of setting the conditional breakpoint on the function name or source code line 1 or 2, set the conditional
on source code line 3 where the local variable fooTmp is declared and initialized:

:BPX .3 if (foo==0)

Source code line 13 marks the end of the function body, and is where the epilogue code begins execution. At
this point, local variables and parameters are considered to be out of scope. To set a conditional at the end of
the function, use source line 12:

:BPX .12 if ( fooTmp == 1)

What's New in SoftICE 3.0 Page 5

NOTE: While it is possible to use local variables as the input to a breakpoint command (such as BPMD RW),
their use is not recommended. This is because local variables are relative to the stack, and as such, their
absolute address changes each time the function scope where the variable is declared is executed. Once the
original function scope exits, the address tied to the breakpoint will no longer refer to the value of the local
variable.

Using the Watch Window

Now you can set watches on local variables and structure data. You can expand or condense items in the
Watch window with the keyboard or the mouse (Pentium only). If a watch item goes out of scope, the message
"error evaluating expression" is displayed for the item until it comes back in scope. SoftICE uses the item's type
information to determine the correct size and format to display. You can set more than eight watches, determine
the size of the watch window, and use the keyboard or mouse to scroll it.

TO DO THIS: USE THIS KEY SEQUENCE: OR THIS MOUSE ACTION

Set focus to/from watch window Alt-W click in watch window
Open or close the watch window WW [window-size] not supported
Add a watch WATCH expression not supported
Delete a watch Scroll to the item, then press DELETE Click item, then press DELETE
Expand or condense an item Scroll to the item, then press Enter double-click item (Pentium only)
Scroll the watch window one line NORTH | SOUTH click on outermost scroll arrows
Scroll up or down one page Page Up | Page Down click on innermost scroll arrows
Scroll to first or last item HOME | END not supported
Horizontal scroll EAST | WEST click on horizontal scroll arrows

Mouse Support
Select your mouse type at install-time, or change it later with Mouse Setup. Options are Serial (COM1 or
COM2, Microsoft-compatible mouse only), PS/2 or None. Double-click is only supported for Pentium-class
machines.

Note: The mouse is not supported if you are using SoftICE from a second PC with the SERIAL.EXE utility.

Use SET MOUSE [on | off] to enable or disable the SoftICE mouse at run-time. Use SET MOUSE ON [1|2|3] to
adjust the speed of mouse movements (1=slow, 2=normal, 3=fast).

What you can do with the mouse:

· Set breakpoints in the Code window. Double-click sets or clears a breakpoint (Pentium only). Single click
selects a line, then use F7 or HERE command to execute to that line.

· Right click to display a context menu of frequently used functions such as Copy, Paste, Unassemble,
Display and What. You can point at a function name and select Unassemble to show the code for that
function. Then use the Previous command to go back to the code window originally displayed. Point at a
data item and press What to identify what the item is, or press Display to dump the item to the data
window. The Previous command restores the data window to its prior state.

· Double-click to expand or collapse structures in the Locals and Watch windows (Pentium only).

· Scroll Command, Code, Locals, Watch and Data windows by clicking on the scroll arrows.

What's New in SoftICE 3.0 Page 6

· Resize windows by dragging the divider line (Pentium only).

· Edit items in the Register and Data windows.

New and Enhanced Commands For All Users

COMMAND NEW MAJOR WHAT'S NEW
CHANGE
Alt-C X Set focus to or from the Code window.
Alt-D X Set focus to or from the Data window.
Alt-L X Set focus to or from the Locals window.
Alt-R X Set focus to or from the Register window.
Alt-W X Set focus to or from the Watch window.
Ctrl-C X Copy data selected with mouse.
Ctrl-V X Paste data from SoftICE copy buffer to the Command window.
Esc X Returns the cursor to the Command window, or discards the line
being edited if cursor is already in the Command window.
Home key X Returns to first column of Code, Locals or Watch window if you
have scrolled the window horizontally.
CPU X Display CPU register information (replaces CR). CPU -i displays
the I/O APIC.
CR X Obsolete. Use CR to display the control registers.
CWATCH X Obsolete. To delete a watch, select item in watch window, then
press Delete.
FIBER [address] X NT only. Displays a fiber data structure returned by
CreateFiber(). If no address is specified the fiber data associated
with the current thread is displayed.
HELP X Get help on command (alias for H command).
LOCALS X Lists local variables (the current stack frame) in the command
window.
Example:
:locals
[EBP-4] struct _BOUNCEDATA * pbd = 0x0000013F <{...}>
[EBP+8] void * hWnd = 0x000006D8
NOTYPE type cast X Causes the expression evaluator to ignore type information when
operator it evaluates an expression or sub-expression. Instead, it displays
the expression in hexadecimal, decimal, and ASCII.
Example:
:? ebx
unsigned long = 0x63F92E, "\0c\xF9."
:? notype (ebx)
0063F92E 0006551854 "cù."

What's New in SoftICE 3.0 Page 7

PCI X Displays PCI information. SoftICE cannot detect if the PCI
register actually exists, so do not use on a non-PCI system.
PEEK[size] addr X Read from physical memory. Useful for reading memory-mapped
I/O registers. Size is B (byte), W (word) or D (dword).
POKE[size] addr value X Write to physical memory. Useful for writing to memory-mapped
I/O registers. Size is B (byte), W (word) or D (dword).
SET CASESENSITIVE X If on, requires local and global symbol names to be typed exactly
[on|off] as displayed by the SYM command.
SET MOUSE [on|off] [1| X Enables or disables mouse support in SoftICE, and sets the
2|3] speed of mouse movements (1=slow, 2=normal, 3=fast).
SET SYMBOLS [on|off] X If on, the disassembler displays symbol names. If off, the
disassembler displays numbers (values or addresses).
TABLE R X Removing tables with TABLE R is no longer supported. Use
SoftICE Loader-Edit-Symbol Tables to remove tables.
TYPES [type-name] X Lists all types in the current context if no type-name is entered,
or displays all type information for the type-name entered. If
type-name is a structure, expands the structure and displays the
typedefs for all members.

Example (no type-name entered, partial listing):

:types
Size Type Name Typedef
0x0004 ABORTPROC int stdcall (*proc) ( void )
0x0004 ACCESS_MASK unsigned long
0x0004 ACL_INFORMATION_CLASS int
0x0018 ARRAY_INFO struct ARRAY_INFO
0x0002 ATOM unsigned short
0x0048 BALLDATA struct _BALLDATA
0x0048 _BALLDATA struct _BALLDATA
0x0020 _BEZBUFFER struct _BEZBUFFER
0x0004 BOOL int
0x0001 BOOLEAN unsigned char
0x0010 _BOUNCEDATA struct _BOUNCEDATA
0x0004 BSTR unsigned short *

Example (type-name entered):

:types _bouncedata
typedef struct _BOUNCEDATA {
public:
void * hBall1 ;
void * hBall2 ;
void * hBall3 ;
void * hBall4 ;
};

What's New in SoftICE 3.0 Page 8

WATCH X SoftICE automatically determines the size of the item to be
watched based on its type information. WATCHB, WATCHW,
WATCHD, WATCHS, WATCHL and WATCHT are no longer
supported.
WL [window-size] X Opens and closes the new Locals window. [Window-size] sets
the number of lines for the window.
WSTR type cast X Use this operator with the expression evaluator to display
operator UNICODE strings. Example:
? WSTR(eax)
short *eax = <“Company Name”>
WW [window-size] X Opens and closes Watch window. No longer restricted to 8
watch items. [Window-size] sets the number of lines for the
window.

What's New For Windows 95 SoftICE Users

For Windows 95, we updated SoftICE with many features that first appeared in the Windows NT version.
Highlights include:

· Automatic VM Switching, with context or VM displayed on the status bar

· New SoftICE Expression Evaluator

· Conditional breakpoints and breakpoint actions

· Macros

· New QUERY command to display the virtual address map of a process

· New WHAT command to analyze names or expressions to determine if they are a "known" type

New and Enhanced Commands for Windows 95 Users

COMMAND NEW ENHANCED MINOR OBSOLETE WHAT'S NEW

OR MAJOR CHANGE
CHANGE
? X Evaluates expressions only. Use H for help on
commands.
A X Supports these new instruction sets: 486, Pentium,
Pentium Pro, numeric coprocessor instruction sets
and MMX instruction sets.
ACTION X Replaced by conditional breakpoint DO "command1;
command2…" for breakpoint commands BMSG,
BPINT, BPIO, BPM, BPX.

What's New in SoftICE 3.0 Page 9

ANSWER X For remote debugging. Auto-answers and redirects
console to modem.
BMSG X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
C= for counts replaced by BPCOUNT, BPMISS, and
BPTOTAL conditional expressions
BPINT X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
C= for counts replaced by BPCOUNT, BPMISS, and
BPTOTAL conditional expressions
BPIO X Now you can trap Ring 0 I/O in VxDs (use -H to set
breakpoint with hardware debug registers.)

Supports conditional breakpoints and actions, and

logging breakpoints to history buffer.
C= for counts replaced by BPCOUNT, BPMISS, and
BPTOTAL conditional expressions.
BPM X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
C= for counts replaced by BPCOUNT, BPMISS, and
BPTOTAL conditional expressions
BPR X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
BPRW X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
BPX X Supports conditional breakpoints and actions, and
logging breakpoints to history buffer.
C= for counts replaced by BPCOUNT, BPMISS, and
BPTOTAL conditional expressions
BSTAT X Displays breakpoint statistics on hits and misses.
CR X Displays CR4 control register on Pentium machines.
CSIP X No longer available for 32-bit modules. Only 16-bit
modules supported.
D X Use -L to list data in command window, then use
Save SoftICE History Buffer to save as a file.
DIAL X For remote debugging. Redirects console to modem.
EXIT X No longer supported because it causes
unpredictable results if process in context does not
handle Interrupt 21 function 4C exit.
G X Uses debug registers instead of INT 3 breakpoints.
H X Provides help on commands, but no longer
evaluates expressions. Use "?" for expressions.
HERE X Uses debug registers instead of INT 3 breakpoints.
LINES X Supports 60 lines for single-monitor debugging.

What's New in SoftICE 3.0 Page 10

MACRO X Now you can define your own commands. If you use
the same sequence of SoftICE commands every
time a breakpoint triggers, use MACRO to define a
new command that performs this sequence.
MAP32 X Now you can display the memory map for your
module by entering MAP32 EIP.
PROC X Displays summary information for processes,
including Ring 3 process objects..
QUERY X Displays the virtual address map of a process.
P X By default, stepping is now thread-specific. This
means SoftICE only stops when you are in the
starting thread context. This is useful for debugging
system DLLs and you don't want the process to
switch.
R X Use -L to list registers in command window, then
use Save SoftICE History Buffer to save as a file.
S X Now you can use -c to do case-sensitive searches
or -u to search memory for Unicode strings.
SERIAL X New syntax for setting COM port in WINICE.DAT.
SET X New keywords MOUSE to enable or disable mouse
in SoftICE, THREADP to enable or disable thread-
specific stepping, and TAB to set source code tab
stops.
SYMLOC X Specify a context value for a symbol table with -C.
TABLE R X Removing tables with TABLE R is no longer
supported. Use SoftICE Loader-View-Tables to
remove tables (available in Beta 2.)
THREAD X Displays Ring-3 thread IDs and Ring 3 kernel
threads.
U X Use -L to send code to command window, then use
Save SoftICE History Buffer to save as a file.
WF X Displays floating point stack in floating point or MMX
formats.
WHAT X Determines if a name or expression is a "known"
type.
WMSG X Now you can enter a Windows message number to
retrieve the message name.
WR X Opening or closing the Register window also affects
the floating point register window if one is displayed.
XFRAME X Displays exception handler frames that are currently
installed.

What's New in SoftICE 3.0 Page 11

Using the New Expression Evaluator
The SoftICE expression evaluator evaluates command line arguments and conditional breakpoints. It provides
full operator precedence, support for standard ‘C’ arithmetic, bit-wise, logical and indirection operators,
predefined macros for data type conversion and access to common SoftICE and operating system values.

The SoftICE expression evaluator parses and evaluates expressions in a manner very similar to how a ‘C’ or
‘C++’ language compiler translates an expression. Multiple operators, operands, and expressions can be
combined to create compound expressions for conditional breakpoints, or expression evaluation:

The following example uses a compound expression to trigger a breakpoint if the first parameter (ESP+4)
passed to the IsWindow() API function is an HWND with the value of 0x10022 or 0x1001E. If either of the two
expressions is TRUE, the conditional expression will be TRUE, and the breakpoint will trigger.

BPX IsWindow if (esp->4 == 10022) || (esp->4 == 1001E)

NOTE: The expression esp->4 is shorthand notation for *(esp+4).

Operator Precedence
Operator precedence within the SoftICE expression evaluator is equivalent to ‘C’ operator precedence, with the
addition of the special SoftICE operators. This is a change from previous SoftICE expression evaluators which
evaluated all basic operators as having equal precedence and left-to-right associativity.

Operator precedence drastically affects the original SoftICE indirection operator ‘@’ which was always
evaluated after all other operators had been evaluated. Expressions such as @ebp+8, or @ebp-4 no longer
evaluate as you may expect, because the indirection operator ‘@’ has a higher precedence than the ‘+’
operator. You need to use parentheses to force the addition to be evaluated first: @(ebp+8) or @(ebp-4).

NOTE: Since the use of parentheses can be somewhat cumbersome for simple indirection’s, use the new ‘->’
operator to perform the same evaluation. For example, ebp->8 or ebp->-4.

Refer to Using SoftICE for a complete discussion of the expression evaluator and how to use it.

Copyright 1996 NuMega Technologies, Inc.

11/18/96

What's New in SoftICE 3.0 Page 12