Software Recommendations - 1998 Season 1/DNBCD4.iso/develop/NUMEGA/softice/patch/README.322

Text File | 1997-10-22 | 22.9 KB | 606 lines

README.TXT

SoftICE 3.22 Release Notes


-----------------------------------------------------------------
                        Table Of Contents
-----------------------------------------------------------------
* What's New in SoftICE 3.22 (versus 3.2)
* What's New in SoftICE 3.2 (versus 3.0)
      SMP Support (Windows NT version)
      Windows 98 Beta support (Windows 95 version)
      Universal Video Driver
      Improved serial operation
      43 Lines on Hercules-compatible Monochrome Cards
      Miscellaneous Options
* System Requirements
* Installation
* Quick Start to Debugging
* Using Multiple Monitors Under Windows 98
* Debugging Display Drivers Under Windows 98
* Using SoftICE with Visual C++ 5.0
* Using SoftICE with Borland C++ Builder
* VToolsD Support
* Known Anomalies
* Troubleshooting Tips
* Known Problems Related to Watcom C++
* Windows 95 OSR2 Crash Problem Related to 3Com Ethernet Card
* Reporting Problems And Suggestions


What's New in SoftICE 3.22 (versus 3.2)
---------------------------------------

* SoftICE for Windows NT now supports Windows NT 5.0 Beta 1 (build 1671)

* SoftICE for Windows 95 now supports debugging WDM drivers under
Windows 95 OEM Service Release 2.1.

* When the universal video driver is in use, the new WIDTH command can
be used to set the number of display columns between 80 and 160.

* Improved rendering performance of the universal video driver.

* New command: PAGEIN. This command can be used to force a page of
memory to be brought in from disk. To succeed (i.e. not crash the
system) the currently executing thread must be in a context where it can
touch pagable memory. Although PAGEIN does some sanity checking, it's
still fairly easy to shoot yourself in the foot, so this facility is
recommended for OS experts only.

* New option: SET FORCEPALETTE [ON|OFF]. See the "Universal Video
Driver" section below for details.

* The Symbol Loader (loader32) writes its configuration file
(siload.ini) to the SoftICE directory rather than the system directory.

* Miscellaneous bug fixes.


What's New in SoftICE 3.2 (versus 3.0)
--------------------------------------

* SMP support (Windows NT version)

* Windows 98 Beta support (Windows 95 version)

* Universal video driver: hardware-independent video support that works
with most recent cards.

* Improved serial operation

* 43 lines on Hercules-compatible monochrome cards (first introduced in
SoftICE 3.01)


SMP Support (Windows NT version)
--------------------------------

SoftICE 3.2 supports Pentium and Pentium Pro multiprocessor systems, up
to 8 CPUs, which use the standard Intel multiprocessor scheme (APIC).
Note that there are a variety of semistandard and proprietary
multiprocessor systems on the market; these are NOT supported.

The CPU command can be used to dump the state of the various processors.
While SoftICE is active (popped up) only one CPU is in use; the rest are
halted. At other times all CPUs run concurrently, as normal.


Windows 98 Beta support (Windows 95 version)
--------------------------------------------

SoftICE 3.22 (Windows 95 version) supports Windows 98 Beta 1 and Beta 2.
The following features have been added:

* The DEVICE, DRIVER, FOBJ, IRP and OBJDIR commands have been added.
These commands operate in the same manner as those found in SoftICE for
Windows NT. Please refer to the SoftICE Command Reference manual for
additional information.

* If WDMEXPORTS=ON is placed in WINICE.DAT, SoftICE for Windows 95 will
dynamically build exports for WDM drivers.


Universal Video Driver
----------------------

Previous versions of SoftICE ran exclusively in text mode, and relied on
device-dependent drivers, written by NuMega, to switch from normal
Windows hires mode to text mode and back. The main problem with this is
that each display device requires special support. SoftICE 3.2
introduces a "universal" video driver which works in a largely device-
independent manner, eliminating the need to explicitly support each
device.

Rather than switch into text mode, the universal video driver uses
whatever video mode is currently in effect, and writes directly into the
frame buffer. Thus SoftICE appears as a movable "window" on the Windows
display.

In the case where Windows hires mode is not active, e.g. full-screen DOS
box, SoftICE switches the display to text mode, just as it would if the
universal video driver were not selected. Although this involves device-
dependent register access, in most cases the Standard VGA driver can be
used successfully, since the display is in a standard VGA mode. (An
exception would be a DOS program that switched the display into a SVGA
mode).

To summarize, the key benefits of the universal video driver are:

* Device-independent (within certain parameters); most new cards work
automatically without requiring special support.

* SoftICE pops up as a movable "window" on the Windows desktop. Up to
160 columns by 128 lines are supported, along with 3 font choices.

The universal video driver is enabled during the video setup phase of
the installation by selecting the "Universal Video Driver" checkbox. As
explained above, when the universal video driver is enabled the video
card choice only affects SoftICE when the system is in VGA mode (e.g.
full-screen DOS box), so Standard VGA is an acceptable choice if your
video card is not listed.

Be sure to select the "Test" button to verify that your video card and
driver are supported. In order to use the universal video driver the
video card must meet the following conditions:

1) The video card uses a linear (not bank-switched) frame buffer (only
required on Windows NT)

2) The video driver supports DirectDraw (only required on Windows NT).
Note that being able to run DirectDraw programs does not imply that your
video driver supports DirectDraw.

3) The video card must run in 8-bit, 15/16-bit, 24-bit, or 32-bit modes.

With the universal video driver enabled, SoftICE will pop up directly on
the Windows desktop, using whatever video mode is currently in effect.

The universal video driver is not supported under NT 3.51.


COMMANDS

The following commands and hotkeys can be used to change the location
and appearance of the SoftICE "window":

LINES n
      Where n is 25-128, selects the number of lines for SoftICE to use

WIDTH n
      Where n is 80-160, selects the number of columns for SoftICE to
use.

SET FONT n
      Where n is 1, 2 or 3, selects a font.

SET ORIGIN x y
      Where x and y are pixel coordinates, locates the window.

SET FORCEPALETTE [ON|OFF]
      When on, SoftICE will prevent the system colors (palette indices
0-7 and 248-255) from being changed in 8-bpp mode. This ensures that the
SoftICE display can always be seen. This is OFF by default.

Control-Alt- cursor keys
      Moves the SoftICE window by a character increment.

Control-Alt-Home
      Resets the SoftICE window position to (0, 0)

Control-L
      Refreshes the SoftICE display. This is useful in the rare case
where the part of the display used by SoftICE is overlapped by a bitblt
operation that happened to be running when SoftICE popped up.


SETTING THE VIDEO MEMORY SIZE

When using the universal video driver, SoftICE must save the existing
contents of the frame buffer so it can be restored later. The amount of
memory required depends on the video mode, the number of lines used by
SoftICE, and (for DirectDraw applications) how many flipping surfaces
are in use. In any case, the amount of memory required can't exceed the
amount of memory on your video card. By default, SoftICE reserves 2MB,
but you can modify this using the Symbol Loader (go to Edit -> SoftICE
Initialization Settings and change the "Video memory size" setting).


Improved serial operation
-------------------------

SoftICE 3.2 includes a new Win32 implementation of the utility used
control SoftICE over a standard serial port, called SERIAL32.EXE. If the
remote machine is running MSDOS, the old MSDOS version of SERIAL may
still be used. (The DOS SERIAL.EXE program has been relocated to the
UTIL16 directory).  The command line syntax for SERIAL32 is as follows:

serial32 [-l=25|43|50|60] [<port name> [<baud rate>]]

'-l' sets initial screen lines
<port name> is COM1, COM2, etc...
<baud rate> is the baud rate

The SoftICE SERIAL command line usage has not changed.  This is
documented in the manual.

As an alternative to running SERIAL32 or SERIAL, SoftICE 3.2 can also be
used with a VT100 compatible terminal (or program) as the controlling
device.  In VT100 mode, function keys can be entered by using the key
sequence "^F" "digit" ("^F" denotes pressing the "F" key while holding
down the Control key).  The digits "0" thru "9" may be used.  Example:
"^F" "1" denotes function key F1.  "^F" "0" denotes function key F10.
Some ALT keys may be entered by using the key sequence "^A" "character".
Example:  "^A" "A" denotes ALT-A.

To initiate use of the VT100 serial mode in SoftICE, use the following
command:

SERIAL VT100 [com-port] [baud-rate]


43 Lines on Hercules-compatible Monochrome Cards
------------------------------------------------

As of version 3.01, SoftICE has the ability to run in graphics mode on
Hercules-compatible monochrome cards, allowing it to display 43 lines of
text rather than the 25 lines possible in text mode. This mode is
entered via the commands:

ALTSCR MONO
LINES 43

In SoftICE 3.22, 43-line monochrome mode was extended to provide a 90-
column display, rather than the 80-columns supported previously.


Miscellaneous Options
---------------------

Some miscellaneous options have been added in this release.

SET WHEELLINES n
    For IntelliPoint mice: sets the number of lines that should be
scrolled for each wheel movement.

SET BUTTONREVERSE [on|off]
    Setting this to ON will reverse the normal meaning of the two
mouse buttons.


System Requirements
-------------------

For All Systems:

* 5 MB disk space required
* 2.5 MB disk space optional (Adobe Acrobat Reader for on-line manuals)
* Microsoft-compatible Serial or PS/2 mouse (optional)
* Single monitor, an additional monochrome monitor, and remote debugging
are supported

For Windows 95:

* Windows 95
* 16 MB RAM minimum (32 MB recommended)

For Windows NT:

* Intel x86 uniprocessor or Intel-standard SMP system
* Windows NT 3.51
* Windows NT 4.0 (Build 1381)
* 32 MB RAM minimum (64 MB recommended)
* Installation account with administrator rights


Installation
------------

* To install SoftICE, run SETUP.EXE. For Windows NT, run Setup from an
account with administrator rights.

* Setup will prompt you to select your display adapter's make and model,
and allow you to select the "Universal" video driver or an additional
monochrome monitor.

* Setup will prompt you to select the type of mouse you are using (none,
serial-COM1, serial-COM2, or PS/2). The bus mouse is not supported.

* You can change your display adapter or mouse later by running Display
Adapter or Mouse Setup from the SoftICE start menu (Windows 95) or the
SoftICE program group (Windows NT).

* For Windows NT only: Setup will prompt you to select a startup mode
for SoftICE. You can change your startup mode later by running Startup
Mode Setup from the SoftICE program group.

* To uninstall SoftICE, select Remove SoftICE from the SoftICE start
menu (Windows 95) or from the SoftICE program group (Windows NT).


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 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)


Using Multiple Monitors Under Windows 98
----------------------------------------

NOTE: This section applies to Windows 98 only. SoftICE does not
currently support multiple displays under Windows NT.

Windows 98 supports multiple display devices. One of the devices, called
the primary display, supports VGA (this is the device that is active at
boot time); the other devices run with VGA disabled.

In the video setup phase of the installation, be sure to select the
device being used as the primary video card. For example, if you're
using an S3 card as the primary display and an ATI card as the secondary
display, tell SoftICE to use the S3 card.


SPECIFYING WHICH MONITOR TO USE

When the Universal Video Driver is in use, it is possible to control
which monitor SoftICE will use. Add a line to WINICE.DAT such as this:

MONITOR=1

This tells SoftICE to use the "second" monitor. Other numbers (0, 1, 2,
etc) can be used to select the desired display.


Debugging Display Drivers Under Windows 98
------------------------------------------

Under Windows 98 there can be multiple display drivers loaded
simultaneously, and multiple instances of display drivers.
Unfortunately, all these drivers have the same module name, DISPLAY, so
SoftICE doesn't know which driver it should associate with the symbol
table. The symbol table will be associated with the first driver loaded,
which may not be the one you want to debug.

There are two solutions to this problem:

* Don't load multiple display drivers or display driver instances unless
it's really necessary.

* Use the SYMLOC command to tell SoftICE which module it should
associate with the symbol table, as follows:

SYMLOC [hmod]

Where hmod is a module handle (a 16-bit number). Use the MOD command
(e.g. MOD DISPLAY) to get a list of the loaded display drivers and their
handles.


Using SoftICE with Visual C++ 5.0
---------------------------------

When linking, the /PDBTYPE:CON option must be used (/PDBTYPE:SEP is not
supported). To set this option from the IDE, go to the Link tab of the
project settings, select Category "Debug", and ensure that the "Separate
types" option is NOT selected.

Notes for building VxDs:

1) You MUST use link V4.1 or later. Earlier versions do not emit debug
information properly.

2) You must -NOT- link using the /PDB:NONE option. If you link with
/PDB:NONE you will not get any debug information (it disappears into the
ether).


Using SoftICE with Borland C++ Builder
--------------------------------------

C++ Builder stores the Borland debug information in .TDS files separate
from the executable. TDS files are also produced by the TDSTRP32
utility. To load symbols and source into SoftICE, simply use the Symbol
Loader to load the .TDS file. If you want to load the executable from
the Symbol Loader that must be done afterward as a separate step.
Alternatively, you could set the desired breakpoints and then load the
executable normally.


VToolsD Support
---------------

SoftICE 3.2 includes support for locals and structures, which makes it
easier than ever to develop VxDs in C/C++. To take full advantage of
SoftICE 3.2, VToolsD users will need to make some minor modifications to
the VtoolsD make files.

NOTE:
Replacement makefiles incorporating these changes are available from
ftp://ftp.numega.com/pub/tech/vtoolsd.zip

Microsoft Visual C++ users:

Edit vtd95\include\ms9.mak as follows:

1) Replace all instances of /Zd with /Zi. This ensures that full debug
information is included.

2) Remove references to DBG2MAP and MSYM. Those tools were used with
older versions of SoftICE but are now obsolete. Instead, to create your
.NMS symbol file, use:

NMSYM /PROMPT /TRANSLATE:package,always /SOURCE:$(VTOOLSD)\lib\source;$(VTOOLSD)\lib\classlib;$(VTOOLSD)\lib\include $(TARGNAME)

Unzipping the VtoolsD source code is recommended for full source-level
debugging.

Borland C++ users:

1) Build your VxD with debug information using the /v switch for the
compiler and linker (as usual).

2) Use the PELE utility with the -s switch to create a section mapping
file (.SMF). Translate the .SMF file to a .NMS symbol file with LOADER32
or NMSYM. Note that translating the .DLL produced by the linker will not
work; it is essential to translate from the .SMF file.


Known Anomalies
---------------

* When using the universal video driver, you may notice that the Windows
cursor overlays the SoftICE display. This occurs because the Windows
cursor is (usually) implemented as a hardware sprite. If this bothers
you, one way around it is to select a color or animated cursor (in the
Windows control panel settings); the operating system will revert to a
software cursor, which can be erased by the SoftICE display rendering.

* Under the following conditions SoftICE for Windows NT may appear to
hang your machine (it is not really hung however!):
- You start SoftICE for Windows NT manually, and you are NOT in full-
screen (VGA) mode.
- You are using the universal video driver.
- You do not have an "X;" at the end of your SoftICE INIT string.

If all these conditions are met, SoftICE will start but will be
invisible. Hit Control-D to regain control of the system. The next time
you hit Control-D SoftICE should pop up normally. The reason for this
anomaly is that the SoftICE universal video driver can't begin to
operate until at least one command has been passed to the display
driver. None of this applies to SoftICE for Windows 95.

* When debugging 16-bit programs, ? <variable> and WATCH <variable> are
not supported. However, the locals window is fully functional.

* The NT 3.51 checked build crashes when SoftICE is loaded using the
default winice.dat file. To fix the problem, change winice.dat as
follows:
- Add the line: mouse=off
- If you are using a mouse in SoftICE, add "set mouse on" to your INIT
string. Example: init="set mouse on;X;"

* SoftICE 3.2 for Windows 95 is not compatible with BoundsChecker for
Windows 3.x (16-bit).

* The Windows 95 shutdown option Restart computer in MS-DOS mode is not
supported when running SoftICE. Loading SoftICE after choosing this
option causes the system to become unstable and eventually crash. To
return to MS-DOS after you shut down Windows 95, set BOOTGUI=0 in
MSDOS.SYS (really an ini file with hidden, read-only, system
attributes). Then use Shutdown the Computer to restart your system.

* Windows NT becomes unstable when it runs low on non-paged memory. This
can occur if you load many symbols and source files. Use Symbol Loader-
Help-About Symbol loader to monitor SoftICE memory usage. You may need
to be selective about how much information you load into SoftICE.
SoftICE loads all source files by default. To limit the source files,
list the files to be loaded in a .SRC file with the same name as your
module. Put the .SRC file in the same directory with your executable.


Troubleshooting Tips
--------------------

* Erratic keyboard behavior:  If the keyboard behaves erratically when
you load SoftICE, run Symbol Loader, select Edit-SoftICE Initialization
Settings, and select the following option on the Troubleshooting page,
and restart SoftICE:

--- Disable Num Lock and Caps Lock programming

If the erratic behavior persists in Windows NT, select this
Troubleshooting option as well:

--- Do not patch keyboard driver

* Erratic mouse pointer movement: If mouse movement occurs when SoftICE
pops up, the operating system and the mouse hardware might become out of
sync because part of a mouse packet is lost. This results in erratic
mouse pointer movement. Use one of the following to resync the mouse:
- Type ctrl-M in SoftICE. You may need to do this a few times.
- Switch to a full screen DOS box in Windows NT.
- Use SET MOUSE OFF, followed by SET MOUSE ON, in Windows 95.

* If you encounter a situation where either program logic or a corrupt
data structure causes SoftICE to enter an endless loop and the
informational commands do not respond in a timely manner, press the
Escape (Esc) key one or more times to abort the current operation.

* Debugging Delphi Programs - Be sure to use the $O- option to turn off
optimizations. When optimizations are on, many unreferenced parameters
and locals are optimized out, although some reference to them still
exists in the debug information.


Known Problems Related to Watcom C++
------------------------------------

* Watcom C++ V11.0 does not seem to produce correct Codeview debug
information in all cases (line number sections are missing). No such
problem was observed with earlier versions of Watcom C++.

* When Watcom C++ V10.6 is used with the Microsoft linker (from VC++
V4.2) to produce VxDs, the line number debug information produced by the
linker is not correct. The reason for this is unknown, and may affect
other versions as well.


Windows 95 OSR2 Crash Problem Related to 3Com Ethernet card
-----------------------------------------------------------

A crash during system startup may occur when using the NDIS3 miniport
driver on the EtherDisk v2.1x for the 3Com EtherLink and Fast EtherLink
XL cards under Windows 95 OSR2. This is caused by a memory management
problem in the 3Com driver when running under Win95-OSR2. Although not
related to SoftICE, this problem is more likely to manifest itself when
SoftICE is loaded.

An updated Ethernet driver (currently in beta) which resolves the
problem is available from 3Com.


Reporting Problems And Suggestions
----------------------------------

Be sure to check our web site at http://www.numega.com for product
updates, FAQs, white papers and other technical support information.

Contact Technical Support via our SUPPORT page at our web site or send
e-mail to [e-mail].  Priority Support Customers can call us at 1
888 NUMEGAS or [phone].    You can also FAX us at +1 603 578
8401 (attention: Technical Support).

If you are not a Priority Support Customer but are interested in
becoming one, visit our website or call 1 800 4NUMEGA.

Include the following in your problem report:

* System Configuration (O/S, processor, and RAM)
* Detailed problem description (include exact error message text)
* If video related, include video adapter and driver names and version
  (include PCI Vendor ID and Device ID as well if available)
* How to reproduce the problem


-----------------------------------------------------------------
Copyright 1997 NuMega Technologies Inc.
10/22/97