ID Number: Q75252
3.00
WINDOWS
Summary:
The WDEB386 debugger that is provided in the Windows Software
Development Kit (SDK) is automatically made available by the
installation process; however, additional procedures may be needed to
take full advantage of the features it provides. This article
describes the procedures necessary to fully configure this
protected-mode debugger.
More Information:
Hardware
--------
A terminal connected to a COM port is required to use WDEB386. Unlike
CVW, there is no support for running the debugger on a secondary
monitor. Optionally, a second computer can be attached to a COM port
on the primary computer. Running the Windows Terminal application on
the second machine allows saving and printing portions of debug traces
or memory dumps.
The /C:n option (where n is 1 or 2) can be used to specify which COM
port to use with WDEB386. WDEB386 sends all output to the specified
COM port. However, if the debugging version of WIN386.EXE (explained
below) is run without running WDEB386, output is directed by default
to COM1.
Related Files
-------------
Because of the similarity of a number of filenames, there is some
confusion as to what the debugger is and how to install and use it.
The following list provides a description of some files that have
similar names, but completely different functions.
WDEB386.EXE - This file is the actual WDEB386 debugger. The debugger
is described in more detail in Chapter 9 of the
"Microsoft Windows Software Development Kit Tools"
manual.
WIN386.EXE - This executable file comprises the core of the Windows
enhanced-mode operating system layer. It includes the
VMM (virtual machine manager), and various standard
VxDs (virtual devices).
WINDEBUG.386 - This VxD may be installed in Windows running in
enhanced mode (it is not included in WIN386.EXE). It
provides a number of low-level services for debuggers,
the most well-known being the ability to use the key
combination CTRL+ALT+SYS RQ as a break request. This
VxD is NOT necessary for WDEB386 to function properly.
By default, the WDEB386.EXE file is installed in the WINDEV directory,
making it available in the PATH DOS environment variable. The
WINDEBUG.386 file is also installed during the SDK installation
process. The file itself is copied to the Windows system directory,
and the line "DEVICE=WINDEBUG.386" is added to the [386enh] section in
the SYSTEM.INI file. Therefore, these modules should require no
special attention regarding their installation.
WIN386.EXE
----------
Special care may be required concerning WIN386.EXE. The retail version
of this file is part of Windows, and Windows does not run in enhanced
mode without it. To take advantage of some of the more advanced and
extremely useful features of WDEB386, however, the debugging version
of WIN386.EXE must first be installed. This step is optional, but
without it, a significant number of WDEB386 commands are not
available.
Most programmers are aware of the procedure to install "the debugging
version of Windows." This procedure is NOT sufficient to install the
debugging version of WIN386.EXE. The difference is that the debugging
version of Windows consists of the debugging versions of the KERNEL,
USER, and GDI modules, along with the corresponding symbol files.
These files are all available as part of the Software Development Kit
(SDK). In contrast, the debugging version of WIN386.EXE is available
only as part of the Device Development Kit (DDK) in the
VXD\TOOLS\DEBUG directory.
Therefore, even after the debugging version of Windows is installed,
an additional action to install the debugging version of WIN386.EXE is
required. Installing WIN386.EXE is easy. Simply save the retail
version under a different filename and copy the debugging version from
the DDK disks into the Windows SYSTEM directory. The retail version
has a file size of around 500K bytes, whereas the debugging version is
more than 900K bytes.
Note: The SYM file for the debugging version of WIN386.EXE is NOT
available. There is a WIN386.SYM file supplied on the DDK in the same
directory as the debugging version of WIN386.EXE, but this file
contains the symbols for the retail version, and does NOT contain
symbol information that matches the accompanying EXE file. Attempting
to use this SYM file is worse than not using one at all because it
assigns labels to addresses incorrectly.
The Grabber
-----------
Once the debugging version of WIN386.EXE is installed, it may also be
necessary to install the debugging version of the "grabber" file. To
test this, start the debugging Windows system in enhanced mode and
attempt to start a DOS session. If the attempt fails with the message
"Incorrect System Version," then it is necessary to build and install
the debug version of the 386 grabber. This should be in the
set in the MAKE file, MAKE the grabber, and copy it to the Windows
SYSTEM directory. The file may be renamed, but the "386grabber=" line
in the SYSTEM.INI file must reflect the correct name. If it is
possible to start a DOS session on the Windows debugging system while
running in enhanced mode, then this step has been completed
successfully.
See Chapter 6 of the "Device Development Kit Installation and Update
Guide" for more information about building the grabber.
Starting the Debugger
---------------------
In the process of testing the grabber, a number of messages should
have been written to the COM1 terminal by Windows itself. This is an
indication that the debugging version of WIN386.EXE has been correctly
installed, and that the system is ready for the debugger. At this
point, refer to chapter 9 of the SDK tools manual for instructions on
starting and using the debugger. For some tips on using the WDEB386
debugger, query on the words:
prod(winddk) and wdeb386
Additional reference words: 3.00 protected mode protect