100% found this document useful (1 vote)

739 views

WinDbg Help

debug help

Uploaded by

Joy Martin

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

739 views

WinDbg Help

debug help

Uploaded by

Joy Martin

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 1651

Introduction

Page 1 of 1651

Debugging Tools for Windows

Introduction

Purpose
This edition of the Debugging Tools for Windows documentation describes four Microsoft debuggers: WinDbg, KD, CDB, and NTSD. It also describes additional debugging
tools, as well as various debugging techniques.
WinDbg, KD, CDB, and NTSD Debuggers
These Microsoft debuggers are fully capable of running on computers with x86-based, Itanium, or x64-based processors. The debuggers can debug the Windows operating
system, applications, services, and drivers that run on the operating system. The following operating systems are supported:

Windows 7
Windows Server 2008
Windows Vista
Windows Server 2003
Windows XP
Windows 2000

The CDB and NTSD debuggers are virtually identical. In this documentation set, references to "CDB" refer to both CDB and NTSD. Any differences between the two
debuggers are stated explicitly. For more information, see CDB and NTSD.
A copy of NTSD resides in the System32 directory of Windows prior to Windows Vista. This documentation describes the version of NTSD in the Debugging Tools for
Windows packageit might not match the version of NTSD in the System32 directory.
If you need to perform debugging on an older version of Windows, see Installation and Setup.
32-Bit and 64-Bit Packages
There are three versions of the debugger package: a 32-bit version for x86-based and x64-based binaries, a 64-bit version for Itanium-based binaries, and a 64-bit version for
x64-based binaries. Since debugging typically involves multiple applications, or multiple operating systems, selecting a debugger package is not as straightforward as it is
with other applications. For more information, see Choosing a 32-bit or 64-bit Debugger Package.
Other Tools in Debugging Tools for Windows
For a full list of the tools and where they are documented, see List of Tools and Documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Legal Information
Debugging Tools for Windows
Information in this document, including URL and other Internet Web site references, is subject to change without notice. The entire risk of the use or the results of the use of
this document remains with the user. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and
events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place or event is intended or
should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be
reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for
any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly
provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other
intellectual property.
2008 Microsoft Corporation. All rights reserved.
Microsoft, Microsoft Press, MSN, MS-DOS, Windows, Windows NT, Windows Server, Windows Vista, Win32, Win64, CodeView, MSDN, Visual C++, and Visual Studio
are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Intel is a registered trademark of Intel Corporation.
Itanium is a registered trademark of Intel Corporation.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 2 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

List of Tools and Documentation

Microsoft Debugging Tools for Windows includes a number of debuggers and other tools. Some of them are described in this documentation, and others are described
elsewhere. The following list briefly describes each tool and where its documentation can be found.
Debuggers
Debugging Tools for Windows includes the following debuggers. These are described throughout this documentation, and are referred to by their individual names or
collectively as "the debugger":
WinDbg (Windbg.exe)
A user-mode and kernel-mode debugger with a graphical interface.
KD (Kd.exe)
A kernel-mode debugger with a console interface.
CDB (Cdb.exe)
A user-mode debugger with a console interface.
NTSD (Ntsd.exe)
A user-mode debugger with a console interface. CDB and NTSD are virtually identical. In this documentation, whenever a reference is made to "CDB", it applies to both
CDB and NTSD. When these two debuggers differ, it is noted. (See CDB and NTSD for details.)
Additional Tools and Utilities
Debugging Tools for Windows also includes the following tools and utilities:
Logger (Logger.exe and Logexts.dll)
A tool and an extension DLL that record the function calls and other actions of a program. Logger is described in this documentation; see Logger and LogViewer.
LogViewer (Logviewer.exe)
A tool that displays the logs created by Logger. LogViewer is described in this documentation; see Logger and LogViewer.
ADPlus (Autodump+, Adplus.vbs)
A console-based Microsoft Visual Basic script that can automatically create memory dump files and log files with debug output from one or more processes. ADPlus is
described in this documentation; see ADPlus.
DbgRpc (Dbgrpc.exe)
A tool used to display Microsoft Remote Procedure Call (RPC) state information. DbgRpc is described in this documentation; see RPC Debugging and Using the
DbgRpc Tool.
KDbgCtrl (Kernel Debugging Control, Kdbgctrl.exe)
A tool that controls and configures the kernel debugging connection. KDbgCtrl is described in this documentation; see Using KDbgCtrl.
SrcSrv (Srcsrv.dll)
A source server that can be used to deliver source files while debugging. SrcSrv is described in this documentation; see SrcSrv.
SymSrv (Symsrv.dll)
A symbol server that the debugger can use to connect to a symbol store. SymSrv is described in this documentation; see SymSrv.
SymStore (Symstore.exe)
A tool used to create a symbol store. SymSrv is described in this documentation; see Using SymStore.
SymProxy
A tool used to create a single HTTP symbol server on your network that all your debuggers can point to. This has the benefit of pointing to multiple symbol servers (both
internal and external) with a single symbol path, handling all authentication, and increasing performance via symbol caching. SymProxy is described in this
documentation; see SymProxy.
AgeStore (Agestore.exe)
A tool that removes old entries in the downstream store of a symbol server or a source server. AgeStore is described in this documentation; see AgeStore.
DBH (Dbh.exe)
A tool that displays information about the contents of a symbol file. DBH is described in this documentation; see DBH.
PDBCopy (Pdbcopy.exe)
A tool that removes private symbol information from a symbol file, and controls which public symbols are included in the file. PDBCopy is described in this
documentation; see PDBCopy.
DumpChk (Dump File Checking Utility, Dumpchk.exe)
A tool used to validate a memory dump file. DumpChk is described in this documentation; see DumpChk.
DbgSrv (Dbgsrv.exe)
A process server used for remote debugging. DbgSrv is described in this documentation; see Process Servers (User Mode).
KdSrv (Kdsrv.exe)
A KD connection server used for remote debugging. KDSrv is described in this documentation; see KD Connection Servers (Kernel Mode).
DbEngPrx (Dbengprx.exe)
A repeater (small proxy server) used for remote debugging. DbgSrv is described in this documentation; see Repeaters.
The Remote tool (Remote.exe)
A remoting tool that can be used to remotely control any console program, including KD, CDB, and NTSD. The Remote tool is described in this documentation; see
Remote Tool and Remote Debugging Through Remote.exe.
GFlags (Global Flags Editor, Gflags.exe)
A tool used to control registry keys and other settings. GFlags is described in this documentation; see GFlags.
The Kill tool (Kill.exe)
A tool used to terminate a process. The Kill tool is described in this documentation; see Kill Tool.
The Breakin tool (Breakin.exe)
A tool used to cause a user-mode break to occur in a process. Breakin.exe is not described in this documentation. Use the breakin /? command for help with this tool.
The List tool (File List Utility, List.exe)
List.exe is not described in this documentation. Use the list /? command for help with this tool.
TList (Task List Viewer, Tlist.exe)
A tool used to list all running processes. TList is described in this documentation; see TList.
RTList (Remote Task List Viewer, Rtlist.exe)
A tool used to list running processes via a DbgSrv process server. RTList is not described in this documentation. Use the rtlist /? command for help with this tool.
UMDH (User-Mode Dump Heap utility, Umdh.exe)
A tool used to analyze heap allocations. UMDH is described in this documentation; see UMDH.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 3 of 1651

USBView (Universal Serial Bus Viewer, Usbview.exe)

A tool used to display the USB devices connected to a computer. USBView is described in this documentation; see USBView.
If you peform a custom install of Debugging Tools for Windows and select the SDK feature and all of its subfeatures, the libraries, headers, and samples used to build
debugger extensions will be installed.
Documentation
"Debugging Tools for Windows" (Debugger.chm)
This is the documentation you are currently reading. It is the central documentation for Debugging Tools for Windows.
"Debug Help Library" (Dbghelp.chm)
This documentation describes the DbgHelp API and the ImageHlp API, and also explains how to create your own symbol server. This is installed when you peform a
custom install of Debugging Tools for Windows and select the SDK feature and its subfeatures.
Tools Outside the Debugging Tools for Windows Package
The following related tools are not part of the Debugging Tools for Windows package:
Dr. Watson (Drwtsn32.exe)
A tool used for automatically creating dump files and sending error reports to Microsoft Online Crash Analysis (OCA). Dr. Watson is partially described in this
documentation; see Dr. Watson. The other features of Dr. Watson are described in the help file associated with drwtsn32.exe.
Build utility (Build.exe)
A compiler and linker used to build debugger extensions and other programs. The Build utility and its documentation can be found in the Windows Driver Kit, and in
earlier versions of the Windows DDK.
BinPlace (Binplace.exe)
A tool used to control symbol files for build products. BinPlace and its documentation can be found in the Windows Driver Kit, and in earlier versions of the Windows
DDK.
Application Verifier (AppVerif.exe and !avrf)
A tool used to test user-mode applications. This tool consists of two components: the AppVerif.exe utility and the !avrf extension command. All the features of
Application Verifier that are debugger-related are described in Application Verifier. The other features of Application Verifier are described in the help file associated
with AppVerif.exe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debuggers
This section includes:
Debuggers in this Package
Installation and Setup
Debugger Operation
Symbols
Crash Dump Files
Security Considerations
Debugger Reference
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debuggers in this Package

This documentation describes the workings of four Microsoft debuggers:
CDB and NTSD
KD
WinDbg
For a full list of the tools in this package and where they are documented, see List of Tools and Documentation.
The Microsoft Visual Studio debugger is also capable of debugging user-mode programs on all Windows operating systems. Refer to the Visual Studio documentation for
details on this debugger.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 4 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CDB and NTSD

CDB and NTSD are console applications which can debug user-mode programs. These two debuggers are nearly identical, except in the manner in which they are launched.
This documentation will use "CDB" when referring to the capabilities of both CDB and NTSD. Except as noted, all references to CDB in this documentation apply equally to
NTSD. There are a few techniques that can only work properly with CDB, or can only work properly with NTSD. These differences are documented in the appropriate
sections.

CDB
Microsoft Console Debugger (CDB) is a character-based console program that enables low-level analysis of Windows user-mode memory and constructs.
CDB is extremely powerful for debugging a program that is currently running or has recently crashed ("live analysis"), yet simple to set up. It can be used to investigate the
behavior of a working application. In the case of a failing application, CDB can be used to obtain a stack trace or to look at the guilty parameters. It works well across a
network (using a remote access server), as it is character-based.
With CDB, you can display and execute program code, set breakpoints, and examine and change values in memory. CDB can analyze binary code by "disassembling" it and
displaying assembly instructions. It can also analyze source code directly.
Because CDB can access memory locations through addresses or global symbols, you can refer to data and instructions by name rather than by address, making it easy to
locate and debug specific sections of code. You can also display disassembled machine code. CDB supports debugging multiple threads and processes. It is extensible, and
can read and write both paged and non-paged memory.
If the target application is itself a console application, the target will share the console window with CDB. To spawn a separate console window for a target console
application, use the -2 command-line option.

NTSD
There is a variation of the CDB debugger named Microsoft NT Symbolic Debugger (NTSD). It is identical to CDB in every way, except that it spawns a new text window
when it is started, whereas CDB inherits the Command Prompt window from which it was invoked.
Like CDB, NTSD is fully capable of debugging both console applications and graphical Windows programs. (The name "Console Debugger" is used to indicate the fact that
CDB is classified as a console application; it does not imply that the target application must be a console application.)
Since the start command can also be used to spawn a new console window, the following two constructions will give the same results:
start cdb parameters
ntsd parameters
NTSD in the System32 Directory
Whereas CDB is only available as part of the Debugging Tools for Windows package, NTSD is available both in this package and as part of the Windows system itself. It can
be found in the system32 directory of Windows.
If you are planning on using the NTSD that appears in the system32 directory, there are two important facts you should be aware of:

This version of NTSD cannot be used for Remote Debugging Through the Debugger.
This version of NTSD may not match the version of the documentation you are currently reading.

To avoid these issues, it is recommended that you use only the version of NTSD or CDB that was installed as part of the Debugging Tools for Windows package.
Controlling CDB or NTSD from the Kernel Debugger
It is possible to redirect the input and output from CDB or NTSD so that it can be controlled from a kernel debugger (either KD or WinDbg).
If this technique is used with CDB, the CDB window will appear but will not be useable for input and output. If this is used with NTSD, no console window will appear at all.
Controlling NTSD from the kernel debugger is therefore especially useful, since it results in an extremely light-weight debugger that places almost no burden on the computer
containing the target application. This combination can be used to debug system processes, shutdown, and the later stages of boot up. See Controlling the User-Mode
Debugger from the Kernel Debugger for details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KD
Microsoft Kernel Debugger (KD) is a character-based console program that enables in-depth analysis of kernel-mode activity on all NT-based operating systems.
KD can be used to debug kernel-mode programs and drivers, or to monitor the behavior of the operating system itself. KD also supports multiprocessor debugging.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 5 of 1651

Typically, the KD tool will not be run on the computer being debugged. Two machines (the host computer and the target computer) are needed for kernel-mode debugging.
Most KD commands cannot be targeted to specific processes or threads, as they can in CDB, NTSD, and WinDbg.
Debugging different target platforms
KD is capable of debugging a target computer which is running on an x86, Itanium, or x64 platform.
The debugger will automatically detect the platform on which the target is running. You do not need to specify the target on the KD command line. The older syntax (using
the name I386KD or IA64KD) is obsolete.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WinDbg
Microsoft Windows Debugger (WinDbg) is a powerful Windows-based debugging tool. It is capable of both user-mode and kernel-mode debugging.
WinDbg provides full source-level debugging for the Windows kernel, kernel-mode drivers, and system services, as well as user-mode applications and drivers.
WinDbg uses the Microsoft Visual Studio debug symbol formats for source-level debugging. It can access any symbol or variable from a module that has PDB symbol files,
and can access any public function's name that is exposed by modules that were compiled with COFF symbol files (such as Windows .dbg files).
WinDbg can view source code, set breakpoints, view variables (including C++ objects), stack traces, and memory. Its Debugger Command window allows the user to issue a
wide variety of commands.
For kernel-mode debugging, WinDbg requires two machines (the host computer and the target computer). Kernel debugging is only supported on NT-based Windows
operating systems.
WinDbg also supports various remote debugging options for both user-mode and kernel-mode targets.
WinDbg is the graphical-interface counterpart to CDB / NTSD and to KD.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installation and Setup

This section includes the following topics:
Debugger Installation
Kernel-Mode Setup
User-Mode Setup
Windows 95, 98, and Millennium
Windows NT 4.0
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Installation
Microsoft Debugging Tools for Windows is available in three different versions: a 32-bit package and two 64-bit packages. You can install these packages from the Customer
Support Diagnostics CD, the Microsoft Windows SDK, the Windows Driver Kit (WDK), or the Web. You can customize the installation in several ways.
This section includes the following topics:
Choosing a 32-Bit or 64-Bit Debugger Package
Installing from the Customer Support Diagnostics CD
Installing from the Windows SDK

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 6 of 1651

Installing from the Windows Driver Kit

Installing from the Web
Installing from a Script
Customizing the Installation
Uninstalling the Debugger Package
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Choosing a 32-Bit or 64-Bit Debugger Package

The Debugging Tools for Windows package is available in three different versions: a 32-bit version, a native Intel Itanium version, and a native x64 version.
To determine which package to use, you have to know the processor that your host computer is running on.
x86-based Host Computer
If your host computer uses an x86-based processor, always use the 32-bit package.
Itanium Host Computer
If your host computer uses an Itanium-based processor, the following rules apply:

If you are analyzing a dump file, and if the dump file was made on Microsoft Windows XP or a later version of Windows, you can use the 32-bit package or the Itanium
package. (It is not important whether the dump file is a user-mode dump file or a kernel-mode dump file, and it is not important whether the dump file was made on an
x86-based or an Itanium-based platform.)
If you are analyzing a dump file, and if the dump file was made on Windows 2000, you should use the 32-bit package. (It is not important whether the dump file is a
user-mode dump file or a kernel-mode dump file)
If you are performing live kernel-mode debugging, and if the target computer is running Windows XP or a later version of Windows, you can use the 32-bit package or
the Itanium package. (This situation applies to both x86-based and Itanium-based targets.)
If you are performing live kernel-mode debugging, and if the target computer is running Windows 2000, you should use the 32-bit package.
If you are performing live user-mode debugging, always use the Itanium package. It is not important whether the target is a 64-bit application or a 32-bit application.
The debugger that is included in the Itanium package can debug any kind of application and the WOW64 emulator.

x64-based Host Computer

If your host computer uses an x64-based processor, the following rules apply:

If you are analyzing a dump file, and if the dump file was made on Windows XP or a later version of Windows, you can use either the 32-bit package or the x64
package. (It is not important whether the dump file is a user-mode dump file or a kernel-mode dump file, and it is not important whether the dump file was made on an
x86-based or an x64-based platform.)
If you are analyzing a dump file, and if the dump file was made on Windows 2000 operating system, you should use the 32-bit package. (It is not important whether the
dump file is a user-mode dump file or a kernel-mode dump file)
If you are performing live kernel-mode debugging, and if the target computer is running Windows XP or a later version of Windows, you can use either the 32-bit
package or the x64 package. (This situation applies to both x86-based and x64-based targets.)
If you are performing live kernel-mode debugging, and if the target computer is running Windows 2000, you should use the 32-bit package.
If you are performing live user-mode debugging, use the x64 package for debugging WOW64 with both 64-bit and 32-bit code. To debug other targets, use a 32-bit
debugger to debug 32-bit code.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing from the Customer Support Diagnostics CD

To install Debugging Tools for Windows from the Customer Support Diagnostics CD, insert the CD into the CD drive. A window appears with options for what you can
install, including the debuggers, checked-build symbols, and free-build symbols.
Follow the links to install the debuggers and debugging tools that you want.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 7 of 1651

Installing from the Windows SDK

Debugging Tools for Windows is included as part of the Microsoft Windows SDK.
To install Debugging Tools for Windows from the Windows SDK, use the Custom Install option and then select the Debugging Tools for Windows item.
When the Windows SDK installation is complete, click Start, point to All Programs, point to Microsoft Windows SDK, and then click Install Debugging Tools for
Windows. Then, the Debugging Tools for Windows installation application runs.
After the installation is complete, you can find the debugger shortcuts by clicking Start, pointing to All Programs, and then pointing to Debugging Tools for Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing from the Windows Driver Kit

Debugging Tools for Windows is included as part of the Microsoft Windows Driver Kit (WDK) and its predecessor, the Driver Development Kit (DDK).
To install Debugging Tools for Windows from the WDK or the DDK, insert the WDK or DDK CD and find the appropriate link on the screen that appears. This link enables
you to install the debuggers to a location of your choice.
After the installation is complete, you can find the debugger shortcuts by clicking Start, pointing to All Programs, and then pointing to Debugging Tools for Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing from the Web

To download the latest version of the Debugging Tools for Windows, visit the

Debugging Tools for Windows Web site and follow the instructions.

The Debugging Tools for Windows package is frequently updated. Update your tools from the Web site to make sure that you have the latest debugging tools.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing from a Script

To install Debugging Tools for Windows from a script or a command-line prompt, you must first obtain the debugger installation file. You can find this package from any of
the installation sources referenced in this document. Next, use the MsiExec application to install the debugger package. The general format for this instruction is:
msiexec /i dbg_Architecture_Version.msi INSTDIR=TargetDirectory
Architecture specifies the target architecture for the debugger tools - x86 (for the 32-bit package), amd64 (for the x64 package), or ia64 (for the Intel Itanium package).
Version specifies the version of the package being installed. Typically, Version only appears with files that are downloaded from the Web site. Package files found on the CDs
usually do not contain a Version number. TargetDirectory is the parent directory for the package installation. If TargetDirectory contains embedded spaces in the value, then
enclose the directory path in quotation marks. If TargetDirectory contains no embedded spaces, the quotation marks are optional. For example, if your debugger package file
is dbg_x86_6.10.3.2.233.msi and you want to install the debuggers under the directory c:\DbgPath, the command would be as follows:
msiexec /i dbg_x86_6.10.3.233.msi INSTDIR=c:\DbgPath

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Customizing the Installation

When you install Debugging Tools for Windows, select Custom Install to control which features in this package are installed.
You can select the following custom install options:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 8 of 1651

By default, the Debuggers feature is selected. If you leave this feature selected, the installation includes the debuggers (WinDbg, KD, CDB, and NTSD), associated
modules (such as DbgHelp), the symbol server (SymSrv), the source server (SrcSrv), the dump file tool (ADPlus), the remoting tool (DbgSrv), and several extension
libraries.
Note Another copy of NTSD exists in the \system32 directory of Microsoft Windows. This Help documentation corresponds to the version of NTSD that is included in
the Debugging Tools for Windows package. But this documentation might not match the version of NTSD that is installed with Windows.

By default, the Tools feature and its Helpful Tools subfeature are selected. If you leave these features selected, the installation includes the SymStore, SymChk,
DbgRpc, Logger, LogViewer, KDbgCtrl, DumpChk, GFlags.exe, TList.exe, Kill.exe, List.exe, Breakin.exe, UMDH, and the remoting tools (Remote.exe, DbEngPrx, and
KdSrv).
By default, the Documentation feature and its Debugging Tools subfeature are selected. If you leave these options selected, the installation includes the Debugging
Tools for Windows documentation (Debugger.chm). This documentation is the Help file that you are currently reading.
By default, the SDK feature and its subfeatures are not selected. If you select these features, the installation includes the headers and libraries that you must have to
build debugger extensions, several sample extensions and other samples, and the Debug Help Library documentation (Dbghelp.chm).
By default, the Location for the installation is a subdirectory of C:\Program Files. To choose a different installation location, click Browse and navigate to an alternate
path.

For more information about each tool in this package and where they are documented, see List of Tools and Documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Uninstalling the Debugger Package

The Debugging Tools for Windows package is available in three different versions: a 32-bit version, a native Intel Itanium version, and a native x64 version. The removal
process is virtually the same for all versions.
The following steps uninstall the debugger package:
1. On the Start menu, point to All Programs.
2. Select the package to uninstall. For example, for the 32-bit installation, select Debugging Tools for Windows.
3. Select the uninstall option. For example, for the 32-bit installation, select Uninstall Debugging Tools for Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel-Mode Setup
This section includes the following topics:
Configuring Hardware for Kernel-Mode Debugging
Configuring Software on the Target Computer
Configuring Software on the Host Computer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Hardware for Kernel-Mode Debugging

This section includes the following topics:
Target Computer and Host Computer
Setting Up a Null-Modem Cable Connection
Setting Up a 1394 Cable Connection
Setting Up a USB 2.0 Debug Cable Connection
Testing the Connection
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 9 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Target Computer and Host Computer

Kernel-mode debugging requires a target computer and a host computer. The target computer is used to run the kernel-mode application. The host computer is used to run the
debugger.
The following diagram shows the typical Microsoft Windows setup that you can use to perform kernel debugging and diagnose system failures.

Typical Windows debugging setup

This diagram shows the typical setup. However, the current versions of KD and WinDbg (which you installed with this documentation) are flexible. KD and WinDbg can do
the following

Debug a target computer that is running Windows.

Debug a target computer that is running on an x86-based platform, an Itanium-based platform, or an x64-based platform.
Can be started from a host computer that is running Windows.
Can be started from a host computer that is on an x86-based platform, an Itanium-based platform, or an x64-based platform.

The target computer and host computer do not have to use the same platform or the same version of Windows.
Kernel debugging does not require specific combinations of the free or checked builds. You can debug a free system from a free or checked system, and you can debug a
checked system from a free or checked system. However, typically, there is no reason for the host computer to run the slower checked build.
Note If you are running the debuggers from an Itanium-based host computer, make sure that you are using the correct version of the binaries. For more information about
which version of the debugger package to use, see Choosing a 32-bit or 64-bit Debugger Package.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Up a Null-Modem Cable Connection

When the host computer is in the same location as the target computer, or when you must put a local host computer that has remote access server (RAS) capabilities between
the target and a remote host, you must connect the two computers by using a debug (null-modem) cable, an IEEE 1394 ("FireWire") cable, or a USB 2.0 debug cable.
Null-modem cables are serial cables that have been configured to send data between two serial ports. They are available at most computer stores. Do not confuse null-modem
cables with standard serial cables. Standard serial cables do not connect serial ports to each other.
If you are accessing the target system's modem over a phone line, debugging a failed user-mode process on the same computer, or analyzing a dump file, you do not have to
use a null-modem cable.
COM Ports
The default serial port for debug output from the target computer is the highest enumerated port (typically COM2). You can change this default port by setting the debugport
boot option. For more information about how to change the port, see Configuring Software on the Target Computer.
The default serial port for debug input to the host computer is COM1. You can change this default port by setting the _NT_DEBUG_PORT environment variable. For more
information about how to set this environment variable, see Configuring Software on the Host Computer.
Software Setup
For information about how to configure the boot entries on the target computer, see Boot Parameters to Enable Debugging. For more information about how to start a kernel
debugging session, see Attaching to a Target Computer (Kernel Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 10 of 1651

Setting Up a 1394 Cable Connection

When the host computer is in the same location as the target computer, or when you have to put a local host computer that has remote access server (RAS) capabilities
between the target and a remote host, you must connect the two computers by using an IEEE 1394 ("FireWire") cable, a debug (null-modem) cable, or a USB 2.0 debug cable.
Kernel debugging through a 1394 cable is not supported on all systems. The target computer and the host computer must be running Microsoft Windows XP or a later version
of Windows. (The target computer and host computer do not have to be running the same version of Windows.)
The target computer and host computer must have a 1394 adapter. Plug the 1394 cable into any port on the target computer and into any port on the host computer. The choice
of port is not important, and it does not affect the channel number that is used during software setup.
Note The drivers for the IEEE 1394 host debugging are not compatible with Microsoft Windows 2000.
Note Additional support can be requested by sending mail to

[email protected].

Software Setup
For information about how to configure the boot entries on the target computer, see Boot Parameters to Enable Debugging. For more information about how to start a kernel
debugging session, see Attaching to a Target Computer (Kernel Mode).
Note Before you perform kernel debugging over a 1394 cable, you must configure some additional software on the target computer and the host computer. For more
information about this configuration, see Disabling the 1394 Host Controller and Installing the 1394 Virtual Driver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Up a USB 2.0 Debug Cable Connection

A USB 2.0 debug cable. This cable is not a standard USB 2.0 cable, because it has an extra hardware component that makes it compatible with the USB2 Debug
Device Functional Specification. You can find these cables with an Internet search for "USB 2.0 debug cable".
The host computer must have a USB 2.0 controller that is compatible with the Enhanced Host Controller Interface (EHCI) specification.
The target computer must have a USB 2.0 controller that is compatible with the EHCI specification, and which supports kernel debugging. Not all EHCI-compatible
controllers have this support, and there is no programmatic method to determine whether a given computer does have this support.
If the EHCI-compatible controller provides kernel debugging support, you must use Port 1 of the controller on the target computer for the debug connection. The USB
debugging port must be exposed to the outside of the target computer. (A few computers have a USB 2.0 controller that supports debugging through a certain physical
port that is not accessible from the outside of the computer.) You can use the USBView utility that helps to identify which port number is assigned to each USB
connector.

USB debugging does not work over a hub or docking station.

[email protected].

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Testing the Connection

Before you start the debugger, you should test the connection between the host and target. You can do that by using the PowerShell utility.
Note You can use HyperTerminal to test the connection in Windows XP and Windows 2000. However, HyperTerminal is not part of the Windows Vista operating system.
Using PowerShell to Test the Connection
If you dont have PowerShell installed, you can install it from the following Web site:

Windows PowerShell.

To test the serial connection by using PowerShell, do the following:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 11 of 1651

1. Connect the null-modem serial cable between the host and the target.
2. Run the PowerShell tool from the Start menu on either the host or the target machine and enter the following command:
PS> [System.IO.Ports.SerialPort]::getportnames()
3. If more than one port is displayed, you will need to validate the selected one. This can be performed by entering the following commands in the PowerShell window:
PS>
PS>
PS>
PS>

$port= new-Object System.IO.Ports.SerialPort COM1,19200,None,8,one

$port.open()
$port.Write("Hello, world!")
$port.Close()

This sends the message "Hello, world!" to the other machine.

Note In the previous commands, it is assumed that the serial port is COM1 and the baud rate is 19200. If these assumptions do not work, try again using another port.
4. In order to prepare the computer on the other end of the cable to read the message, you can use any terminal emulator or PowerShell. First enter the following
command:
PS> [System.IO.Ports.SerialPort]::getportnames()
This command returns serial port enumeration.
5. Assuming the serial port is COM1 and the baud rate is 19200, enter the following commands in the PowerShell window:
PS> $port= new-Object System.IO.Ports.SerialPort COM1,19200,None,8,one
PS> $port.add_DataReceived({`$this is a handle to SerialPort. $_ is a pointer to SerialDataRecievedEventArgs})
PS> $port.Open()
6. Once the "Hello, world!" message appears on the screen of the other computer, you can be sure that the correct port is selected and the connection is functional.
Using Hyperterminal to Test the Connection
To test the serial connection by using Hyperterminal, do the following:
1. On the host computer, click Start, point to All Programs, point to Accessories, point to Communications, and then click Hyperterminal.
Note If Hyperterminal is not installed, you can install it from the product CD by using Add or Remove Programs from the Control Panel.
2.
3.
4.
5.

In the Connection Description box, enter a name for the new connection. (The name is not important.)
In the Connect To box, in the Connect using list, select the COM port that corresponds to the port that the null-modem cable is connected to on this computer.
In the next window, accept the defaults for the COM port properties.
Repeat steps 1 through 4 for the target computer.

Hyperterminal is now ready for testing. Type a string of characters on the host system. If the null-modem cable is installed correctly and you chose the correct COM ports
within HyperTerminal on both computers, the string of characters that you type on the host computer should be displayed in the HyperTerminal window of the target system.
If the string does not appear on the target system, confirm the cable is plugged into both computers. Also make sure that the cable is a null-modem cable instead of a passthough serial cable.
If the cable is correct, the problem might be the COM ports. Create a new connection in HyperTerminal on the target system by using a different COM port. If the problem is
not fixed, try changing the COM port on the host system. If the problem persists, change the target system's COM port setting back to the original setting and retest.
Eventually, you should find the correct configuration, and the test will succeed.
If, you forget which computer is using which port, on the File menu in HyperTerminal, click Properties to reveal the current COM port setting for the debug session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Software on the Target Computer

To perform kernel-mode debugging, you must enable and configure features that are established when the operating system loads. The settings for these features are included
in the boot options, the values that determine how the boot loader loads and configures the operating systems and other bootable programs and devices.
The target computer's kernel debugging settings can also be changed after boot by using the KDbgCtrl utility.
Beginning in Windows Vista, Windows includes a new boot loader architecture, new boot options, and a new boot options editor. For information, see Boot Options in
Windows Vista.
This section includes:
Introduction to Boot Options
Editing Boot Options
Boot.ini Boot Parameter Reference

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 12 of 1651

BCD Boot Options Reference

Using Boot Parameters
Bypassing Boot Options
Disabling the 1394 Host Controller
Using KDbgCtrl
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Introduction to Boot Options

The concept and content of boot options are very similar on all computers that run Microsoft Windows operating systems. However, prior to Windows Vista, computers with
different processor firmware store boot options differently and require different tools to view and edit the options on each system. Computers with BIOS firmware, namely
those with x86 and x64 processors, store boot options in a Boot.ini text file that can be edited in Notepad. Computers with EFI firmware, primarily computers with Itanium
processors, store their options in non-volatile RAM that must be edited by using specialized tools.
Windows Vista, and later versions of Windows, store boot option in a firmware-independent storage and configuration system. Windows Vista also introduces a new Boot
Manager and system-specific boot loaders. For more information, see Boot Options in Windows Vista and Later.
This section includes:
Boot Options in a Boot.ini File
Boot Options in EFI NVRAM
Boot Options in Windows Vista and Later
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Options in a Boot.ini File

Boot.ini is a text file located at the root of the system partition, typically c:\Boot.ini. Boot.ini stores boot options for computers with BIOS firmware, traditionally, computers
with x86 and x64-based processors.
On Windows Server 2003 and earlier versions of NT-based Windows operating systems, when the computer starts, the Windows boot loader, Ntldr, reads the Boot.ini file and
displays the entries for each operating system in the boot menu. Then, Ntldr loads the selected operating system in accordance with settings in the Boot.ini file.
By default, on NTFS drives, the system, hidden, archived, and read-only attributes are set to protect the Boot.ini file; however, members of the Administrators group can
change these attributes. The file attributes do not affect the operation of boot loader.
The following sections briefly describe the Boot.ini file and explain the aspects of boot options that are specific to computers with Personal Computer Advanced Technology
(PC/AT)-type BIOS firmware.
This section includes:
Overview of the Boot.ini File
Editing the Boot.ini File
Backing Up the Boot.ini File
This document describes aspects of the Boot.ini file that are of special interest to driver developers and testers. For a complete list of the Boot.ini file parameters, see
Available Switch Options for the Windows XP and the Windows Server 2003 Boot.ini Files topic in the Microsoft Knowledge Base.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Overview of the Boot.ini File

The Boot.ini file is a text file that contains the boot options for computers with BIOS firmware running NT-based operating system prior to Windows Vista. It is located at the

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 13 of 1651

root of the system partition, typically c:\Boot.ini.

The following sample shows the content of a typical Boot.ini file.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
C:\CMDCONS\BOOTSECT.DAT="Microsoft Windows Recovery Console" /cmdcons
The Boot.ini file has two main sections:

The [boot loader] section contains option settings that apply to all boot entries on the system. The options include timeout, the boot menu time-out value, and default,
the location of the default operating system.
The following sample shows the [boot loader] section of a Boot.ini file.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS

The [operating systems] section is comprised of one or more boot entries for each operating system or bootable program installed on the computer.
A boot entry is a set of options that defines a load configuration for an operating system or bootable program. The boot entry specifies an operating system or bootable
program and the location of its files. It can also include parameters that configure the operating system or program.
The following sample shows the [operating systems] section of a Boot.ini file on a computer with two operating systems, Microsoft Windows XP and Microsoft
Windows 2000. It has two boot entries, one for each operating system.
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
multi(0)disk(0)rdisk(0)partition(2)\WINNT="Microsoft Windows 2000 Professional" /fastdetect

Each boot entry includes the following elements:

The location of the operating system. The Boot.ini file uses the Advanced RISC Computing (ARC) naming convention to display the path to the disk partition and
directory where the operating system resides. For example:
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS

A friendly name for the boot entry. The friendly name represents the boot entry in the boot menu. The friendly name is surrounded by quotation marks and represents
the boot entry in the boot menu. For example:
"Microsoft Windows XP Professional"

Boot entry parameters, also known as boot parameters or load options enable, disable, and configure operating system features. Boot parameters resemble commandline parameters, each beginning with a forward slash (/), such as /debug. You can have zero or more boot parameters on each boot entry.
For a list of boot parameters that are relevant to driver testing and debugging, see Boot.ini Boot Parameter Reference.

You can have multiple boot entries for the same operating system, each with a different set of boot parameters. Windows creates a standard boot entry when you install the
operating system, and you can create additional, customized entries for an operating system by editing the Boot.ini file.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Editing the Boot.ini File

Prior to Windows Vista, BIOS-based computers running Windows store boot options in a Boot.ini text file. You can edit the Boot.ini file by using Bootcfg (bootcfg.exe), a
tool included in Windows XP and Windows Server 2003, or by using a text editor such as Notepad. Bootcfg is documented in Windows Help and Support.
You can also view and change some boot options in Control Panel under System. In the System Properties dialog box, on the Advanced tab, click Settings under Startup and
Recovery. Because this functionality is limited, it is not discussed in this section. For information about the Startup and Recovery dialog box, see Help and Support Center.
Bootcfg
Bootcfg is a command-line tool that edits boot options on local and remote computers. Using the same Bootcfg commands and procedures, you can edit a Boot.ini file or the
boot options in Extensible Firmware Interface, Non-Volatile Random Access Memory (EFI NVRAM). Bootcfg is included in the %Systemroot%\System32 directory in
Windows XP and Windows Server 2003. (The Bootcfg display is slightly different on systems that store boot options in EFI NVRAM, but the commands are the same.)
You can use Bootcfg to add, delete, and change all boot entry parameters and boot options; however, you cannot use it to set an indefinite boot time-out value. You can also
use Bootcfg commands in a script or batch file to set boot options or to reset them after you replace or upgrade an operating system.
Unlike manual editing, Bootcfg edits boot options without changing the protective attributes on the Boot.ini file. It also helps you avoid typing errors that might prevent the
operating system from starting.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 14 of 1651

You must be a member of the Administrators group on the computer to use Bootcfg. For detailed instructions about using Bootcfg, see Help and Support Center.
Editing in Notepad
You can edit use a text editor, such as Notepad, to edit the Boot.ini file. However, because this method is prone to error, use it only when Bootcfg is not available.
Before editing the Boot.ini file, you must remove the file attributes that Windows uses to protect the file from inadvertent changes. When the Boot.ini file is on an NTFS
drive, you must be a member of the Administrators group on the computer to change its attributes.
Use the following procedure to prepare the Boot.ini file for manual editing. This procedure removes the system, hidden, and read-only attributes of the file.
To configure the Boot.ini file attributes for editing
1. At a command prompt, navigate to the root of the boot directory.
2. Type the following text at the command line:
attrib -s -h -r Boot.ini
System, hidden, and read-only attributes are removed from the file.
3. When your editing is complete, you can restore the file attributes to protect the Boot.ini file. However, Ntldr can use the Boot.ini file with any attribute set. At a
command prompt, type the following text:
attrib +s +h +r Boot.ini
This restores the attributes that protect the Boot.ini file.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Backing Up the Boot.ini File

When you install or upgrade an NT-based Windows operating system prior to Windows Vista, the Windows installer creates a new Boot.ini file for the computer. The new file
retains some, but not all, of the changes you might have made to the file.
To preserve an edited Boot.ini file, make a backup copy before upgrading or installing an operating system.
After an update completes, you can replace the new file with your backup copy. If you have installed a new operating system, you can copy customized entries from your
backup copy and then paste them into the new Boot.ini file.
An update or installation restores the default security attributes on the Boot.ini file, including the read-only attribute. To edit the file, use the Bootcfg command or change the
file attributes. For more information, see Editing the Boot.ini File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Options in EFI NVRAM

Computers with Extensible Firmware Interface (EFI) firmware, such as Intel Itanium 2 processors, store boot options in NVRAM, a storage medium that can be edited, but
retains its state even when you turn off the computer.
EFI firmware serves the same purpose as BIOS firmware, but it overcomes many limitations of the traditional BIOS. The startup functions that are implemented in the BIOS
and boot manager (NTLDR) on x86-based systems are handled by EFI components, namely the EFI BIOS and EFI Boot Manager.
To configure features related to driver debugging and testing on EFI-based systems running Windows Server 2003 and earlier versions of NT-based Windows operating
systems, you must edit the boot options in NVRAM. The following sections briefly describe the boot options in EFI NVRAM and explain the aspects of boot options that are
specific to systems that use this technology.
On Windows Vista and later versions of Windows, boot options on BIOS-based and EFI-based computers are stored in Boot Configuration Data (BCD), a firmwareindependent configuration and storage system for boot options. For more information, see Boot Options in Windows Vista and Later.
For a detailed description of boot options on Itanium-based systems, see the Extensible Firmware Interface Specification. You can download a copy of the updated
specification from the Intel Extensible Firmware Interface Web site.
This section includes:
Overview of Boot Options in EFI
Editing Boot Options in EFI
Backing up Boot Options in EFI

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 15 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Overview of Boot Options in EFI

Like the boot options on a system with BIOS firmware, there are two types of boot options in EFI NVRAM:

Globally-defined variables that apply to all bootable devices and bootable programs on the computer.
Boot option variables that apply only to a particular load configuration of a bootable device or program, such as an operating system. The system-specific variables
comprise a boot entry for each configuration of a bootable device or bootable program on the computer.

The Bootcfg tool (discussed in Editing Boot Options in EFI and documented in Windows Help and Support) allows you to view and edit the boot options in EFI NVRAM.
The following sample shows a Bootcfg display of a computer with an Itanium processor.
Boot Options
-----------Timeout:
Default:
CurrentBootEntryID:

30
\Device\HarddiskVolume3\WINDOWS
1

Boot Entries
-----------Boot entry ID:
1
OS Friendly Name: Windows Server 2003, Enterprise
OsLoadOptions: /debug /debugport=COM1 /baudrate=57600
BootFilePath:
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi
OsFilePath:
\Device\HarddiskVolume3\WINDOWS
Boot entry ID:
2
OS Friendly Name: EFI Shell [Built-in]
The following table describes the elements of the Bootcfg display of boot data in EFI NVRAM.
Field
Boot Options
Timeout

Description
Contains options that apply to all boot entries.
Determines how long the boot menu is displayed. When this value expires, the boot loader
loads the default operating system.
Default
Specifies the location of the default operating system.
CurrentBootEntryID Identifies the boot entry that was used to start the current session of the operating system.
Boot Entries
Contains system-specific data. It is comprised of one or more boot entries for each operating
system or bootable program installed on the computer.

Example
(Section heading)
Timeout:
30
\Device\HarddiskVolume3\WINDOWS
CurrentBootEntryID: 1
(Section heading)

A boot entry is a set of options that defines a load configuration for an operating system or
bootable program.
Boot entry ID

Identifies the boot entry to Bootcfg. This value changes when you reorder the boot entries.

Boot entry ID:

This is not the EFI boot entry ID, which is a persistent identifier for the EFI components.
OS Friendly Name

Represents the boot entry in the boot menu.

OsLoadOptions

Specifies the boot parameters for the entry. Boot parameters are commands to enable,
disable, and configure features of the operating system. The EFI Boot Manager passes these
parameters to the bootable device or system to be interpreted and implemented.

Windows Server 2003,

Enterprise
OsLoadOptions: /debug
/debugport=COM1 /baudrate=57600

For a list of the boot parameters that are related to driver debugging and testing, see Boot.ini
Boot Parameter Reference.
BootFilePath

Specifies the location of the EFI boot loader for the operating system. On EFI-based systems, BootFilePath: \Device\HarddiskVolume1
\EFI\Microsoft\WINNT50\ia64ldr.efi
each operating system or bootable device has its own copy of the boot loader on the EFI
partition.
In EFI NVRAM, the boot loader file path is stored as a binary EFI device path that uses a
globally unique identifier (GUID) to identify the EFI partition .
Bootcfg uses the NT device name of the partition in its path display.

OsFilePath

Specifies the location of the operating system.

OsFilePath: \Device\HarddiskVolume3
\WINDOWS

Windows Vista introduced a new boot loader architecture, a new firmware-independent boot configuration and storage system called Boot Configuration Data (BCD), and a
new boot option editing tool, BCDEdit (BCDEdit.exe).
Boot Loading Architecture in Windows Vista and Later
Windows Vista and later versions of Windows include boot loader components that are designed to load Windows quickly and securely. The previous Windows NT boot
loader, ntldr, is replaced by three components:

Windows Boot Manager (Bootmgr.exe)

Windows operating system loader (Winload.exe)
Windows resume loader (Winresume.exe)

In this configuration, the Windows Boot Manager is generic and unaware of the specific requirements for each operating system while the system-specific boot loaders are
optimized for the system that they load.
When a computer with multiple boot entries includes at least one entry for Windows Vista or a later version of Windows, the Windows Boot Manager, which resides in the
root directory, starts the system and interacts with the user. It displays the boot menu, loads the selected system-specific boot loader, and passes the boot parameters to the
boot loader.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 19 of 1651

The boot loaders reside in the root directory of each Windows partition. Once selected, the boot loaders take over the boot process and load the operating system in
accordance with the selected boot parameters.
Boot Configuration Data
On Windows Vista and later versions of Windows, boot options are stored in the Boot Configuration Data (BCD) store on BIOS-based and EFI-based computers.
BCD replaces the traditional Boot.ini text file in BIOS-based systems. Storing boot parameters in a text file, however simple, was considered to be too vulnerable to malicious
attacks to justify its use. On EFI-based computers, where boot options are stored in NVRAM, you use the same BCD methods to edit boot options as you would use on a
BIOS-based computer, instead of accessing NVRAM directly using Windows APIs or specialized tools.
BCD provides a common, firmware-independent boot option interface for all computers running Windows Vista and later versions of Windows. It is more secure than
previous boot option storage configurations, because it permits secure lockdown of the BCD store and lets Administrators assign rights for managing boot options. BCD is
available at run time and during all phases of setup. You can even call BCD during power state transitions and use it to define the boot process for resuming after hibernation.
You can manage BCD remotely and manage BCD when the system boots from media other than the media on which the BCD store resides. This feature is extremely
important for debugging and troubleshooting, especially when a BCD store must be restored while running Startup Repair from a CD, from USB-based storage media, or even
remotely.
BCD is easy to use. The BCD store, with its familiar object-and-element architecture, uses GUIDs to precisely identify boot-related applications.
This new data format for BCD uses a new set of boot options. Most of the Windows boot options that were used in pre-Vista versions of Windows, such
as /debug, /maxmem, and /pae, have been preserved; however, in some cases, the names of the options might have changed to better suite their function. For more
information about these boot options, see BCD Boot Options Reference.
Multiboot Scenarios
If multiple Windows operating systems are installed on the computer, and one of the them is Windows Vista, or a later version of Windows, the Windows Boot Manager
works with the booting components for older ("legacy") versions of Windows to interact with the user and start the selected operating system.
When a multiboot computer is started, the following scenario occurs:

The Windows Boot Manager displays a menu with the boot entries for Windows Vista and later versions of Windows, and a Legacy option.
If you select a boot entry for Windows Vista or a later version of Windows, the Windows Boot Manager loads the system-specific boot loader for that operating system
and passes the parameters for that boot entry to the system-specific boot loader. The system-specific boot loader loads the operating system in accordance with the boot
parameters.
If you select Legacy, the Windows Boot Manager starts Ntldr, the boot manager for NT-based Windows operating systems prior to Windows Vista. From this point
forward, the boot process proceeds as it did prior to Windows Vista.
If the computer includes multiple installations of pre-Windows Vista Windows, Ntldr displays a boot menu consisting of the entries for Windows Server 2003,
Windows XP, Windows 2000, and Windows NT operating systems. This boot menu is generated from the entries in the Boot.ini file on BIOS-based systems and the
boot entries stored in EFI-NVRAM on EFI-based systems. When you select a boot entry, Ntldr loads the operating system in accordance with the boot parameters.

Editing Boot Options in Windows Vista

To edit boot options in Windows Vista and later versions of Windows, use BCDEdit (BCDEdit.exe), a tool included in these versions of Windows. You cannot use Bootcfg or
NvrBoot to edit boot options on Windows Vista and later versions of Windows, although you can continue to use them to edit boot options on prior versions of Windows.
To use BCDEdit, you must be a member of the Administrators group on the computer. BCDEdit is documented in Windows Help and Support.
To change boot options programmatically on Windows Vista and later versions of Windows, use the Windows Management Instrument (WMI) interface to boot options. This
BCD WMI interface is the best method to programmatically change the boot options. For information about the BCD WMI interface, see Boot Configuration Data in the
Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Editing Boot Options

This section is a practical guide to editing the boot options on a computer running Windows Vista and later versions of Windows, and Windows Server 2003, Windows XP, or
Windows 2000. It suggests a step-by-step procedure for customizing the basic elements of boot options.
For Windows Server 2003 and Windows XP, this section describes a method of using Bootcfg, a tool included in Windows Server 2003 and Windows XP.
For Windows Vista and later versions of Windows, this section describes a method of using BCDEdit, a tool included with the operating system. For information about
BCDEdit command syntax, type bcdedit /? or bcdedit /? TOPICS in a Command Prompt window.
For help on editing boot entry parameters to enable and disable Windows features, see Using Boot Parameters.
To configure operating system features in boot options:

Add a new boot entry for the operating system by copying an existing boot entry from the same operating system.
Change the friendly name of the newly created boot entry so that you can identify it in the boot menu.
Add parameters to the boot entry that enable and configure Windows features.

Then, to make testing quicker and easier:

Make the new boot entry the default entry.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 20 of 1651

Change the boot menu time-out. You can shorten the boot menu time-out so that Windows boots quickly. Or, lengthen the boot menu time-out so that you have ample
time to select the preferred boot entry.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Adding Boot Entries

The first step in customizing boot options in operating systems is to add a new boot entry for an operating system. A boot entry is a set of options that define a load
configuration for an operating system or bootable program.
You can have multiple boot entries for an operating system, each with a different set of boot parameters. Windows Installer creates a standard boot entry when you install an
operating system, and you can create additional, customized boot entries for an operating system by editing the boot options.
You can add, delete, and change the options in the boot entry that Windows Installer created. However, it is prudent to keep the standard entry and, instead, add a separate
entry that you customize.
To add a boot entry, copy an existing boot entry, and then modify the copy.
Using Bootcfg in operating systems prior to Windows Vista
You can use the Bootcfg /copy switch to copy a boot entry on any system, regardless of the type of firmware.
The following Bootcfg command copies the second boot entry to create a new entry. The /ID switch identifies the line number of the entry being copied and the /d
(description) switch specifies a friendly name for the new entry, which must be in quotation marks.
bootcfg /copy /ID 2 /d "Microsoft Windows XP Professional - new"
If you have added boot entries that you are no longer using, be sure to delete them, especially on computers that store boot options in the finite EFI NVRAM resource. Use the
Bootcfg /delete switch to delete unused entries.
If you have more than one boot entry for an operating system, be sure to select your preferred entry from the boot menu or set the preferred entry as the default boot entry. For
instructions, see Changing the Default Boot Entry.
For complete instructions for using Bootcfg, see Help and Support Services. For examples, see Using Boot Parameters.
Editing the Boot.ini File in operating systems prior to Windows Vista
To add a boot entry to a Boot.ini file, copy and paste an existing boot entry. Then, change the friendly name of the entry so you can easily distinguish it in the file and on the
boot menu. The friendly name is the quoted string in the boot entry.
For example, in the following sample Boot.ini file, the original entry for Windows XP was duplicated, and then the friendly name of the duplicate entry was changed. The
newly created entry appears in bold text.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINNT
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Microsoft Windows 2000 Professional" /fastdetect
multi(0)disk(0)rdisk(0)partition(3)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
multi(0)disk(0)rdisk(0)partition(3)\WINDOWS="Microsoft Windows XP Professional - new" /fastdetect
Adding a new boot entry in Windows Vista and Later
In Windows Vista and later versions of Windows, you use BCDEdit to modify your boot options. To add a new boot entry, open a Command Prompt window with elevated
privileges (right click Command Prompt and click Run as administrator from the shortcut menu).
Use BCDEdit with the /copy option to copy an existing boot entry. For example, in the following command, BCDEdit copies the Microsoft Windows boot entry that was last
used to boot Windows, identified as {current}, and creates a new boot entry. The /d description option specifies DebugEntry as the name of the new boot entry.
bcdedit /copy {current} /d "DebugEntry"
If the command succeeds, BCDEdit displays a message similar to the following:
The entry was successfully copied to {49916baf-0e08-11db-9af4-000bdbd316a0}.
When you copy a boot loader entry that appears on the boot menu, the copy is automatically added as the last item on the boot menu.
The GUID in the preceding message (which appears between braces ({})) is the identifier of the new boot entry. You use the identifier to represent the entry in all subsequent
BCDEdit commands.
If the command fails, be sure that you are running in a Command Prompt window with administrator privileges and that all of the command parameters are spelled correctly,
including the braces around {current}.
You can also add a boot entry using the /create option. For example, the following creates a new operating system boot entry called "My Windows Vista":

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 21 of 1651

bcdedit /create /d "My Windows Vista" /application osloader

When you use the /create option, the new boot loader entries are not added to the boot menu automatically. You must add the new boot entry to the boot menu by using
the /displayorder option. You can place the boot loader entries in any order.
For information about the /create command parameters, type bcdedit /? /create in a Command Prompt window.
Editing the boot menu in Windows Vista and Later
In Windows Vista and later versions of Windows, new boot loader entries are not added to the boot menu automatically. You can place the boot loader entries in any order.
You can use the /displayorder option to set the order in which the boot manager displays the boot entries on a multi-boot menu. The command has the following syntax:
bcdedit /displayorder {ID} {ID} ...
The ID is the GUID of the boot entry or a reserved identifier, such as {current}). Separate each identifier with a space. Be sure to include the braces ({}).
For example, to add the DebugEntry boot entry to the boot menu after the {current} entry, use the following command:
bcdedit /displayorder {current} {49916baf-0e08-11db-9af4-000bdbd316a0}
You can also use the options /addlast, /addfirst, and /remove to order and remove items from the menu. For example, the following command adds the DebugEntry boot
entry as the last item on the menu:
bcdedit /displayorder {49916baf-0e08-11db-9af4-000bdbd316a0} /addlast
To verify that the display order is correct, use the following command:
bcdedit
When you type bcdedit without additional parameters, BCDEdit displays the boot manager entry and the boot loader entries in the order that they will appear in the menu.
The Windows Boot Manager entry also includes the boot menu display order, as the following example shows.

Windows Boot Manager

-------------------identifier
device
description
locale
inherit
default
displayorder
toolsdisplayorder
timeout

{bootmgr}
partition=C:
Windows Boot Manager
en-US
{globalsettings}
{current}
{current}
{18b123cd-2bf6-11db-bfae-00e018e2b8db}
{memdiag}
30

Windows Boot Loader

------------------identifier
device
path
description
locale
inherit
osdevice
systemroot
resumeobject
nx

{current}
partition=C:
\Windows\system32\winload.exe
Microsoft Windows Vista
en-US
{bootloadersettings}
partition=C:
\Windows
{d7094401-2641-11db-baba-00e018e2b8db}
OptIn

Windows Boot Loader

------------------identifier
device
path
description
locale
inherit
osdevice
systemroot
resumeobject
nx
debug

{18b123cd-2bf6-11db-bfae-00e018e2b8db}
partition=C:
\Windows\system32\winload.exe
Debugger Boot
en-US
{bootloadersettings}
partition=C:
\Windows
{d7094401-2641-11db-baba-00e018e2b8db}
OptIn
Yes

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 22 of 1651

Debugging Tools for Windows

Changing the Friendly Name of a Boot Entry

On Windows Server 2003 and earlier versions of NT-based Windows, the boot loader generates the boot menu from the boot entries. The items that appear in the boot menu
are the friendly names of each boot entry. Similarly, on Windows Vista and later versions of Windows, the items that appear in the Windows Boot Manager are the
descriptions of each boot entry.
Typically, after you copy a boot entry, you change the friendly name of the newly created entry to distinguish it from the original.
You can also change the friendly name to make it easier to recognize customized boot entries. A string that precisely describes the entry can save significant time and effort.
For example, the following friendly name strings add little value.
"Windows XP Debug1"
"Windows XP Debug2"
However, more precise strings, such as the ones that follow, make the boot choice much easier.
"Windows XP NullModem"
"Windows XP 1394"
Note When a boot entry is configured for debugging (/debug /debugport) or for Emergency Management Services (EMS) (/redirect) on an x86- or an x64-based system, the
boot loader appends a bracketed phrase ([debugger enabled] or [ems enabled]) to the friendly name that appears in the boot menu.
However, the boot loader omits the bracketed phrase from the boot menu when the friendly name and the bracketed phrase together exceed 70 characters. To restore the
bracketed phrase, shorten the friendly name.
To change the friendly name of a boot entry in a Boot.ini file, you can use Bootcfg or edit the Boot.ini file in Notepad. On systems that store boot options in EFI NVRAM, use
Bootcfg.
To change the friendly name of a boot entry for Windows Vista or later versions of Windows, use BCDEdit.
Using Bootcfg
With Bootcfg, you can change the friendly name of a boot entry only while copying the entry. Use the Bootcfg /copy switch to copy the entry and change its friendly name.
The following Bootcfg command copies the first boot entry to create a new entry. The /ID switch specifies the line number of the entry being copied. The /d (description)
switch specifies the friendly name of the newly-created entry.
bootcfg /copy /ID 1 /d "Windows XP Debug"
For complete instructions for using Bootcfg, see Help and Support Services. For examples, see Using Boot Parameters.
Editing the Boot.ini File
In the Boot.ini file, the friendly name of a boot entry appears in the boot entry in quotation marks.
For example, the following sample from a Boot.ini file has duplicate boot entries for Microsoft Windows XP Professional.
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
To change the friendly name of a boot entry, type over the quoted string in the boot entry. In the following example, because the first entry will be customized for debugging,
the name is changed to Windows XP Debug.
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows XP Debug" /fastdetect
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
Using BCDEdit
To change the description of a boot entry as it appears on the boot menu, you can use the /set ID description option. The command uses the following syntax. The ID is the
GUID that is associated with the boot entry (or one of the well-known identifiers, for example, {current}).
bcdedit /set ID description "The new description"
For example:
bcdedit /set {802d5e32-0784-11da-bd33-000476eba25f} description "Windows Vista NullModem"
To change the description of the boot entry that corresponds to the operating system that is currently running, use the following example:
bcdedit /set {current} description "Windows Vista NullModem"
You can also change the description when you copy an existing boot entry using the /d option.
bcdedit /copy {current} /d "Windows Vista NullModem"

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 23 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Changing Boot Parameters

To enable and configure boot-related operating system features, such as debugging, you must add boot parameters to a boot entry for the operating system.
For a list of boot parameters for Windows Server 2003 and earlier versions of NT-based Windows that are related to developing, testing, and debugging drivers, see Boot.ini
Boot Parameter Reference.
For examples of boot entries configured for driver debugging and testing on Windows Server 2003 and earlier versions of NT-based Windows, see Using Boot Parameters.
To change boot parameters on a system with BIOS firmware that is running Windows Server 2003 and earlier versions of NT-based Windows, you can use Bootcfg or edit the
Boot.ini file in Notepad. On systems with EFI firmware, use Bootcfg or Nvrboot.
To change boot parameters on a system running Windows Vista or later versions of Windows, you can use BCDEdit.
Using Bootcfg
Bootcfg displays the boot parameters in the OS Load Options field (labeled OsLoadOptions on systems with EFI firmware).
The following Bootcfg sample shows the Bootcfg display of the boot options in EFI NVRAM. The sample boot entry includes the /fastdetect and /debug parameters with
the /debugport and /baudrate subparameters.
Boot entry ID:
OS Friendly Name:
OsLoadOptions:
BootFilePath:
OsFilePath:

2
Microsoft Windows XP 64-Bit Edition
/fastdetect /debug /debugport=COM1 /baudrate=115200
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50C\ia64ldr.efi
\Device\HarddiskVolume3\WINDOWS.0

To add a boot parameter to a boot entry, use the Bootcfg parameter-specific switches, such as /ems, /debug, and /dbg1394, or the Bootcfg /addsw or /raw switches. For a
complete list of Bootcfg switches, at a command prompt, type bootcfg /?.
For example, the following Bootcfg command uses the Bootcfg /addsw switch with the /MM argument and a value of 512 to add the /maxmem boot parameter to the second
entry in the Boot Entries section and to set the value of /maxmem to 512 (MB). The /ID switch with a value of 2 identifies the second boot entry (line number 2).
bootcfg /addsw /MM 512 /ID 2
The resulting entry is shown in a sample display from the 64-bit version of Bootcfg.
Boot entry ID:
OS Friendly Name:
OsLoadOptions:
BootFilePath:
OsFilePath:

2
Microsoft Windows XP 64-Bit Edition
/fastdetect /debug /debugport=COM1 /baudrate=115200 /maxmem=512
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50C\ia64ldr.efi
\Device\HarddiskVolume3\WINDOWS.0

Editing the Boot.ini File

In the Boot.ini file, the boot parameters appear in the boot entry immediately following the friendly name.
For example, the following boot entry in the Boot.ini file includes the /fastdetect and /debug parameters with the /debugport and /baudrate subparameters.
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows XP Debug1" /fastdetect /debug /debugport=COM1 /baudrate=57600
To add a boot parameter, type the parameter using the prescribed syntax.
For example, to add the /maxmem parameter, type /maxmem and a value, in megabytes, to the list of boot parameters in the entry. Parameters can appear in any order. In the
following example, the /maxmem parameter and a value of 512 (MB) appear at the end of the parameter list.
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows XP Debug1" /fastdetect /debug /debugport=COM1 /baudrate=57600 /maxmem=512
Using BCDEdit
To add a boot configuration parameter to a boot entry, use the BCDEdit boot entry options to change global settings, such as /ems, /debug, /dbgsettings, or set individual
parameters using the BCDEdit /set options. For a complete list of BCDEdit options, at a command prompt, type BCDEdit /? or BCDEdit /? <command> to find help about a
specific command.
For example, the following command enables PAE for a specified boot entry:
bcdedit /set {802d5e32-0784-11da-bd33-000476eba25f} pae forceenable
To turn the kernel debugger on or off, use the /debug option with the following syntax:
bcdedit /debug <ID> [on | off]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 24 of 1651

The <ID> is the GUID that is associated with the boot entry. If you do not specify an <ID>, the command modifies the operating system that is currently active. The
following command turns on the kernel debugger for a boot entry, called DebugEntry:
bcdedit /debug {49916baf-0e08-11db-9af4-000bdbd316a0} on
To view the current boot entries, type bcdedit at the command prompt. The boot entry for DebugEntry shows that the kernel debugger is turned on.
Windows Boot Loader
------------------identifier
device
path
description
locale
inherit
osdevice
systemroot
resumeobject
nx
pae
debug

{49916baf-0e08-11db-9af4-000bdbd316a0}
partition=C:
\Windows\system32\winload.exe
DebugEntry
en-US
{bootloadersettings}
partition=C:
\Windows
{3e3a9f69-024a-11db-b5fc-a50a1ad8a70e}
OptIn
ForceEnable
Yes

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Changing the Default Boot Entry

The default boot entry is the entry that the boot loader selects when the boot menu time-out expires. You can change the default boot entry to ensure that the operating system
configuration that you prefer is loaded automatically.
For Windows Server 2003 and earlier versions of NT-based Windows, you can use Bootcfg or edit the Boot.ini file in Notepad to change the default boot entry in the Boot.ini
files. To change the default boot entry in EFI NVRAM, you can use Bootcfg or Nvrboot. On either architecture, Bootcfg provides the easiest and safest method of specifying
the default boot entry.
For Windows Vista or later versions of Windows, you can use BCDEdit to change the default boot entry.
Using Bootcfg
Bootcfg provides the easiest method of changing the default boot entry on an all systems. However, the Bootcfg display on each system differs slightly.

On computers with BIOS firmware, Bootcfg displays the boot entries in the order in which they appear in the Boot.ini file. In this display, the default boot entry is the
first entry in the Bootcfg Boot Entries section that starts the default operating system.
On computers with EFI firmware, Bootcfg displays the boot entries in boot order. Thus, the first boot entry listed is the default boot entry. (Bootcfg adds a default
parameter to the display, but it is not stored in EFI NVRAM.)

To change the default boot entry on either type of system, use the Bootcfg /default switch. The following command makes the second boot entry (line number two) the
default boot entry.
bootcfg /default /ID 2
The effect of the Bootcfg /default switch is slightly different on each type of system. On systems with BIOS firmware, the /default switch changes the value of the Boot.ini
default parameter and/or reorders the boot entries as necessary to make the selected boot entry the default. On systems with EFI firmware, the Bootcfg /default switch
changes the boot order. As a result, the specified boot entry appears first in the Bootcfg Boot Entries section.
For complete instructions about using Bootcfg, see Help and Support Services. For examples, see Using Boot Parameters.
Note The Boot entry ID field in Bootcfg and the boot entry number in Nvrboot do not display the value of the EFI boot entry ID. The Bootcfg and Nvrboot IDs are line
numbers that represent the order of the boot entry in the Boot Entries section and change when the entries are reordered.
Editing the Boot.ini File
Before changing the default boot entry, you have to identify the current default boot entry. The following elements of the Boot.ini file determine which boot entry is the
default:

The value of the default parameter.

The order of the entries in the [operating systems] section of the Boot.ini file.

The default boot entry is the first entry in the [operating systems] section that starts the default operating system.
For example, the following sample Boot.ini file has two boot entries for Windows 2000 and two boot entries for Windows XP. The default parameter specifies the operating
system in the WINNT directory on disk 0, partition 1, that is, Windows 2000. The default boot entry, named "Microsoft Windows 2000 Professional", is shown in bold type in
the following sample. It is the first entry in the [operating systems] section that boots Windows 2000 (the operating system in the WINNT directory on disk 0, partition 1).
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINNT

9/18/2010

Introduction

Page 28 of 1651

The /basevideo parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later, set the vga parameter using BCDEdit,
see BCDEdit /set.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/bootlog
The /bootlog parameter records the names of drivers as they load during the boot process and saves the ordered list in the %SystemRoot%\ntbtlog.txt file.
/bootlog
Comments
The /bootlog parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later versions of Windows, use the
LogInitialization element in BCDEdit.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /bootlog
Bootcfg Command
bootcfg /raw "/bootlog" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/break
The /break parameter sets a breakpoint at HAL initialization.
/break
Comments
The /break parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later versions of Windows, use the
HALBreakPoint element in BCDEdit.
When the /break parameter is used with the /debug parameter, the HAL waits at the breakpoint indefinitely until a debugger is connected.
When the /break parameter is used without the /debug parameter, Windows issues Bug Check 0x78: PHASE0_EXCEPTION and displays a blue screen when it hits the
breakpoint.
This parameter is used primarily in HAL development and debugging.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /break /debug
Bootcfg Command
bootcfg /raw "/break /debug" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/burnmemory
The /burnmemory parameter reduces the amount of memory available to Windows by the specified amount.
/burnmemory=SizeInMB

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows Server 2003, Standard" /noexecute=optout /fastdetect /debug=disable,noumex /de

Bootcfg Commands
bootcfg /debug ON /ID 1
bootcfg /debug ON /port=COMx [/baud=115200] /ID 2
bootcfg /dbg1394 ON /channel=44 /ID 3

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/execute
The /execute parameter disables Data Execution Prevention (DEP) and Physical Address Extension (PAE).
Note DEP is a highly effective security feature. Do not disable DEP unless you have no other alternative.
Note The /execute parameter is supported in in Windows Server 2003 with SP1 to disable both DEP and PAE . To disable DEP and PAE in Windows XP with Service
Pack 2 (SP2), use /noexecute=alwaysoff. For more information, see /noexecute.
For more information about using the /execute parameter and the other parameters that affect DEP configuration, see Boot Parameters to Configure DEP and PAE.
/execute
Comments
What is DEP?
DEP consists of hardware and software methods. Software-enforced DEP, which protects only user-mode processes, must be supported by the operating system. Hardwareenforced DEP sets a bit in the page table entry that prevents code from being executed from a virtual memory page that should contain only data. Hardware-enforced DEP
must be supported by the operating system and the processor on the computer. If the operating system supports DEP, but the processor does not, only software-enforced DEP
is enabled on the system.
Operating System Support
DEP is supported in Windows Server 2003 with SP1, Windows XP with SP2, Windows Vista, and later versions of Windows. The /execute option is supported only on
Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, use the NX element in BCDEdit.
32-bit and 64-bit Support
The /execute parameter is effective only on 32-bit processes. On 64-bit processes, DEP is enabled by default and cannot be disabled. For these processes, the /execute
parameter is ignored. On a 64-bit operating system, the /execute parameter affects only on 32-bit processes running on the system.
Enabling and Configuring DEP

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 32 of 1651

To enable, disable, and configure DEP on Windows Server 2003 with SP1 and Windows XP with SP2, use the/noexecute boot parameter.
DEP and PAE
On 32-bit operating systems, hardware-enforced DEP requires PAE. Therefore, when DEP is enabled on a computer that supports hardware-enforced DEP, 32-bit versions of
the Windows operating system automatically enable PAE (see /pae).
The /execute parameter disables both DEP and PAE.
On Windows XP, Windows Vista and later versions of Windows when you disable DEP, Windows also disables PAE. On Windows XP, the /execute parameter has the same
effect as the /noexecute=alwaysoff and noexecute=alwaysoff /nopae parameters; they all disable both DEP and PAE.
However, on Windows Server 2003 with SP1, the /noexecute=alwaysoff parameter disables DEP, but it does not disable PAE, and the system ignores /nopae. To disable
both DEP and PAE on Windows Server 2003 with SP1, you must use /execute.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/fastdetect
The /fastdetect parameter disables NTDETECT serial and parallel port device detection at the specified communications ports. If you do not specify a communications port,
this parameter disables detection on all serial and parallel ports.
/fastdetect[=COMx | =COMx,y,z...]
Subparameter
COMx, y, z
Limits the /fastdetect parameter only to the specified ports. The x, y, and z subparameter represent one or more communication ports on the computer.
Comments
Because the /fastdetect parameter permits Plug and Play (PnP) to detect devices on these ports and prevents detection of unsupported devices, it typically results in a faster,
more reliable boot.
Setup adds the /fastdetect parameter (without specified ports) to the boot entries that it creates for Windows Server 2003, Windows XP, and Windows 2000.
You can omit the /fastdetect parameter when using devices known only to the BIOS (not to Windows). For example, you should omit /fastdetect to test a port that is hidden
from PnP.
This boot parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000.
Examples
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect=COM2
Bootcfg Commands
bootcfg /raw "/fastdetect" /A /ID 1
bootcfg /raw "/fastdetect=COM2" /A /ID 2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/hal
The /hal parameter directs the boot loader to load an alternate hardware abstraction layer (HAL) file for the operating system. The default HAL file is hal.dll.
/hal=HALFile
Subparameter
HALFile
Specifies a HAL file. The specified file must be located in the %SystemRoot%\system32 directory, and its file name must conform to 8.3character format.
Comments
The /hal option is supported only on Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, use the HAL element in

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 33 of 1651

BCDEdit.
You can use this parameter to test a HAL patch or use it with the /kernel parameter to load a partial checked build installation.
Do not use this parameter unless you have deliberately installed a different HAL.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /hal=HALtest.dll
Bootcfg Command
bootcfg /raw "/hal=HALtest.dll" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/kernel
The /kernel parameter directs the boot loader to load an alternate kernel file for the operating system.
/kernel=KernelFile
Subparameter
KernelFile
Specifies a kernel file. The specified file must be located in the %SystemRoot%\system32 directory, and its file name must conform to 8.3character format.
Comments
The /execute option is supported only on Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, use the Kernel
element in BCDEdit.
For computers with less than 4 GB of memory, the default kernel file is ntoskrnl.exe. For computers with 4 GB or more of memory, the default kernel file is ntkrnlpa.exe.
Do not use this parameter unless you have deliberately installed a different kernel. You can use this parameter to test a kernel patch, or use it with the /hal parameter to load a
partial checked build installation.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /hal=KRNLtest.dll
Bootcfg Command
bootcfg /raw "/kernel=KRNLtest.dll" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/maxmem
The /maxmem parameter limits the physical memory available to Windows.
/maxmem=SizeInMB
Subparameter
SizeInMB
Specifies the maximum amount of physical memory available to Windows. Enter a decimal number that represents the amount of memory in megabytes.
Comments
This parameter actually limits Windows to memory addresses less than or equal to the specified value. Because some memory within the remaining address space might be
reserved for nonsystem use, the actual memory available to Windows might be less than the amount that you specify.
The /maxmem parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Server 2003 and Windows XP, use /burnmemory to
limit system memory more precisely. On Windows Vista and later versions of Windows, use the removememory or truncatememory parameters with the BCDEdit /set
command

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 34 of 1651

You can use this parameter to test a driver in low memory conditions. For example, you can use this parameter to limit a computer with 1 GB of memory to 256 MB of
memory.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /maxmem=256
Bootcfg Command
bootcfg /addsw /MM 256 /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/nodebug
The /nodebug parameter disables kernel debugging.
/nodebug
Comments
The /nodebug option is supported only on Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, in BCDEdit, use
the /debug command with a value of OFF (bcdedit /debug [ID] OFF).
If you include the /nodebug parameter, then the /debug parameter and its /debugport, /baudrate, and /targetname subparameters are ignored. If you include
the /crashdebug parameter, then the /nodebug parameter is ignored.
You can use this parameter to disable a debugging configuration without deleting it from the boot options on your computer.
Examples
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /nodebug

multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /debug /debugport=1394 /channel=52 /n

Bootcfg Command
bootcfg /raw "/nodebug" /A /ID 1n

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/noguiboot
The /noguiboot parameter suppresses all bit-mapped graphics during the boot process, including the splash screen and progress bar that precede the logon prompt and the blue
background of a bug check screen.
/noguiboot
Comments
This boot parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000.
The /noguiboot option is supported only on Windows Server 2003 with SP1 and Windows XP with SP2.
OnWindows Vista and later, use the quietboot option with BCDEdit. The quietboot option controls the display of a high-resolution bitmap in place of the Windows boot
screen display and animation.
When /noguiboot is used, the system does not initialize bootvid.dll, the software component that provides basic video support before the computer's graphics drivers are
loaded. Because bootvid.dll is not operating, the computer cannot display bit-mapped graphics during the boot process.
You can use this parameter to investigate problems with video devices.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /noguiboot
Bootcfg command

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 35 of 1651

bootcfg /addsw /NG /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/noexecute
The /noexecute parameter enables, disables, and configures Data Execution Prevention (DEP), a set of hardware and software technologies designed to prevent harmful code
from running in protected memory locations.
For more information about using the /noexecute parameter and the other parameters that affect DEP configuration, see Boot Parameters to Configure DEP and PAE.
Note DEP is a highly effective security feature. Do not disable DEP unless you have no alternative.
/noexecute={alwayson | optout | optin | alwaysoff}
Subparameter
alwayson
Enables DEP for the operating system and all processes, including the Windows kernel and drivers. All attempts to disable DEP are ignored.
optout
Enables DEP for the operating system and all processes, including the Windows kernel and drivers. However, administrators can disable DEP on selected executable files
by using System in Control Panel.
optin
Enables DEP only for operating system components, including the Windows kernel and drivers. Administrators can enable DEP on selected executable files by using the
Application Compatibility Toolkit (ACT).
alwaysoff
Disables DEP. Attempts to enable DEP selectively are ignored.
On Windows XP with SP2, this subparameter also disables Physical Address Extension (PAE). This subparameter does not disable PAE on Windows Server 2003 with
SP1.
Comments
What is DEP?
Data Execution Prevention (DEP) consists of hardware and software methods. Software-enforced DEP, which protects only user-mode processes, must be supported by the
operating system. Hardware-enforced DEP sets a bit in the page table entry that prevents code from being executed from a virtual memory page that should contain only data.
Hardware-enforced DEP must be supported by the operating system and the processor on the computer. If the operating system supports DEP, but the processor does not, only
software-enforced DEP is enabled on the system.
Operating System Support
DEP is supported in Windows Server 2003 with SP1, Windows XP with SP2, Windows Vista, and later versions of Windows.
The /noexecute parameter is supported only on Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, use the NX
element in BCDEdit.
32-bit and 64-bit Support
The /noexecute parameter is effective only on 32-bit processes. It enables software-enforced DEP and, if the processor supports DEP, it also enables hardware-enforced DEP.
On 64-bit processes, DEP is enabled by default and cannot be disabled (equivalent to /noexecute=alwayson). For these processes, the /noexecute parameter is ignored. On a
64-bit operating system, the /noexecute parameter affects only 32-bit processes running on the system.
Default Values
On Windows XP with SP2, the installation program adds /noexecute=optin to the boot entry.
On Windows Server 2003 with SP1, the installation program adds /noexecute=optout to the boot entry.
However, on all operating systems that support DEP, if the /noexecute parameter is not present in the boot options, the system behaves as though the setting
is /noexecute=optin.
DEP and PAE
On 32-bit operating systems, hardware-enforced DEP requires Physical Address Extension (PAE). Therefore, when DEP is enabled on a computer that supports hardwareenforced DEP, 32-bit versions of the Windows operating system automatically enable PAE and ignores /nopae.
On Windows XP with SP2, , when you disable DEP by using /noexecute=alwaysoff, Windows disables both DEP and PAE. This is the equivalent of
using /noexecute=alwaysoff /nopae. To enable PAE without DEP on a system with hardware-enforced DEP, use /noexecute=alwaysoff /pae. This explicitly enables PAE
while disabling DEP.
However, on Windows Server 2003 with SP1, when you disable DEP by using /noexecute=alwaysoff, Windows disables only DEP. PAE is still enabled and the system
ignores explicit attempts to disable PAE, such as the /nopae parameter. To disable both DEP and PAE on Windows Server 2003 with SP1, use /execute.
For a table that describes these parameters and their effects, see Boot Parameters to Configure DEP and PAE.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 36 of 1651

Setting DEP in Control Panel

To set the /noexecute=optin or /noexecute=optout policies, or to disable DEP on a particular executable file, open Control Panel, and then double-click System. Click the
Advanced tab and under Performance, click Settings, and then click the Data Execution Prevention tab. To make the new settings effective, you must restart the computer.
For more information about DEP, see

Changes to Functionality in Microsoft Windows XP Service Pack 2, Part 3: Memory Protection Technologies.

Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /noexecute=alwayson
Bootcfg command
bootcfg /raw "/noexecute=alwayson" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/nolowmem
The /nolowmem parameter loads the operating system, device drivers, and all applications into addresses above the 4 GB boundary, and directs Windows to allocate all
memory pools at addresses above the 4 GB boundary.
/nolowmem
Comments
This parameter is valid only on boot entries for 32-bit versions of Windows on computers with x86 or x64-based processors, and only when Physical Address Extension
(PAE) is enabled.
This boot parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000.
On versions of Windows prior to Windows Server 2003 with Service Pack 1, if a boot entry includes both /nolowmem and /3GB, then /nolowmem is ignored. These
parameters can be used together in Windows Server 2003 with Service Pack 1.
On Windows Vista and later versions of Windows, use the NoLowMem element in BCDEdit.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /nolowmem
Bootcfg command
bootcfg /raw "\nolowmem" /A /ID 1
See Also
/pae
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/nopae
The /nopae parameter disables Physical Address Extension (PAE) and forces the boot loader to load the non-PAE version of the Windows kernel.
For more information about using the /nopae parameter and the other parameters that affect PAE configuration, see Boot Parameters to Configure DEP and PAE.
/nopae
Comments
This parameter is valid only on boot entries for 32-bit versions of Windows that run on computers with x86 and x64-based processors.
The /nopae option is supported only on Windows Server 2003 with SP1 and Windows XP with SP2. On Windows Vista and later versions of Windows, use the PAE element
in BCDEdit with a value of ForceDisable.
Consider using this parameter on systems on which a device does not operate properly when PAE is enabled.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 37 of 1651

Typically, this parameter is not necessary because PAE is not enabled unless you use the /pae boot parameter. However, on computers with x86 processors, Windows
automatically enables PAE when the computer is configured for hot-add memory devices in memory ranges beyond the 4 GB region, as defined by the Static Resource
Affinity Table (SRAT). Hot-add memory supports memory devices that you can add without rebooting or turning off power to the computer. In this case, because PAE must
be enabled when the system starts, it is enabled automatically so that the system can immediately address extended memory that is added between restarts. (Disabling PAE on
these systems disables hot-add memory.) Hot-add memory is supported only on Windows Server 2003, Datacenter Edition; Windows Server 2003, Enterprise Edition;
Windows Server 2008, Datacenter Edition; Windows Server 2008, Enterprise IA64 Edition; and on the datacenter and enterprise editions of all later versions of Windows
Server. Moreover, for versions of Windows prior to Windows Server 2008, hot-add memory is supported only on computers with an ACPI BIOS, an x86 processor, and
specialized hardware. For Windows Server 2008 and later versions of Windows Server, it is supported for all processor architectures.
On a computer that supports hardware-enabled Data Execution Protection (DEP) and is running a 32-bit version of the Windows operating system that supports DEP, PAE is
automatically enabled when DEP is enabled, even if /nopae is set. On all 32-bit versions of Windows that support DEP, except Windows Server 2003 with SP1, when you
disable DEP, Windows automatically disables PAE, but you can use /pae to enable it. For information about DEP, see /noexecute.
PAE is supported in Windows 2000 and later versions of Windows.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows Server 2003, Enterprise" /fastdetect /nopae
Bootcfg Command
bootcfg /raw "/nopae" /A /ID 1
See Also
/pae
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/pae
The /pae parameter enables Physical Address Extension (PAE). This parameter directs the system to load the PAE version of the Windows kernel.
For more information about using the /pae parameter and the other parameters that affect PAE configuration, see Boot Parameters to Configure DEP and PAE.
/pae
Comments
The /pae parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later versions of Windows, use the PAE element
with the BCDEdit /set command.
PAE is an addressing strategy that uses a page-translation hierarchy to enable systems with 32-bit addressing to address more than 4 GB of physical memory. PAE also
supports several advanced system and processor features, such as Data Execution Prevention (DEP; "No execute"), Non-Uniform Memory Architecture (NUMA), and hot-add
memory, so it is also used on computers with less than 4 GB of memory. PAE must be supported by the processor and by the operating system.
PAE is supported beginning with the Windows 2000 operating system.
Operating system
Maximum memory support with PAE
Windows 2000 Advanced Server
8 GB of physical RAM
Windows 2000 Datacenter Server
32 GB of physical RAM
Windows XP (all versions)
4 GB of physical RAM*
Windows Server 2003 (and SP1), Standard Edition 4 GB of physical RAM*
Windows Server 2003, Enterprise Edition
32 GB of physical RAM
Windows Server 2003, Datacenter Edition
64 GB of physical RAM
Windows Server 2003 SP1, Enterprise Edition
64 GB of physical RAM
Windows Server 2003 SP1, Datacenter Edition
128 GB of physical RAM
* Total physical address space is limited to 4 GB on these versions of Windows. When 4 GB of memory is installed and PAE is enabled, the amount of available memory
could be less than what you would expect. For more information about memory usage, see article Q888137, "The amount of RAM reported by the System Properties dialog
box and the System Information tool is less than you expect after you install Windows XP Service Pack 2" in the Microsoft Knowledge Base.
The /pae parameter is valid only on boot entries for 32-bit versions of Windows that run on computers with x86 and x64-based processors. On 32-bit versions of Windows,
PAE is disabled by default. You must use the /pae boot parameter to enable PAE.
However, Windows automatically enables PAE when the computer is configured for hot-add memory devices in memory ranges beyond the 4 GB region, as defined by the
Static Resource Affinity Table (SRAT). Hot-add memory supports memory devices that you can add without rebooting or turning off the computer. In this case, because PAE
must be enabled when the system starts, it is enabled automatically so that the system can immediately address extended memory that is added between restarts. Hot-add
memory is supported only on Windows Server 2003, Datacenter Edition; Windows Server 2003, Enterprise Edition; Windows Server 2008, Datacenter Edition; Windows
Server 2008, Enterprise IA64 Edition; and on the datacenter and enterprise editions of all later versions of Windows Server. Moreover, for versions of Windows prior to
Windows Server 2008, hot-add memory is supported only on computers with an ACPI BIOS, an x86 processor, and specialized hardware. For Windows Server 2008 and later
versions of Windows Server, it is supported for all processor architectures.
On a computer that supports hardware-enabled Data Execution Prevention (DEP) and is running a 32-bit version of the Windows operating system that supports DEP, PAE is

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 38 of 1651

automatically enabled when DEP is enabled and, on all 32-bit versions of the Windows operating system, except Windows Server 2003 with SP1, PAE is disabled when you
disable DEP. To enable PAE when DEP is disabled, you must enable PAE explicitly, by using /noexecute=alwaysoff /pae. For more information about DEP, see /noexecute
and /execute.
PAE is required to support Cache Coherent Non-Uniform Memory Architecture (known as ccNUMA or NUMA) on computers with x86 processors, although Windows can
run in non-NUMA mode on NUMA-capable computers without PAE. Even when it is required, PAE is not enabled automatically. NUMA is supported in all editions of
Windows XP and Windows Vista, and in the Enterprise and Datacenter editions of Windows Server 2003.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows Server 2003, Enterprise" /fastdetect /pae
Bootcfg command
bootcfg /raw "/pae" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/pcilock
The /pcilock parameter prevents the HAL from reallocating I/O and IRQ resources on the PCI bus. The I/O and memory resources set by the BIOS are preserved.
/pcilock
Comments
This parameter is valid only on boot entries for 32-bit versions of Windows that run on computers with x86 or x64-based processors.
The /pcilock parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later versions of Windows, use the
UseFirmwarePCISettings element in BCDEdit.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows Server 2003, Standard" /fastdetect /pcilock
Bootcfg Command
bootcfg /raw "/pcilock" /A /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/redirect
The /redirect parameter enables Emergency Management Services (EMS) console redirection on a Windows server.
Computers with ACPI BIOS firmware and an SPCR table
In the [boot loader] section:
redirect=COMx
[redirectbaudrate=BaudRate]
- OR redirect=USEBIOSSETTINGS

In the [operating systems] section:

/redirect

Computers with BIOS firmware and no SPCR table

In the [boot loader] section:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 39 of 1651

redirect=COMx
[redirectbaudrate=BaudRate]

In the [operating systems] section:

/redirect

Computers with EFI firmware

/redirect

Parameters
redirect=
Establishes a port for EMS console redirection. This should be the same port that the computer uses for out-of-band management.
This parameter is required and valid only on computers with BIOS firmware. It appears in the [boot loader] section of the Boot.ini file and applies to all boot entries on
the computer.
The following table describes the values of the redirect= statement.
Value
COMx

Description
Specifies a serial port. Valid values are COM1, COM2, COM3, and COM4. Set this value to the serial port that is designated for out-of-band
management in the firmware. You cannot use the same port for debugging and for EMS console redirection.
This value is required on computers with BIOS firmware that do not have an ACPI Serial Port Console Redirection (SPCR) table.
When used on computers that have an SPCR table, this value is used instead of the settings in the SPCR table.

USEBIOSSETTINGS Uses the port and connection speed that are designated for out-of-band management in the firmware.
Valid only on computers with a BIOS firmware and an ACPI Serial Port Console Redirection (SPCR) table.

redirectbaudrate=
Establishes the connection speed for EMS transmission. This parameter is optional and valid only with redirect=COMx. If you omit this parameter on any computer
with BIOS firmware, the default connection speed for EMS transmission is 9600 kilobits per second (Kbps).
When redirect=COMx and redirectbaudrate= are used on computers with an SPCR table, the specified COM port and transmission rate are used instead of the settings
in the SPCR table.
The following table describes the value of the redirectbaudrate= parameter.
Value
Description
BaudRate Specifies the connection speed for EMS transmission. Valid values are 9600, 19200, 57600, and 115200 in kilobits per second (Kbps). (38400 is not a valid
value.) The default value is 9600 Kbps.
/redirect
Enables EMS console redirection on a Windows server operating system associated with the boot entry. This parameter is valid on boot entries for Windows Server 2003
and later version of Windows server systems on all computers.
Comments
The /redirect parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. In Windows Vista and later versions of Windows, use BCDEdit and
the /emssettings parameter and its subparameters to establish EMS settings for all boot entries. Then, use the /ems parameter to enable EMS for a particular boot entry.
EMS allows users to control particular components of a server remotely, even when the server is not connected to the network or to other standard remote-administration
tools. For information about EMS, search for Emergency Management Services on the Microsoft TechNet Web site.
EMS is supported on all versions of Windows Server 2003 and later and versions of Windows server systems for x86-, x64-, and Itanium-based computers.
To properly enable EMS console redirection after Windows is installed, Windows needs to know the port and transmission rate that the computer uses for out-of-band
communication. Windows uses these same settings for EMS console redirection.
On computers with EFI firmware, Windows automatically retrieves the out-of-band settings from the EFI firmware. On computers with BIOS firmware, Windows must find
the out-of-band settings in the Boot.ini file.
On computers with BIOS firmware and an ACPI Serial Port Console Redirection (SPCR) table, Windows can find the out-of-band settings established in the BIOS by reading
entries in the SPCR table. On these systems, you can add the redirect=USEBIOSSETTINGS parameter to the Boot.ini file to direct Windows to look in the SPCR table for
the port settings, or you can use the redirect=COMx and redirectbaudrate= parameters to override the settings in the SPCR table.
On computers that have BIOS firmware, but do not have an SPCR table, repeat the out-of-band settings in the Boot.ini file. Use the redirect=COMx parameter to specify the
port and the redirectbaudrate= parameter to specify the transmission rate.
On all systems, use the /redirect parameter on a boot entry to enable EMS console redirection on the operating system that the boot entry loads.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 40 of 1651

The boot parameters described in this section enable EMS console redirection after Windows is installed. For information about enabling EMS during a new installation or
upgrade of Windows, search for "Enabling Emergency Management Services" on the Microsoft TechNet Web site.
For a detailed example, see Boot Parameters to Enable EMS Redirection.
For more information about EMS, see "Emergency Management Services" in Help and Support. Also, review the topics in the "Headless Server and Emergency
Management Services Design" section of the Server Platform Design - Overview page on the Windows Hardware Developer Central Web site.
Examples
Computers with no SPCR table (or to override the SPCR table)
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
redirect=COM1
redirectbaudrate=115200
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows Server 2003, Standard" /fastdetect /redirect
Computers with an SPCR table
[boot loader]
timeout=2
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
redirect=USEBIOSSETTINGS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows Server 2003, Standard" /fastdetect /redirect
Computers with EFI firmware (Bootcfg display)
Boot Options
-----------Timeout:
Default:
CurrentBootEntryID:

30
\Device\HarddiskVolume3\WINDOWS
1

Boot Entries
-----------Boot entry ID:
OS Friendly Name:
OsLoadOptions:
BootFilePath:
OsFilePath:

1
Microsoft Windows .NET Enterprise Server
/redirect
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi
\Device\HarddiskVolume3\WINDOWS

Bootcfg Commands
bootcfg
bootcfg
bootcfg
bootcfg

/ems
/ems
/ems
/ems

ON /port COM1 /baud 115200 /ID 1

ON /port BIOSSET /ID 1
ON /ID 1
EDIT /port COM1 /baud 115200 /ID 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

/sos
The /sos parameter displays the names of the drivers as they load during the boot process.
/sos
Comments
The /sos parameter is supported only on Windows Server 2003, Windows XP, and Windows 2000. On Windows Vista and later versions of Windows, use the SOS option
with BCDEdit.
Example
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /sos
Bootcfg Command
bootcfg /addsw SO /ID n

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 41 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

BCD Boot Options Reference

Boot entry parameters, or boot parameters, are optional, system-specific settings that represent configuration options. You can add boot parameters to a boot entry for an
operating system.
This section describes the boot options for Windows Vista and later versions of Windows that are related to developing, testing, and debugging drivers on computers with
x86-based, x64-based, and Itanium-based processors. You can add these parameters to the boot entries for Windows operating systems.
BCDEdit /bootdebug
BCDEdit /dbgsettings
BCDEdit /debug
BCDEdit /ems
BCDEdit /emssettings
BCDEdit /set
Mapping Boot.ini Options to BCDEdit Options and Elements
The following table provides a mapping from the boot options used in operating systems prior to Windows Vista (in Boot.ini), to the BCDEdit options and the BCD elements
used in Windows Vista and later versions of Windows. For information about the BCD boot elements see BCD Reference on MSDN.
Boot.ini
/3GB
/BASEVIDEO

increaseuserva
vga

BCDEdit option

BCD element type

BcdOSLoaderInteger_IncreaseUserVa
BcdOSLoaderBoolean_UseVgaDriver

/BOOTLOG

bootlog

BcdOSLoaderBoolean_BootLogInitialization

/BREAK

halbreakpoint

BcdOSLoaderBoolean_DebuggerHalBreakpoint

/CRASHDEBUG

/dbgsettings /start

/DEBUG, BOOTDEBUG /debug

/DEBUG

/bootdebug

BcdLibraryBoolean_DebuggerEnabled

/debug

BcdOSLoaderBoolean_KernelDebuggerEnabled

/DEBUG, /DEBUGPORT= /dbgsettings

/DEBUGPORT=

/dbgsettings DebugType [debugport:Port] [baudrate:Baud] [channel:Channel]

[targetname:TargetName] [/start {Active |Autoenable |Disable} /noemux]

BcdLibraryInteger_DebuggerType

BcdLibraryInteger_SerialDebuggerPort
BcdLibraryInteger_SerialDebuggerBaudRate
BcdLibraryInteger_1394DebuggerChannel
BcdLibraryString_UsbDebuggerTargetName

/EXECUTE

BcdOSLoaderInteger_NxPolicy

/FASTDETECT
/HAL=

hal

BcdOSLoaderString_HalPath

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 42 of 1651

/KERNEL=

kernel

BcdOSLoaderString_KernelPath

/MAXMEM=

truncatememory

BcdLibraryInteger_TruncatePhysicalMemory

/NODEBUG

/debug

/NOEXECUTE

nx {

BcdOSLoaderInteger_NxPolicy

/NOGUIBOOT

quietboot

BcdOSLoaderBoolean_DisableBootDisplay

/NOLOWMEM

nolowmem

BcdOSLoaderBoolean_NoLowMemory

/NOPAE
/ONECPU

pae
onecpu

BcdOSLoaderInteger_PAEPolicy
BcdOSLoaderBoolean_UseBootProcessorOnly

/PAE
/PCILOCK

pae
usefirmwarepcisettings

BcdOSLoaderInteger_PAEPolicy
BcdOSLoaderInteger_UseFirmwarePciSettings

/REDIRECT

/ems

BcdOSLoaderBoolean_EmsEnabled

/emssettings [ BIOS ] |
[ EMSPORT:{port} | [EMSBAUDRATE: {baudrate}] ]

/SOS

sos

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

BCDEdit /bootdebug
The /bootdebug boot option enables or disables boot debugging of the current or specified Windows operating system boot entry.
bcdedit /bootdebug [{ID}] { on | off }
Parameters
{ID}
The {ID} is the GUID that is associated with the boot entry. If you do not specify an {ID}, the command modifies the operating system that is currently active. If a boot
entry is specified, the GUID associated with the boot entry must be enclosed in braces { }.
on
Enables boot debugging of the specified boot entry. If a boot entry is not specified, boot debugging is enabled for the current operating system.
off
Disables boot debugging of the specified boot entry. If a boot entry is not specified, boot debugging is disabled for the current operating system.
Comments
The /bootdebug boot option enables boot debugging for a specific boot entry. Use the /dbgsettings option to configure the type of debugging connection (debugtype) to use

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 43 of 1651

and the connection parameters. If no /dbgsettings are specified for the boot entry, the global debug settings are used. The default values for the global settings are shown in
the following table.
dbgsetting parameter Default value
Debugtype
Serial
Debugport
1
Baudrate
115200
The following command disables boot debugging of Windows Boot Manager (Bootmgr.exe). Windows Boot Manager selects which operating system will start, and then
loads the Windows boot loader.
bcdedit /bootdebug {bootmgr} off
The following command enables boot debugging of the Windows boot loader for the current operating system. The Windows boot loader (Winload.exe) controls the progress
bar and loads the kernel boot drivers.
bcdedit /bootdebug on
In the following example, the first command sets the global debugger settings for a 1394 kernel debugging connection. The next three commands enable debugging of
Windows Boot Manager, the boot loader, and then kernel debugging of the operating system. This combination allows debugging at every stage of startup. If this combination
is used, the target computer will break into the debugger three times: when Windows Boot Manager loads, when the boot loader loads, and when the operating system starts
up.
bcdedit
bcdedit
bcdedit
bcdedit

/dbgsettings 1394 CHANNEL:1

/bootdebug {bootmgr} on
/bootdebug on
/debug on

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

BCDEdit /dbgsettings
The /dbgsettings option sets or displays the current global debugger settings for the computer. To enable or disable the kernel debugger, use the BCDEdit /debug option.
bcdedit /dbgsettings SERIAL [DEBUGPORT:port] [BAUDRATE:baud] [/start startpolicy] [/noumex]
bcdedit /dbgsettings 1394 [CHANNEL:channel] [/start startpolicy] [/noumex]
bcdedit /dbgsettings USB TARGETNAME:targetname [/start startpolicy] [/noumex]
Parameters
SERIAL
Specifies that the target machine and the host machine will use a serial connection for debugging. When this option is used, the DEBUGPORT and BAUDRATE
parameters can be included as well.
1394
Specifies that the target machine and the host machine will use an IEEE 1394 (FireWire) connection for debugging. When this option is used, the CHANNEL parameter
can be included as well.
USB
Specifies that the target machine and the host machine will use a USB 2.0 connection for debugging. When this option is used, the TARGETNAME parameter must be
included as well.
DEBUGPORT:port
(Only used when the connection type is SERIAL.) Specifies the serial port to use as the debugging port. This is an optional setting. The default port is 1 (COM 1).
BAUDRATE:baud
(Only used when the connection type is SERIAL.) Specifies the baud rate to use. This parameter is optional. Valid values for baud are 9600, 19200, 38400, 57600, and
115200. The default baud rate is 115200 bps.
Note If the Windows Special Administration Console (SAC) application is running on a target machine that is configured for kernel mode debug through a serial port,
the SAC application may cause the debugger connection to drop. This event occurs because the COM port baud value changes after the debugger connection is
established. Either close the SAC application before running the debugger or change the debugger COM port baud value to 9600.
CHANNEL:channel
(Only used when the connection type is 1394.) Specifies the 1394 channel to use. The value for channel must be a decimal integer between 0 and 62, inclusive, and must
match the channel number used by the host computer. The channel specified in this parameter does not depend on the physical 1394 port chosen on the adapter. The
default value for channel is 0.
TARGETNAME:targetname
(Only used when the connection type is USB.) Specifies a string value to use for the target name. This string can be any value.
/start startpolicy
This option specifies the debugger start policy. The following table shows the options for the startpolicy.
startpolicy
Description
ACTIVE
Specifies that the kernel debugger is active.
AUTOENABLE Specifies that the kernel debugger is enabled automatically when an exception or other critical event occurs. Until then, the debugger is active but is
disabled.
DISABLE.
Specifies that the kernel debugger is enabled when you type kdbgctrl to clear the enable block. Until then, the debugger is active but is disabled.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 44 of 1651

If a start policy is not specified, ACTIVE is the default.

Introduction

Page 46 of 1651

Debugging Tools for Windows

BCDEdit /set
The /set command sets a boot entry option value in the boot configuration data store. Use this command to configure specific boot entry elements, such as kernel debugger
settings, data execution protection (DEP) and processor address extension (PAE) options, and to load alternate hardware abstraction layer (HAL) and kernel files.
bcdedit

/set [{ID}] datatype value

Parameters
[{ID}]
The {ID} is the GUID that is associated with the boot entry. If you do not specify an {ID}, the command modifies the current operating system boot entry. If a boot entry
is specified, the GUID associated with the boot entry must be enclosed in braces { }. To view the GUID identifiers for all of the active boot entries, use the
bcdedit /enum command.
Possible values of datatype value
bootlog [ yes | no]
Enables the system initialization log. This log is stored in the Ntbtlog.txt file in the %WINDIR% directory. It includes a list of loaded and unloaded drivers in text format.
groupsize maxsize
Sets the maximum number of logical processors in a single processor group, where maxsize is any power of 2 between 1 and 64 inclusive. By default, processor groups
have a maximum size of 64 logical processors. You can use this boot configuration setting to override the size and makeup of a computers processor groups for testing
purposes. Processor groups provide support for computers with greater than 64 logical processors. This boot option is available on 64-bit versions of Windows 7 and
Windows Server 2008 R2 and later versions. This boot option has no effect on the 32-bit versions of Windows 7.
Use the groupsize option if you want to force multiple groups and the computer has 64 or fewer active logical processors. For more information about using this option,
see Boot Parameters to Test Drivers for Multiple Processor Group Support.
groupaware [ on | off ]
Forces drivers to be aware of multiple groups in a multiple processor group environment. Use this option to help expose cross-group incompatibilities in drivers and
components. Processor groups provide support for computers with greater than 64 logical processors. This boot option is available on 64-bit versions of Windows 7
and Windows Server 2008 R2 and later versions. This boot option has no effect on the 32-bit versions of Windows 7. You can use the groupaware option and the
groupsize option to test driver compatibility to function with multiple groups when computer has 64 or fewer active logical processors.
The groupaware on setting ensures that processes are started in a group other than group 0. This increases the chances of cross-group interaction between drivers and
components. The option also modifies the behavior of the legacy functions, KeSetTargetProcessorDpc, KeSetSystemAffinityThreadEx, and
KeRevertToUserAffinityThreadEx, so that they always operate on the highest numbered group that contains active logical processors. Drivers that call any of these
legacy functions should be changed to call their group-aware counterparts (KeSetTargetProcessorDpcEx, KeSetSystemGroupAffinityThread, and
KeRevertToUserGroupAffinityThread).
For more information about using this option, see Boot Parameters to Test Drivers for Multiple Processor Group Support.
hal file
Directs the operating system loader to load an alternate HAL file. The specified file must be located in the %SystemRoot%\system32 directory, and its file name must
conform to 8.3character format.
increaseuserva Megabytes
Specifies the amount of memory, in megabytes, for user-mode virtual address space. This variable can have any value between 2048 (2 GB) and 3072 (3 GB) megabytes
in decimal notation. Windows uses the remaining address space (4 GB minus the specified amount) as its kernel-mode address space.
kernel file
Directs the operating system loader to load an alternate kernel. The specified file must be located in the %SystemRoot%\system32 directory, and its file name must
conform to 8.3character format.
loadoptions busparams=Bus.Device.Function
Specifies the target controller when multiple controllers exist. This syntax is appropriate when using either a 1394 cable or a USB 2.0 debug cable for debugging. Bus
specifies the bus number, Device specifies the device number, and Function specifies the function number.
Note For 1394 debugging, the bus parameters must be specified in decimal, regardless of which version of Windows is being configured. The format of the bus
parameters used for USB 2.0 debugging depends on the Windows version. In Windows Vista and Windows Server 2008, the USB 2.0 bus parameters must be specified
in hexadecimal. In Windows 7 and later versions of Windows, the USB 2.0 bus parameters must be specified in decimal.
maxgroup [ on | off ]
Maximizes the number of groups created in a processor group configuration.
The maxgroup on setting assigns NUMA nodes to groups in a manner that maximizes the number of groups for a particular computer. The number of groups created is
either the number of NUMA nodes the computer has, or the maximum number of groups supported by this version of Windows, whichever is smaller. The default
behavior (maxgroup off) is to pack the NUMA nodes tightly into as few groups as possible.
Use this option if you want to use multiple groups, the computer has 64 or fewer active logical processors, and the computer already has multiple NUMA nodes. This
option can also be used to alter the default group configuration of a computer that has more than 64 logical processors.
Processor groups provide support for computers with greater than 64 logical processors. This option is available on 64-bit versions of Windows 7 and Windows Server
2008 R2 and later versions. This boot option has no effect on the 32-bit versions of Windows 7.
For more information about using this option, see Boot Parameters to Test Drivers for Multiple Processor Group Support.
nolowmem [ on | off ]
Controls the use of low memory. When nolowmem on is specified, this option loads the operating system, device drivers, and all applications into addresses above the 4
GB boundary, and directs Windows to allocate all memory pools at addresses above the 4 GB boundary.
nx [Optin |OptOut | AlwaysOn |AlwaysOff]
Enables, disables, and configures Data Execution Prevention (DEP), a set of hardware and software technologies designed to prevent harmful code from running in
protected memory locations. For information about how to use the Control Panel to change the DEP settings, see the Change Data Execution Prevention settings page
on the Windows Help and How-to Web site.
Optin

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 47 of 1651

Enables DEP only for operating system components, including the Windows kernel and drivers. Administrators can enable DEP on selected executable files by using
the Application Compatibility Toolkit (ACT).
Optout
Enables DEP for the operating system and all processes, including the Windows kernel and drivers. However, administrators can disable DEP on selected executable
files by using System in Control Panel.
AlwaysOn
Enables DEP for the operating system and all processes, including the Windows kernel and drivers. All attempts to disable DEP are ignored.
AlwaysOff
Disables DEP. Attempts to enable DEP selectively are ignored.
On Windows Vista, this parameter also disables Physical Address Extension (PAE). This parameter does not disable PAE on Windows Server 2008.
onecpu [ on | off ]
Forces only the boot CPU to be used in a computer that has more than one logical processor.
For example, the following command configures the current operating system loader to use one processor.
bcdedit /set onecpu on
pae [ Default | ForceEnable | ForceDisable ]
Enables or disables Physical Address Extension (PAE). When PAE is enabled, the system loads the PAE version of the Windows kernel.
The pae parameter is valid only on boot entries for 32-bit versions of Windows that run on computers with x86-based and x64-based processors. On 32-bit versions of
Windows, PAE is disabled by default. However, Windows automatically enables PAE when the computer is configured for hot-add memory devices in memory ranges
beyond the 4 GB region, as defined by the Static Resource Affinity Table (SRAT). Hot-add memory supports memory devices that you can add without rebooting or
turning off the computer. In this case, because PAE must be enabled when the system starts, it is enabled automatically so that the system can immediately address
extended memory that is added between restarts. Hot-add memory is supported only on Windows Server 2003, Datacenter Edition; Windows Server 2003, Enterprise
Edition; Windows Server 2008, Datacenter Edition; Windows Server 2008, Enterprise IA64 Edition; and on the datacenter and enterprise editions of all later versions of
Windows Server. Moreover, for versions of Windows prior to Windows Server 2008, hot-add memory is supported only on computers with an ACPI BIOS, an x86
processor, and specialized hardware. For Windows Server 2008 and later versions of Windows Server, it is supported for all processor architectures.
On a computer that supports hardware-enabled Data Execution Prevention (DEP) and is running a 32-bit version of the Windows operating system that supports DEP,
PAE is automatically enabled when DEP is enabled and, on all 32-bit versions of the Windows operating system, except Windows Server 2003 with SP1, PAE is
disabled when you disable DEP. To enable PAE when DEP is disabled, you must enable PAE explicitly, by using /set nx AlwaysOff and /set pae ForceEnable. For
more information about DEP, see Boot Parameters to Configure DEP and PAE.
PAE is required to support Cache Coherent Non-Uniform Memory Architecture (known as ccNUMA or NUMA) on computers with x86 processors, although Windows
can run in non-NUMA mode on NUMA-capable computers without PAE. Even when it is required, PAE is not enabled automatically. NUMA is supported in all editions
of Windows XP and Windows Vista, and in the Enterprise and Datacenter editions of Windows Server 2003.
For more information about using the pae parameter and the other parameters that affect PAE configuration, see Boot Parameters to Configure DEP and PAE.
If you are running a 32-bit version of Windows Vista on a computer that has 4 GB of memory installed, the amount of RAM available for use could be less than what you
would expect. For more information about memory usage, see article Q929605, "The system memory that is reported in the System Information dialog box in
Windows Vista is less than you expect if 4 GB of RAM is installed" in the Microsoft Knowledge Base.
quietboot [ on | off ]
Controls the display of a high-resolution bitmap in place of the Windows boot screen display and animation. In operating systems prior to Windows Vista,
the /noguiboot serves a similar function.
removememory Megabytes
Removes memory from the total available memory that the operating system can use.
For example, the following command removes 256 MB of memory from the total available to the operating system associated with the specified boot entry.
bcdedit /set {49916baf-0e08-11db-9af4-000bdbd316a0} removememory 256
sos [ on | off ]
Controls the display of the names of the drivers as they load during the boot process. Use sos on to display the names. Use sos off to suppress the display.
testsigning [ on | off ]
Controls whether Windows 7, Windows Server 2008, or Windows Vista will load any type of test-signed kernel-mode code. This option is not set by default, which
means test-signed kernel-mode drivers on 64-bit versions of Windows 7, Windows Server 2008, and Windows Vista will not load by default. After you run the BCDedit
command, restart the computer so that the change takes effect. For more information, see Introduction to Test-Signing in the Windows Driver Kit (WDK)
documentation.
truncatememory address
Limits the amount of physical memory available to Windows. When you use this option, Windows ignores all memory at or above the specified physical address. Specify
the address in bytes.
For example, the following command sets the physical address limit at 1 GB. You can specify the address in decimal (1073741824) or hexadecimal (0x40000000).
bcdedit /set {49916baf-0e08-11db-9af4-000bdbd316a0} truncatememory 0x40000000
usefirmwarepcisettings [ yes | no ]
Enables or disables the use of BIOS-configured peripheral component interconnect (PCI) resources.
vga [ on | off ]
Forces the use of the VGA display driver.
Comment
For more information about specific BCD elements and boot options, you can use the commands BCDEdit /? OSLOADER and BCDEdit /? TYPES OSLOADER.
To view the current boot entries and their settings, use the bcdedit /enum command. This command displays the active boot entries and their associated globally unique
identifiers (GUID). Use the identifiers with the /set command to configure options for a specific boot entry.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 48 of 1651

To delete a boot option value that you have set, use the /deletevalue option. The syntax for the command is as follows:
bcdedit [{ID}] /deletevalue datatatype
For example, if you change the processor group option, groupsize, to a new value for testing purposes, you can revert to the default value of 64 by typing the following
command and then restarting the computer.
bcdedit /deletevalue groupsize
Any change to a boot option requires a restart to take effect. For information about commonly used BCDEdit commands, see
Asked Questions.

Boot Configuration Data Editor Frequently

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Boot Parameters

Driver developers and testers often have to add, delete, and change the parameters of boot entries to test their drivers under variable conditions. This section describes a few
common scenarios and suggests strategies for configuring boot parameters in the Boot.ini file and in NVRAM.
This section contains the following topics:
Boot Parameters to Enable Debugging
Boot Parameters to Manipulate Memory
Boot Parameters to Load a Partial Checked Build
Boot Parameters to Enable EMS Redirection
Boot Parameters to Configure DEP and PAE
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Enable Debugging

When a kernel debugging connection is established, the system gives a kernel debugger control over its execution. Also, when a bug check occurs or a kernel-mode program
communicates with a debugger, the computer waits for a response from a kernel debugger before it continues.
There are four basic debugging methods that you can configure by using boot parameters:

Single-computer (local) debugging

Debugging with a null-modem cable
Debugging with an IEEE 1394 cable (only if the target computer and the host computer are both running Microsoft Windows XP or a later version of Windows)
Debugging with a USB 2.0 debug cable (only if the target computer is running Windows Vista or a later version of Windows and the host computer is running
Windows 2000 or a later version of Windows)

Boot Parameters for Local Debugging in Operating Systems Prior to Windows Vista
To enable kernel debugging on a single computer, add the /debug parameter to a boot entry. Do not add any other debugging-related parameters to a boot entry.
The first boot entry in the following sample Boot.ini file includes the /debug parameter.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Local Debugging" /fastdetect /debug
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
The following Bootcfg command enables local debugging. The Bootcfg /debug switch, with a value of ON, adds the /debug parameter to a boot entry. The /ID switch
identifies the boot entry.
bootcfg /debug ON /ID 1
The following sample Bootcfg display of a system with a Boot.ini file shows the result. The first boot entry is configured for local debugging.
Boot Entries
------------

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 49 of 1651

Boot entry ID:

OS Friendly Name:
Path:
OS Load Options:

1
Windows XP Local Debugging
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
/fastdetect /debug

Boot entry ID:

OS Friendly Name:
Path:
OS Load Options:

2
Microsoft Windows XP
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
/fastdetect

Boot Option for Local Debugging in Windows Vista and Later

To enable kernel debugging on a single computer, use the BCDEdit /debug boot option.
To use BCDEdit, open a Command Prompt window with elevated privileges (right click Command Prompt and click Run as administrator from the shortcut menu).
The /debug option has the following syntax:
bcdedit /debug [{ID}] { on | off }
The {ID} is the GUID associated with a boot entry. If an {ID} is not specified, the settings apply to the current boot entry. The following command enables kernel debugging
for the current Windows operating system boot entry:
bcdedit /debug on
The following command enables kernel debugging for the specified Windows operating system boot entry:
bcdedit /debug

{18b123cd-2bf6-11db-bfae-00e018e2b8db} on

You can use the bcdedit /enum command to view the current boot entries, their settings, and to identify the GUID associated with each entry.
For more details, see BCDEdit /debug.
Boot Parameters to Debug with a Null-modem Cable in Operating Systems prior to Windows Vista
To enable debugging with a null-modem cable, add the /debug parameter with the /debugport and /baudrate subparameters to a boot entry.
The first boot entry in the following sample Boot.ini file is configured for debugging with a null modem cable.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Debugging with Cable" /fastdetect /debug /debugport=COM1 /baudrate=57600
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
Set the value of the /debugport subparameter to a COM port on the computer. Set the value of the /baudrate subparameter to the connection speed of the cable. (19200 bits
per second is the default.)
The following Bootcfg command enables debugging on the first boot entry. It sets the debugging port to COM1, and it sets the baud rate to 57,600 BPS.
The Bootcfg /debug switch with a value of ON adds the /debug parameter to the boot entry. The Bootcfg /port switch adds the /debugport subparameter with a value of
COM1. The Bootcfg /baud switch adds the /baudrate subparameter with a value of 57600. The /ID switch identifies the boot entry.
bootcfg /debug ON /port COM1 /baud 57600 /ID 1
The following Bootcfg sample shows the resulting boot entry on an Itanium-based system. The newly added parameters are displayed in bold type.

Boot Entries
-----------Boot entry ID:
OS Friendly Name:
OsLoadOptions:
BootFilePath:
OsFilePath:

1
Windows Server 2003, Enterprise
/debug /debugport=COM1 /baudrate=57600
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi
\Device\HarddiskVolume3\WINDOWS

Boot Options to Debug with a Null-modem Cable in Windows Vista and Later
To enable debugging with a null-modem cable in Windows Vista and later, use BCDEdit and set the debugging connection type to "SERIAL". You can set this globally by
using the BCDEdit /dbgsettings command followed by serial, or set it for a specific boot entry by using the BCDEdit /set command followed by debugtype serial. You
must also use the BCDEdit /debug command to enable kernel debugging globally or for the desired operating system.
If BCDEdit has not been used, the default global debug settings are for serial communications, using COM1 and a baud rate of 115,200.
To display the current settings, use the following command:
bcdedit /dbgsettings
debugtype
debugport

Serial
1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

baudrate

Page 50 of 1651

115200

To use BCDEdit, open a Command Prompt window with elevated privileges (right click Command Prompt and click Run as administrator from the shortcut menu).
To set the global debug settings to serial communications, use the following syntax:
bcdedit /dbgsettings serial [DEBUGPORT:port] [BAUDRATE:baud]
The following example shows how to specify serial communications as the global debug setting.
bcdedit /dbgsettings serial debugport:1 baudrate:115200
To set the debug settings to serial for a specific boot entry, or for the current entry, use the following syntax:
bcdedit /set [{ID}] [ debugtype serial | [DEBUGPORT port] | [BAUDRATE baud] ]
If no {ID} is specified, the settings apply to the currently active boot entry.
The following example shows how to specify the serial debug settings for a specific boot entry.
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype serial
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugport 1
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} baudrate 115200
You can use the bcdedit /enum command to view the current boot entries and their settings.
For more details, see BCDEdit /debug and BCDEdit /dbgsettings.
Boot Parameters to Debug with a 1394 Cable in Operating Systems prior to Windows Vista
If your host computer and target computer are both running Windows XP or later, you can perform kernel debugging with an IEEE 1394 (FireWire) cable.
To enable debugging with an IEEE 1394 cable, add the /debug parameter with the /debugport and /channel subparameters to a boot entry. Set the value of the /debugport
subparameter to 1394. Set the value of the /channel subparameter to the cable channel.
The first boot entry in the following sample Boot.ini file is configured for debugging with a 1394 cable.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Debugging with 1394" /fastdetect /debug /debugport=1394 /channel=44
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
The following Bootcfg command enables debugging with a 1394 cable and sets the debugging channel to 44. The /dbg1394 switch with a value of ON adds the /debug
parameter and /debugport=1394 subparameter to the boot entry, and the /ch switch adds the /channel subparameter to the boot entry. The /id switch identifies the second
boot entry.
bootcfg /dbg1394 ON /ch 44 /id 2
The following Bootcfg displays shows the result of the command on a system with a Boot.ini file. The newly added parameters are displayed in bold type. The computer now
has boot options for both a nondebug startup of Windows XP and a startup that enables debugging with a 1394 cable. The nondebugging startup is the default.
Boot Entries
-----------Boot entry ID:
Friendly Name:
Path:
OS Load Options:

1
"Microsoft Windows XP Professional"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
/fastdetect

Boot entry ID:

Friendly Name:
Path:
OS Load Options:

2
"1394 Debug Windows XP"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
/fastdetect /debug /debugport=1394 /channel=44

Note Before performing kernel debugging over a 1394 cable, you must properly configure the software on both the target and the host. See Disabling the 1394 Host
Controller and Installing the 1394 Virtual Driver for details.
Boot Parameters to Debug with a 1394 Cable in Windows Vista and Later
To enable debugging with an IEEE 1394 cable in Windows Vista and later, use BCDEdit and set the debugging connection type to "1394". You can set this globally by using
the BCDEdit /dbgsettings command followed by 1394, or set it for a specific boot entry by using the BCDEdit /set command followed by debugtype 1394. You must also
use the BCDEdit /debug command to enable kernel debugging globally or for the desired operating system.
To use BCDEdit, open a Command Prompt window with elevated privileges (right click Command Prompt and click Run as administrator from the shortcut menu).
To set the debug settings for 1394 globally, use the following syntax:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 51 of 1651

bcdedit /dbgsettings 1394 [channel:channel]

The following example shows how to specify 1394 as the global debug setting.
bcdedit /dbgsettings 1394 channel:32
To set the debug settings to serial for a specific boot entry, or for the current entry, use the following syntax:
bcdedit /set [{ID}] [ debugtype 1394 | channel channel ]
If an {ID} is not specified, the settings apply to the current boot entry.
The following example shows how to specify the 1394 debug settings for a specific boot entry, and how to use the /debug option to enable kernel debugging for that boot
entry.
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype 1394
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} channel 32
bcdedit /debug {18b123cd-2bf6-11db-bfae-00e018e2b8db} on
You can use the bcdedit /enum command to view the current boot entries and their settings.
For more details, see BCDEdit /debug and BCDEdit /dbgsettings.
Boot Parameters to Debug with a USB 2.0 Debugging Cable in Operating Systems prior to Windows Vista
Debugging with a USB 2.0 debugging cable is not supported on a target computer running a version of Windows prior to Windows Vista.
Boot Parameters to Debug with a USB 2.0 Debugging Cable in Windows Vista and Later
If your target computer is running Windows Vista or later, and your host computer is running Windows 2000 or later, you can perform kernel debugging with a USB 2.0
debugging cable.
To enable debugging with a USB cable in these versions of Windows, use BCDEdit and set the debugging connection type to "USB". You can set this globally by using the
BCDEdit /dbgsettings command followed by usb, or set it for a specific boot entry by using the BCDEdit /set command followed by debugtype usb. You must also use the
BCDEdit /debug command to enable kernel debugging globally or for the desired operating system.
To use BCDEdit, open a Command Prompt window with elevated privileges (right click Command Prompt and click Run as administrator from the shortcut menu).
To set the debug settings for USB globally, use the following syntax:
bcdedit /dbgsettings usb [targetname:targetname]
The following example shows how to specify USB as the global debug setting.
bcdedit /dbgsettings usb targetname:U1
To set the debug settings to serial for a specific boot entry, or for the current entry, use the following syntax:
bcdedit /set [{ID}] [ debugtype usb | targetname targetname ]
If no {ID} is specified, the settings apply to the current boot entry.
The following example shows how to specify the USB debug settings for a specific boot entry, and how to use the /debug command to enable kernel debugging for that boot
entry.
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} debugtype usb
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} targetname u2
bcdedit /debug {18b123cd-2bf6-11db-bfae-00e018e2b8db} on
You can use the bcdedit /enum command to view the current boot entries and their settings.
For more details, see BCDEdit /debug and BCDEdit /dbgsettings.
Boot Parameters to Debug the Boot Process in Windows Vista and Later
If your target computer is running Windows Vista or later, and your host computer is running Windows 2000 or later, you can perform boot debugging of one of the boot
components.
To enable boot debugging, use the BCDEdit /bootdebug command and specify the appropriate boot component. If you wish to perform kernel debugging after Windows
starts, use the BCDEdit /debug command as well.
You must also select a debugging connection (serial, 1394, or USB 2.0). This can be done with either the BCDEdit /dbgsettings or BCDEdit /set command, just as in normal
kernel debugging. command to enable debugging.
For more details, see BCDEdit /bootdebug.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 52 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Manipulate Memory

You can simulate a low-memory environment for testing without changing the amount of physical memory on the computer. Instead, you can limit the memory available to
the operating system by using the /burnmemory and /maxmem boot parameters in Windows Server 2003 and Windows XP, and by using truncatememory or
removememory options with the BCDedit /set command on Windows Vista and later.
The /burnmemory parameter, which is available on Windows Server 2003 and Windows XP, reduces the memory available to Windows by the specified amount. It is
calibrated in megabytes (MB). Set the value to any amount less than the actual physical memory on the computer.
The /maxmem parameter specifies the maximum amount of memory available to Windows. It is calibrated in megabytes (MB). Set the value to any amount less than the
actual physical memory on the computer.
The /maxmem parameter actually determines the largest memory address available to Windows. Due to gaps in the mapping of physical memory, Windows might receive
somewhat less memory than the value of /maxmem. For more precision, use /burnmemory.
The truncatememory or removememory options are available on Windows Vista and later. The truncatememory option disregards all memory at or above the specified
physical address. The removememory option reduces memory available to Windows by the specified amount (measured in MB). Both options reduce memory, but the
removememory option is better at restricting the operating system to use the specified memory while accounting for memory gaps.
Boot Parameters to Test in a Low-memory Environment in Operating Systems prior to Windows Vista
To simulate a low-memory environment on Windows Server 2003 and Windows XP, add the /burnmemory parameter to a boot entry. Set its value to the amount of physical
memory on the system minus the desired memory size for this test.
For example, to limit the memory of a computer with 1 GB of physical memory to a maximum of 128 MB of available memory, set the value of the /burnmemory parameter
to 896 (1 GB (1024 MB) - 128 MB = 896 MB).
The first boot entry in the following sample Boot.ini file has the /burnmemory parameter.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Low Memory" /fastdetect /burnmemory=896
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
To add the /burnmemory parameter to a boot entry, use Bootcfg. Because Bootcfg does not have a parameter-specific switch for /burnmemory, use the Bootcfg /raw
switch, which allows you to specify any boot parameter for a boot entry.
In the following Bootcfg command, the /raw switch adds the content of the string, "/burnmemory=896" to a boot entry. The /A switch directs Bootcfg to append the string
to the entry, rather than replacing all boot parameters for the entry. The /ID switch identifies the boot entry.
bootcfg /raw "/burnmemory=896" /A /ID 1
The following Bootcfg display shows the result of the command on a system with a Boot.ini file.
Boot Entries
-----------Boot entry ID:
Friendly Name:
Path:
OS Load Options:

1
"Microsoft Windows XP Professional"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
/fastdetect /burnmemory=896

Boot Parameters to Test in a Low-memory Environment in Windows Vista and Later

To simulate a low-memory environment on Windows Vista and later, use the BCDedit /set command and the removememory option to modify a boot entry. Set the value of
removememory to the amount of physical memory on the system minus the desired memory size for this test.
For example, to limit the memory of a computer with 2 GB of physical memory to a maximum of 512 MB of available memory, set the value of the removememory
parameter to 1536 (1 GB (2048 MB) - 512 MB = 1536 MB).
The following example shows a BCDEdit command used to remove 1536 MB of memory from the total available to the system for the specified boot entry.
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} removememory 1536
You can also use the truncatememory option with the bcdedit /set command to achieve the same result. When you use this option, Windows ignores all memory at or above
the specified physical address. Specify the address in bytes. For example, the following command sets the physical address limit at 1 GB for the specified boot entry. You can
specify the address in decimal (1073741824) or hexadecimal (0x40000000).
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} truncatememory Ox40000000
Because the removememory option makes more efficient use of system memory, its use is recommended instead of truncatememory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 53 of 1651

Boot parameters to debug in a low-memory environment in operating systems prior to Windows Vista
To simulate a low-memory environment on Windows 2000, add the /maxmem parameter to a boot entry. Set its value to the desired memory size for the test.
The first boot entry in the following sample Boot.ini file includes the /maxmem parameter.
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Low Memory" /fastdetect /maxmem=128
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
In this example, the /maxmem parameter is used to limit Windows to 128 MB of memory and the computer is configured for debugging with a debug (null modem) cable.
This configuration requires two Bootcfg commands.
The first Bootcfg command uses the Bootcfg /addsw (add switch) switch with the /MM argument and a value of 128 to add the /maxmem parameter and to set it to a value of
128 (MB). The /ID switch identifies the boot entry.
bootcfg /addsw /MM 128 /ID 1
The second Bootcfg command uses the Bootcfg /debug switch with a value of ON to add the /debug parameter to the boot entry. It uses the /port switch with a value of
COM1 to add the /debugport parameter and to set it to COM1, and it uses the /baud switch with a value of 19200 to add the /baudrate parameter and set it to 19,200 BPS.
The /ID parameter identifies the boot entry.
bootcfg /debug ON /port COM1 /baud 19200 /ID 1
The following Bootcfg sample shows the resulting boot entry. The newly added parameters are displayed in bold type.
Boot Entries
-----------Boot entry ID:
Friendly Name:
Path:
OS Load Options:

1
"Windows XP 128MB Debug"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
/fastdetect /maxmem=128 /debug /debugport=COM1 /baudrate=19200

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Load a Partial Checked Build

A partial checked build contains checked build versions of the kernel and HAL and a free build of the remainder of the operating system. For details, see Installing Just the
Checked Operating System and HAL (For Windows XP and Windows Server 2003) and Installing Just the Checked Operating System and HAL (For Windows Vista and
Later) in the Windows Driver Kit (WDK) documentation.
Configuring a Partial Checked Build in Operating Systems prior to Windows Vista
To configure a partial checked build on Windows 2000, Windows XP, or Windows Server 2003, add the /kernel and /hal parameters to a boot entry. Because Bootcfg does
not have a parameter-specific switch to add the /kernel and /hal parameters, use the Bootcfg /raw switch, which allows you to specify any boot parameters for a boot entry.
The first boot entry in the following sample Boot.ini file loads a partial checked build of Windows XP .
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Partial Checked Build" /fastdetect /kernel=ntoskrnl.chk /hal=halacpi.chk
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect
In the following Bootcfg command, the /raw switch adds the content of the string "/kernel=ntoskrnl.chk /hal=halacpi.chk" to a boot entry. The /A switch directs Bootcfg
to append the string to the entry, rather than replacing the parameters for the entry. The /ID switch identifies the boot entry.
Without /A, the specified parameters would replace all parameters in the second boot entry in this case, /fastdetect.
bootcfg /raw "/kernel=ntoskrnl.chk /hal=halacpi.chk" /A /id 1
The following Bootcfg display of boot options in EFI NVRAM shows the result of the command. The parameters that the command added are displayed in bold type.
Boot Options
-----------Timeout: 30
Default: \Device\HarddiskVolume3\WINDOWS
CurrentBootEntryID: 1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 54 of 1651

Boot Entries
-----------Boot entry ID: 1
OS Friendly Name: Windows Server 2003, Enterprise
OsLoadOptions: /fastdetect /kernel=ntoskrnl.chk /hal=halacpi.chk
BootFilePath: Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi
OsFilePath: \Device\HarddiskVolume3\WINDOWS
Configuring a Partial Checked Build in Windows Vista and Later
To configure a partial checked build on Windows Vista and later, use the BCDedit /set command and the kernel and hal options.
The following commands configure a boot entry to use the checked versions of the kernel and hardware abstraction layer (HAL).
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} kernel ntoskrnl.chk
bcdedit /set {18b123cd-2bf6-11db-bfae-00e018e2b8db} hal halacpi.chk
To view the results of the commands, type bcdedit /enum. The /enum option lists all of the boot entries. The boot entry that has been modified to use the checked versions of
the kernel and HAL has also been configured for kernel debugging over a serial connection.
Windows Boot Loader
------------------identifier
device
path
description
locale
inherit
debugtype
debugport
baudrate
osdevice
systemroot
kernel
hal
resumeobject
nx
debug

{18b123cd-2bf6-11db-bfae-00e018e2b8db}
partition=C:
\Windows\system32\winload.exe
PartialCheckedBuild
en-US
{bootloadersettings}
serial
1
115200
partition=C:
\Windows
ntoskrnl.chk
halacpi.chk
{d7094401-2641-11db-baba-00e018e2b8db}
OptIn
Yes

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Enable EMS Redirection

Emergency Management Services (EMS) technology allows you to control the selected components of servers remotely, even when a server is not connected to the network
or to other standard remote-administration tools. EMS is supported on all versions of Windows Server 2003 operating systems for x86-, x64-, and Itanium-based computers.
For more information about EMS, search for Emergency Management Services on the

Microsoft TechNet Web site.

Notes This topic explains how to enable EMS on computers running Windows Server 2003. The boot parameters described in this section are not supported on Windows
Vista or later versions of Windows.
When a boot entry is configured for EMS on a computer with BIOS firmware, the boot loader appends a bracketed phrase, [ems enabled], to the friendly name that appears on
the boot menu. However, the boot loader omits the bracketed phrase from the boot menu when the friendly name and the bracketed phrase together exceed 70 characters. To
restore the bracketed phrase, shorten the friendly name.
To determine whether a computer has ACPI firmware, use Device Manager (devmgmt.msc). In Device Manager, expand the Computer node. On computers with ACPI
firmware, the name of node under Computer includes the word, ACPI.
Enabling EMS on a computer without an ACPI SPCR table in operating systems prior to Windows Server 2008
To enable EMS console redirection on a computer that has BIOS firmware, but does not have an ACPI Serial Port Console Redirection (SPCR) table, add the
redirect=COMx and the redirectbaudrate= parameters to the [boot loader] section of the Boot.ini file. These parameters set the port and transmission rate for EMS console
redirection. Use the same port and transmission rate that are established for out-of-band communication in the BIOS. Then, add the /redirect parameter to a boot entry.
The following Bootcfg command enables EMS console redirection on the first boot entry in the list. It sets the port for COM2 and sets the transmission rate to 115,200
kilobits per second (Kbps). These are the same port and baud rate settings that the administrator set in the BIOS for the out-of-band port.
bootcfg /ems ON /port COM2 /baud 115200 /id 1
The following Bootcfg display shows the result of the command. The newly added parameters are displayed in bold type.
Boot Loader Settings
--------------------

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

timeout:
default:
redirect:
redirectbaudrate:
Boot Entries
-----------Boot entry ID:
Friendly Name:
Path:
OS Load Options:

Page 55 of 1651

3
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
COM2
115200

1
"Windows Server 2003, Standard with EMS"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
/fastdetect /redirect

The following sample shows the result of the same command on a sample Boot.ini file.
[boot loader]
timeout=1
default=multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
redirect=COM2
redirectbaudrate=115200
[operating systems]
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="EMS boot" /fastdetect /redirect
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="Windows Server 2003, Standard" /fastdetect
Enabling EMS on a Computer without an ACPI SPCR Table in Windows Server 2008
To enable EMS console redirection on a computer that has BIOS firmware, but does not have an ACPI Serial Port Console Redirection (SPCR) table, use the
BCDEdit /emssettings command to set the COM port and baud rate.
These parameters set the global port and transmission rate for EMS console redirection. Use the same port and transmission rate that are established for out-of-band
communication in the BIOS.
Then, use the BCDEdit /ems command to enable EMS for a boot entry.
The following commands set the global EMS redirection settings to use COM2 and a baud rate of 115200, and enable EMS for the specified boot entry.
bcdedit /emssettings EMSPORT:2 EMSBAUDRATE:115200
bcdedit /ems {18b123cd-2bf6-11db-bfae-00e018e2b8db} on
Enabling EMS on a computer with an SPCR table in operating systems prior to Windows Server 2008
To enable EMS on a computer with ACPI BIOS firmware and an ACPI SPCR table, you can either use the redirect=USEBIOSSETTINGS parameter or the
redirect=COMx and redirectbaudrate= parameters. Then, you can add the /redirect parameter to a boot entry.
The following example demonstrates use of the redirect=USEBIOSSETTINGS parameter. The following Bootcfg command enables EMS console redirection on the first
boot entry in the list.
bootcfg /ems ON /port BIOSSET /id 1
The following Bootcfg display shows the result of the command. The newly added parameters are displayed in bold type.
Boot Loader Settings
-------------------timeout: 1
default: multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
redirect:USEBIOSSETTINGS
Boot Entries
-----------Boot entry ID:
OS Friendly Name:
Path:
OS Load Options:

1
EMS boot
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
/fastdetect /redirect

Boot entry ID:

OS Friendly Name:
Path:
OS Load Options:

2
Windows Server 2003, Standard
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS
/fastdetect

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 56 of 1651

To enable EMS on a computer with ACPI BIOS firmware and an ACPI SPCR table, you can use the BCDEdit /emssettings and specify either the BIOS parameter or the
emsport and emsbaudrate parameters. To enable EMS for a boot entry, use the BCDEdit /ems command.
The following example demonstrates how to use the BIOS parameter. The following BCDEdit command enables EMS console redirection on the current boot entry.
bcdedit /emssettings bios
bcdedit /ems on
Enabling EMS on a computer with EFI firmware in operating systems prior to Windows Server 2008
To enable EMS on a computer with EFI firmware, use Bootcfg to add the /redirect parameter to a boot entry. Windows finds the out-of-band port and its settings in the
firmware by reading the SPCR table and uses the same port and rate for EMS console redirection.
The following Bootcfg command enables EMS redirection on an Itanium-based computer. It uses the Bootcfg /ems switch with the ON argument to add the /redirect
parameter to the boot entry. The /id switch identifies the boot entry.
bootcfg /ems ON /id 1
The following Bootcfg display of boot options in EFI NVRAM shows the result of the Bootcfg command. The first boot entry is configured to load the operating system with
EMS console redirection enabled.
Boot Options
-----------Timeout:
Default:
CurrentBootEntryID:
Boot Entries
-----------Boot entry ID:
OS Friendly Name:
OsLoadOptions:
BootFilePath:
OsFilePath:

30
\Device\HarddiskVolume3\WINDOWS
1

1
Windows Server 2003, Enterprise with EMS
/fastdetect /redirect
\Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi
\Device\HarddiskVolume3\WINDOWS

Enabling EMS on a Computer with EFI Firmware in Windows Server 2008

To enable EMS on a computer with EFI firmware, use the BCDEdit /ems command and specify a boot entry. Windows finds the out-of-band port and its settings in the
firmware by reading the SPCR table and uses the same port and rate for EMS console redirection.
The following command enables EMS console redirection on the specified boot entry that has the identifier of {18b123cd-2bf6-11db-bfae-00e018e2b8db}.
bcdedit /ems {18b123cd-2bf6-11db-bfae-00e018e2b8db} on
Changing EMS Settings on a Computer with BIOS Firmware in Operating Systems prior to Windows Server 2008
When you configure EMS on a single boot entry, add the redirect= parameter to the [boot loader] section of the Boot.ini file. However, when you enable EMS on additional
boot entries, you do not need to add the redirect= parameter again. Like all entries in the [boot loader] section, redirect= (and redirectbaudrate=) applies to all boot entries
on the computer.
The following Bootcfg command enables EMS on the second boot entry. Because the port and baud rate are already set, there are no /port or /baud switches in the command.
bootcfg /ems ON /id 2
To change the port and baud rate settings, use the Bootcfg /ems switch with the EDIT argument. The following command changes the EMS port to COM1 and changes the
baud rate to 57,600 Kbps.
bootcfg /ems EDIT /port COM1 /baud 57600
To disable EMS on a boot entry, use the Bootcfg /ems switch with the OFF argument. The following command disables EMS on the first boot entry.
bootcfg /ems OFF /id 1
If EMS is not enabled on any other boot entries, Bootcfg also deletes the EMS port and baud rate settings from the [boot loader] section of the Boot.ini file.
Changing EMS Settings on a Computer running Windows Server 2008
When you configure EMS on a boot entry on a computer that has ACPI BIOS firmware and an ACPI SPCR table, you can use the BCDEdit /emssettings command and
specify either the BIOS option or the emsport and emsbaudrate options. If you use the BIOS option, do not set the emsport or emsbaudrate options.
When you configure EMS on a computer that has EFI firmware, or with ACPI BIOS firmware and without an ACPI SPCR table, you can use the BCDEdit /emssettings
command and specify the emsport and emsbaudrate options.
The emsport and emsbaudrate options set the serial port and transmission rate for EMS console redirection. These settings apply to all boot entries on the computer. To use
emsbaudrate, you must also set the emsport option. By default, the transmission rate is set to 9600 (9,600 Kbps).
For example, the following command changes the EMS port to COM2 and changes the baud to 57,600 Kbps.
bcdedit /emssettings EMSPORT:2 EMSBAUDRATE:57600
To enable or disable EMS on a boot entry, use the BCDEdit /ems command.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 57 of 1651

For example, the following command enables EMS on a specific boot entry that has an identifier of {173075c9-2cb2-11dc-b426-001558c41f5c}..
bcdedit /ems {173075c9-2cb2-11dc-b426-001558c41f5c} on
To disable EMS on the current boot entry, use the following command.
bcdedit /ems off
Note Each boot entry uses a GUID as an identifier. If you do not specify an identifier, the BCDEdit command modifies the current operating system boot entry. If a boot
entry is specified, the GUID associated with the boot entry must be enclosed in braces { }. To view the GUID identifiers for all the active boot entries, use the bcdedit /enum
command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Configure DEP and PAE

This topic explains how to use boot parameters to enable, disable, and configure Data Execution Prevention (DEP) and Physical Address Extension (PAE) on operating
systems that support these features.
For information about the boot parameters for DEP on operating systems prior to Windows Vista, including operating system support and the default values of the parameters,
see /noexecute and /execute. For similar information about PAE, see /pae and /nopae.
For information about the boot parameters for DEP and PAE on Windows Vista and later, see the BCDEdit /set command and the nx and pae options.
Important DEP is a highly effective security feature that should not be disabled unless you have no alternative. The default settings for DEP and PAE are optimal for most
systems. Do not change the default settings unless they interfere with essential processing tasks. This section is included to show you how to configure these features, but it
should not be interpreted as a recommendation to change the default settings.
DEP and PAE Boot Parameters
On operating systems prior to Windows Vista, DEP and PAE are enabled at boot time and are configured by using the following four boot parameters:

/noexecute enables and configures DEP.

/execute disables DEP and PAE.
/pae enables PAE.
/nopae disables PAE.

On Windows Vista and later, DEP and PAE are enabled at boot time and are configured by setting values for the nx and pae parameters using the BCDEdit /set command.
These boot parameters have conflicting effects. To configure DEP and PAE, use only the parameter combinations that are described in the documentation for each parameter
and discussed in this topic. Do not experiment with conflicting parameters, especially on a production system.
The Interaction of DEP and PAE Boot Parameters
There are two types of DEP:

Hardware-enforced DEP enables DEP for both kernel-mode and user-mode processes. It must be supported by the processor and the operating system.

Software-enforced DEP enables DEP only on user-mode processes. It must be supported by the operating system.

DEP is supported by Windows XP with SP2, Windows Server 2003 with SP1, Windows Vista, and later versions of Windows.
On 32-bit versions of Windows, hardware-enforced DEP requires PAE, which is supported by all Windows operating systems that support DEP. When DEP is enabled on a
computer with a processor that supports hardware-enforced DEP, Windows automatically enables PAE and ignores the boot parameter values that disable it.
The parameter combinations for each Windows operating system are summarized in the following section.
DEP and PAE Parameter Combinations
The following list describes the boot parameter combinations that can be used to configure DEP and PAE.
Note In the examples for Windows Vista and later, the optional {ID} is the GUID for the specific Windows boot loader boot entry that you want to configure. If you do not
specify an {ID}, the command modifies the current operating system boot entry. For more information, see the BCDEdit /set command .
Action
To enable DEP
(Select one parameter combination)

Prior to Windows Vista

/noexecute=alwayson
/noexecute=optin
/noexecute=optout

(Select one parameter combination)

/set [{ID}] nx OptIn

/set [{ID}] nx OptOut

When DEP is enabled on computers that support hardware-enforced DEP, these parameter
combinations also enable PAE.
To enable DEP and PAE on systems with software-enforced DEP

Windows Vista and later

/set [{ID}] nx AlwaysOn

/noexecute=alwayson /pae
/noexecute=optin /pae
/noexecute=optout /pae

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

/set [{ID}] nx AlwaysOn

/set [{ID}] pae default

9/18/2010

Introduction

Page 58 of 1651

On computers that support hardware-enforced DEP, PAE is automatically enabled when you enable
DEP.
/set [{ID}] nx OptIn
/set [{ID}] pae default

/set [{ID}] nx OptOut

/set [{ID}] pae default
To disable DEP, but enable PAE

To disable DEP, but enable PAE

/noexecute=alwaysoff /pae

/set [{ID}] nx AlwaysOff

(Windows XP with SP2)

/set [{ID}] pae

ForceEnable

/noexecute=alwayoff
/noexecute=alwaysoff /pae

/set [{ID}] nx AlwaysOff

(Windows Server 2003 with SP1 only)

/set [{ID}] pae

ForceEnable

(These parameter combinations are

equivalent.)
To disable both DEP and PAE

/noexecute=alwaysoff
/noexecute=alwaysoff /nopae
(Windows XP with SP2)

/set [{ID}] nx AlwaysOff

/set [{ID}] pae
ForceDisable

(These parameter combinations are

equivalent.)
To disable both DEP and PAE

/execute
(Windows Server 2003 with SP1 only)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Boot Parameters to Test Drivers for Multiple Processor Group Support

[This is preliminary documentation and subject to change.]
Windows 7 and Windows Server 2008 R2 provide support for computers with more than 64 processors. This support is made possible by introducing Processor groups. For
testing purposes, you can configure any computer that has multiple logical processors to have multiple processor groups by limiting the group size. This means you can test
drivers and components for multiple processor group compatibility on computers that have 64 or fewer logical processors.
Note The concept of processor groups, introduced with Windows 7, allows existing APIs and DDIs to continue to work on computers with more than 64 logical processors.
Typically, a groups processors are represented by an affinity mask, which is 64 bits long. Any computer with more than 64 logical processors will necessarily have more than
one group.
When a process is created, the process is assigned to a specific group. By default, threads of the process can run on all logical processors of the same group, although the
thread affinity can be explicitly changed. Calls to any API or DDI that takes an affinity mask or processor number as an argument, but not a group number, is limited to
affecting or reporting on those processors in the calling threads group. The same is true of APIs or DDIs that return an affinity mask or processor number, like
GetSystemInfo.
Starting with Windows 7, an application or driver can make use of functions that extend the legacy APIs. These new group-aware functions accept a group number argument
to unambiguously qualify a processor number or affinity mask, and therefore can manipulate processors outside of the calling threads group. The interaction between drivers
and components running in different groups within a computer introduces the potential for bugs when legacy APIs or DDIs are involved. You can use the legacy non-groupaware APIs on Windows 7 and Windows Server 2008 R2. However, driver requirements are more stringent. For functional correctness of drivers on computers that have more
than one processor group, you must replace any DDI that either accepts a processor number or mask as a parameter without an accompanying processor group or returns a
processor number or mask without an accompanying processor group. These legacy non-group-aware DDIs can perform erratically on a computer that has multiple process
groups because the inferred group may be different than what the calling thread intended. Therefore, drivers that use these legacy DDIs and are targeted for Windows Server
2008 R2 must be updated to use the new extended versions of the interfaces. Drivers that do not call any functions that use processor affinity masks or processor numbers will
operate correctly, regardless of the number of processors. Drivers that call the new DDIs can run on previous versions of Windows by including the procgrp.h header, calling
WdmlibProcgrpInitialize, and linking against the Processor Group Compatibility Library (procgrp.lib).
For more information on the new group-aware APIs and DDIs, download the white paper
Developers from WHDC.

Supporting System that Have More than 64 Logical Processors: Guideline for

To help identify potential processor group-related problems in drivers and components, you can use the BCDEdit /set options. The two BCD boot configuration settings,
groupsize and maxgroup, can configure any computer that has multiple logical processors to support multiple processor groups. The groupaware option modifies the

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 59 of 1651

behavior of certain DDIs and manipulates the group environment for testing purposes.
Create Multiple Processor Groups by Changing the Group Size
The groupsize option specifies the maximum number of logical processors in a group. By default, the groupsize option is not set, and any computer with 64 or fewer logical
processors has one group, which is group 0.
Note A physical processor, or processor package, can have one or more cores, or processor units, each of which can contain one or more logical processors. The operating
system considers a logical processor as one logical computing engine.
To create multiple processor groups, run BCDEdit /set in an elevated Command Prompt window and specify a new maxsize value for groupsize that is less than the total
number of logical processors. Note that the group size setting is for testing and you should not configure shipping systems with this setting. The command uses the following
syntax:
bcdedit.exe /set groupsize maxsize
For example, the following command sets the maximum number of processors in a group to 2.
bcdedit.exe /set groupsize 2
If a non-NUMA computer has 8 logical processors, setting the groupsize to 2 creates 4 processor groups with 2 logical processors each.
Group 0: 1 NUMA node containing 1 package of 2 logical processors
Group 1: 1 NUMA node containing 1 package of 2 logical processors
Group 2: 1 NUMA node containing 1 package of 2 logical processors
Group 3: 1 NUMA node containing 1 package of 2 logical processors
By design, a non-NUMA computer is considered to have one NUMA node. Because NUMA nodes cannot span groups, the system creates a node for each group after you
restart the computer.
If groupsize is set to a value less than the number of logical processors in a physical processor package (socket), the system redefines its concept of a package upon restart
such that the package does not span a group. This means that more packages than that are actually present are reported by processor topology APIs. This also means that the
Windows (package-level) processor licensing limits might prevent some processor packages from starting when groupsize is set.
A processor package can span groups if it has multiple NUMA nodes defined within it and the system assigns these nodes to different groups.
Windows limits the number of groups supported. This number could change with new versions of Windows or in service pack releases. Drivers or components should not
depend on the number of groups Windows supports as being constant. The limit on the number of groups could restrict the number of logical processors allowed to start when
small values are used for the groupsize boot option.
To remove the groupsize setting you used for testing and return to the default setting of 64 logical processors per group, use the following BCDEdit command.
bcdedit.exe /deletevalue groupsize
This command is the equivalent of setting groupsize to 64.
Maximize the Number of Processor Groups
The maxgroup option is another way to create processor groups on a computer with multiple logical processors and NUMA nodes. The maxgroup boot option has no effect
on non-NUMA computers.
To maximize the number of groups, run the BCDEdit /set command in an elevated Command Prompt window. The command uses the following syntax:
bcdedit.exe /set maxgroup on
For example, consider a computer that has 2 NUMA nodes, 1 processor package per node, and 4 processor cores per package, for a total of 8 logical processors.
The default group configuration is:
Group 0: 8 logical processors, 2 packages, 2 NUMA nodes
If you enter a bcdedt.exe /set maxgroup on command followed by a restart, the command yields the following group configuration:
Group 0: 4 logical processors, 1 package, 1 NUMA node
Group 1: 4 logical processors, 1 package, 1 NUMA node
Note that NUMA nodes are assigned to groups in a manner that maximizes the number of groups.
To change back to the default the setting, use the following BCDEdit command.
bcdedit.exe /set maxgroup off
Test Multiple-Group Compatibility by Setting the Group Aware Boot Option
Windows 7 and Windows Server 2008 R2 have introduced a new BCD option (groupaware) that forces drivers and components to be aware of multiple groups in a multiple
processor group environment. The groupaware option changes the behavior of a set of device driver functions to help expose cross-group incompatibilities in drivers and
components. You can use the groupaware boot option along with the groupsize and maxgroup options to test driver compatibility with multiple groups when a computer
has 64 or fewer active logical processors.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 60 of 1651

When the groupaware boot option is set, the operating system ensures that processes are started in a group other than group 0. This increases the chances of cross-group
interaction between drivers and components. The option also modifies the behavior of the legacy functions that are not group-aware, KeSetTargetProcessorDpc,
KeSetSystemAffinityThreadEx, and KeRevertToUserAffinityThreadEx, so that they always operate on the highest numbered group that contains active logical
processors. Drivers that call any of these legacy functions should be changed to call their group-aware counterparts (KeSetTargetProcessorDpcEx,
KeSetSystemGroupAffinityThread, and KeRevertToUserGroupAffinityThread),
To test for compatibility, use the following BCDEdit /set command.
bcdedit.exe /set groupaware on
Legacy non-group aware functions Windows 7 group-aware replacement
KeSetTargetProcessorDpc
KeSetTargetProcessorDpcEx
KeSetSystemAffinityThreadEx
KeSetSystemGroupAffinityThread
KeRevertToUserAffinityThreadEx KeRevertToUserGroupAffinityThread
To reset the computer to the default setting, use the following BCDEdit command.
bcdedit.exe /set groupaware off

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bypassing Boot Options

You may encounter a situation in which you need to debug a computer that has not been configured for kernel debugging, but you are unable to edit the boot options.
For example, you may have a computer that encounters a bug check before the login screen is reached, preventing you from editing the Boot.ini file through Windows. You
can start Microsoft MS-DOS from a floppy disk, but if the boot partition of your hard disk is in NTFS format, you will not be able to edit the Boot.ini file from MS-DOS.
If you are unable to edit the boot options directly, restart the computer and wait until the initial BIOS procedures are complete. At this point, if you have multiple operating
systems installed, you will see the boot menu. When this menu appears, press the F8 key. If you do not have multiple boot options, you will not see the boot menu, but you
can still press the F8 key during the first two seconds of the loading of Windows you may find it easiest to just begin pressing F8 repeatedly when the BIOS procedures are
nearly complete and keep pressing it until the menu appears.
Pressing F8 will cause the Troubleshooting and Advanced Startup Options menu to appear. One of the choices on this menu is Debugging Mode. If you select this option,
you will be able to start Windows with kernel debugging support. The kernel debugger connection will be active at a baud rate of 19200 through the highest enumerated COM
port (for example, COM2 if you have two ports).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Disabling the 1394 Host Controller

For kernel debugging to work properly with a IEEE 1394 (FireWire) connection, you might have to disable the 1394 host controller on the target computer or disable the 1394
network adapter on the host computer. The required adjustments vary depending on the operating system on the target computer.
When the target computer is running Microsoft Windows Server 2003 (with no service packs installed) or Windows XP with Service Pack 1 (SP1), you must disable the 1394
host controller on the target computer to perform kernel debugging with a 1394 connection. If the 1394 host controller remains enabled on computers that are running these
operating systems, the core 1394 stack might compete with the 1394 debugging connection for resources. This competition might cause the debugging connection to fail or to
be lost shortly after boot time.
On Windows Vista (any version), Windows Server 2003 with Service Pack 1 (SP1), and Windows XP with Service Pack 2 (SP2), do not disable the host controller on the
target computer. In fact, disabling the host controller while running these operating systems can prevent you from debugging the system during some power state changes.
Do not disable the host controller on the host computer under any circumstances, regardless of the operating system.
If you are having trouble debugging a computer that is running a pre-Windows Vista version of Windows over a 1394 connection, consider disabling the 1394 network
adapter on the host computer. Disabling the 1394 network adapter can resolve issues that result from bus resets that are caused by loading the 1394 network adapter driver. Do
not disable the 1394 network adapter if you are using IP1394. This method does not apply to Windows Vista, because it does not support 1394 network adapters.
To disable the 1394 host controller on the target computer
1. (Windows Server 2003 (with no service packs installed) and Windows XP SP1 only)
2. On the target computer, open Device Manager (that is, click Start, click Run, and then enter Devmgmt.msc).
3. Locate the 1394 host controller. Depending on which view you are using in Device Manager, you can find this controller in different locations. Typically, you can find
it in the tree under the PCI Bus node.
4. Right-click the 1394 host controller, and then click Disable.
5. Restart the target computer.
Be careful not to accidentally disable the 1394 network adapter.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 61 of 1651

To disable the 1394 network adapter on the host computer

1.
2.
3.
4.
5.

(Windows Server 2003 and earlier only)

On the target computer, open Device Manager (that is, click Start, click Run, and then enter Devmgmt.msc).
Expand Network Adapters, and locate 1394 Net Adapter.
Right-click 1394 Net Adapter, and then click Disable.
Restart the target computer.

Note Before performing kernel debugging over a 1394 cable, you must also configure the software on the host computer. For more details, see Installing the 1394 Virtual
Driver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using KDbgCtrl
The KDbgCtrl (Kernel Debugging Control, kdbgctrl.exe) tool can be used to control the kernel debugging connection from the target computer.
To use this tool, your target computer must be running Windows Server 2003 or a later version of Windows.
KDbgCtrl can control four different settings: Full Kernel Debugging, Automatic Kernel Debugging, User-Mode Error Handling, and the size of the DbgPrint buffer.
To use KDbgCtrl, you must have already enabled kernel debugging in the boot settings of the target computer before the last boot. KDbgCtrl cannot be used to enable kernel
debugging if this was not done. See Boot Parameters to Enable Debugging for details on these boot settings.
Full Kernel Debugging
When Full Kernel Debugging is enabled, a kernel debugger running on the host computer can break into the target computer. The target computer will break into the kernel
debugger if a kernel-mode exception is hit. Messages from the target to the host, such as DbgPrint output, symbol load messages, and redirected user-mode debuggers, are
also allowed.
If this setting is disabled, all signals from the host computer will be ignored by the target.
Full Kernel Debugging is enabled by default. To check the current setting value, use kdbgctrl -c. To disable this setting, use kdbgctrl -d. To enable this setting, use kdbgctrl
-e.
If you wish to check the current setting and use it to control execution within a batch file, you can use the kdbgctrl -cx command. For details on this command, see KDbgCtrl
Command-Line Options.
Automatic Kernel Debugging
If Full Kernel Debugging is enabled, the current setting for Automatic Kernel Debugging is immaterial all communication is permitted.
When Full Kernel Debugging is disabled and Automatic Kernel Debugging is enabled, only the target computer can initiate a debugging connection.
In this case, only a kernel-mode exception, breakpoint, or other kernel-mode event will cause a connection to be established. The connection will not be established for
DbgPrint output, symbol load messages, redirected user-mode debugger input and output, or other similar messages these will be stored in the DbgPrint buffer instead of
being sent to the kernel debugger.
If an exception or event causes the target to break into the kernel debugger, then Full Kernel Debugging will be automatically turned on, just as if you had executed kdbgctrl e.
Automatic Kernel Debugging is disabled by default (although this is immaterial unless Full Kernel Debugging is disabled as well). To check the current setting value, use
kdbgctrl -ca. To disable this setting, use kdbgctrl -da. To enable this setting, use kdbgctrl -ea.
User-Mode Error Handling
When User-Mode Error Handling is enabled, some user-mode events will cause the target computer to break into the kernel debugger.
Specifically, all int 3 interrupts such as breakpoints inserted into the code by a debugger or calls to DbgBreakPoint will cause a break into the kernel debugger.
However, standard exceptions such as access violations and division by zero will usually not be sent to the kernel debugger.
If a user-mode debugger is already attached to the process, this debugger will capture all user-mode errors, and the kernel debugger will not be alterted. For the precedence
ranking of the various user-mode error handlers, see Enabling Postmortem Debugging.
For User-Mode Error Handling to function, either Full Kernel Debugging or Automatic Kernel Debugging must be enabled as well.
User-Mode Error Handling is enabled by default. To check the current setting value, use kdbgctrl -cu. To disable this setting, use kdbgctrl -du. To enable this setting, use
kdbgctrl -eu.
The DbgPrint Buffer Size
The DbgPrint buffer stores messages that the target computer has sent to the kernel debugger.
If Full Kernel Debugging is enabled, these messages will automatically appear in the kernel debugger. But if this option is disabled, these messages will be stored in the
buffer. At a later point in time, you can enable kernel debugging, connect to a kernel debugger, and use the !dbgprint extension to see the contents of this buffer. For more
information about this buffer, see The DbgPrint Buffer.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 62 of 1651

The default size of the DbgPrint buffer is 4 KB on a free build of Windows, and 32 KB on a checked build of Windows. To determine the current buffer size, use kdbgctrl cdb. To change the buffer size, use kdbgctrl -sdb Size, where Size specifies the new buffer size. For syntax details, see KDbgCtrl Command-Line Options.
Examples
To display all the current settings, use the following command:
kdbgctrl -c -ca -cu -cdb
To restore the default settings, use the following command:
kdbgctrl -e -da -eu -sdb 0x1000
To lock out the host computer so that it only is contacted on exceptions, use the following command:
kdbgctrl -d -ea -eu
To disable all kernel debugging, use the following command:
kdbgctrl -d -da
If you are disabling all kernel debugging, you may also wish to increase the size of the DbgPrint buffer. This insures that all messages will be saved in case you need to see
them later. If you have a megabyte of memory to spare, you might use the following command:
kdbgctrl -sdb 0x1000000

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Software on the Host Computer

This section includes:
Choosing Kernel Debugging Settings
Installing the 1394 Virtual Driver
Installing Symbol Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Choosing Kernel Debugging Settings

Before you can begin kernel debugging, you must choose your connection settings.
The debuggers support several different kinds of kernel debugging:

Host computer and target computer connected through the COM ports.
Host computer and target computer connected by a 1394 cable. This is supported only if both the host and the target are running Windows XP or later. Before you can
debug over a 1394 cable, you must properly configure the software on both the target and the host. See Disabling the 1394 Host Controller and Installing the 1394
Virtual Driver for details.
Host computer and target computer connected by a USB 2.0 debug cable. This is supported only if the host computer is running Windows, and the target computer is
running Windows Vista or later. Additional configuration is required; see Setting Up a USB 2.0 Debug Cable Connection for details.
Host computer and target computer communicating through a modem.
Debugger and virtual machine (on the same computer or a different computer) communicating through a named pipe.
Local kernel debugging on a single computer. This is supported only on Windows XP and later.

There are three ways to configure the kernel debugging settings: through environment variables, on the debugger command line, or through the WinDbg graphical interface. If
none of these methods are used, the debugger will default to a COM port connection, using COM1 and 19200 baud.
Environment Variables
If you are configuring a COM port connection with environment variables, the following two variables should be used:
set _NT_DEBUG_PORT = ComPort
set _NT_DEBUG_BAUD_RATE = BaudRate
If you are configuring a 1394 connection with environment variables, the following three variables should be used:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 63 of 1651

set _NT_DEBUG_BUS = 1394

set _NT_DEBUG_1394_CHANNEL = 1394Channel
set _NT_DEBUG_1394_SYMLINK = 1394Protocol
Environment variables cannot be used to set up debugging over a USB 2.0 debug cable, debugging over a modem, debugging through a named pipe, or local kernel
debugging.
KD Command Line
If you are using the KD command line, you can specify the connection settings after the -k command-line option. The com:port parameter causes the debugger to connect
through a COM port. The 1394 parameter causes the debugger to connect through a 1394 cable. The usb2 parameter causes the debugger to connect through a USB 2.0 debug
cable. The com:modem parameter causes the debugger to connect through a modem. The com:pipe parameter causes the debugger to connect through a named pipe. The -kl
command-line option starts local kernel debugging. If these parameters are omitted, the environment variable settings or the defaults are used.
kd
kd
kd
kd
kd
kd
kd

...
...
...
...
...
...
...

-k com:port=ComPort,baud=BaudRate ...
-k 1394:channel=1394Channel[,symlink=1394Protocol] ...
-k usb2:targetname=USBString ...
-k com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect] ...
-k com:modem ...
-kl ...

WinDbg Command Line

The WinDbg connection parameters are the same as those for KD. The only difference is that if you wish to use the environment variable settings or the defaults, you still
must specify the -k option.
windbg
windbg
windbg
windbg
windbg
windbg
windbg

...
...
...
...
...
...
...

WinDbg Dialog Box

If WinDbg is already running and is in dormant mode, you can use the File | Kernel Debug menu option to start a new kernel debugging session. A dialog box will appear
with four tabs: COM, 1394, USB 2.0, and Local. Each of them specifies a different connection method:

The COM tab indicates that the connection will use a COM port. In the Baud Rate box, enter the BaudRate. In the Port box, enter the ComPort.
The 1394 tab indicates that the connection will use 1394. In the Channel box, enter the 1394Channel.
The USB 2.0 tab indicates that the connection will use USB 2.0. In the Target Name box, enter the USBString.
The Local tab indicates that WinDbg will perform local kernel debugging. Local kernel debugging is supported only on Windows XP and later versions of Windows.

This dialog box cannot be used to set up debugging over a modem or a named pipe.
Parameters
The parameters used for these environment variables, command line options, and the WinDbg dialog box have the following possible values:
ComPort
Specifies the name of the COM port. This can be in the format "com2" or in the format "\\.\com2", but should not simply be a number.
BaudRate
Specifies the baud rate. This can be 9600, 19200, 38400, 57600, or 115200.
1394Channel
Specifies the 1394 channel number. Valid channel numbers are any integer between 0 and 62, inclusive. 1394Channel must match the number used by the target
computer, but does not depend on the physical 1394 port chosen on the adapter.
Note 1394 kernel debugging is supported only if both the host and the target are running Windows XP or later. Before you can debug over a 1394 cable, you must
properly configure the software on both the target and the host. See Disabling the 1394 Host Controller and Installing the 1394 Virtual Driver for details.
1394Protocol
Specifies the connection protocol to be used for the 1394 kernel connection. This can almost always be omitted, since the debugger will automatically choose the correct
protocol. If you wish to set this manually, and the target computer is running Windows XP, 1394Protocol should be set equal to "channel". If the target computer is
running Windows Server 2003 or later, 1394Protocol should be set equal to "instance". If it is omitted, the debugger will default to the protocol appropriate for the
current target computer. This can only be specified through the command line or the environment variables, not through the WinDbg graphical interface.
USBString
Specifies a USB 2.0 connection string. This must match the string specified with the /targetname boot option. For information on this boot option prior to Windows
Vista, see /debug. For information on this boot option in Windows Vista and later versions of Windows, see BCDEdit / dbgsettings.
Note USB 2.0 kernel debugging is supported only if the host computer is running Windows, and the target computer is running Windows Vista or later. Additional
configuration is required; see Setting Up a USB 2.0 Debug Cable Connection for details.
VMHost
When debugging a virtual machine, VMHost specifies the name of the physical computer on which the virtual machine is running. The virtual machine documentation
usually refers to this as the virtual machine host. If the virtual machine is running on the same computer as the kernel debugger itself, use a single period (.) for VMHost.
PipeName
Specifies the name of the pipe created by the virtual machine for the debugging connection.
resets=0
Specifies that an unlimited number of reset packets can be sent to the target when the host and target are synchronizing. This parameter is only needed when debugging
certain kinds of virtual machines. See Attaching to a Virtual Machine (Kernel Mode) for details.
reconnect

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 64 of 1651

Causes the debugger to automatically disconnect and reconnect the pipe if a read/write failure occurs. Additionally, if the named pipe is not found when the debugger is
started, the reconnect parameter will cause it to wait for a pipe of this name to appear. This parameter is only needed when debugging certain kinds of virtual machines.
See Attaching to a Virtual Machine (Kernel Mode) for details.
modem
Causes the debugger to connect through a modem.
-kl
Causes the debugger to perform local kernel debugging. Only users that have debug privileges can start this process. For local kernel debugging to work, the x86 boot.ini
file or the Itanium OsLoadOptions settings must include the /debug option. See Performing Local Kernel Debugging for features peculiar to this technique.
For a list of other useful environment variables and command line options, see Environment Variables and Command-Line Options.
Examples
The following batch file could be used to set up a COM connection:
set
set
set
set
kd

_NT_SYMBOL_PATH=d:\mysymbols
_NT_DEBUG_PORT=com1
_NT_DEBUG_BAUD_RATE=19200
_NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log

The following batch file could be used with a 1394 connection:

set _NT_SYMBOL_PATH=d:\mysymbols
set _NT_DEBUG_BUS=1394
set _NT_DEBUG_1394_CHANNEL=44
set _NT_DEBUG_LOG_FILE_OPEN=d:\debuggers\logfile1.log
windbg -k
The following command lines would each start KD, without any environment variables:
kd -y d:\mysymbols -k com:modem
kd -y d:\mysymbols -k com:port=com2,baud=57600
kd -y d:\mysymbols -k com:port=\\.\com2,baud=115200
kd -y d:\mysymbols -k 1394:channel=20,symlink=instance

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing the 1394 Virtual Driver

If you are debugging over a 1394 connection, the debugger will install a 1394 virtual driver that allows the debugger to communicate with the target computer.
There are three stages to this installation:
1. When the debugger package is installed on your system, it places certain files in the 1394 subdirectory of the debugger installation directory.
2. The first time you start a kernel debugging session over a 1394 connection, the debugger will perform a pre-installation of the 1394 virtual drivers.
3. If this pre-installation is successful, the debugger will call the bus driver. The bus driver will then complete the installation process.
During steps 2 and 3, you must be logged in as Administrator on the host computer, since only Administrator can install new drivers.
There are two different 1394 drivers: one for target computers running Windows XP, and one for target computers running Windows Server 2003 or a later version of
Windows. These correspond to the two different 1394 protocol settings. You should not need to configure the protocol setting; it will be determined automatically. If you have
some reason for overriding the protocol choice, see Choosing Kernel Debugging Settings for details on this setting.
If you debug a Windows XP target over 1394, and later debug a Windows Server 2003 (or later) target over 1394, or vice-versa, both drivers will be installed on your host
computer.
Relocating the Debugger Binaries
Each 1394 virtual driver will only be installed once.
As a result, if you have installed the Debugging Tools for Windows package and then performed 1394 debugging, you should not copy the binaries to a different computer.
The copied version will not attempt to reinstall the 1394 driver, which will make it impossible to debug over the 1394 connection.
A similar problem can occur if you have a dual-boot machine with a single copy of the debugger binaries.
To assure that 1394 debugging will work, each computer (or operating system on a dual-boot computer) should install a separate Debugging Tools package. See Debugger
Installation for instructions.
Note Before performing kernel debugging over a 1394 cable, you must also configure the software on the target computer. See Disabling the 1394 Host Controller.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 65 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing Symbol Files

The symbol files matching the operating system installation of the target computer must be installed on the host computer, or must be accessible to the host computer through
a symbol server. For more information about the proper installation of symbol files, see Accessing Symbols for Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User-Mode Setup
This section includes:
Configuring Hardware for User-Mode Debugging
Configuring Software for User-Mode Debugging
Enabling Postmortem Debugging
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Hardware for User-Mode Debugging

User-mode debugging is generally done on a single machine: the debugger is run on the same computer as the application that failed.
In this case, no specific hardware setup is required. Throughout this document, the terms host computer and target computer are interchangeable in this case.
If you choose to perform user-mode debugging on two machines, set up the host computer and target computer in the manner described in Configuring Hardware for KernelMode Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Software for User-Mode Debugging

This section includes:
Basic User-Mode Configuration
Configuring tools.ini
Finding the Process ID
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Basic User-Mode Configuration

Before you can begin user-mode debugging, you must install the necessary symbol files and set certain environment variables.
Installing the Symbol Files

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 66 of 1651

You must install the symbol files for the user-mode process that is being debugged. If this is an application you have written, it should be built with full symbol files. If it is a
commercial application, the symbol files may be on the product disk; if not, contact the manufacturer.
If possible, you should also install the symbol files for the version of Microsoft Windows on which the user-mode process is running.
If you are performing remote debugging, the symbol file location depends on the method you are using:

If you are performing remote debugging through the debugger, the symbol files should be on the computer with the debugging server.
If you are performing remote debugging through remote.exe, the symbol files should be on the computer with the debugger.
If you are performing remote debugging through a process server or a KD connection server, the symbol files should be on computer with the smart client.
If you are controlling the user-mode debugger from the kernel debugger, the symbol files need to be on both computers.

For more information about the proper installation of symbol files, see Symbols.
Configuring Environment Variables
The debugger uses a variety of environment variables to indicate a number of important settings.
For a complete list of environment variables used in user-mode debugging, see General Environment Variables.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring tools.ini
The file tools.ini contains information to initialize the command-line debuggers. On startup, the debugger searches for the appropriate section header in the tools.ini file and
extracts initialization information from the entries under the header. Each command-line debugger has its own section header - [CDB], [NTSD], and [KD]. The environment
variable INIT must point to the directory containing the tools.ini file.
WinDbg does not use the tools.ini file. Instead, WinDbg saves initialization settings in workspaces.
The tools.ini entries are shown in the following table.
Keywords must be separated from the values by white space or a colon. Keywords are not case-sensitive.
For TRUE or FALSE values, "FALSE" is the only false value. Anything else is TRUE.
Entry
$u0: value
...
$u9: value
DebugChildren: flag
DebugOutput: flag
IniFile: file
LazyLoad: flag

Description
Assign values to fixed-name aliases. You can specify numeric values n or 0xn or any other string. See Using Aliases for details. No command-line
equivalent.
TRUE or FALSE. If TRUE, CDB debugs the specified application as well as any child processes that it might spawn. Command-line equivalent is o.
TRUE or FALSE. If TRUE, CDB sends output and receives input through a terminal. If FALSE, output goes to the user screen. The command-line
option -d is similar but not identical.
Specifies the name of the script file that CDB or KD takes commands from at startup. The default is the ntsd.ini file in the current directory.
Command-line equivalent is -cf. For details, see Using Script Files.
TRUE or FALSE. If TRUE, CDB performs lazy symbol loading; that is, symbols are not loaded until required. Command-line equivalent is -s.
For details, and other methods of setting this option, see Deferred Symbol Loading.

SetDll: filename

Set extension DLL. The .dll filename extension should be omitted. Default is userexts.dll. Command-line equivalent is -a.
For details, and other methods of setting this default, see Loading Debugger Extension DLLs.

StopFirst: flag
StopOnProcessExit:
flag
sxd: event
sxe: event

True or false. If true, CDB stops on the breakpoint at the end of the image-loading process. Command-line equivalent is -g.
TRUE or FALSE. If TRUE, CDB stops when it receives a process termination notification. Command-line equivalent is -G.
Sets the debugger response and the handling status for the specified exception or event.
Exceptions and events may be specified in the following ways:
*: Default exception
n: Exception n (decimal)
0xn: Exception 0xn (hexadecimal)
(other): Event code
See Controlling Exceptions and Events for details of this process and for other methods of controlling these settings.

VerboseOutput: flag

TRUE or FALSE. If TRUE, CDB will display detailed information about symbol handling, event notification, and other run-time occurrences.
Command-line equivalent is -v.

A sample [NTSD] section in the tools.ini file follows:

[NTSD]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 67 of 1651

sxe: 3c
sxe: cc
$u0: VeryLongName
VerboseOutput:true

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Finding the Process ID

Each process running in Microsoft Windows is assigned a unique decimal number called the process ID, or PID. This number is used to specify the process when attaching a
debugger to it.
There are several ways to determine the PID for a given application: using the Task Manager, using the tasklist command, using the TList utility, or using the debugger.
Task Manager
The Task Manager may be activated in a number of ways, but the simplest is to press CTRL+ALT+DELETE and then click on Task Manager.
If you select the Processes tab, each process and its PID will be listed, along with other useful information.
Some kernel errors may cause delays in Task Manager's graphical interface.
The Tasklist Command
In Windows XP and later versions of Windows, you can use the tasklist command from a Command Prompt window. This displays all processes, their PIDs, and a variety of
other details.
TList
TList (Task List Viewer, tlist.exe) is a command-line utility that displays a list of tasks, or user-mode processes, currently running on the local computer. TList is included in
the Debugging Tools for Windows package.
When you run TList from the command prompt, it will display a list of all the user-mode processes in memory with a unique process identification (PID) number. For each
process, it shows the PID, process name, and, if the process has a window, the title of that window.
For more information, see TList.
The .tlist Debugger Command
If there is already a user-mode debugger running on the system in question, the .tlist (List Process IDs) command will display a list of all PIDs on that system.
CSRSS and User-Mode Drivers
To debug a user-mode driver running on another computer, debug the Client Server Run-Time Subsystem (CSRSS) process. For more information, see Debugging CSRSS.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enabling Postmortem Debugging

The most common application errors are called exceptions. These include access violations, division-by-zero errors, numerical overflows, and many other kinds of errors.
Applications can also cause breakpoint interrupts. These occur when Windows is unable to run the application (for example, when a necessary module cannot be loaded) or
when a breakpoint is encountered. Breakpoints can be inserted into the code by a debugger, or invoked through a function such as DbgBreakPoint. In assembly language, a
breakpoint interrupt is generated by an int 3 instruction.
Windows can handle user-mode errors in a variety of ways. The following sequence shows the precedence used for error handling:
1. If a user-mode debugger is currently attached to the faulting process, all errors will cause the target to break into this debugger.
As long as the user-mode debugger is attached, no other error-handling methods will be used even if the gn (Go With Exception Not Handled) command is used.
2. If no user-mode debugger is attached and the executing code has its own exception handling routines (for example, try - except), this exception handling routine will
attempt to deal with the error.
3. If no user-mode debugger is attached, and Windows has an open kernel-debugging connection, and the error is a breakpoint interrupt, Windows will attempt to contact
the kernel debugger.
Kernel debugging connections must be opened during Windows' boot process. If you are using Windows Server 2003 or a later version of Windows and wish to prevent
a user-mode interrupt from breaking into the kernel debugger, you can use the KDbgCtrl utility with the -du parameter. For details on how to configure kerneldebugging connections and how to use KDbgCtrl, see Configuring Software on the Target Computer.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 68 of 1651

If Windows does attempt to contact a kernel debugger but there is no debugger running at the other end of the connection, Windows will freeze until kernel debugger is
activated.
In the kernel debugger, you can use gh (Go With Exception Handled) to disregard the error and continue running the target. You can use gn (Go With Exception Not
Handled) to bypass the kernel debugger and go on to step 4.
4. If the conditions in steps 1, 2, and 3 do not apply, Windows will activate a debugging tool. Any program can be selected in advance as the tool to use in this situation.
The chosen program is referred to as the postmortem debugger. This is also known as the just-in-time debugger or the JIT debugger.
If the postmortem debugger is a standard user-mode debugger (such as CDB, WinDbg, or Microsoft Visual Studio), this debugger will start up and break into your
application.
If the postmortem debugger is a tool for writing dump files (such as Dr. Watson), a memory dump file will be created, and then the application will be terminated.
Note If Dr. Watson is activated on Windows XP or a later version of Windows, a message box will appear. This window gives you the option of sending an error report to
Microsoft. If you choose Don't Send, a dump file will created and stored on your hard disk. If you choose Send Error Report, a dump file will be created and stored on your
hard disk, and will also be transmitted to Microsoft over the internet.
If you have not reconfigured Windows' postmortem settings, Dr. Watson is used as the default postmortem debugger. This setting can be changed programmatically or
through the registry; any changes take effect immediately.

To change the postmortem debugger to WinDbg, run windbg -I. (The I must be capitalized.) This command will display a success or failure message after it is used.
When WinDbg is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger to CDB, run cdb -iae or cdb -iaec KeyString. When the -iaec parameter is used, KeyString specifies a string to be appended to the
end of command line used to launch the postmortem debugger. If KeyString contains spaces, it must be enclosed in quotation marks. This command will display no
message if it succeeds, but will display a failure message if it fails. When CDB is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger to NTSD, run ntsd -iae or ntsd -iaec KeyString. When the -iaec switch is used, KeyString specifies a string to be appended to the
end of command line used to launch the postmortem debugger. If KeyString contains spaces, it must be enclosed in quotation marks. This command will display no
message if it succeeds, but will display a failure message if it fails. When NTSD is the postmortem debugger, it will be activated whenever an application crashes.
To change the postmortem debugger back to Dr. Watson, run drwtsn32 -i. When Dr. Watson is the postmortem debugger, a memory dump file will be written to disk if
an application crashes. See Dr. Watson Command-Line Options for details.

These methods will set the appropriate registry values so that the debugger will be automatically launched whenever an applicaiton crashes. The debugger command line will
include the argument string -p %ld -e %ld -g. The -p %ld parameter specifies the process ID that will be debugged, the -e %ld parameter provides the event that caused the
exception, and the -g parameter causes the debugger to skip the initial breakpoint. If the -iaec switch is used when installing CDB or NTSD as the postmortem debugger, the
additional arguments specified as KeyString will then follow.
Note Because the -p %ld -e %ld -g parameters always appear first on the command line of the postmortem debugger, you should not use the -iaec switch to specify the
-server parameter because -server will not work unless it appears first on the command line. To install a postmortem debugger that includes this parameter, you must edit the
registry manually.
Only a system administrator can alter the postmortem settings.
If a postmortem debugger has been installed, you can deliberately break into the debugger from a user-mode application by calling the DebugBreak function.
Editing the Registry
The postmortem debugging settings are stored in the registry. If you wish to control these settings, it is recommended that you use the WinDbg, CDB, NTSD, or Dr. Watson
commands described above; these will automatically change the relevant registry keys. If you do need to manually edit the registy, do so very carefully, since improper
changes to the registry may render Windows unusable.
On an x86 computer, the postmortem settings are stored in the \\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug key.
On an Intel Itanium computer, there are two registry keys used for postmortem debugging:
1. A failing 64-bit application will be debugged according to the settings stored in the
\\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug key.
2. A failing 32-bit application will be debugged according to the settings stored in the
\\HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug key. However, if the Debugger value in this key
specifies an application in the %windir%\system32 directory, Windows will look in %windir%\syswow64 instead.
When using an Itanium computer, it is often simplest to place identical values in each of these keys. In particular, if you are using WinDbg, CDB, or NTSD as your
postmortem debugger, the same version will work for 32-bit and 64-bit user-mode applications on an Itanium computer. See Choosing a 32-bit or 64-bit Debugger Package
for details.
There are two registry values that should appear in these keys:
Debugger
This REG_SZ value specifies the debugger that will handle postmortem debugging. The full path to the debugger must be listed, unless the debugger is located in a
directory that is in the default path.
Auto
This REG_SZ value is always either 0 or 1. If Auto is set to 0, a message box will be displayed prior to postmortem debugging.
When an unhandled application error occurs, Windows checks to see if the Debugger and Auto registry values exist.
If the Auto value is 0, a message box will appear.
In Windows 2000, the message box will have one of the following formats:

If the Debugger value contains the name of a valid debugger or Dr. Watson, the message box will have two buttons: OK and Cancel. If the OK button is pressed, the
application will be terminated. If the Cancel button is pressed, the tool specified in the Debugger value will be started.
If the Debugger value is empty, the message box will have only an OK button and no debugger will start.

In Windows XP and later versions of Windows, the message box will have one of the following formats:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 69 of 1651

If the Debugger value contains the name of a valid debugger or Dr. Watson, the message box will have three buttons: Send Error Report, Don't Send, and Debug. If
the Don't Send button is pressed, the application will be terminated. If the Send Error Report button is pressed, a minidump file will be sent to Microsoft and the
application will be terminated. If the Debug button is pressed, the tool specified in the Debugger value will be started. (Note that all of these buttons have different
effects than the buttons on the message window for Dr. Watson when the Auto value does not equal 0.)
If the Debugger value is empty, the message box will have only the Send Error Report and Don't Send buttons.

If the Auto value equals 1, no message box appears. The debugger referred to in the Debugger value is automatically started.
Registry Examples
The following registry values can be used to set Dr. Watson as the postmortem debugger (this is the default):
Debugger = "drwtsn32 -p %ld -e %ld -g"
Auto = 1
The following values can be used to set WinDbg as the postmortem debugger:
Debugger = "Path\WinDbg -p %ld -e %ld"
Auto = 1
The following values can be used to set CDB as the postmortem debugger:
Debugger = "Path\CDB -p %ld -e %ld -g"
Auto = 1
In these examples, Path is the directory where the debugger is located, -p %ld specifies the process ID that will be debugged, -e %ld provides the event that caused the
exception, and -g causes the debugger to skip the initial breakpoint. (Dr. Watson ignores the -g option.)
Security Vulnerabilities
If you are considering enabling postmortem debugging on a computer that you share with other people, see Security During Postmortem Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Windows 95, 98, and Millennium

Debugging Tools for Windows no longer supports debugging of applications that run on Windows 95, Windows 98, or Windows Millennium Edition.
If you want to perform user-mode debugging on one of these versions of Windows, you should use Debugging Tools for Windows version 6.7.5.1. You can install this
package from the Debugging Tools for Windows Web site.
When using an older version of Debugging Tools for Windows, refer to the documentation included in that package, not a more recent version of the Debugging Tools for
Windows documentation. In particular, refer to the topic entitled "Limitations of Debugging on Windows 9x/Me" in that documentation.
Kernel-Mode Debugging of Windows 95, 98, and Millennium Computers
Debugging Tools for Windows cannot be used for kernel mode debugging of Windows 95, Windows 98, or Windows Millennium Edition targets.
For kernel-mode debugging of these Windows versions, use the WDeb family of debuggers (for example, wdeb386.exe) or the Microsoft Windows System Debugger
(debugger.exe). For more information, see the Windows Millennium Edition DDK or the Debugging Tools for Windows Me Web site.
Installing the Debuggers on Windows 95, 98, or Millennium
It is more complicated to install Debugging Tools for Windows on Windows 95, 98, and Millennium for two reasons. First, Unicode support must be supplied to these
operating systems. Second, the installation program used by Debugging Tools for Windows is not compatible with these operating systems.
The following procedure describes how to install Debugging Tools for Windows successfully on these operating systems.
To install the debugging tools on Windows 95, 98, or Millennium
1. Install the Microsoft Layer for Unicode (MSLU) on the Windows 95, 98, or Millennium computer. You can download MSLU from Microsoft Layer for Unicode on
Windows 95, 98, and Me Systems.
2. Download Debugging Tools for Windows, version 6.7.5.1 (or any earlier version) from the Debugging Tools for Windows Web site. Install this package on any NTbased Windows computer.
3. Create a new folder on the Windows 95, 98, or Millennium computer where you want to use the debugging tools. Copy the contents of the Debugging Tools for
Windows folder from your NT-based computer to this new folder.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 70 of 1651

Windows NT 4.0
Debugging Tools for Windows no longer supports the debugging of Windows NT 4.0 targets.
If you want to debug a Windows NT 4.0 target computer or perform user-mode debugging on Windows NT 4.0, you should use Debugging Tools for Windows version
6.7.5.1. You can install this package from the Debugging Tools for Windows Web site.
When using an older version of Debugging Tools for Windows, refer to the documentation included in that package, not a more recent version of the Debugging Tools for
Windows documentation.
Alpha Host Computer or Target Computer
Debugging Tools for Windows no longer runs on or debugs the Alpha (RISC) processor.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Operation
This section includes the following topics:
Starting the Debugger
The Debugger Command Window
The WinDbg Graphical Interface
Debugger Configuration
Debugger Operation (General)
Debugger Operation (User Mode)
Debugger Operation (Kernel Mode)
Debugger Extensions
Remote Debugging
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Starting the Debugger

SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]

-k com:port=ComPort,baud=BaudRate
-k 1394:channel=1394Channel[,symlink=1394Protocol]
-k usb2:targetname=String
-k com:modem
-kl

[-y
[-y
[-y
[-y
[-y
[-y

SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]
SymbolPath]

-k com:port=ComPort,baud=BaudRate
-k 1394:channel=1394Channel[,symlink=1394Protocol]
-k usb2:targetname=String
-k com:modem
-kl
-k

If you do not include the -k command-line option, the connection settings are based on the values of certain environment variables. For more information about the kernel
connection options and the restrictions on their use, see Choosing Kernel Debugging Settings. For more information about other options, see WinDbg Command-Line
Options.
You can change the kernel debugging baud rate after the session has begun by clicking the Debug | Kernel Connection | Cycle Baud Rate command or pressing
CTRL+ALT+A.
WinDbg Menu
When WinDbg is in dormant mode, you can begin a kernel debugging session by clicking Kernel Debug on the File menu or by pressing CTRL+K.
When the Kernel Debugging dialog box appears, click the COM tab, the 1394 tab, or the Local tab. Each tab specifies a different connection method. For more information
about the dialog box and its entries, see File | Kernel Debug.
If you leave the boxes in the Kernel Debugging dialog box blank, the connection settings are based on the values of certain environment variables. For more information
about these settings, see Choosing Kernel Debugging Settings.
Beginning the Session
After the debugger on the host side has started and is waiting to connect, start the target computer. If the target computer is debugger-enabled (as described in Boot Parameters
to Enable Debugging), the target computers debugger will connect automatically, early in the startup process.
If the target computer has stopped responding, the target computer is still stopped because of an earlier kernel debugging action, or you used the -b command-line option, the
debugger breaks into the target computer immediately.
Otherwise, the target computer continues running until the debugger orders it to break.
For more information about the next steps, see Debugger Configuration, Symbols, Debugger Operation (General) and Debugger Operation (Kernel Mode).
1394 Configuration
When you first start the kernel debugger after enabling debugging over a 1394 connection, a driver is installed on your host computer. You must be logged on as an
Administrator on the host computer during this debugging session. For more information about this driver, see Installing the 1394 Virtual Driver.
You must also configure the target computer for kernel debugging over a 1394 cable. For more information about this configuration, see Disabling the 1394 Host Controller.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Opening a Crash Dump

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 78 of 1651

Windows Kernel Version 6001 MP (1 procs) Free x64

To address this problem, check the configuration of the root partition by typing bcdedit at a command prompt, and verify that the values are correct.
Vmdemux Problems
If you restart vmdemux (virtual machine demultiplexer) after you have begun debugging Windows hypervisor, you must add -channel 0 to its command-line options in order
to have the hypervisor channel re-created. This is typically done automatically by Windows hypervisor, but in this case it is not possible, because Windows hypervisor is
already being debugged.
For a full list of the VMDemux command-line options, type vmdemux -? at the command prompt.
Problems with Unmodified Partitions
If you have already set up Hyper-V debugging across a null-modem cable, and have copied the Kdhvcom.dll file to the root partition, and then you later restart the target
computer in another partition that does not have this file installed, the debugger may freeze. In this case, restart vmdemux. This problem arises because unmodified partitions
cannot handle multiplexed traffic. Typically, vmdemux closes down all the pipes on a clean shutdown. However, a non-clean shutdown, such as doing a hard restart, is not
detectable.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling the User-Mode Debugger from the Kernel Debugger

You can redirect the input and output from a user-mode debugger to a kernel debugger. This redirection enables the kernel debugger to control a specific user-mode
debugging session that is occurring on the target computer.
You can use either KD or WinDbg as the kernel debugger.
You can use either CDB or NTSD as the user-mode debugger. NTSD is the better choice, because it requires minimal resources from the processor and operating system of
the computer whose application is being debugged. In fact, when NTSD is started under the control of the kernel debugger, no NTSD window is created. With NTSD, you can
perform user-mode debugging through the serial port early in the boot phase and late into shutdown.
This section includes the following:

Starting the Debugging Session describes how to begin a session where the user-mode debugger is controlled from the kernel debugger.
Switching Modes describes the four different modes that are involved, and how to alternate between them.
When to Use This Technique describes scenarios where this technique is particularly useful.
Combining This Method with Remote Debugging describes how to control the user-mode debugger from a kernel debugger, and use it as a debugging server at the
same time. This combination can be useful if your user-mode symbols are located on a symbol server.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Starting the Debugging Session

In this documentation of how to control user-mode debugging from the kernel debugger, target application refers to the user-mode application that is being debugged, target
computer refers to the computer that contains the target application and the NTSD or CDB process, and host computer refers to the computer that contains the kernel
debugger.
To begin using this technique, you must do the following. You can do steps 1 and 2 in either order.
1. Start NTSD or CDB on the target computer, with the -d command-line option.
For example, you can attach to a running process by using the following syntax.
ntsd -d [-y UserSymbolPath] -p PID
Or, you can start a new process as the target by using the following syntax.
ntsd -d [-y UserSymbolPath] ApplicationName
If you are installing this as a postmortem debugger, you would use the following syntax.
ntsd -d [-y UserSymbolPath]
For more information about this step, see Attaching to a Running Process (User Mode) or Spawning a New Process (User Mode).
2. Start WinDbg or KD on the host computer, as if you were going to debug the target computer, but do not actually break in to the target computer. To use WinDbg, use
the folloinwg syntax.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

This section includes the following topics:
Using Debugger Commands
Evaluating Expressions
Using Shell Commands
Using Aliases
Using Script Files
Using Debugger Command Programs
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Debugger Commands

For KD or CDB, "Debugger Command window" refers to the whole window. You enter commands at the prompt at the bottom of the window. If the commands have any
output, the window displays the output and then displays the prompt again.
For WinDbg, "Debugger Command window" refers to the window that is labeled "Command" in the title bar. This window contains two panes:

In the small, bottom pane, you enter commands.

In the large, upper pane, you view command output.

This window is always open at the beginning of a debugging session. You can reopen or switch to this window by clicking Command on the View menu, pressing ALT+1, or
clicking the Command (Alt+1) button (

) on the toolbar.

You can use the UP ARROW and DOWN ARROW keys to scroll through the command history. When a previous command appears, you can edit it and then press ENTER
to execute the previous command (or the edited version of the previous command). The cursor does not have to be at the end of the line for this procedure to work correctly.
Debugger Command Window Prompt
When you are performing user-mode debugging, the prompt in the Debugger Command window looks like the following example.
2:005>
In the preceding example, 2 is the current process number, and 005 is the current thread number.
If you attach the debugger to more than one computer, the system number is included before the process and thread number, as in the following example.
3:2:005>
In this example, 3 is the current system number, 2 is the current process number, and 005 is the current thread number.
When you are performing kernel-mode debugging on a target computer that has only one processor, the prompt looks like the following example.
kd>
However, if the target computer has multiple processors, the number of the current processor appears before the prompt, as in the following example.
0: kd>
If the debugger is busy processing a previously issued command, new commands will temporarily not be processed, although they can be added to the command buffer. In
addition, you can still use control keys in KD and CDB, and you can still use menu commands and shortcut keys in WinDbg. When KD or CDB is in this busy state, no
prompt is displayed. When WinDbg is in this busy state, the following indicator will appear in place of the prompt:
*BUSY*
You can use the .pcmd (Set Prompt Command) command to add text to this prompt.
Kinds of Commands

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 82 of 1651

WinDbg, KD, and CDB support a variety of commands. Some commands are shared between the debuggers, and some are available only on one or two of the debuggers.
Some commands are available only in live debugging, and other commands are available only when you debug a dump file.
Some commands are available only during user-mode debugging, and other commands are available only during kernel-mode debugging.
Some commands are available only when the target is running on certain processors. For more information about all of the commands and their restrictions, see Debugger
Commands.
Editing, Repeating, and Canceling Commands
You can use standard editing keys when you enter a command:

Use the UP ARROW and DOWN ARROW keys to find previous commands.
Edit the current command with the BACKSPACE, DELETE, INSERT, and LEFT ARROW and RIGHT ARROW keys.
Press the ESC key to clear the current line.

You can press the TAB key to automatically complete your text entry. In any of the debuggers, press the TAB key after you enter at least one character to automatically
complete a command. Press the TAB key repeatedly to cycle through text completion options, and hold down the SHIFT key and press TAB to cycle backward. You can also
use wildcard characters in the text and press TAB to expand to the full set of text completion options. For example, if you type fo*!ba and then press TAB, the debugger
expands to the set of all symbols that start with "ba", in all modules with module names that start with "fo". As another example, you can complete all extension commands
that have "prcb" in them by typing !*prcb and then pressing TAB.
When you use the TAB key to perform text completion, if your text fragment begins with a period (.), the text is matched to a dot command. If your text fragment begins with
an exclamation point (!), the text is matched to an extension command. Otherwise, the text is matched with a symbol. When you usee the TAB key to enter symbols, pressing
the TAB key completes code and type symbols and module names. If no module name is apparent, local symbols and module names are completed. If a module or module
pattern is given, symbol completion completes code and type symbols from all matches.
You can right-click in the Debugger Command window to automatically paste the contents of the clipboard into the command that you are typing.
The maximum command length is 4096 characters. However, if you are controlling the user-mode debugger from the kernel debugger, the maximum line length is 512
characters.
In CDB and KD, press the ENTER key by itself to repeat the previous command. In WinDbg, you can enable or disable this behavior. For more information about this
behavior, see ENTER (Repeat Last Command).
If the last command that you issued presents a long display and you want to cut it off, use the CTRL+C key in CDB or KD. In WinDbg, use Debug | Break or press
CTRL+BREAK.
In kernel-mode debugging, you can cancel commands from the keyboard of the target computer by pressing CTRL+C.
You can use the .cls (Clear Screen) command to clear all of the text from the Debugger Command window. This command clears the whole command history. In WinDbg,
you can clear the command history by using the Edit | Clear Command Output command or by clicking Clear command output on the shortcut menu of the Debugger
Command window.
Expression Syntax
Many commands and extension commands accept expressions as their arguments. The debugger evaluates these expressions before executing the command. For more
information about expressions, see Evaluating Expressions.
Aliases
Aliases are text macros that you can use to avoid having to retype complex phrases. There are two kinds of aliases. For more information about aliases, see Using Aliases.
Self-Repeating Commands
You can use the following commands to repeat an action or conditionally execute other commands:

The j (Execute If-Else) conditional command

The z (Execute While) conditional command
The ~e (Thread-Specific Command) command qualifier
(Windows XP and later versions of Windows) The !list extension command

For more information about each command, see the individual command topics.
Controlling Scrolling
You can use the scrollbar to view your previous commands and their output.
When you are using CDB or KD, any keyboard entry automatically scrolls down the Debugger Command window back to the bottom.
In WinDbg, the display automatically scrolls down to the bottom whenever a command produces output or you press the ENTER key. If you want to disable this automatic
scrolling, click the Options on the View menu and then clear the Automatically scroll check box.
WinDbg Text Features
In WinDbg, you can use several additional features to change how text is displayed in the Debugger Command window. You can access some of these features in the WinDbg
window, some in the shortcut menu in the Debugger Command window, and some by clicking on the appropriate menu icon.

The Word wrap command on the shortcut menu turns on and off the word wrap status. This command affects the whole window, not only commands that you use after
this state is changed. Because many commands and extensions produce formatted displays, we typically do not recommend word wrap.
The Edit | Add to Command Output menu command adds a comment in the Debugger Command window. The Add to command output command on the shortcut
menu has the same effect.
You can customize the colors that are used for the text and the background of the Debugger Command window. You can specify different colors for different kinds of

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 83 of 1651

text. For example, you can display the automatic register output in one color, error messages in another color, and DbgPrint messages in a third color. For more
information about this customization, see View | Options.
You can use all of the features common to WinDbg's debugging information windows, such as customizing the fonts and using special editing commands. For more
information about these features, see Using Debugging Information Windows.

Remote Debugging
When you are performing remote debugging through the debugger, the debugging client can access a limited number of commands. To change the number of commands that
the client can access, use the -clines command-line option or the _NT_DEBUG_HISTORY_SIZE environment variable.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Evaluating Expressions
The debugger understands two different forms of expressions: MASM expressions and C++ expressions.
Microsoft Macro Assembler (MASM) expressions are used in the examples in this Help documentation, except when otherwise noted. In MASM expressions, all symbols are
treated as addresses.
C++ expressions are the same as those used in actual C++ code. In these expressions, symbols are understood as the appropriate data types.
When Each Syntax is Used
You can select the default expression evaluator in one of the following ways:

Use the _NT_EXPR_EVAL environment variable before the debugger is started.

Use the -ee {masm|c++} command-line option when the debugger is started.
Use the .expr (Choose Expression Evaluator) command to display or change the expression evaluator after the debugger is running.

If you do not use one of the preceding methods, the debugger uses the MASM expression evaluator.
If you want to evaluate an expression without changing the debugger state, you can use the ? (Evaluate Expression) command.
All commands and debugging information windows interpret their arguments through the default expression evaluator, with the following exceptions:

The ?? (Evaluate C++ Expression) command always uses the C++ expression evaluator.
The Watch window always uses the C++ expression evaluator.
The Locals window always uses the C++ expression evaluator.
Some extension commands always use the MASM expression evaluator (and other extension commands accept only numeric arguments instead of full expressions).
If any part of an expression is enclosed in parentheses and you insert two at signs (@@) before the expression, the expression is evaluated by the expression evaluator
that would not typically be used in this case.

The two at signs (@@) enable you to use two different evaluators for different parameters of a single command. It also enables you to evaluate different pieces of a long
expression by different methods. You can nest the two at signs. Each appearance of the two at signs switches to the other expression evaluator.
Warning C++ expression syntax is useful for manipulating structures and variables, but it is not well-suited as a parser for the parameters of debugger commands. When you
are using debugger commands for general purposes or you are using debugger extensions, you should set MASM expression syntax as the default expression evaluator. If you
must have a specific parameter use C++ expression syntax, use the two at sign (@@) syntax.
For more information about the two different expression types, see Numerical Expression Syntax.
Numbers in Expressions
Numbers in MASM expressions are interpreted according to the current radix. The n (Set Number Base) command can be used to set the default radix to 16, 10, or 8. All unprefixed numbers will be interpreted in this base. The default radix can be overridden by specifying the 0x prefix (hexadecimal), the 0n prefix (decimal), the 0t prefix (octal),
or the 0y prefix (binary).
Numbers in C++ expressions are interpreted as decimal numbers unless you specify differently. To specify a hexadecimal integer, add 0x before the number. To specify an
octal integer, add 0 (zero) before the number. (However, in the debugger's output, the 0n decimal prefix is sometimes used.)
If you want to display a number in several bases at the same time, use the .formats (Show Number Formats) command.
Symbols in Expressions
The two types of expressions interpret symbols differently:

In MASM expressions, each symbol is interpreted as an address. Depending on what the symbol refers to, this address is the address of a global variable, local variable,
function, segment, module, or any other recognized label.
In C++ expressions, each symbol is interpreted according to its type. Depending on what the symbol refers to, it might be interpreted as an integer, a data structure, a
function pointer, or any other data type. A symbol that does not correspond to a C++ data type (such as an unmodified module name) creates a syntax error.

If a symbol might be ambiguous, precede it with the module name and an exclamation point ( ! ). If the symbol name could be interpreted as a hexadecimal number, precede it
with the module name and an exclamation point ( ! ) or only an exclamation point. In order to specify that a symbol is meant to be local, omit the module name, and include a
dollar sign and an exclamation point ( $! ) before the symbol name. For more information about interpreting symbols, see Symbol Syntax and Symbol Matching.
Operators in Expressions

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 84 of 1651

Each expression type uses a different collection of operators.

For more information about the operators that you can use in MASM expressions and their precedence rules, see MASM Numbers and Operators.
For more information about the operators that you can use in C++ expressions and their precedence rules, see C++ Numbers and Operators.
Remember that MASM operations are always byte-based, and C++ operations follow C++ type rules (including the scaling of pointer arithmetic).
For some examples of the different syntaxes, see Expression Examples.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Shell Commands

The debugger can transmit certain commands to the Microsoft Windows environment in which the debugger is running.
You can use the .shell (Command Shell) command in any Windows debugger. With this command, you can execute an application or a Microsoft MS-DOS command
directly from the debugger. If you are performing remote debugging, these shell commands are executed on the server.
The .noshell (Prohibit Shell Commands) command or the -noshell command-line option disables all shell commands. The commands are disabled while the debugger is
running, even if you begin a new debugging session. The commands remain disabled even if you issue a .restart (Restart Kernel Connection) command in KD.
If you are running a debugging server,you might want to disable shell commands. If the shell is available, a remote connection can use the .shell command to change your
computer.
Network Drive Control
In WinDbg, you can use the File | Map Network Drive and File | Disconnect Network Drive commands to control the network drive mappings. These changes always occur
on the computer that WinDbg is running on, never on any computer that is remotely connected to WinDbg.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Aliases
Aliases are character strings that are automatically replaced with other character strings. You can use them in debugger commands and to avoid retyping certain common
phrases.
An alias consists of an alias name and an alias equivalent. When you use an alias name as part of a debugger command, the name is automatically replaced by the alias
equivalent. This replacement occurs immediately, before the command is parsed or executed.
The debugger supports three kinds of aliases:

You can set and name user-named aliases.

You can set fixed-name aliases, but they are named $u0, $u1, ..., $u9.
The debugger sets and names automatic aliases.

Defining a User-Named Alias

When you define a user-named alias, you can choose the alias name and the alias equivalent:

The alias name can be any string that does not contain white space.
The alias equivalent can be any string. If you enter it at the keyboard, the alias equivalent cannot contain leading spaces or carriage returns. Alternatively, you can set it
equal to a string in memory, the value of a numeric expression, the contents of a file, the value of an environment variable, or the output of one or more debugger
commands.

Both the alias name and the alias equivalent are case sensitive.
To define or redefine a user-named alias, use the as (Set Alias) or aS (Set Alias) command.
To remove an alias, use the ad (Delete Alias) command.
To list all current user-named aliases, use the al (List Aliases) command.
Defining a Fixed-Name Alias
There are 10 fixed-name aliases. Their alias names are $u0, $u1, ..., $u9. Their alias equivalents can be any string that does not contain the ENTER keystroke.
Use the r (Registers) command to define the alias equivalents for fixed-name aliases. When you define a fixed-name alias, you must insert a period (.) before the letter "u".
The text after the equal sign (=) is the alias equivalent. The alias equivalent can include spaces or semicolons, but leading and trailing spaces are ignored. You should not

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 85 of 1651

enclose the alias equivalent in quotation marks (unless you want quotation marks in the results).
Note Do not be confused by using the r (Registers) command for fixed-name aliases. These aliases are not registers or pseudo-registers, even though you use the r command
to set their alias equivalents. You do not have to add an at (@) sign before these aliases, and you cannot use the r command to display the value of one of these aliases.
By default, if you do not define a fixed-name alias, it is an empty string.
Automatic Aliases
The debugger sets the following automatic aliases.
Alias name
$ntnsym
$ntwsym

Alias equivalent
The most appropriate module for NT symbols on the computer's native architecture. This alias can equal either ntdll or nt.
The most appropriate module for NT symbols during 32-bit debugging that uses WOW64. This alias could be ntdll32 or some other 32-bit
version of Ntdll.dll.
$ntsym
The most appropriate module for NT symbols that match the current machine mode. When you are debugging in native mode, this alias is the
same as $ntnsym. When you are debugging in a non-native mode, the debugger tries to find a module that matches this mode. (For example,
during 32-bit debugging that uses WOW64, this alias is the same as $ntwsym.)
$CurrentDumpFile
The name of the last dump file that the debugger loaded.
$CurrentDumpPath
The directory path of the last dump file that the debugger loaded.
$CurrentDumpArchiveFile The name of the last dump archive file (CAB file) that the debugger loaded.
$CurrentDumpArchivePath The directory path of the last dump archive file (CAB file) that the debugger loaded.
Automatic aliases are similar to automatic pseudo-registers, except that you can use automatic aliases with alias-related tokens (such as ${ }), while you cannot use pseudoregisters with these tokens.
Using an Alias in the Debugger Command Window
After you define an alias, you can use it in any command entry. The alias name is automatically replaced with the alias equivalent. Therefore, you can use the alias as an
expression or as a macro.
An alias name expands correctly even if it is enclosed in quotation marks. Because the alias equivalent can include any number of quotation marks or semicolons, the alias
equivalent can represent multiple commands.
A user-named alias is recognized only if its name is separated from other characters by white space. The first character of its alias name must begin the line or follow a space,
a semicolon, or a quotation mark. The last character of its alias name must end the line or be followed by a space, a semicolon, or a quotation mark.
Note Any text that you enter into the Debugger Command window that begins with "as", "aS", "ad", or "al" does not receive alias replacement. This restriction prevents the
alias commands from being rendered inoperable. However, this restriction also means that commands that follow ad or al on a line do not have their aliases replaced. If you
want aliases to be replaced in a line that begins with one of these strings, add a semicolon before the alias.
However, you can use the ${ } token to expand a user-named alias even when it is next to other text. You can also use this token together with certain switches to prevent an
alias from being expanded or to display certain alias-related values. For more information about these situations, see ${ } (Alias Interpreter).
A fixed-name alias expands correctly from any point within a line, regardless of how it is embedded within the text of the line.
You cannot use commands that are available only in WinDbg (.open, .write_cmd_hist (Write Command History), .lsrcpath, and .lsrcfix) and a few additional commands
(.hh, .cls, .wtitle, .remote, kernel-mode .restart, and user-mode .restart) with aliases.
Using an Alias in a Script File
When you use an alias in a script file, you must take special care to make sure that the alias is expanded at the correct time. Consider the following script:
.foreach (value {dd 610000 L4})
{
as /x ${/v:myAlias} value + 1
.echo value myAlias
}
ad myAlias
The first time through the loop, the as, aS (Set Alias) command assigns a value to the myAlias. The value assigned to myAlias is 1 plus 610000 (the first output of the dd
command). However, when the .echo (Echo Comment) command is executed, myAlias has not yet been expanded, so instead of seeing 610001, we see the text "myAlias".
0:001> $$>< c:\Script02.txt
00610000 myAlias
00905a4d 0x610001
00000003 0x905a4e
00000004 0x4
0000ffff 0x5
The problem is that myAlias is not expanded until a new block of code is entered. The next entry to the loop is a new block, so myAlias gets expanded to 610001. But it is too
late: we should have seen 610001 the first time through the loop, not the second time.We can fix this problem by enclosing the .echo (Echo Comment) command in a new
block as shown in the following script.
.foreach (value {dd 610000 L4})
{
as /x ${/v:myAlias} value + 1
.block{.echo value myAlias}
}

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 86 of 1651

ad myAlias
With the altered script, we get the following correct output.
0:001> $$>< c:\Script01.txt
00610000 0x610001
00905a4d 0x905a4e
00000003 0x4
00000004 0x5
0000ffff 0x10000
For more information, see .block and ${ } (Alias Interpreter).
Examples
You can use aliases so that you do not have to type long or complex symbol names, as in the following example.
0:000> as Short usersrv!NameTooLongToWantToType
0:000> dw Short +8
The following example is similar to the preceding example but it uses a fixed-name alias.
0:000> r $.u0=usersrv!NameTooLongToWantToType
0:000> dw $u0+8
You can use aliases as macros for commands that you use frequently. The following example increments the eax and ebx registers two times.
0:000> as GoUp r eax=eax+1; r ebx=ebx+1
0:000> GoUp
0:000> GoUp
The following example uses an alias to simplify typing of commands.
0:000> as Cmd "dd esp 14; g"
0:000> bp MyApi Cmd
The following example is similar to the preceding example but it uses a fixed-name alias.
0:000> r $.u5="dd esp 14; g"
0:000> bp MyApi $u5
Both of the preceding examples are equivalent to the following command.
0:000> bp MyApi "dd esp 14; g"
Recursive Aliases
You can use a fixed-name alias in the definition of any alias. You can also use a user-named alias in the definition of a fixed-name alias. However, to use a user-named alias
in the definition of another user-named alias, you have to add a semicolon before the as or aS command, or else the alias replacement does not occur on that line.
When you are using recursive definitions of this type, each alias is translated as soon as it is used. For example, the following example displays 3, not 7.
0:000> r
0:000> r
0:000> r
0:000> ?
Evaluate

$.u2=2
$.u1=1+$u2
$.u2=6
$u1
expression: 3 = 00000003

Similarly, the following example displays 3, not 7.

0:000> as fred 2
0:000> r $.u1= 1 + fred
0:000> as fred 6
0:000> ? $u1
Evaluate expression: 3 = 00000003
The following example is also permitted and displays 9.
0:000> r
0:000> r
0:000> ?
Evaluate

$.u0=2
$.u0=7+$u0
$u0
expression: 9 = 00000009

Tools.ini File
In CDB (and NTSD), you can predefine fixed-name aliases in the tools.ini file. To predefine a fixed-name alias, add the $u fields that you want to your [NTSD] entry, as in
the following example.
[NTSD]
$u1:_ntdll!_RtlRaiseException

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 87 of 1651

$u2:"dd esp 14;g"

$u9:$u1 + 42
You cannot set user-named aliases in the Tools.ini file.
Fixed-Name Aliases vs. User-Named Aliases
User-name aliases are easier to use than fixed-named aliases. Their definition syntax is simpler, and you can list them by using the al (List Aliases) command.
Fixed-named aliases are replaced if they are used next to other text. To make a user-named alias be replaced when it is next to other text, enclose it in the ${ } (Alias
Interpreter) token.
Fixed-name alias replacement occurs before user-named alias replacement.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Script Files

A script file is a text file that contains a sequence of debugger commands. There are a variety of ways for the debugger to load a script file and execute it. A script file can
contain commands to be executed sequentially or can use a more complex flow of execution.
To execute a script file, you can do one of the following:

(KD and CDB only; only when the debugger starts) Create a script file that is named Ntsd.ini and put it in the directory where you are starting the debugger from. The
debugger automatically executes this file when the debugger starts. To use a different file for the startup script file, specify the path and file name by using the -cf
command-line option or by using the IniFile entry in the Tools.ini file.
(KD and CDB only; when each session starts) Create a script file and specify its path and file name by using the -cfr command-line option. The debugger automatically
executes this script file when the debugger starts and every time that the target is restarted.
Use the $<, $><, $$<, and $$>< commands to execute a script file after the debugger is running. For more information about the syntax, see $<, $><, $><, $$>< (Run
Script File).

The $>< and $$>< commands differ from the other methods of running scripts in one important way. When you use these commands, the debugger opens the specified script
file, replaces all carriage returns with semicolons, and executes the resulting text as a single command block. These commands are useful for running scripts that contain
debugger command programs. For more information about these programs, see Using Debugger Command Programs.X
You cannot use commands that are available only in WinDbg (such as .lsrcfix (Use Local Source Server), .lsrcpath (Set Local Source Path), .open (Open Source File),
and .write_cmd_hist (Write Command History)) in script files, even if the script file is executed in WinDbg. In addition, you cannot use the .beep (Speaker Beep),
.cls (Clear Screen), .hh (Open HTML Help File), .idle_cmd (Set Idle Command), .remote (Create Remote.exe Server), kernel-mode .restart (Restart Kernel
Connection), user-mode .restart (Restart Target Application), or .wtitle (Set Window Title) commands in a script file.
Note WinDbg supports the same scripts as KD and CDB, with one minor exception. You can use the .remote_exit (Exit Debugging Client) command only in a script file
that KD or CDB uses. You cannot exit from a debugging client though a script that is executed in WinDbg.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Debugger Command Programs

This section includes the following topics:
Elements of a Debugger Command Program
Control Flow Tokens
Debugger Command Program Execution
Debugger Command Program Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Elements of a Debugger Command Program

A debugger command program is a small application that consists of debugger commands and control flow tokens, such as .if, .for, and .while. (For a full list of control flow

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 88 of 1651

tokens and their syntax, see Control Flow Tokens.)

You can use braces ( { } ) to enclose a block of statements within a larger command block. When you enter each block, all aliases within the block are evaluated. If you later
alter the value of an alias within a command block, commands after that point do not use the new alias value unless they are within a subordinate block.
You cannot create a block by using a pair of braces. You must add a control flow token before the opening brace. If you want to create a block only to evaluate aliases, you
should use the .block token before the opening brace.
A debugger command program can use user-named aliases or fixed-name aliases as its local variables. If you want to use numeric or typed variables, you can use the $tn
pseudo-registers.
User-named aliases are evaluated only if they are not next to other text. If you want to evaluate an alias that is next to other text, use the ${ } (Alias Interpreter) token. This
token has optional switches that enable you to evaluate the alias in a variety of ways.
You can add comments to a debugger command program by using two dollar signs ($$ (Comment Specifier)). You should not insert a comment between a token and its
elements (such as braces or conditions).
Note You should not use an asterisk (* (Comment Line Specifier)). Because comments that are specified with an asterisk do not end with a semicolon, the rest of the
program is disregarded.
Typically, you should use MASM syntax within a debugger command program. When you have to use C++ elements (such as specifying a member of a structure or class),
you can use the @@c++( ) token to switch to C++ syntax for that clause.
The $scmp, $sicmp, and $spat string operators in MASM syntax are particularly useful. For more information about these operators, see MASM Numbers and Operators.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Control Flow Tokens

You can use control flow tokens to create conditional execution and execution loops within debugger command programs.
Control flow tokens behave like their counterparts in C and C++, with the following general exceptions:

You must enclose each block of commands that is executed conditionally or repeatedly in braces, even if there is only one such command. For example, you cannot
omit the braces in the following command.
0:000> .if (ebx>0) { r ebx }

Each condition must be a expression. Commands are not permitted. For example, the following example produces a syntax error.
0:000> .while (r ebx) { .... }

The final command before a closing brace does not have to be followed by a semicolon.

The following control flow tokens are supported within a debugger command program. For more information about the syntax of each token, see the individual reference
topics.

The .if token behaves like the if keyword in C.

The .else token behaves like the else keyword in C.
The .elsif token behaves like the else if keyword combination in C.
The .foreach token parses the output of debugger commands, a string, or a text file. This token then takes each item that it finds and uses them as the input to a
specified list of debugger commands.
The .for token behaves like the for keyword in C, except that you must separate multiple increment commands by semicolons, not by commas.
The .while token behaves like the while keyword in C.
The .do token behaves like the do keyword in C, except that you cannot use the word "while" before the condition.
The .break token behaves like the break keyword in C. You can use this token within any .for, .while, or .do loop.
The .continue token behaves like the continue keyword in C. You can use this token within any .for, .while, or .do loop.
The .catch token prevents a program from ending if an error occurs. The .catch token is followed by braces that enclose one or more commands. If one of these
commands generates an error, the error message is displayed, all remaining commands within the braces are ignored, and execution resumes with the first command
after the closing brace.
The .leave token is used to exit from a .catch block.
The .printf token behaves like the printf statement in C.
The .block token performs no action. You should use this token only to introduce a block, because you cannot create a block by only using a pair of braces. You must
add a control flow token before the opening brace.

The !for_each_module, !for_each_frame, and !for_each_local extensions are also useful with a debugger command program.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 89 of 1651

Executing a Debugger Command Program

You can execute a debugger command program in one of the following ways:

Enter all of the statements in the Debugger Command window as a single string, with individual statements and commands separated by semicolons.
Add all of the statements in a script file on a single line, with individual statements and commands separated by semicolons. Then, run this script file by using one of the
methods described in Using Script Files.
Add all of the statements in a script file, with each statement on a separate line. (Alternatively, separate statements by any combination of carriage returns and
semicolons.) Then, run this script file by using the $>< (Run Script File) or $$>< (Run Script File) command. These commands open the specified script file, replace
all carriage returns with semicolons, and execute the resulting text as a single command block.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Command Program Examples

The following sections in this topic describe examples of debugger command programs.
Using the .foreach Token
The following example uses the .foreach token to search for word values and then display them as DWORDs and characters.
0:000> .foreach (place { s-[1]w 77000000 L?4000000 5a4d }) { dc place L8 }
The -[1] option together with the s (Search Memory) command causes its output to include only the addresses it finds, not the values that are found at those addresses.
The following command displays verbose module information for all modules that are located in the memory range from 0x77000000 through 0x7F000000.
0:000> .foreach (place { lm1m }) { .if ((${place} >= 0x77000000) & (${place} <= 0x7f000000)) { lmva place } }
The 1m option together with the lm (List Loaded Modules) command causes its output to include only the addresses of the modules, not the full description of these
modules.
The preceding example uses the ${ } (Alias Interpreter) token to make sure aliases are replaced even if they are next to other text. If the command did not include this token,
the opening parentheses that is next to place prevents alias replacement. Note that the ${} token works on the variables that are used in .foreach and on true aliases.
Walking the Process List
The following example walks through the kernel-mode process list and displays the executable name for each entry in the list.
This example should be stored as a text file and executed with the $$>< (Run Script File) command. This command loads the whole file, replaces all carriage returns with
semicolons, and executes the resulting block. This command enables you to write readable programs by using multiple lines and indentation, instead of having to squeeze the
whole program onto a single line.
This example illustrates the following features:

The $t0, $t1, and $t2 pseudo-registers are used as variables in this program. The program also uses aliases named Procc and $ImageName.
This program uses the MASM expression evaluator. However, the @@c++( ) token appears one time. This token causes the program to use the C++ expression
evaluator to parse the expression within the parentheses. This usage enables the program to use the C++ structure tokens directly.
The ? flag is used with the r (Registers) command. This flag assigns typed values to the pseudo-register $t2.

$$ Get process list LIST_ENTRY in $t0.

r $t0 = nt!PsActiveProcessHead
$$ Iterate over all processes in list.
.for (r $t1 = poi(@$t0);
(@$t1 != 0) & (@$t1 != @$t0);
r $t1 = poi(@$t1))
{
r? $t2 = #CONTAINING_RECORD(@$t1, nt!_EPROCESS, ActiveProcessLinks);
as /x Procc @$t2
$$ Get image name into $ImageName.
as /ma $ImageName @@c++(&@$t2->ImageFileName[0])
.block
{
.echo ${$ImageName} at ${$Procc}
}
ad $ImageName
ad Procc
}
Walking the LDR_DATA_TABLE_ENTRY List

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 90 of 1651

The following example walks through the user-mode LDR_DATA_TABLE_ENTRY list and displays the base address and full path of each list entry.
Like the preceding example, this program should be saved in a file and executed with the $$>< (Run Script File) command.
This example illustrates the following features:

This program uses the MASM expression evaluator. However, in two places, the @@c++( ) token appears. This token causes the program to use the C++ expression
evaluator to parse the expression within the parentheses. This usage enables the program to use C++ structure tokens directly.
The ? flag is used with the r (Registers) command. This flag assigns typed values to the pseudo-registers $t0 and $t1. In the body of the loop, $t1 has the type ntdll!
_LDR_DATA_TABLE_ENTRY*, so the program can make direct member references.
The user-named aliases $Base and $Mod are used in this program. The dollar signs reduce the possibility that these aliases have been used previously in the current
debugger session. The dollar signs are not necessary. The ${/v: } token interprets the alias literally, preventing it from being replaced if it was defined before the script
is run. You can also use this token together with any block to prevent alias definitions before the block from being used.
The .block token is used to add an extra alias replacement step. Alias replacement occurs one time for the whole script when it is loaded and one time when each block
is entered. Without the .block token and its braces, the .echo command does not receive the values of the $Mod and $Base aliases that are assigned in the previous
lines.

$$ Get module list LIST_ENTRY in $t0.

r? $t0 = &@$peb->Ldr->InLoadOrderModuleList
$$ Iterate over all modules in list.
.for (r? $t1 = *(ntdll!_LDR_DATA_TABLE_ENTRY**)@$t0;
(@$t1 != 0) & (@$t1 != @$t0);
r? $t1 = (ntdll!_LDR_DATA_TABLE_ENTRY*)@$t1->InLoadOrderLinks.Flink)
{
$$ Get base address in $Base.
as /x ${/v:$Base} @@c++(@$t1->DllBase)
$$ Get full name into $Mod.
as /msu ${/v:$Mod} @@c++(&@$t1->FullDllName)
.block
{
.echo ${$Mod} at ${$Base}
}
ad ${/v:$Base}
ad ${/v:$Mod}
}

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WinDbg Graphical Interface

This section includes the following topics:
Using Debugging Information Windows
Using Workspaces
Using the Toolbar and Status Bar
Using the Help Documentation
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Debugging Information Windows

WinDbg has ten kinds of debugging information windows. You can have only one instance of the following windows open at the same time: the Debugger Command
window, the Watch window, the Locals window, the Registers window, the Calls window, the Disassembly window, the Processes and Threads window, and the Scratch Pad.
In addition to these eight individual windows, WinDbg can display multiple Source windows and Memory windows at the same time.
This section describes the features that are common to all of these windows:
Opening a Window
Closing a Window
Configuring a Window

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 91 of 1651

Moving Through a Window

Cutting and Pasting Text
Changing Text Properties
Positioning the Windows
For more information about the contents and use of a specific window, see Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Opening a Window
When WinDbg begins a debugging session, the Debugger Command window automatically opens. The Disassembly window also automatically opens, unless you deselect
Automatically Open Disassembly on the Window menu.
Whenever WinDbg discovers a source file that corresponds to the current program counter, WinDbg opens a Source window for that file. For other ways to open Source
windows, see Source Path.
You can use the following menu commands, toolbar buttons, and shortcut keys to switch to these windows. That is, if a window is not open, it opens. If a window is open but
inactive, it becomes active. If a window is docked and there is a floating window in front of it, the docked window becomes active but the floating window stays in front of
the docked window.
Window
Menu command
Debugger Command window View | Command

Button Shortcut keys

ALT+1

Watch window

View | Watch

ALT+2

Locals window

View | Locals

ALT+3

Registers window

View | Registers

ALT+4

Memory window

View | Memory

ALT+5

Calls window

View | Call Stack

ALT+6

Disassembly window

View | Disassembly

ALT+7

Scratch Pad

View | Scratch Pad

ALT+8

Processes and Threads window View | Processes and Threads

Source window
Click File | Open Source File and then select a source file.

ALT+9
CTRL+O

You can also activate a window by selecting it from the list of open windows at the bottom of the Window menu.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Closing a Window
To close a debugging information window, click the Close button in the upper-right corner of the window.
If you want to close the active window, you can also click Close Current Window on the File menu or press CTRL+F4.
You can close one of the debugging information windows by pressing ALT+SHIFT+number, where ALT+number are the shortcut keys that open this window. (For a list of
the possible shortcut keys, see Opening a Window.)
To close all Source windows at the same time, click Close All Source Windows on the Window menu. This command will not close a Source window that has been
designated as a tab-dock target. For more information on this setting, see the Source Window topic.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring a Window
Each debugging information window has a shortcut menu that you can access by right-clicking the title bar of the window or by clicking the icon near the upper-right corner
of the title bar. You can use the commands on this shortcut menu to configure the window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 92 of 1651

Many debugging information windows also have toolbars that contain buttons. Most of these buttons have features that are the same as commands on the shortcut menu.
For more information about a specific window's shortcut menu and toolbar, see Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Moving Through a Window

There are several ways of moving through a debugging information window.
If a scrollbar appears in the window, you can use it to display more of the window.
In addition, some windows support the Find, Go to Address, or Go to Line commands. These commands only change the WinDbg display. They do not affect the execution
of the target or any other debugger operations.
Find Command
You can use the Find command in the Debugger Command window or in a Source window.
When one of these windows is active, click Find on the Edit menu or press CTRL+F. The Find dialog box opens.
Enter the text that you want to find in the dialog box, and select Up or Down to determine the direction of your search. The search begins wherever the cursor is in the
window. You can put the cursor at any point by using the mouse.
Select the Match whole word only check box if you want to search for a single whole word. (If you select this check box and you enter multiple words, this check box is
ignored.) Select the Match case check box to perform a case-sensitive search.
If you close the Find dialog box, you can repeat the previous search in a forward direction by clicking Find Next on the Edit menu or pressing F3. You can repeat the search
in a backward direction by pressing SHIFT+F3.
Go to Address Command
The Go to Address command searches for an address in the application that you are debugging. To use this option, click Go to Address on the Edit menu or press CTRL+G.
When the View Code Offset dialog box appears, enter the address that you want to search for. You can enter this address as an expression, such as a function, symbol, or
integer memory address. If the address is ambiguous, a list appears with all of the ambiguous items.
After you click OK, the debugger moves the cursor to the beginning of the function or address in the Disassembly window or a Source window.
You can use the Go to Address command regardless of which debugging information window is open. If the debugger is in disassembly mode, the debugger finds the address
that you are searching for in the Disassembly window. If the debugger is in source mode, the debugger tries to find the address in a Source window. If the debugger cannot
find the address in a Source window, the debugger finds the address in the Disassembly window. If the needed window is not open, the debugger opens it.
Moving to a Specific Line
The Go to Line command searches for a line number in the active Source window. If the active window is not a Source window, you cannot use the Go to Line command.
To activate this option, click Go to Line on the Edit menu or press CTRL+L.
When the Go to Line dialog box appears, enter the line number that you want to find and then click OK. The debugger moves the cursor to that line. If the line number is
larger than the last line in the file, the cursor moves to the end of the file.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Cutting and Pasting Text

WinDbg uses many common methods of manipulating text and several methods that are less familiar.
Selecting Text
To select text in a Source window, in the Disassembly window, in either pane of the Debugger Command window, or in a dialog box, point to one end of the text, press and
hold the left mouse button, and drag the pointer to the other end of the text.
To select all of the text in a window, you can also click Select All on the Edit menu or press CTRL+A.
In the Calls window, Watch window, Locals window, Registers window, and Memory window, you cannot select an arbitrary span of text, but you can select a whole line or
cell. Click in the desired line or cell to select its text.
While you are entering text, press the DELETE and BACKSPACE keys to delete the text to the right or left of the cursor, respectively. If you select text, you can press these

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 93 of 1651

keys to delete the selection. If you select text and then type any characters, the new characters replace what you selected.
Copying Text
To copy text, select that text and then do one of the following:

Press the right mouse button. (This method works only in some locations. For more information about how to use the right mouse button, see The Right Mouse Button.)
Press CTRL+C.
Press CTRL+INSERT.
(Docked and tabbed windows only) Click Copy on the Edit menu.

Click the Copy (Ctrl+C) button (

) on the toolbar.

Cutting Text
To cut text and move it to the clipboard, select the text and then do one of the following:

Press CTRL+X.
Press SHIFT+DELETE.
(Docked and tabbed windows only) Click Cut on the Edit menu.

Click the Cut (Ctrl+X) button (

) on the toolbar.

You can cut text from the bottom pane of the Debugger Command window, from the left column of the Watch window, and from any dialog box (that is, from any location
that supports text entry).
Pasting Text
To paste text from the clipboard, put the cursor where you want to insert the text (or select the text that you want to replace) and then do one of the following:

Press the right mouse button. (This method works only in some locations, and you cannot use this method to replace text. For more inormation about how to use this
method, see The Right Mouse Button.)
Press CTRL+V.
Press SHIFT+INSERT.
(Docked and tabbed windows only) Click Paste on the Edit menu.

Click the Paste (Ctrl+V) button (

) on the tooblar.

You can paste text into the bottom pane of the Debugger Command window, into the left column of the Watch window, and into any dialog box (that is, into any location that
supports text entry).

Right Mouse Button

The right mouse button has several effects that can make copying and pasting much quicker:

If you select text in either pane of the Debugger Command window, in the Scratch Pad, in the Disassembly window, or in any Source window, and then you press the
right mouse button, the text is copied to the clipboard. However, if QuickEdit Mode has been deselected in View | Options, right-clicking in these locations will pop
up the menu most relevant to the current location.
If you put the cursor (without selecting any text) in either pane of the Debugger Command window, in the Scratch Pad, or in the text entry space of the Watch window,
and then you press the right mouse button, the contents of the clipboard are pasted into the window. However, if QuickEdit Mode has been deselected in View |
Options, right-clicking in these locations will pop up the menu most relevant to the current location.
If you put the cursor in any box and then press the right mouse button, a menu with Undo, Cut, Copy, Paste, and Select All options appears. You can choose any of
these options.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Changing Text Properties

You can customize the font that is used in all of the debugging information windows. You can also change the tab width that is used in the Source windows.
Setting the Font, Font Style, and Font Size
All debugging information windows share the same font. To change this font, click Font on the View menu, or click the Font button (

) on the toolbar.

In the Font dialog box, select the font, style, and size from the appropriate lists, and then click OK. All of the available fonts are fixed-pitch, because these kinds of fonts are
the most useful for viewing code.
Setting the Tab Width
To change the tab width settings, click Options on the View menu or click the Options button (

) on the toolbar.

The Options dialog box then appears. In the Tab width box, enter the number of spaces that the tab width should be equivalent to, and then click OK.
The tab settings affect the display of the code in any Source window.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 94 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Positioning the Windows

Each debugging information window can be floating or docked.
You can position floating windows separately from other windows. Docked windows are connected to the WinDbg window or to an independent dock. Each docked window
can occupy a unique position in its dock or can be combined with other docked windows in a tabbed collection.
This section includes the following topics:
Debugging with Floating and Docked Windows
Docking a Window
Tabbing a Window
Undocking a Window
Creating a New Dock
Resizing and Moving Windows
Arranging Windows
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging with Floating and Docked Windows

The features that are available in a debugging information window are not affected by whether the window is floating, docked, or docked in a tabbed collection.
Overview of the Window Configuration
A floating window is not connected to the WinDbg window or any other dock. Floating windows always appear directly in front of the WinDbg window.
A docked window occupies a fixed position within the WinDbg window or in a separate dock.
When two or more docked windows are tabbed together, they occupy the same position within the frame. You can see only one of these tabbed windows at one time. At the
bottom of each tabbed window collection is a set of tabs. The selected tab indicates which window in the collection is visible.
Making a Window Active
You can make any window active, regardless of its position. When a floating window is active, it appears in the foreground. When a window that is inside an additional dock
is active, that dock appears in the foreground. When a docked window within the WinDbg window is active, one or more floating windows might still obscure the docked
window.
To make a floating window or a docked window active, click its title bar. To make a docked window in a tabbed collection active, click its tab.
You can also make a window active by using the WinDbg menu or toolbar. You can activate any window by clicking the window name at the bottom of the Window menu.
You can also activate any window (other than a Memory window or a Source window) by clicking its name on the View menu or clicking its toolbar button.
Press CTRL+TAB to switch between debugging information windows. By pressing these keys repeatedly, you can scan through all of the windows, regardless of whether
they are floating, docked by themselves, or part of a tabbed collection of docked windows. When you release the CTRL key, the window that you are currently viewing
becomes active.
The ALT+TAB shortcut keys are the standard Microsoft Windows shortcut keys to switch between the windows on the desktop. You can use these shortcut keys to switch
between the WinDbg window and any additional docks that you have created. You can also make a dock active by clicking its button in the Windows taskbar.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Docking a Window
To dock a floating window, do one of the following:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 95 of 1651

Double-click the window's title bar.

Open the shortcut menu by right-clicking the window's title bar or clicking the window's icon in the upper-right corner, and then click Dock.
In the WinDbg window, on the Window menu, click Dock All. This command docks all of the windows except those that have the Always floating option selected on
their individual shortcut menus.
Drag the window to a docking location. This action causes the window to dock unless Always floating is selected on the shortcut menu for that window, or unless you
press and hold the ALT key as you begin dragging the window.

When you dock a window by any method other than dragging it, WinDbg automatically positions the docked window. If the window has never been docked before, WinDbg
moves the window to a new untabbed location within the WinDbg window. If the window has been docked before, WinDbg returns the window to its most recent docking
location, which might be tabbed or untabbed.
When you dock a window by dragging it, you can control its destination position. As you drag the window, you will see a semi-transparent outline of the window appear. This
outline shows where the window will be docked if you release the mouse button at that point. The following rules determine where a dragged window is docked:

If you drag the mouse pointer over the WinDbg window when the window is empty or over an empty dock, and then you release the mouse button, the dragged window
is docked in that location and completely fills the frame or dock.
If you drag the mouse pointer over the left, right, top, or bottom portion of an already-docked window and then you release the mouse button, the dragged window is
docked to the left, right, top, or bottom of the already-docked window, respectively.
When you drag the mouse pointer over a floating window (including the original position of the window that you are dragging), no docking occurs. This exception
means that you might have to drag other windows out of the way (or drag the current window two times) before you can move the window to where you want it.
If you drag the mouse pointer to a position that is not inside the WinDbg frame or any other dock and then you release the mouse button, the dragged window remains
floating.

All of the preceding rules apply to the mouse pointer location itself. They do not depend on where you originally clicked within the title bar of the window that you are
dragging.
Re-docking
If you let WinDbg automatically dock a floating window that was previously docked, WinDbg tries to put the window in the same docking position that it previously
occupied. Also, if you load a workspace, WinDbg tries to restore all of the debugging information windows to their previous positions, whether docked or floating.
However, multiple instances of Memory windows and Source windows are not distinguished when the docking position is saved. For example, if you combine the Locals
window together with a Memory window in a tabbed collection, and this state is saved and later restored, the Locals window joins a Memory window in a tabbed collection,
but it might not be the same Memory window as before.
If you load a workspace that includes one or more Source windows when the source files are inaccessible, those Source windows are not reopened. When this situation occurs,
other windows that were tabbed together with those windows might return to the floating state. If you want to keep all of your Source windows tabbed together, you should
include at least one source file that is always present, or include an additional window in the tabbed collection.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Tabbing a Window
To tab a floating or docked window, drag it on top of another docked window. Drag the window with the mouse pointer over the center of an already-docked window, and
then release the mouse button. The dragged window joins the already-docked window as a tabbed window collection.
All Source windows can be grouped automatically into a tabbed collection by selecting one Source window and designating it as the tab-dock target for all Source windows
by choosing the Set as tab-dock target for window type option in its short-cut menu. Once this is done, all future Source windows that are opened will automatically be
included in a tabbed collection with this first Source window. The Source window marked as the tab-dock target will not be closed when the Window | Close All Source
Windows menu command is selected. Thus you can set up a placeholder window for the Source windows without worrying that it will be closed when you don't want it to be.
The same process also works for Memory windows.
Note If you want a window to join another window in a tabbed window collection, watch the outline of the window that moves as you drag the window. When this outline
completely surrounds the window that you want to join, release the mouse button.
A set of tabs always controls the window immediately above the tabs. In the following illustration, the Debugger Command window is selected and is visible above the tabs.

Docked and tabbed Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 96 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Undocking a Window
To undock a window and make it a floating window, do one of the following:

Double-click the window's title bar.

Open the shortcut menu by right-clicking the window's title bar, right-clicking the window's tab if it is part of a tabbed collection, or clicking the window's icon in the
upper-right corner, and then click Undock.
In the WinDbg window, on the Window menu, click Undock All. This command changes all of the docked windows into floating windows.

When you undock a window by one of the preceding methods, the window returns to its previous undocked position.
You can also drag a docked window by clicking its title bar. This action enables you to move the window to a different docked position or undock it. (Dragging a docked
window to a new position works exactly like dragging a floating window to a new position. For more information about dragging a floating window to a new position, see
Docking a Window.)
When you try to undock or drag a tabbed window by any of these methods, only the active window in the tabbed collection is moved.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Creating a New Dock

When WinDbg is started, the WinDbg window is the only possible docking location.
To create a new dock, on the Window menu, click Open Dock. This dock is an independent window that you can maximize, minimize, or drag like any other window on the
desktop.
A new dock can also be created by using the Move to new dock option on the shortcut menu for any already open window. This selection will close the window and open it
in a new dock.
You can create as many docks as you want.
To close a dock and any debugging information windows that are currently docked there, click the Close button in the upper-right corner of the dock.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Resizing and Moving a Window

Floating windows are always associated with the WinDbg window. If you minimize WinDbg, all floating windows are minimized. And if you restore WinDbg, all floating
windows are restored. You can never put a floating window behind the WinDbg window.
Each floating window moves independently from each other and from the WinDbg window, unless you have selected Move with frame on the window's shortcut menu.
A docked window occupies a fixed position within the WinDbg frame. If you resize WinDbg, all of the docked windows are automatically scaled to the new size. The same
situation applies to windows that have been docked in a separate dock.
If you move the mouse pointer to the border between two docked windows, the mouse pointer becomes an arrow. By dragging this arrow, you can resize the two adjacent
windows and leave them in the docked state.
The WinDbg window is always filled with docked windows. There is never any empty area in the window unless there are no windows docked. The same situation applies to
independent docks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 97 of 1651

Arranging Windows
One useful window arrangement is to combine all of your Source windows into a single tabbed collection. The easiest way to do this is by marking your first source window
as the tab-dock target for all Source windows by selecting the Set as tab-dock target for window type option in the Source window's short-cut menu. Once this is done, all
future Source windows that are opened will automatically be included in a tabbed collection with this first Source window. The Source window marked as the tab-dock target
will not be closed when the Window | Close All Source Windows menu command is selected. Thus you can set up a placeholder window for the Source windows that will
only be closed when you want it to be.
This collection can occupy half of the WinDbg window or you can put it in a separate dock.
If you want each debugging information window to be completely separate, you can create one dock for each window. This arrangement enables you to minimize or
maximize each window separately.
If you want all of your windows to be floating, you should select Always floating on each window's shortcut menu so that you can drag each window independently to any
location.
Alternatively, you can use the MDI Emulation command on the Window menu. This command makes all of the windows floating windows and constrains them within the
frame window. This behavior emulates the behavior of WinDbg before the introduction of docking mode.
If you are using dual monitors, you can put the WinDbg window in one monitor and an extra dock in the other.
Some standard window arrangements for various debugging scenarios are included in the Debugging Tools for Windows package. For details on these arrangements, see
Using and Customizing WinDbg Themes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Workspaces
When you exit WinDbg, it saves your session configuration in a workspace. A workspace enables you to easily preserve your settings from one session to another. You can
also save or clear the workspaces manually, or even use a workspace to save a debugging session that is still in progress.
This section includes the following topics:
Creating and Opening a Workspace
Workspace Contents
Using and Customizing WinDbg Themes
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Creating and Opening a Workspace

WinDbg has two kinds of workspaces: default workspaces and named workspaces.
Default Workspaces
WinDbg has several different kinds of default workspaces:

The base workspace is used when WinDbg is in a dormant state.

The default user-mode workspace is used when you are attaching to a user-mode process (by using the -p command-line option or by using the File | Attach to a
Process command).
The remote default workspace is used when you are connecting to a debugging server.
The default kernel-mode workspace is used when WinDbg begins a kernel-mode debugging session.
The processor-specific workspace is used during kernel-mode debugging after WinDbg attaches to the target computer. There are separate processor-specific
workspaces for x86-based, Itanium-based, and x64-based processors.

When WinDbg creates a user-mode process for debugging, a workspace is created for that executable file. Each created executable file has its own workspace.
When WinDbg analyzes a dump file, a workspace is created for that dump file analysis session. Each dump file has its own workspace.
When you begin a debugging session, the appropriate workspace is loaded. When you end a debugging session or exit WinDbg, a dialog box is displayed and asks you if you
want to save the changes that you have made to the current workspace. If you start WinDbg with the -QY command-line option, this dialog box does not appear, and
workspaces are automatically saved. Also, if you start WinDbg by the -Q command-line option, this dialog box does not appear, and no changes are saved.
Workspaces load in a cumulative manner. The base workspace is always loaded first. When you begin a particular debugging action, the appropriate workspace is loaded. So
most debugging is completed after two workspaces have been loaded. Kernel-mode debugging is completed after three workspaces have been loaded (the base workspace, the
default kernel-mode workspace, and the processor-specific workspace).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 98 of 1651

For greatest efficiency, you should save settings in lower-level workspaces if you want them to apply to all of your WinDbg work.
Note The layout of the debugging information windows is one exception to the cumulative behavior of workspaces. The position, docking status, and size of each window are
determined by only the most recent workspace that you opened. This behavior includes the contents of the Watch window and the locations that you viewed in each Memory
window. The command history in the Debugger Command window is not cleared when a new workspace is opened, but all other window states are reset.
To access the base workspace, start WinDbg with no target, or click Stop Debugging on the Debug menu after your session is complete. You can then make any edits that are
allowed in the base workspace.
Named Workspaces
You can also give workspaces names and then save or load them individually. After you load a named workspace, all automatic loading and saving of default workspaces is
disabled.
Named workspaces contain some additional information that default workspaces do not. For more information about this additional information, see Workspace Contents.
Opening, Saving, and Clearing Workspaces
To control workspaces, you can do the following::

Open and load a named workspace by using the -W command-line option.

Open and load a workspace from a file by using the -WF command-line option.
Disable all automatic workspace loading by using the -WX command-line option. Only explicit workspace commands cause workspaces to be saved or loaded.
Open and load a named workspace by clicking Open Workspace on the File menu or pressing CTRL+W.
Save the current default workspace or the current named workspace by clicking Save Workspace on the File menu.
Assign a name to the current workspace and save it by clicking Save Workspace As on the File menu.
Delete specific items and settings from the current workspace by clicking Clear Workspace on the File menu.
Delete workspaces by clicking Delete Workspaces on the File menu.
Open and load a workspace from a file by clicking Open Workspace in File on the File menu.
Save a workspace to a file by clicking Save Workspace to File on the File menu.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Workspace Contents
Each workspace preserves the following information about the current debugging session. This information is applied cumulatively, starting with the base workspace and
ending with the most recently-loaded workspace.

All break and handling information for exceptions and events. For more information about the break and handling information, see Breakpoints in Workspaces.
All open source files. If a source file is not found, an error message appears. You can close these error messages individually or by using the Window | Close All Error
Windows command.
All user-defined aliases.

Each workspace preserves the following information about the debugger configuration settings. This information is applied cumulatively, starting with the base workspace
and ending with the most recently-loaded workspace.

The symbol path.

Introduction

Page 101 of 1651

Standard.reg Theme
Standardvs.reg
The Standardvs.reg theme can be used for most debugging purposes, but is more similar in layout to Visual Studio. In this arrangement, the WinDbg window is divided
horizontally into thirds. The upper third is further divided vertically into halves. The left half of the upper third contains a tabbed collection that includes the Watch, Locals,
Registers, Memory, Disassembly, and Scratchpad windows. The right half of the upper third contains a tabbed collection that includes the Calls and Processes and Threads
windows. The lower third of the WinDbg window is taken by the Debugger Command window. The middle third is filled by a placeholder window that indicates where the
Source windows are opened in a tabbed collection.
In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing
them may change the configuration of the windows. All of the windows in this arrangement are docked.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 102 of 1651

Standardvs.reg Theme
Srcdisassembly.reg
The Srcdisassembly.reg theme includes a Disassembly window, for debugging in assembly mode. In this arrangement, the WinDbg window is divided in half vertically, and
each half formed is further divided into thirds horizontally. On the right half, the upper third is a tabbed collection of the Locals and Watch windows, the middle third is the
Debugger Command window, and the lower third is a tabbed collection of the Processes and Threads and Calls windows. On the left half, the upper two-thirds are taken by a
placeholder window that indicates where the Source windows opens in a tabbed collection; the lower third is taken up by the Disassembly window.
In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing
them may change the configuration of the windows. All of the windows in this arrangement are docked.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 103 of 1651

Srcdisassembly.reg Theme
Multimon.reg
The Multimon.reg theme is set up for debugging with multiple monitors. In this arrangement, a new dock is created so that the WinDbg window can be viewed on one
monitor and the new dock can be viewed on the other monitor. The WinDbg window is filled by a placeholder window that indicates where the Source windows open in a
tabbed collection. The new dock is divided into fourths. The upper left contains a tabbed collection that includes the Watch and Locals windows. The upper right contains a
tabbed collection that includes the Registers, Memory, Disassembly, Scratchpad, and Processes and Threads windows. The lower left contains the Debugger Command
window. The lower right contains the Calls window.
In each docking location, a placeholder window is also included as a point of reference for the other windows. The placeholder windows should not be closed because closing
them may change the configuration of the windows. All of the windows in this arrangement are docked.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 104 of 1651

Multimon.reg Theme
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the Toolbar and Status Bar

The toolbar appears underneath the menu bar, near the top of the WinDbg window. The status bar appears at the bottom of the WinDbg window.
Using the Toolbar

Toolbar
The toolbar buttons have various effects. Most of them are equivalent to menu commands. To execute the command that is associated with a toolbar button, click the toolbar
button. When you cannot use a button, it appears unavailable.
For more information about each button, see Toolbar Buttons.
Using the Status Bar

Status bar
The following table describes the sections of the WinDbg status bar.
Section
Description
Message Displays messages from the debugger.
Ln, Col Displays the line number and column number at the cursor in the active Source window.
Sys
Shows the internal decimal number of the system that you are debugging, followed by its computer name (or <Local> if it is the same as the computer as the
debugger is running on).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Proc
Thrd
ASM
OVR
CAPS
NUM

Page 105 of 1651

Shows the internal decimal number of the process that you are debugging, followed by its hexadecimal process ID.
Shows the internal decimal number of the thread that you are debugging, followed by its hexadecimal thread ID.
Indicates that WinDbg is in assembly mode. If ASM is unavailable, WinDbg is in source mode.
Indicates that overtype mode is active. If OVR is unavailable, insert mode is active.
Indicates that CAPS LOCK is on.
Indicates that NUM LOCK is on.

Hiding the Toolbar or Status Bar

To display or hide the toolbar, select or clear Toolbar on the View menu. To display or hide the status bar, select or clear Status Bar on the View menu.
If you hide the toolbar or the status bar, you have more space for debugging information windows in the WinDbg display area.
Setting the Window Title
You can change the title of the WinDbg window by using the .wtitle (Set Window Title) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the Help Documentation

The WinDbg Help documentation that you are reading is the documentation for the Debugging Tools for Windows package.
This documentation uses the viewer that is supplied with Microsoft HTML Help (hh.exe). This viewer provides a table of contents and index and enables you to search
through the documentation, mark your favorite or frequently used topics, and print one or more topics.
The following sections in this topic describe the features of and how to use the Help documentation.
Contents Tab
The Contents tab provides an expandable view of the documentation's table of contents.
Click the plus sign (+) next to a node or double-click the node's title to expand or contract the table of contents under that node.
Index Tab
The Index tab displays the complete index of terms that are used in this documentation. You can enter the beginning of a term or use the scrollbar to look through this index.
Search Tab
In the Search tab, you can search for any word or phrase that is contained in the documentation. You can search all text or limit your search to topic titles.
To search for phrases that contain more than one word, enclose the phrase in quotation marks. You can connect multiple words and phrases with the AND, OR, and NOT
operators. The default operator is AND.
Note that "AND NOT" is invalid. To search for topics that contain x and not y, use "x NOT y". You can also use NEAR in searches.
Wildcard characters are also permitted. Use a question mark (?) to represent any single character and an asterisk (*) to represent zero or more characters. However, you
cannot use wildcard characters within quoted strings.
All letters and numbers are treated literally, but some symbols are not permitted in searches.
A search returns a list of all topics that match the specified criteria. If you select the Search previous results box, you can then search these results for more terms.
Favorites Tab
In the Favorites tab, you can save the titles of commonly-visited topics. While you are viewing a topic, click the Favorites tab and then click the Add button.
To rename a page on your favorites list, click its name two times slowly, and retype the name. To view a topic on the Favorites list, double-click its name or click it one time
and then click Display. To remove a topic from the favorites list, click it one time and then click Remove.
Printing Topics
To print one or more topics, click a topic in the Contents tab, and then click the Print button on the toolbar. You will be asked whether you want to print only the selected
topic or that topic and all of its subtopics.
You can also print the topic that you are viewing by right-clicking within the view window, and clicking Print on the shortcut menu. However, this method does not enable
you to print subtopics.
Searching Within a Topic
To search for a text string within the topic that you are viewing, press CTRL+F, or click Find in this Topic on the Edit menu.
Accessing the Help Documentation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 106 of 1651

To open this Help documentation, do one of the following:

Click Start, point to All Programs, point to Debugging Tools for Windows, and then click Debugging Help.
Open Windows Explorer, locate the Debugger.chm file, and then double-click it.
At a command prompt, browse to the folder that contains Debugger.chm and run hh debugger.chm.
In any Windows debugger, use the .hh (Open HTML Help File) command.
In WinDbg, click Contents on the Help menu. This command open the Help documentation and opens the Contents tab.
In WinDbg, click Index on the Help menu. This command open the Help documentation and opens the Index tab.
In WinDbg, click Search on the Help menu. This command opens the Help documentation and opens the Search tab.
Many dialog boxes in WinDbg have Help buttons. Click Help to open this documentation and open the relevant page.

Updating This Help Documentation

To obtain an updated version of this Help documentation, you should install the most recent version of Debugging Tools for Windows. For more information about how to
install this tool, see Installing from the Web.
Warning When you update the documentation, you will lose any favorites that you added.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring the Debugger

This section includes the following:
Keeping a Log File
Specifying Module and Function Owners
Controlling Exceptions and Events
Setting Paths and Loading Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using a Log File

The debugger can write a log file that records the debugging session. This log file contains all of the contents of the Debugger Command window, including the commands
that you type and the responses from the debugger.
In WinDbg, some menu and toolbar actions cause a display to appear in the Debugger Command window. The log file does not record actions that do not generate text in this
window.
Opening a New Log File
To open a new log file, or to overwrite a previous log file, do one of the following:

(CDB and KD only) Before you start the debugger, set the _NT_DEBUG_LOG_FILE_OPEN environment variable.
When you start the debugger, use the -logo command-line option.
Use the .logopen (Open Log File) command. If you use the /t option, the date and time are appended to your specified file name. If you use the /u option, the log file is
written in Unicode instead of in ASCII.
(WinDbg only) Use the Edit | Open/Close Log File command.

Appending to an Existing Log File

To append command window text to a log file, do one of the following:

(CDB and KD only) Before you start the debugger, set the _NT_DEBUG_LOG_FILE_APPEND environment variable.
When you start the debugger, use the -loga command-line option.
Use the .logappend (Append Log File) command. If you are appending to a Unicode log file, you must use the /u option.
(WinDbg only) Use the Edit | Open/Close Log File command, and then selct Append.

Controlling Exceptions and Events from the Debugger

You can configure the debugger to react to specified exceptions and events in a specific way.
The debugger can set the break status for each exception or event:

The event can cause a break into the debugger as soon as it occurs (the "first chance").
The event can break in after other error handlers have been given an opportunity to respond (the "second chance").
The event can also send the debugger a message but continue executing.
The debugger can ignore the event.

The debugger can also set the handling status for each exception and event. The debugger can treat the event like a handled exception or an unhandled exception. (Of course,
events that are not actually errors do not require any handling.)
You can control the break status and handling status by doing one of the following:

Use the SXE, SXD, SXN, or SXI command in the Debugger Command window.
(CDB only) Use the -x, -xe, -xd, -xn, or -xi option on the CDB command line.
(CDB only) Use the sxe or sxd keyword in the Tools.ini file.
(WinDbg only) Click Event Filters on the Debug menu to open the Event Filters dialog box, and then choose the options that you want.

The SX* command, the -x* command-line option, and the sx* Tools.ini keyword typically set the break status of the specified event. You can add the -h option to cause the
handling status to be set instead.
There are four special event codes (cc, hc, bpec, and ssec) that always specify handling status instead of break status.
You can display the most recent exception or event by using the .lastevent (Display Last Event) command.
Controlling Break Status
When you set the break status of an exception or event, you can use the following options.
Command Status name
SXE
Break
or
-xe
(Enabled)
SXD
or
-xd

Description
When this exception occurs, the target immediately breaks into the debugger. This break in occurs before any other error handlers are activated.
This method is called first-chance handling.

Second chance The debugger does not break in for this kind of first-chance exception (although a message is displayed). If other error handlers cannot address
break
this exception, execution stops and the target breaks into the debugger. This method is called second-chance handling.
(Disabled)

SXN
or
-xn

Output

SXI
or
-xi

Ignore

When this exception occurs, the target application does not break into the debugger at all. However, a message is displayed that informs the
user of this exception.

(Notify)
When this exception occurs, the target application does not break into the debugger, and no message is displayed.

If an exception is not anticipated by an SX* setting, the target application breaks into the debugger on the second chance. The default status for events is listed in the
following "Event Definitions and Defaults" section of this topic.
To set break status by using the WinDbg graphical interface, Event Filters on the Debug menu, click the event that you want from the list in the Event Filters dialog box,
and then select Enabled, Disabled, Output, or Ignore.
Controlling Handling Status
All events are considered unhandled, unless you use the gh (Go with Exception Handled) command.
All exceptions are considered unhandled, unless you use the sx* command together with the -h option.
Additionally, SX* options can configure the handling status for invalid handles, STATUS_BREAKPOINT break instructions, and single-step exceptions. (This configuration
is separate from their break configuration.) When you configure their break status, these events are named ch, bpe, and sse, respectively. When you configure their handling
status, these events are named hc, bpec, and ssec, respectively. (For the full listing of events, see the following "Event Definitions and Defaults" section.)
You can configure the handling status for the CTRL+C event (cc), but not its break status. If an application receives a CTRL+C event, the application always breaks into the
debugger.
When you use the SX* command on cc, hc, bpec, and ssec events, or when you use the SX* command together with the -h option on an exception, the following actions
occur.
Command Status name
Description
SXE
Handled
The event is considered handled when execution resumes.
SXD,
Not Handled The event is considered not handled when execution resumes.
SXN,
SXI
To set handling status by using the WinDbg graphical interface, click Event Filters on the Debug menu, click the event that you want from the list in the Event Filters dialog
box, and then select Handled or Not Handled.
Automatic Commands

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 110 of 1651

The debugger also enables you to set commands that are automatically executed if the event or exception causes a break into the debugger. You can set a command string for
the first-chance break and a command string for the second-chance break. You can set these strings with the SX* command or the Debug | Event Filters command. Each
command string can contain multiple commands that are separated with semicolons.
These commands are executed regardless of the break status. That is, if the break status is "Ignore," the command is still executed. If the break status is "Second-chance
break," the first-chance command is executed when the exception first occurs, before any other exception handlers are involved. The command string can end with an
execution command such as g (Go), gh (Go with Exception Handled), or gn (Go with Exception Not Handled).
Event Definitions and Defaults
You can change the break status or handling status of the following exceptions. Their default break status is indicated.
The following exceptions' default handling status is always "Not Handled". Be careful about changing this status. If you change this status to "Handled", all first-chance and
second-chance exceptions of this type are considered handled, and this configuration bypasses all of the exception-handling routines.
Event code
asrt
Assertion failure
av
Access violation
dm
Data misaligned
dz
Divide by zero
eh
C++ EH exception
gp
Guard page violation
ii
Illegal instruction
iov
Integer overflow
ip
In-page I/O error
isc
Invalid system call
lsq
Invalid lock sequence
sbo
Stack buffer overflow
sov
Stack overflow
wkd
Wake debugger
aph
Application hang

Meaning

Default break status

Break
Break
Break
Break
Second-chance break
Break
Second-chance break
Break
Break
Break
Break
Break
Break
Break
Break

This exception is triggered if the Windows operating system concludes that a process has stopped responding (that is, is hung).
3c
ch
hc
Number

Child application termination

Invalid handle

Second-chance break
Break

Any numbered exception

Second-chance break

Note You can override the asrt break status for a specific address by using the ah (Assertion Handling) command. The ch and hc event codes refer to the same exception.
When you are controlling its break status, use sx* ch. When you are controlling its handling status, use sx* hc.
You can change the break status or handling status of the following exceptions. Their default break status is indicated.
The following exceptions' default handling status is always "Handled". Because these exceptions are used to communicate with the debugger, you should not typically change
their status to "Not Handled". This status causes other exception handlers to catch the exceptions if the debugger ignores them.
An application can use DBG_COMMAND_EXCEPTION (dbce) to communicate with the debugger. This exception is similar to a breakpoint, but you can use the SX*
command to react in a specific way when this exception occurs.
Event code
Meaning
Default break status
dbce
Special debugger command exception
Ignore
vcpp
Special Visual C++ exception
Ignore
wos
WOW64 single-step exception
Break
wob
WOW64 breakpoint exceptionBreak
sse
Single-step exception
Break
ssec
bpe
Breakpoint exception
Break
bpec
cce
CTRL+C or CTRL+BREAK
Break
cc
This exception is triggered if the target is a console application and CTRL+C or CTRL+BREAK is passed to it.

Note The final three exceptions in the preceding table have two different event codes. When you are controlling their break status, use sse, bpe, and cce. When you are
controlling their handling status, use ssec, bpec, and cc.
You can change the break status of the following events. Because these events are not exceptions, their handling status is irrelevant.
Event
Meaning
code
ser
System error
cpr
Process creation
[:Process]
Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel
mode.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Default break status

Ignore
Ignore

9/18/2010

Introduction

Page 111 of 1651

You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either
through the -o command-line option or through the .childdbg (Debug Child Processes) command.
The process name can include an optional file name extension and an asterisk (*) or question mark (?) as
wildcard characters. The debugger remembers only the most recent cpr setting. Separate settings for separate
processes are not supported. Include a colon or a space between cpr and Process.
If Process is omitted, the setting applies to any child process creation.
epr
Process exit
[:Process]
Setting the break status of this event applies only to user-mode debugging. This event does not occur in kernel
mode.

Ignore

You can control this event only if you have activated debugging of child processes in CDB or WinDbg, either
through the -o command-line option or through the .childdbg (Debug Child Processes) command.
The process name can include an optional file name extension and an asterisk (*) or question mark (?) as
wildcard characters. The debugger remembers only the most recent epr setting. Separate settings for separate
processes are not supported. Include a colon or a space between epr and Process.
If Process is omitted, the setting applies to any child process exit.
ct
Thread creation
et
Thread exit
ld
Load module
[:Module]
If you specify Module, the break occurs when the module with this name is loaded. Module can specify the
name or the address of the module. If the name is used, Module might contain a variety of wildcard characters
and specifiers. (For more information about the syntax, see String Wildcard Syntax.)

Ignore
Ignore
Output

The debugger remembers only the most recent ld setting. Separate settings for separate modules are not
supported. Include a colon or a space between ld and Module.
If Module is omitted, the event is triggered when any module is loaded.
Output
ud
Unload module
[:Module]
If you specify Module, the break occurs when the module with this name, or at this base address, is unloaded.
Module can specify the name or the address of the module. If the name is used, Module can be an exact name or
include wildcard characters. If Module is an exact name, it is immediately resolved to a base address by using
the current debugger module list and it is stored as an address. If Module contains wildcard characters, the
pattern string is kept for later matching when unload events occur.
Rarely, the debugger does not have name information for unload events and matches only by the base address.
Therefore, if Module contains wildcard characters, the debugger cannot perform a name match in this particular
unload case and breaks when any module is unloaded.
The debugger remembers only the most recent ud setting. Separate settings for separate modules are not
supported. Include a colon or a space between ld and Module.
If Module is omitted, the event is triggered when any module is loaded.
out
Target application output
Ignore
[:Output]
If you specify Output, the break occurs only when output that matches the specified pattern is received. Output
can contain a variety of wildcard characters and specifiers. (For more information about the syntax, see String
Wildcard Syntax.) However, Output cannot contain a colon or spaces. The match is not case sensitive. Include a
colon or space between out and Output.
ibp

Initial break point

(This event occurs at the beginning of the debug session and after you restart the target computer.)

In user mode: Break. You can change this status

to "Ignore" by using the -g command-line
option.
In kernel mode: Ignore. You can change this
status to "Enabled" by a variety of methods. For
more information about how to change this
status, see Crashing and Rebooting the Target
Computer.

iml

Initial module load

(Kernel mode only)

Ignore. You can change this status to "Break"

by a variety of methods. For more information
about how to change this status, see Crashing
and Rebooting the Target Computer.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 112 of 1651

Setting Paths and Loading Files

To debug effectively, the debugger should have access to as much information about the target computer or target application as possible.
In many situations, the debugger can locate the files that it requires on its own. But if it cannot locate all of the files that it requires, you can set the appropriate path to direct
the debugger to the appropriate files. You can also load source files at any time, regardless of the source path.
This section includes the following topics:
Executable Image Path
Symbol Path
Using a Symbol Server
Source Path
Using a Source Server
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Executable Image Path

An executable file is a binary file that the processor can run. These files typically have the .exe, .dll, or .sys file name extension. Executable files are also known as modules,
especially when executable files are described as units of a larger application. Before the Microsoft Windows operating system runs an executable file, it loads it into memory.
The copy of the executable file in memory is called the executable image or the image.
Note These terms are sometimes used imprecisely. For example, some documents might use "image" for the actual file on the disk. Also, Windows-based applications refer
to the executable name, which typically includes the file name extension. But these applications refer to the module name, which does not include the file name extension.
Also, the Windows kernel and HAL have special module names. For example, the nt module corresponds to the Ntoskrnl.exe file.
The executable image path specifies the directories that the binary executable files are located in.
In most situations, the debugger knows the location of the executable files, so you do not have to set the path for this file.
However, there are situations when this path is required. For example, kernel-mode small memory dump files do not contain all of the executable files that exist in memory at
the time of a stop error (that is, a crash). Similarly, user-mode minidump files do not contain the application binaries. If you set the path of the executable files, the debugger
can find these binary files.
Executable Image Path Syntax
The debugger's executable image path is a string that consists of multiple directory paths, separated by semicolons.
Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path.
Network shares are also supported.
The debugger searches the executable image path recursively. That is, the debugger searches the subdirectories of each directory that is listed in this path.
Controlling the Executable Image Path
To control the executable image path, you can do one of the following:

Before you start the debugger, use the _NT_EXECUTABLE_IMAGE_PATH environment variable to set the path. If you try to add an invalid directory through this
environment variable, the debugger ignores this directory.
When you start the debugger, use the -i command-line option to set the path.
Use the .exepath command to display, set, change, or append to the path.
(WinDbg only) Use the File | Image File Path command or press CTRL+I to display, set, change, or append to the path.

If you use the -sins command-line option, the debugger ignores the executable image path environment variable.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Path
The symbol path specifies the directories where the symbol files are located. For more information about symbols and symbol files, see Symbols.
Some compilers (such as Microsoft Visual Studio) put symbol files in the same directory as the binary files. The symbol files and the checked binary files contain path and

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 113 of 1651

file name information. This information frequently enables the debugger to find the symbol files automatically. If you are debugging a user-mode process on the computer
where the executable was built, and if the symbol files are still in their original location, the debugger can locate the symbol files without you setting the symbol path.
In most other situations, you have to set the symbol path to point to your symbol file locations.
Symbol Path Syntax
The debugger's symbol path is a string that consists of multiple directory paths, separated by semicolons.
Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path.
Network shares are also supported.
For each directory in the symbol path, the debugger looks in three directories. For example, if the symbol path includes the c:\MyDir directory, and the debugger is looking
for symbol information for a DLL, the debugger first looks in c:\MyDir\symbols\dll, then in c:\MyDir\dll, and finally in c:\MyDir. The debugger then repeats this process for
each directory in the symbol path. Finally, the debugger looks in the current directory and then in the current directory with \dll appended to it. (The debugger appends dll,
exe, or sys, depending on which binaries it is debugging.)
However, because symbol files have date and time stamps, you do not have to worry that the debugger will use the wrong symbols because they are the symbols found first in
this sequence. The debugger always looks for the symbols that match the time stamp on the binary files that it is debugging. For more information about responses in case the
symbols files are not available, see Compensating for Symbol-Matching Problems.
Note If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the
srv* or symsrv* string within your symbol path. For more information about symbol servers, see Symbol Stores and Symbol Servers.
Lazy Symbol Loading
The debugger's default behavior is to use lazy symbol loading (also known as deferred symbol loading). This kind of loading means that symbols are not loaded until they are
required. However, if the symbol path is changed, all already-loaded symbols are immediately reloaded. For more information about lazy symbol loading and how to activate
and deactivate it, see Deferred Symbol Loading.
You can turn off lazy symbol loading in CDB and KD by using the -s command-line option. You can also force symbol loading by using the ld (Load Symbols) command or
by using the .reload (Reload Module) command together with the /f option.
Controlling the Symbol Path
To control the symbol path, you can do one of the following:

Before you start the debugger, use the _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH environment variables to set the path. The symbol path is created by
appending _NT_SYMBOL_PATH after _NT_ALT_SYMBOL_PATH. (Typically, the path is set through the _NT_SYMBOL_PATH. However, you might want to use
_NT_ALT_SYMBOL_PATH to override these settings in special cases, such as if you have private versions of shared symbol files.) If you try to add an invalid
directory through these environment variables, the debugger ignores this directory.
When you start the debugger, use the -y command-line option to set the path.
Use the .sympath command to display, set, change, or append to the path. If you are using a source server, the .symfix (Set Symbol Store Path) command is similar
to .sympath but saves you typing.
(WinDbg only) Use the File | Symbol File Path command or press CTRL+S to display, set, change, or append to the path.

If you use the -sins command-line option, the debugger ignores the symbol path environment variable.
cache*localsymbolcache
If you include the string cache*localsymbolcache in your symbol path, the specified directory localsymbolcache will be used to store any symbols loaded from any element
that appears in your symbol path to the right of this string. This allows you to use a local cache for symbols downloaded from any location, not just those downloaded by a
symbol server.
For example, if you set your symbol path with the following .sympath command, the directory c:\mysymbols will be used to store files from both of the \\private shares, but
not from \\someshare:

.sympath \\someshare\that\cachestar\ignores;cache*c:\mysymbols;\\private\binary\symbol\location;\\private\test\build\symbol\share
This can be easily combined with the Microsoft public symbol store by using the following initial setting:
_NT_SYMBOL_PATH=srv*c:\mysymbols*http://msdl.microsoft.com/download/symbols;cache*c:\mysymbols
After this, you can expand the symbol path with the .sympath+ command, which will append additional locations to the right of the current path. Symbols from these new
locations will be cached in c:\mysymbols because they are listed to the right of the cache* string in the path; symbols from the symbol server will be stored in c:\mysymbols
because of the usual syntax used by the symbol server (see Using a Symbol Server).
Using AgeStore to Reduce the Cache Size
You can use the AgeStore tool to delete cached files that are older than a specified date, or to delete enough old files that the resulting size of the cache is less than a specified
amount. This can be useful if your downstream store is too large. For details, see AgeStore.
For more information about symbol servers and symbol stores, see Symbol Stores and Symbol Servers.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 114 of 1651

Using a Symbol Server

A symbol server enables the debugger to automatically retrieve the correct symbol files from a symbol store an indexed collection of symbol files without the user needing
to know product names, releases, or build numbers. The Debugging Tools for Windows package includes the symbol server SymSrv (symsrv.exe).
Using SymSrv with a Debugger
SymSrv can be used with WinDbg, KD, NTSD, or CDB.
To use this symbol server with the debugger, simply include the text srv* in the symbol path. For example:
set _NT_SYMBOL_PATH = srv*DownstreamStore*SymbolStoreLocation
where DownstreamStore specifies the local directory or network share that will be used to cache individual symbol files, and SymbolStoreLocation is the location of the
symbol store either in the form \\server\share or as an internet address. For more syntax options, see Advanced SymSrv Use.
Microsoft has a Web site that makes Windows symbols publicly available. You can refer directly to this site in your symbol path in the following manner:
set _NT_SYMBOL_PATH=srv*DownstreamStore*http://msdl.microsoft.com/download/symbols
where, again, DownstreamStore specifies the local directory or network share that will be used to cache individual symbol files. For more information, see Microsoft Public
Symbols.
If you plan to create a symbol store, configure a symbol store for web (HTTP) access, or write your own symbol server or symbol store, see Symbol Stores and Symbol
Servers.
Using AgeStore to Reduce the Cache Size
Any symbol files downloaded by SymSrv will remain on your hard drive after the debugging session is over. To control the size of the symbol cache, the AgeStore tool can be
used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. For details, see AgeStore.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Source Path
The source path specifies the directories where the C and C++ source files are located.
If you are debugging a user-mode process on the computer where the executable file was built, and if the source files are still in their original location, the debugger can
automatically locate the source files.
In most other situations, you have to set the source path or load the individual source files.
When you are performing remote debugging through the debugger, the debugging server uses the source path. If you are using WinDbg as your debugger, each debugging
client also has its own local source path. All source-related commands access the source files on the local computer. You have to set the proper paths on any client or server
that you want to use source commands.
This multiple-path system also enables a debugging client to use source-related commands without actually sharing the source files with other clients or with the server. This
system is useful if there are private or confidential source files that one of the users has access to.
You can also load source files at any time, regardless of the source path.
Source Path Syntax
The debugger's source path is a string that consists of multiple directory paths, separated by semicolons.
Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path.
Network shares are also supported.
Note If you are connected to a corporate network, the most efficient way to access source files is to use a source server. You can use a source server by using the srv* string
within your source path. For more information about source servers, see Using a Source Server.
Controlling the Source Path
To control the source path and local source path, you can do one of the following:

Before you start the debugger, use the _NT_SOURCE_PATH environment variable to set the source path. If you try to add an invalid directory through this
environment variable, the debugger ignores this directory.
When you start the debugger, use the -srcpath command-line option to set the source path.
Use the .srcpath (Set Source Path) command to display, set, change, or append to the source path. If you are using a source server, .srcfix (Use Source Server) is
slightly easier.
(WinDbg only) Use the .lsrcpath (Set Local Source Path) command to display, set, change, or append to the local source path. If you are using a source server,
.lsrcfix (Use Local Source Server) is slightly easier. You can also use the WinDbg Command-Line with the parameter lscrpath. For more information, see WinDbg
Command-Line Options.
(WinDbg only) Use the File | Source File Path command or press CTRL+P to display, set, change, or append to the source path or the local source path.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 115 of 1651

You can also directly open or close a source file by doing one of the following:

Use the lsf (Load or Unload Source File) command to open or close a source file.
(WinDbg only) Use the .open (Open Source File) command to open a source file.
(WinDbg only) Use the File | Open Source File command or press CTRL+O to open a source file. You can also use the Open source file (Ctrl+O) button (
toolbar.

) on the

Note When you use File | Open Source File (or its shortcut menu or button equivalents) to open a source file, the path of that file is automatically appended to the
source path.

(WinDbg only) Use the File | Recent Files command to open one of the four source files that you most recently opened in WinDbg.
(WinDbg only) Use the File | Close Current Window command or click the Close button in the corner of the Source window to close a source file.

For more information about how to use source files, see Debugging in Source Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using a Source Server

A source server enables the debugger to automatically retrieve the source files that match the current target. To use a source server, you must be debugging binaries that have
been source indexed at build time and whose source file locations are embedded in the PDB files.
Debugging Tools for Windows includes the source server SrcSrv (Srcsrv.exe). For technical information about this tool, see SrcSrv.
Using SrcSrv with a Debugger
SrcSrv can be used with WinDbg, KD, NTSD, or CDB.
To use this source server with the debugger, include the text srv* in the source path, followed by the directory specification or UNC path of the source store:
srv*SourceStoreLocation
For example:
.srcpath srv*\\myserver\myshare;c:\mylocaldir
This example also includes a local source path element (c:\mylocaldir). Regardless of whether srv* is the first element in the path or appears later, the source server will
always be searched before any other source path elements. If SrcSrv is unable to access the source file or discover its location, the other paths will be searched by the
debugger.
If a source file is retrieved by the source server, it will remain on your hard drive after the debugging session is over. Source files are stored locally in the src subdirectory of
the home directory (unlike the symbol server, the source server does not specify a local cache in the srv* syntax itself). The home directory defaults to the debugger
installation directory; it can be changed by using the !homedir extension or by setting the DBGHELP_HOMEDIR environment variable. If this subdirectory does not already
exist, it will be created.
If you use the .open (Open Source File) command to open a new source file through SrcSrv, you must include the -m Address parameter.
For information on how to index your sources, or if you plan to create your own source control provider module, see SrcSrv.
Using AgeStore to Reduce the Cache Size
Any source files downloaded by SrcSrv will remain on your hard drive after the debugging session is over. To control the size of the source cache, the AgeStore tool can be
used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. For details, see AgeStore.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Operation (General)

This section includes the following topics:
Controlling the Target
Using Breakpoints
Reading and Writing Memory
Reading and Writing Registers and Flags

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 116 of 1651

Viewing the Call Stack

Debugging in Assembly Mode
Debugging in Source Mode
Debugging BIOS Code
Debugging Multiple Targets
Ending the Debugging Session
Debug Privilege
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling the Target

While you are debugging a target application in user mode or a target computer in kernel mode, the target can be running or stopped.
When the debugger connects to a kernel-mode target, the debugger leaves the target running, unless you use the -b command-line option, the target system has stopped
responding (that is, crashed), or the target system is still stopped because of an earlier kernel debugging action.
When the debugger starts or connects to a user-mode target, the debugger immediately stops the target, unless you use the -g command-line option. For more information, see
Initial Breakpoint.
When the Target is Running
When the target is running, most debugger actions are unavailable.
If you want to stop a running target, you can issue a Break command. This command causes the debugger to break into the target. That is, the debugger stops the target and
all control is given to the debugger. The application might not break immediately. For example, if all threads are currently executing system code, or are in a wait operation,
the application breaks only after control has returned to the application's code.
If a running target encounters an exception, if certain events occur, if a breakpoint is hit, or if the application closes normally, the target breaks into the debugger. This action
stops the target and gives all control to the debugger. A message appears in the Debugger Command window and describes the error, event, or breakpoint.
When the Target is Stopped
To start or control the target's execution, you can do the following:

To cause the application to begin running, issue the Go command.

To step through the application one instruction at a time, use the Step Into or Step Over commands. If a function call occurs, Step Into enters the function and
continues stepping through each instruction. Step Over treats the function call as a single step. When the debugger is in Assembly Mode, stepping occurs one machine
instruction at a time. When the debugger is in Source Mode, stepping occurs one source line at a time.
To finish the current function and stop when the return occurs, use the Step Out or Trace and Watch commands. The Step Out command continues until the current
function ends. Trace and Watch continues until the current function ends and also displays a summary of the function's calls. However, you must issue the Trace and
Watch command on the first instruction of the function in question. On Itanium-based processors, Trace to Next Branch runs until it encounters a branch instruction.
If an exception occurs, you can use the Go with Exception Handled and Go with Exception Not Handled commands to resume execution and control the status of the
exception. (For more information about exceptions, see Controlling Exceptions and Events.)
(WinDbg only) If you select a line in the Disassembly window or a Source window and then use the Run to Cursor command, the program runs until it encounters the
selected line.
(User Mode only) To close the target application and restart it from the beginning, use the Restart command. You can use this command only with a process that the
debugger created. After the process is restarted, it immediately breaks into the debugger.
(WinDbg only) To close the target application and clear the debugger, use the Stop Debugging command. This command enables you to start debugging a different
target.

Command Forms
Most commands for starting or controlling the targets execution exist as text commands, menu commands, toolbar buttons, and shortcut keys. As basic text commands, you
can use these commands in CDB, KD, or WinDbg. (The text form of the commands frequently supports additional options, such as changing the location of the program
counter or executing a fixed number of instructions.) You can use the menu commands, toolbar buttons, and shortcut keys in WinDbg.
You can use the commands in the following forms.
Command

WinDbg
button

WinDbg
command
Debug | Run to
Cursor

WinDbg
shortcut
keys
F7

Effect

(WinDbg only) Executes until it reaches the line that the cursor marks.

CTRL + F10

(CDB/KD only)
CTRL+C

Debug | Stop
Debugging
Debug | Break

SHIFT + F5

Stops all debugging and closes the target.

CTRL +
BREAK

Execution stops, and the debugger breaks into the target.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

.restart (Restart
Target Application)
g (Go)
gc (Go from
Conditional
Breakpoint)
gh (Go with
Exception Handled)

Page 117 of 1651

Debug | Restart
Debug | Go

CTRL +
SHIFT + F5
F5

(User mode only) Restarts the target application.

Target executes freely.
Resumes execution after a conditional breakpoint.

gn (Go with
Exception Not
Handled)
gu (Go Up)

Debug | Go
Same as g (Go), except that the current exception is treated as handled.
Handled
Exception
Same as g (Go), except that the current exception is treated as unhandled.
Debug | Go
Unhandled
Exception
Debug | Step Out SHIFT + F11 Target executes until the current function is complete.

p (Step)

Debug | Step Over F10

pa (Step to Address)
pc (Step to Next Call)
pct (Step to Next Call
or Return)
ph (Step to Next
Branching
Instruction)
pt (Step to Next
Return)
t (Trace)

Target executes one instruction. If this instruction is a function call, that function is executed as a
single step.
Target executes until it reaches the specified address. All steps in this function are displayed (but
steps in called functions are not).
Target executes until the next call instruction. If the current instruction is a call instruction, this call is
executed completely and execution continues until the next call.
Target executes until it reaches a call instruction or a return instruction.
Target executes until it reaches any kind of branching instruction, including conditional or
unconditional branches, calls, returns, and system calls.
Target executes until it reaches a return instruction.

Debug | Step Into F11

Target executes one instruction. If this instruction is a function call, debugger traces into that call.

F8
ta (Trace to Address)
tb (Trace to Next
Branch)
tc (Trace to Next
Call)
tct (Trace to Next
Call or Return)
th (Trace to Next
Branching
Instruction)
tt (Trace to Next
Return)
wt (Trace and Watch
Data)

Target executes until it reaches the specified address. All steps in this function and called functions
are displayed.
(All modes, except kernel mode, only on x86-based systems) Target executes until it reaches the next
branch instruction.
Target executes until the next call instruction. If the current instruction is a call instruction, the
instruction is traced into until a new call is reached.
Target executes until it reaches a call instruction or return instruction. If the current instruction is a
call instruction or return instruction, the instruction is traced into until a new call or return is
reached.
Target executes until it reaches any kind of branching instruction, including conditional or
unconditional branches, calls, returns, and system calls. If the current instruction is a branching
instruction, the instruction is traced into until a new branching instruction is reached.
Target executes until it reaches a return instruction. If the current instruction is a return instruction,
the instruction is traced into until a new return is reached.
Target executes until the completion of the whole specified function. Statistics are then displayed.

For more information about how to restart the target computer, see Crashing and Rebooting the Target Computer.
Command-Line Options
If you do not want the application to stop immediately when it starts or loads, use CDB or WinDbg together with the -g command-line option. For more information about this
situation, see Initial Breakpoint.
CDB and WinDbg also support the -G command-line option. This option causes the debugging session to end if the application completes properly.
The following command tries to run the application from start to finish, and the debugger prompt appears only if an error occurs.
cdb -g -G ApplicationName
You can use the -pt command-line option to set the break time-out. There are certain problems that can make the target unable to communicate with the debugger. If a break
command is issued and the debugger cannot break into the target after this time, the debugger displays a "Break-in timed out" message.
At this point, the debugger stops trying to break into the target. Instead, the debugger pauses the target and enables you to examine (but not control) the target application.
The default time-out is 30 seconds.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Breakpoints
A breakpoint is a location in executable code at which the operating system stops execution and breaks into the debugger. This allows you to analyze the target and issue

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 118 of 1651

debugger commands.
This section includes the following topics:
Methods of Controlling Breakpoints
Breakpoint Syntax
Unresolved Breakpoints (bu Breakpoints)
Processor Breakpoints (ba Breakpoints)
Initial Breakpoint
User Space and System Space
Risks Entailed When Setting Breakpoints
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Methods of Controlling Breakpoints

You can specify the location of a breakpoint by virtual address, module and routine offsets, or source file and line number (when in source mode). If you put a breakpoint on a
routine without an offset, the breakpoint is activated when that routine is entered.
There are several additional kinds of breakpoints:

A breakpoint can be associated with a certain thread.

A breakpoint can enable a fixed number of passes through an address before it is triggered.
A breakpoint can automatically issue certain commands when it is triggered.
A breakpoint can be set on non-executable memory and watch for that location to be read or written to.

If you are debugging more than one process in user mode, the collection of breakpoints depends on the current process. To view or change a process' breakpoints, you must
select the process as the current process. For more information about the current process, see Controlling Processes and Threads.
Methods of Controlling and Displaying Breakpoints
To control or display breakpoints, you can use the following methods:

Use the bl (Breakpoint List) command to list existing breakpoints and their current status.
Use the .bpcmds (Display Breakpoint Commands) command to list all breakpoints along with the commands that were used to create them.
Use the bp (Set Breakpoint) command to set a new breakpoint.
Use the bu (Set Unresolved Breakpoint) command to set a new breakpoint. Breakpoints that are set with bu are called unresolved breakpoints; they have different
characteristics than breakpoints that are set with bp. For complete details, see Unresolved Breakpoints (bu Breakpoints).
Use the bm (Set Symbol Breakpoint) command to set new breakpoints on symbols that match a specified pattern. A breakpoint set with bm will be associated with an
address (like a bp breakpoint) if the /d switch is included; it will be unresolved (like a bu breakpoint) if this switch is not included.
Use the ba (Break on Access) command to set a processor breakpoint, also known as a data breakpoint. These breakpoints can be triggered when the memory location
is written to, when it is read, when it is executed as code, or when kernel I/O occurs. For complete details, see Processor Breakpoints (ba Breakpoints).
Use the bc (Breakpoint Clear) command to permanently remove one or more breakpoints.
Use the bd (Breakpoint Disable) command to temporarily disable one or more breakpoints.
Use the be (Breakpoint Enable) command to re-enable one or more disabled breakpoints.
Use the br (Breakpoint Renumber) command to change the ID of an existing breakpoint.
Use the bs (Update Breakpoint Command) command to change the command associated with an existing breakpoint.
Use the bsc (Update Conditional Breakpoint) command to change the condition under which an existing conditional breakpoint occurs.
(WinDbg only) The Disassembly window and the Source windows highlight lines that have breakpoints set. Enabled breakpoints are red, disabled breakpoints are
yellow, and a breakpoint that corresponds to the current program counter location is purple.
(WinDbg only) The Edit | Breakpoints command or the ALT+F9 shortcut key open the Breakpoints dialog box. This dialog box lists all breakpoints, and you can use
it to disable, enable, or clear existing breakpoints or to set new breakpoints.
(WinDbg only) If you set the cursor on a specific line in the Disassembly window or in a Source window, you can press F9 or click the Insert or remove button (
on the toolbar to set a breakpoint at that line. If you press the shortcut key or click the button when the active window is not the Disassembly window or a Source
window, it has the same effect as Edit | Breakpoints.

Each breakpoint has a decimal number called the breakpoint ID associated with it. This number identifies the breakpoint in various commands.
Breakpoint Commands
You can include a command in a breakpoint that is automatically executed when the breakpoint is hit.
For example, the following command breaks at MyFunction+0x47, writes a dump file, and then resumes execution.
0:000> bu MyFunction+0x47 ".dump c:\mydump.dmp; g"
Note If you are controlling the user-mode debugger from the kernel debugger, do not use g (Go) in the breakpoint command string. The serial interface might be unable to
keep up with this command, and you will be unable to break back into CDB. For more information about this situation, see Controlling the User-Mode Debugger from the
Kernel Debugger.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 119 of 1651

Number of Breakpoints
In kernel mode, you can use a maximum of 32 software breakpoints. In user mode, you can use any number of software breakpoints.
The number of processor breakpoints that are supported depends on the target processor architecture.
Conditional Breakpoints
You can set a breakpoint that is triggered only under certain conditions. For more information about these kinds of breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Breakpoint Syntax
The following syntax elements can be used when creating a breakpoint, either through the Debugger Command window or through the WinDbg graphical interface.
Addresses in Breakpoints
Breakpoints support many kinds of address syntax, including virtual addresses, function offsets, and source line numbers. For example, you can use any of the following
commands to set breakpoints:
0:000> bp 0040108c
0:000> bp main+5c
0:000> bp `source.c:31`
For more information about this syntax, see Numerical Expression Syntax, Source Line Syntax, and the individual command topics.
Breakpoints on Methods
If you want to put a breakpoint on the MyMethod method in the MyClass class, you can use two different syntaxes:

In MASM expression syntax, you can indicate a method by a double colon or by a double underscore.
0:000> bp MyClass::MyMethod
0:000> bp MyClass__MyMethod

In C++ expression syntax, you must indicate a method by a double colon.

0:000> bp @@( MyClass::MyMethod )

If you want to use a more complex breakpoint command, you should use MASM expression syntax. For more information about expression syntax, see Evaluating
Expressions.
Breakpoints Using Complicated Text
To set a breakpoint on complicated functions, including functions that contain spaces, as well as a member of a C++ public class, enclose the expression in parentheses. For
example, use bp (??MyPublic) or bp (operator new).
A more versatile technique is to use the @!"chars" syntax. This is a special escape in the MASM evaluator that enables you to provide arbitrary text for symbol resolution.
You must start with the three symbols @!" and end with a quotation mark ("). Without this syntax, you cannot use spaces, angle brackets (<, >), or other special characters in
symbol names in the MASM evaluator. This syntax is exclusively for names, and not parameters. Templates and overloads are the primary sources of symbols that require this
quote notation. You can also set the bu command by using the @!"chars" syntax, as the following code example shows.

0:000> bu @!"ExecutableName!std::pair<unsigned int,std::basic_string<unsigned short,std::char_traits<unsigned short>,std::allocat

In this example, ExecutableName is the name of an executable file.
This escape syntax is more useful for C++ (for example, overloaded operators) instead of C because there are no spaces (or special characters) in C function names. However,
this syntax is also important for a lot of managed code because of the considerable use of overloads in the .NET Framework.
To set a breakpoint on arbitrary text in C++ syntax, use bu @@c++(text) for C++-compatible symbols.
Breakpoints in Scripts
Breakpoint IDs do not have to be referred to explicitly. Instead, you can use a numerical expression that resolves to an integer that corresponds to a breakpoint ID. To indicate
that the expression should be interpreted as a breakpoint, use the following syntax.
b?[Expression]
In this syntax, the square brackets are required, and Expression stands for any numerical expression that resolves to an integer that corresponds to a breakpoint ID.
This syntax allows debugger scripts to programmatically select a breakpoint. In the following example, the breakpoint changes depending on the value of a user-defined
pseudo-register.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 120 of 1651

b?[@$t0]
Breakpoint Pseudo-Registers
If you want to refer to a breakpoint address in an expression, you can use a pseudo-register with the $bpNumber syntax, where Number is the breakpoint ID. For more
information about this syntax, see Pseudo-Register Syntax.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Unresolved Breakpoints (bu Breakpoints)

If a breakpoint is set for a routine name that has not been loaded, the breakpoint is called a deferred, virtual, or unresolved breakpoint. (These terms are used interchangeably.)
Unresolved breakpoints are not associated with any specific load of a module. Every time that a new application is loaded, it is checked for this routine name. If this routine
appears, the debugger computes the actual coded address of the virtual breakpoint and enables the breakpoint.
If you set a breakpoint by using the bu command, the breakpoint is automatically considered unresolved. If this breakpoint is in a loaded module, the breakpoint is still
enabled and functions normally. However, if the module is later unloaded and reloaded, this breakpoint does not vanish. On the other hand, a breakpoint that you set with bp
is immediately resolved to an address.
There are three primary differences between bp breakpoints and bu breakpoints:

A bp breakpoint location is always converted to an address. If a module change moves the code at which a bp breakpoint was set, the breakpoint remains at the same
address. On the other hand, a bu breakpoint remains associated with the symbolic value (typically a symbol plus an offset) that was used, and it tracks this symbolic
location even if its address changes.
If a bp breakpoint address is found in a loaded module, and if that module is later unloaded, the breakpoint is removed from the breakpoint list. On the other hand, bu
breakpoints persist after repeated unloads and loads.
Breakpoints that you set with bp are not saved in WinDbg workspaces. Breakpoints that are set with bu are saved in workspaces.

Controlling Address Breakpoints and Unresolved Breakpoints

Address breakpoints can be created with the bp (Set Breakpoint) command, or the bm (Set Symbol Breakpoint) command when the /d switch is included. Unresolved
breakpoints can be created with the bu (Set Unresolved Breakpoint) command, or the bm command when the /d switch is not included. Commands that disable, enable, and
modify breakpoints apply to all kinds of breakpoints. Commands that display a list of breakpoints include all breakpoints, and indicate the type of each. For a listing of these
commands, see Methods of Controlling Breakpoints.
The WinDbg Breakpoints dialog box displays all breakpoints, indicating unresolved breakpoints with the notation "u". This dialog box can be used to modify any
breakpoint.The Command text box on this dialog box can be used to create any type of breakpoint; if the type is omitted, an unresolved breakpoint is created. For details, see
Edit | Breakpoints. When you set a breakpoint by using the mouse in the WinDbg Disassembly window or Source window, the debugger creates an unresolved breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Processor Breakpoints (ba Breakpoints)

Breakpoints that are controlled by the processor at the request of the debugger are known as processor breakpoints or data breakpoints. Breakpoints that are controlled
directly by the debugger are known as software breakpoints.
Note Although the term data breakpoint is commonly used as a synonym for processor breakpoint, this term can be misleading. There are two fundamental types of
breakpoints: processor breakpoints, which are controlled by the processor, and software breakpoints, which are controlled by the debugger. Processor breakpoints are usually
set on program data this is the reason they are called "data breakpoints" but they can also be set on executable code. Software breakpoints are usually set on executable
code, but they can also be set on program data. Unfortunately, it is common in debugging literature to refer to processor breakpoints as "data breakpoints", even when they are
set on executable code.
Processor Breakpoints
A processor breakpoint is triggered when a specific memory location is accessed. There are four types of processor breakpoints, corresponding to the kind of memory access
that triggers it:
Breakpoint type
Action
e (execute)
Triggered when the processor retrieves an instruction from the specified address.
r (read/write)
Triggered when the processor reads or writes memory at the specified address.
w (write)
Triggered when the processor writes memory at the specified address.
i (i/o)
Triggered when the I/O port at the specified Address is accessed.
Each processor breakpoint has a size associated with it. For example, a w (write) processor breakpoint could be set at the address 0x70001008 with a size of four bytes. This
would monitor the block of addresses from 0x70001008 to 0x7000100B, inclusive. If this block of memory is written to, the breakpoint will be triggered.
It can happen that the processor performs an operation on a memory region that overlaps with, but is not identical to, the specified region. In the example given in the
preceding paragraph, a single write operation that includes the range 0x70001000 to 0x7000100F, or a write operation that includes only the byte at 0x70001009, would be an

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 121 of 1651

overlapping operation. In such a situation, whether the breakpoint is triggered is processor-dependent. For details of how this situation is handled on a specific processor,
consult the processor archictecture manual and look for "debug register" or "debug control register". To take one specific processor type as an example, on an x86 processor, a
read or write breakpoint is triggered whenever the accessed range overlaps the breakpoint range.
Similarly, if an e (execute) breakpoint is set on the address 0x00401003, and then a two-byte instruction spanning the addresses 0x00401002 and 0x00401003 is executed, the
result is processor-dependent. Again, consult the processor architecture manual for details.
The processor distinguishes between breakpoints set by a user-mode debugger and breakpoints set by a kernel-mode debugger. A user-mode processor breakpoint does not
affect any kernel-mode processes. A kernel-mode processor breakpoint might or might not affect a user-mode process, depending on whether the user-mode code is using the
debug register state and whether there is a user-mode debugger that is attached.
To apply the current process' existing data breakpoints to a different register context, use the .apply_dbp (Apply Data Breakpoint to Context) command.
On a multiprocessor computer, each processor breakpoint applies to all processors. For example, if the current processor is 3 and you use the command ba e1 MyAddress
to put a breakpoint at MyAddress, any processor not only processor 3 that executes at that address triggers the breakpoint. This holds for software breakpoints as well.
Software Breakpoints
Software breakpoints, unlike processor breakpoints, are controlled by the debugger. When the debugger sets a software breakpoint at some location, it temporarily replaces the
contents of that memory location with a break instruction. The debugger remembers the original contents of this location, so that if this memory is displayed in the debugger,
the debugger will show the original contents of that memory location, not the break instruction. When the target process executes the code at this location, the break
instruction causes the process to break into the debugger. After you have performed whatever actions you choose, you can cause the target to resume execution, and execution
will resume with the instruction that was originally in that location.
Availability of Processor Breakpoint Types
On Windows Server 2003 with Service Pack 1 (SP1), on an Itanium-based computer that uses WOW64 to emulate x86, processor breakpoints do not work with the e
(execute) option but they do work with the r (read/write) and w (write) options.
The i (i/o) option is available only during kernel-mode debugging, with a target computer that is running Windows XP or a later version of Windows on an x86-based
processor.
Not all data sizes can be used with all processor breakpoint types. The permitted sizes depend on the processor of the target computer. For details, see ba (Break on Access).
Limitations of Software Breakpoints and Processor Breakpoints
It is possible to specify a data address rather than a program address when using the bp or bm /a commands. However, even if a data location is specified, these commands
create software breakpoints, not processor breakpoints. When the debugger places a software breakpoint at some location, it temporarily replaces the contents of that memory
location with a break instruction. This does not corrupt the executable image, because the debugger remembers the original contents of this location, and when the target
process attempts to execute this code the debugger can respond appropriately. But when a software breakpoint is set in a data location, the resulting overwrite can lead to data
corruption. Therefore, setting a software breakpoint on a data location is safe only if you are certain that this location will be used only as executable code.
The bp, bu, and bm commands set software breakpoints by replacing the processor instruction with a break instruction. Therefore these cannot be used in read-only code or
any other code that cannot be overwritten. To set a breakpoint in such code, you must use ba (Break on Access) with the e (execute) option.
You cannot create multiple processor breakpoints at the same address that differ only in the command that is automatically executed when the breakpoint is triggered.
However, you can create multiple breakpoints at the same address that differ in their other restrictions (for example, you can create multiple breakpoints at the same address
by using the ba command with different values of the /p, /t, /c, and /C options).
The initial breakpoint in a user-mode process (typically set on the main function or its equivalent) cannot be a processor breakpoint.
The number of processor breakpoints that are supported depends on the target processor architecture.
Controlling Software Breakpoints and Processor Breakpoints
Software breakpoints can be created with the bp (Set Breakpoint), bm (Set Symbol Breakpoint), and bu (Set Unresolved Breakpoint) commands. Processor breakpoints
can be created with the ba (Break on Access) command. Commands that disable, enable, and modify breakpoints apply to all kinds of breakpoints. Commands that display a
list of breakpoints include all breakpoints, and indicate the type of each. For a listing of these commands, see Methods of Controlling Breakpoints.
The WinDbg Breakpoints dialog box displays all breakpoints, indicating processor breakpoints with the notation "e", "r", "w", or "i' followed by the size of the block. This
dialog box can be used to modify any breakpoint. The Command text box on this dialog box can be used to create any type of breakpoint.If a processor breakpoint is desired,
begin the input with "ba". For details, see Edit | Breakpoints. When you set a breakpoint by using the mouse in the WinDbg Disassembly window or Source window, the
debugger creates an unresolved software breakpoint.
Processor breakpoints are stored in the processor's debug registers. It is possible to set a breakpoint by manually editing a debug register value, but this is strongly
discouraged.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Initial Breakpoint
When the debugger starts a new target application, an initial breakpoint automatically occurs after the main image and all statically-linked DLLs are loaded before any DLL
initialization routines are called.
When the debugger attaches to an existing user-mode application, an initial breakpoint occurs immediately.
The -g command-line option causes WinDbg or CDB to ignore the initial breakpoint. You can automatically execute a command at this point. For more information about this

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 122 of 1651

situation, see Controlling Exceptions and Events.

If you want to start a new target and break into it when the execution of the actual application is about to begin, do not use the -g option. Instead, let the initial breakpoint
occur. After the debugger is active, set a breakpoint on the main or winmain routine and then use the g (Go) command. All of the initialization procedures then run, and the
application stops when execution of the main application is about to begin.
For more information about automatic breakpoints in kernel mode, see Crashing and Rebooting the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User Space and System Space

Windows gives each user-mode application a block of virtual addresses. This is known as the user space of that application. The other large block of addresses, known as
system space or kernel space, cannot be directly accessed by the application.
When WinDbg or CDB sets a breakpoint in user space, this breakpoint is set at the specified address in the user space of a single process. During user-mode debugging, the
current process determines the meaning of virtual addresses. For more information, see Controlling Processes and Threads.
In kernel mode, you can set breakpoints in user space with the bp, bu, and ba commands or with the Breakpoints dialog box. You must first use the process context to
specify the user-mode process that owns that address space by using .process /i (or a process-specific breakpoint on some kernel-space function) to switch the target to the
correct process context.
Breakpoints in user space are always associated with the process whose process context was active when the breakpoints were set. If a user-mode debugger is debugging this
process and if a kernel debugger is debugging the computer that the process is running on, this breakpoint breaks into the user-mode debugger, even though the breakpoint
was actually set from the kernel debugger. You can break into the system from the kernel debugger at this point, or use the .breakin (Break to the Kernel Debugger)
command from the user-mode debugger to transfer control to the kernel debugger.
Determining the Range of User Space and System Space
If you need to determine the extent of user space and system space on the target computer, you can use the dp (Display Memory) command from a kernel debugger to display
the Windows global variable MmHighestUserAddress. This variable contains the address of the top of user space. Since system space addresses are always higher than user
space addresses, this value allows you to determine whether any given address is in user space or in kernel space.
For example, on a 32-bit target computer with an x86 processor and standard boot parameters, this command will show the following result:
kd> dp nt!mmhighestuseraddress L1
81f71864 7ffeffff
This indicates that user space ranges from the address 0x00000000 to 0x7FFEFFFF, and system space therefore ranges from 0x80000000 up to the highest possible address
(which is 0xFFFFFFFF on a standard 32-bit Windows installation).
With a 64-bit target computer, different values will occur. For example, this command might show the following:
0: kd> dp nt!mmhighestuseraddress L1
fffff800`038b4010 000007ff`fffeffff
This indicates that user space ranges from 0x00000000`00000000 to 0x000007FF`FFFEFFFF. Therefore, system space includes all addresses from 0x00000800`00000000
upward.
For more information about Windows memory management, see Microsoft Windows Internals by David Solomon and Mark Russinovich (4th edition, Microsoft Press, 2005).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Risks Entailed When Setting Breakpoints

When you are setting a breakpoints by specifying a memory address or a symbol plus an offset, you must not put this breakpoint in the middle of an instruction.
For example, consider the following disassembled code.
770000f1
770000f2
770000f3
770000f4
770000f7

5e
5b
c9
c21000
837ddc00

pop
pop
leave
ret
cmp

esi
ebx
0x10
dword ptr [ebp-0x24],0x0

The first three instructions are only one byte long. However, the fourth instruction is three bytes long. (It includes bytes 0x770000F4, 0x770000F5, and 0x770000F6.) If you
want to put a breakpoint on this instruction by using the bp, bu, or ba command, you must specify the 0x770000F4 address.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 123 of 1651

If you put a breakpoint in the 0x770000F5 address by using the ba command, the processor puts a breakpoint at that location. But this breakpoint would never be triggered,
because the processor considers 0x770000F4 to be the actual address of the instruction.
If you put a breakpoint in the 0x770000F5 address by using the bp or bu commands, the debugger writes a breakpoint at that location. However, this breakpoint might corrupt
the target because of how the debugger creates breakpoints:
1. The debugger saves the contents of 0x770000F5 and overwrites this memory with a breakpoint instruction.
2. If you try to display this memory in the debugger, the debugger does not show the breakpoint instruction that it has written. Instead, the debugger shows the memory
that "should" be there. That is, the debugger shows the original memory, or any modifications to that memory that you have made since inserting the breakpoint.
3. If you use the BC command to remove the breakpoint, the debugger restores the original memory to its proper location.
When you put a breakpoint at 0x770000F5, the debugger saves this byte and a break instruction is written here. However, when the application runs, it reaches the
0x770000F4 address and recognizes this address as the first byte of a multibyte instruction. The processor then tries to combine 0x770000F4, 0x770000F5, and possibly some
later bytes into a single instruction. This combination can create a variety of behaviors, none of which are desirable.
Therefore, when you put breakpoints by using a bp, bu, or ba command, make sure that you always put the breakpoints at the proper address. If you are using the WinDbg
graphical interface to add breakpoints, you do not have to be concerned about this situation because the correct address is chosen automatically.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading and Writing Memory

The three debuggers can read and write directly into memory. This memory can be referenced by addresses or by the names of variables.
This section includes the following topics:
Accessing Memory by Virtual Address
Accessing Memory by Physical Address
Accessing Global Variables
Accessing Local Variables
Controlling Variables Through the Watch Window
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Accessing Memory by Virtual Address

To access specified memory addresses or address ranges, you can use several commands.
The following commands can read or write memory in a variety of formats. These formats include hexadecimal bytes, words (words, double words, and quad-words), integers
(short, long, and quad integers and unsigned integers), floating-point numbers (10-byte, 16-byte, 32-byte, and 64-byte real numbers), and ASCII characters.

The d* (Display Memory) command displays the contents of a specified memory address or range.
The e* (Enter Values) command writes a value to the specified memory address.
(WinDbg only) The Memory window displays the contents of a specified memory range and writes to any location in that range.

You can use the following commands to handle more specialized data types:

The dt (Display Type) command finds a variety of data types and displays data structures that have been created by the application that is being debugged. This
command is highly versatile and has many variations and options.
The ds, dS (Display String) command displays a STRING, ANSI_STRING, or UNICODE_STRING data structure.
The dl (Display Linked List) command traces and displays a linked list.
The d*s (Display Words and Symbols) command finds double-words or quad-words that might contain symbol information and then displays the data and the symbol
information.
The !address extension command displays information about the properties of the memory that is located at a specific address.

You can use the following commands to manipulate memory ranges:

The m (Move Memory) command moves the contents of one memory range to another.
The f (Fill Memory) command writes a pattern to a memory range, repeating it until the range is full.
The c (Compare Memory) command compares the contents of two memory ranges.
The s (Search Memory) command searches for a specified pattern within a memory range or searches for any ASCII or Unicode characters that exist in a memory
range.
The .holdmem (Hold and Compare Memory) command compares one memory range to another.

In most situations, these commands interpret their parameters in the current radix. Therefore, you should add 0x before hexadecimal addresses if the current radix is not 16.
However, the display output of these commands is typically in hexadecimal format, regardless of the current radix. (For more information about the output, see the individual

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 124 of 1651

command topics.) The Memory window displays integers and real numbers in decimal format and displays other formats in hexadecimal format.
To change the default radix, use the n (Set Number Base) command. To quickly convert numbers from one base to another, use the ? (Evaluate Expression) command or
the .formats (Show Number Formats) command.
When you are performing user-mode debugging, the meaning of virtual addresses is determined by the current process. When you are performing kernel-mode debugging, the
meaning of virtual addresses can be controlled by the debugger. For more information, see Process Context.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Accessing Memory by Physical Address

To read from a physical address, use the !db, !dc, !dd, !dp, !du, and !dw extension commands.
To write to a physical address, use the !eb and !ed extension commands.
The fp (Fill Physical Memory) command writes a pattern to a physical memory range, repeating it until the range is full.
When you are using WinDbg in kernel mode, you can also read or write to physical memory directly from the Memory window.
To search physical memory for a piece of data or a range of data, use the !search extension command.
Also, for more information about physical addresses, see Converting Virtual Addresses to Physical Addresses.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Accessing Global Variables

The names of global variables are stored in the symbol files that are created when an application is compiled. The debugger interprets the name of a global variable as a virtual
address. Therefore, any command that accepts an address as a parameter also accepts the name of a variable as that parameter.
Therefore, you can use all of the commands that are described earlier in this topic to read or write global variables.
In addition, you can use the ? (Evaluate Expression) command to display the address that is associated with any symbol.
Consider the following example. Suppose that you want to examine the MyCounter global variable, which is a 32-bit integer. Suppose also that the default radix is 10.
You can obtain this variable's address and then display it as follows.
0:000> ? MyCounter
Evaluate expression: 1244892 = 0012fedc
0:000> dd 0x0012fedc L1
0012fedc 00000052
The first command output tells you that the address of MyCounter is 0x0012FEDC. You can then use the D* command to display one double-word at this address. (You
could also use 1244892, which is the decimal version of this address. However, most C programmers prefer to use 0x0012FEDC.) The second command tells you that the
value of MyCounter is 0x52 (decimal 82).
You could also perform these steps in the following command.
0:000> dd MyCounter L1
0012fedc 00000052
To change the value of MyCounter to decimal 83, use the following command.
0:000> ed MyCounter 83
This example uses decimal input, because that format seems more natural for an integer. However, the output of the D* command is still in hexadecimal format.
0:000> dd MyCounter L1 0012fedc

00000053

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 125 of 1651

Accessing Local Variables

Local variables, like global variables, are stored in the symbol files. Like global variables, the debugger interprets their names as addresses. They can be read and written in
the same manner as global variables. However, if it is necessary to indicate to a command that a symbol is local, precede the symbol with a dollar sign ( $ ) and an
exclamation point ( ! ), as in $!var.
You can also use the following methods to display, change, and use local variables:

The dv (Display Local Variables) command displays the names and values of all local variables.
(WinDbg only) The Locals window displays the names and values of all local variables. You can also use this window to change the values of these variables.
The !for_each_local extension enables you to execute a single command repeatedly, once for each local variable.

However, there is one primary difference between local and global variables. When an application is executing, the meaning of local variables depends on the location of the
program counter, because the scope of such variables extends only to the function in which they are defined.
The debugger interprets local variables according to the local context. By default, this context matches the location of the program counter. But the debugger can change the
context. For more information about the local context, see Local Context.
When the local context is changed, the Locals window is immediately updated to reflect the new collection of local variables. The DV command also shows the new
variables. All of these variable names are then interpreted correctly by the memory commands that are described earlier. You can then read or write to these variables.
When you are debugging optimized code, some local variables might be collapsed, replaced with a register, or perhaps even temporarily stored on the stack. If you want to use
source files or local variables while you are debugging, you should not optimize your code.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling Variables Through the Watch Window

In WinDbg, you can also use the Watch window to display and change global and local variables.
The Watch window can display any list of variables that you want. These variables can include global variables and local variables from any function. At any time, the Watch
window displays the values of those variables that match the current function's scope. You can also change the values of these variables through the Watch window.
Unlike the Locals window, the Watch window is not affected by changes to the local context. Only those variables that are defined in the scope of the current program counter
can have their values displayed or modified.
For more information about this window, see The Watch Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading and Writing Registers and Flags

Registers are small volatile memory units that are located on the CPU. Many registers are dedicated to specific uses, and other registers are available for user-mode
applications to use.
The x86-based and Itanium-based processors have different collections of registers available. For more information about the registers on each processor, see Processor
Architecture.
To manipulate CPU registers, you can do one of the following:

Use the r (Registers) command to display or control the registers. You can customize this display by using several options or by using the rm (Register Mask)
command.
(WinDbg only) Use the Registers window to display or control the registers. You can customize the window to display the registers in any order.
(WinDbg only) Use the Watch window to display any list of registers or variables. You cannot use this window to alter the value of registers.

Registers are also automatically displayed every time that the target stops. If you are stepping through your code with the p (Step) or t (Trace) commands, you see a register
display at every step. To stop this display, use the r option when you use these commands.
On an x86-based processor, the r option also controls several one-bit registers known as flags. To change these flags, you use a slightly different syntax than changing regular
registers. For more information about these flags and an explanation of this syntax, see x86 Flags.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 126 of 1651

Viewing the Call Stack

The call stack is the chain of function calls that have led to the current location of the program counter. The top function on the call stack is the current function, the next
function is the function that called the current function, and so on.
The call stack also preserves some facts whenever a function calls a new function. These facts vary from processor to processor, but typically they include the following:

The name or location of the function called.

The return address. (This address is typically the assembly instruction immediately after the address that the function was called from.)
The parameters that were passed to the function.
The base pointer for the stack frame.

To display the call stack, you can use the following methods:

The k (Display Stack Backtrace) command is the basic stack trace command. This command displays the base pointer for the stack frame, the return address, and the
name of the function. If source line information is available, k also displays source modules and line numbers.
The kb (Display Stack Backtrace) command displays the same stack as the k command and displays the first three parameters that were passed to the function.
The kp (Display Stack Backtrace) command displays the same stack as the kb command and displays a full listing of the parameters that were passed to each function.
The kv (Display Stack Backtrace) command displays the same stack as the kb command and displays additional frame pointer omission (FPO) information. On an
x86-based processor, this command also displays calling convention information. On an Itanium-based processor, this command also displays nonvolatile registers.
The kd (Display Stack Backtrace) command displays the raw stack data, without any formatting.
(WinDbg only) The Calls window displays call stack information. You can customize this window to display different stack data. You can also use this window to
quickly jump to the corresponding function in a Source window or Disassembly window.

If you try to display the call stack at the very beginning of a function (before the function prolog has been executed), you probably see incorrect results. The debugger uses the
frame register to compute the current backtrace, and this register is not set correctly for a function until its prolog has been executed.
The call stack that is displayed is based on the current program counter, unless you change the register context. For more information about how to change the register
context, see Changing Contexts.
A variety of problems can make it difficult to obtain an accurate stack trace. For more information about this matter, see Getting a Stack Trace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging in Assembly Mode

If you have C or C++ source files for your application, you can use the debugger much more powerfully if you debug in source mode.
However, there are many times you cannot perform source debugging. You might not have the source files for your application. You might be debugging someone else's code.
You might not have built your executable files with full .pdb symbols. And even if you can do source debugging on your application, you might have to trace Microsoft
Windows routines that your application calls or that are used to load your application.
In these situations, you have to debug in assembly mode. Moreover, assembly mode has many useful features that are not present in source debugging. The debugger
automatically displays the contents of memory locations and registers as they are accessed and displays the address of the program counter. This display makes assembly
debugging a valuable tool that you can use together with source debugging.
Disassembly Code
The debugger primarily analyzes binary executable code. Instead of displaying this code in raw format, the debugger disassembles this code. That is, the debugger converts
the code from machine language to assembly language.
You can display the resulting code (known as disassembly code) in several different ways:

The u (Unassemble) command disassembles and displays a specified section of machine language.
The uf (Unassemble Function) command disassembles and displays a function.
The up (Unassemble from Physical Memory) command disassembles and displays a specified section of machine language that has been stored in physical memory.
The ur (Unassemble Real Mode BIOS) command disassembles and displays a specified 16-bit real-mode code.
The ux (Unassemble x86 BIOS) command disassembles and displays the x86-based BIOS code instruction set at a specified address.
(WinDbg only) The Disassembly window disassembles and displays a specified section of machine language. This window is automatically active if you select the
Automatically Open Disassembly command on the Window menu. You can also open this window by clicking Disassembly on the View menu, pressing ALT+7, or
pressing the Disassembly (Alt+7) button (

) on the WinDbg toolbar.

The disassembly display appears in four columns: address offset, binary code, assembly language mnemonic, and assembly language details. The following example shows
this display.
0040116b
0040116c
0040116d

45
fc
8945b0

inc
cld
mov

ebp
eax,[ebp-0x1c]

To the right of the line that represents the current program counter, the display shows the values of any memory locations or registers that are being accessed. If this line
contains a branch instruction, the notation [br=1] or [br=0] appears. This notation indicates a branch that is or is not taken, respectively.
You can use the .asm (Change Disassembly Options) command to change how the disassembled instructions are displayed.
In WinDbg's Disassembly window, the line that represents the current program counter is highlighted in green. Lines where breakpoints are set are highlighted in red (an

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 127 of 1651

enabled breakpoint), yellow (a disabled breakpoint), or purple (a breakpoint that coincides with the current program counter).
You can also use the following commands to manipulate assembly code:

The # (Search for Disassembly Pattern) command searches a region of memory for a specific pattern. This command is equivalent to searching the four columns of
the disassembly display.
The a (Assemble) command can take assembly instructions and translate them into binary machine code.

Assembly Mode and Source Mode

The debugger has two different operating modes: assembly mode and source mode.
When you are single-stepping through an application, the size of a single step is one line of assembly code or one line of source code, depending on the mode.
Several commands create different data displays depending on the mode.
In WinDbg, the Disassembly window automatically moves to the foreground when you run or step through an application in assembly mode. In source mode, the Source
window moves to the foreground.
To set the mode, you can do one of the following:

Use the l+, l- (Set Source Options) command to control the mode. The l-t command activates assembly mode.
(WinDbg only) Clear the Source Mode command on the Debug menu to cause the debugger to enter assembly mode.You can also click the Source mode off button (
) on the toolbar.

In WinDbg, when you are in assembly mode, ASM appears visible on the status bar.
The shortcut menu in WinDbg's Disassembly window includes the Highlight instructions from the current source line command. This command highlights all of the
instructions that correspond to the current source line. Frequently, a single source line corresponds to multiple assembly instructions. If code has been optimized, these
assembly instructions might not be consecutive. The Highlight instructions from the current source line command enables you to find all of the instructions that were
assembled from the current source line.
Assembly Language Source Files
If your application was written in assembly language, the disassembly that the debugger produces might not exactly match your original code. In particular, NO-OPs and
comments will not be present.
If you want to debug your code by referencing the original .asm files, you must use source mode debugging. You can load the assembly file like a C or C++ source file. For
more information about this kind of debugging, see Debugging in Source Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging in Source Mode

Debugging an application is easier if you can analyze the source of the code, instead of the disassembled binaries.
WinDbg, CDB, and KD can use source code in debugging, if the source language is C, C++, or assembly.
Compilation Requirements
To use source debugging, you must have your compiler or linker create symbol files (.pdb files) when the binaries are built. These symbol files show the debugger how the
binary instructions correspond to the source lines.
Also, the debugger must be able to access the actual source files , because symbol files do not contain the actual source text.
If it is possible, the compiler and linker should not optimize your code. Source debugging and access to local variables are more difficult, and sometimes almost impossible, if
the code has been optimized. If you are using the Build utility as your compiler and linker, set the MSC_OPTIMIZATION macro to /Od /Oi to avoid optimization.
Locating the Symbol Files and Source Files
To debug in source mode, the debugger must be able to find the source files and the symbol files. For more information, see Setting Paths and Loading Files.
Beginning Source Debugging
The debugger can display source information whenever it has proper symbols and source files for the thread that is currently being debugged.
If you start a new user-mode application by using the debugger, the initial break occurs when Ntdll.dll loads the application. Because the debugger does not have access to the
Ntdll.dll source files, you cannot access source information for your application at this point.
To move the program counter to the beginning of the application, add a breakpoint at the entry point to your binary. In the Debugger Command window, type the following
command.
bp main
g
The application is then loaded and stops when the main function is entered. (Of course, you can use any entry point, not only main.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 128 of 1651

If the application throws an exception, it breaks into the debugger. Source information is available at this point. However, if you issue a break by using the CTRL+C,
CTRL+BREAK, or Debug | Break command, the debugger creates a new thread, so you cannot see your source code.
After you have reached a thread that you have source files for, you can use the Debugger Command window to execute source debugging commands. If you are using
WinDbg, the Source window appears. If you have already opened a Source window by clicking Open Source File on the File menu, WinDbg typically create a new window
for the source. You can close the previous window without affecting the debugging process.
Source Debugging in the WinDbg GUI
If you are using WinDbg, a Source window appears as soon as the program counter is in code that the debugger has source information for.
WinDbg displays one Source window for each source file that you or WinDbg opened. For more information about the text properties of this window, see Source Windows.
You can then step through your application or execute to a breakpoint or to the cursor. For more information about stepping and tracing commands, see Controlling the
Target.
If you are in source mode, the appropriate Source window moves to the foreground as you step through your application. Because there are also Microsoft Windows routines
that are called during the application's execution, the debugger might move a Disassembly window to the foreground when this kind of call occurs (because the debugger does
not have access to the source for these functions). When the program counter returns to known source files, the appropriate Source window becomes active.
As you move through the application, WinDbg highlights your location in the Source window and the Disassembly window in green. Lines at which breakpoints are set are
also highlighted in red (enabled breakpoints), yellow (disabled breakpoints), or purple (if a breakpoint coincides with the current program counter). The source code is colored
according to the parsing of the language. If the Source window has been selected, you can hover over a symbol with the mouse to evaluate it. For more information about
these features and how to control them, see Source Windows.
To activate source mode in WinDbg, use the l+t command, click Source Mode on the Debug menu, or click the Source mode on button (

) on the toolbar.

When source mode is active, the ASM indicator appears unavailable on the status bar.
You can view or alter the values of any local variables as you step through a function in source mode. For more information, see Reading and Writing Memory.
Source Debugging in the Debugger Command Window
If you are using CDB, you do not have a separate Source window. However, you can still view your progress as you step through the source.
Before you can do source debugging in CDB, you have to load source line symbols by issuing the .lines (Toggle Source Line Support) command or by starting the debugger
with the -lines command-line option.
If you execute an l+t command, all program stepping is performed one source line at a time. Use l-t to step one assembly instruction at a time. If you are using WinDbg, this
command has the same effect as selecting or clearing Source Mode on the Debug menu or using the toolbar buttons.
The l+s command displays the current source line and line number at the prompt. If you want to see only the line number, use l+l instead.
If you use l+o and l+s, only the source line is displayed while you step through the program. The program counter, disassembly code, and register information are hidden.
This kind of display enables you to quickly step through the code and view nothing but the source.
You can use the lsp (Set Number of Source Lines) command to specify exactly how many source lines are displayed when you step through or execute the application.
The following sequence of commands is an effective way to step through a source file.
.lines
bp main
l+t
l+s
g
pr
p

enable source line information

set initial breakpoint
stepping will be done by source line
source lines will be displayed at prompt
run program until "main" is entered
execute one source line, and toggle register display off
execute one source line

Because ENTER repeats the last command, you can now step through the application by using the ENTER key. Each step causes the source line, memory offset, and
assembly code to appear.
For more information about how to interpret the disassembly display, see Debugging in Assembly Mode.
When the assembly code is displayed, any memory location that is being accessed is displayed at the right end of the line. You can use the d* (Display Memory) and e*
(Enter Values) commands to view or change the values in these locations.
If you have to view each assembly instruction to determine offsets or memory information, use l-t to step by assembly instructions instead of source lines. The source line
information can still be displayed. Each source line corresponds to one or more assembly instructions.
All of these commands are available in WinDbg and in CDB. You can use the commands to view source line information from WinDbg's Debugger Command window
instead of from the Source window.
Source Lines and Offsets
You can also perform source debugging by using the expression evaluator to determine the offset that corresponds to a specific source line.
The following command displays a memory offset.
? `[[module!]filename][:linenumber]`
If you omit filename, the debugger searches for the source file that corresponds to the current program counter.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 129 of 1651

The debugger reads linenumber as a decimal number unless you add 0x before it, regardless of the current default radix. If you omit linenumber, the expression evaluates to
the initial address of the executable file that corresponds to the source file.
This syntax is understood in CDB only if the .lines command or the -lines command-line option has loaded source line symbols.
This technique is very versatile, because you can use it regardless of where the program counter is pointing. For example, this technique enables you to set breakpoints in
advance, by using commands such as the following.
bp `source.c:31`
For more information, see Source Line Syntax and Using Breakpoints.
Stepping and Tracing in Source Mode
When you are debugging in source mode, there can be multiple function calls on a single source line. You cannot use the p and t commands to separate these function calls.
For example, in the following command, the t command steps into both GetTickCount and printf, while the p command steps over both function calls.
printf( "%x\n", GetTickCount() );
If you want to step over certain calls while tracing into other calls, use .step_filter (Set Step Filter) to indicate which calls to step over.
You can use _step_filter to filter out framework functions (for example, Microsoft Foundation Classes (MFC) or Active Template Library (ATL) calls).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging BIOS Code

BIOS code is not built from standard assembly code, so it requires different debugging techniques.
On an x86-based processor, the BIOS uses 16-bit code. To disassemble this code, use the ux (Unassemble x86 BIOS) command. To display information about the Intel
Multiprocessor Specification (MPS), use the !mps extension.
On an Itanium-based processor, the BIOS uses EFI code (32-bit) and real-mode code (16-bit). To disassemble real-mode code, use ur (Unassemble Real Mode BIOS). The
debuggers cannot disassemble EFI code.
If you are debugging ACPI BIOS code, the preceding commands do not work, because ACPI BIOS is written in ACPI Machine Language (AML). To disassemble this code,
you should use !amli u. For more information about this kind of debugging, see ACPI Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Multiple Targets

You can debug multiple dump files or live user-mode applications at the same time. Each target contains one or more processes, and each process contains one or more
threads.
These targets are also grouped into systems. Systems are sets of targets that are grouped together for easy identification and manipulation. Systems are defined as follows:

Each kernel-mode or user-mode dump file is a separate system.

When you are debugging live user-mode applications on different computers (by using a process server, such as Dbgsrv), each application is a separate system.
When you are debugging live user-mode applications on the local computer, the applications are combined into a single system.

The current or active system is the system that you are currently debugging.
Acquiring Multiple Targets
The first target is acquired in the usual manner.
You can debug additional live user-mode applications by using the .attach (Attach to Process) or .create (Create Process) command, followed by the g (Go) command.
You can debug additional dump files by using the .opendump (Open Dump File) command, followed by the g (Go) command. You can also open multiple dump files when
the debugger is started. To open multiple dump files, include multiple -z switches in the command, each followed by a different file name.
You can use the preceding commands even if the processes are on different systems. You must start a process server on each system and then use the -premote parameter
with .attach or .create to identify the proper process server. If you use the .attach or .create command again without specifying the -premote parameter, the debugger
attaches to, or creates, a process on the current system.
Manipulating Systems and Targets

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 130 of 1651

When debugging begins, the current system is the one that the debugger most recently attached to. If an exception occurs, the current system switches to the system that this
exception occurred on.
To close one target and continue to debug the other targets, use the .kill (Kill Process) command. On Microsoft Windows XP and later versions of Windows, you can use
the .detach (Detach from Process) command or WinDbg's Debug | Detach Debuggee menu command instead. These commands detach the debugger from the target but
leave the target running.
To control the debugging of multiple systems, you can use the following methods:

The || (System Status) command displays information about one or more systems
The ||s (Set Current System) command enables you to select the current system
(WinDbg only) The Processes and Threads window enables you display or select systems, processes, and threads

By using these commands to select the current system, and by using the standard commands to select the current process and thread, you can determine the context of
commands that display memory and registers.
However, you cannot separate execution of these processes. The g (Go) command always causes all targets to execute together.
Note We recommend that you do not debug live targets and dump targets together, because commands behave differently for each type of debugging. For example, if you use
the g (Go) command when the current system is a dump file, the debugger begins executing, but you cannot break back into the debugger, because the break command is not
recognized as valid for dump file debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Ending the Debugging Session

You can exit any Microsoft Windows debugger during the debugging session. The three debuggers have somewhat different methods of exiting. WinDbg also enables you to
end the debugging session without exiting WinDbg.
If you want to avoid accidentally ending the debugging session, you can use the .quit_lock (Prevent Accidental Quit) command.
Exiting CDB
You can exit CDB by using the q (Quit) command. This command also closes the application that you are debugging.
On Windows XP and later versions of Windows, the qd (Quit and Detach) command detaches CDB from the target application, exits the debugger, and leaves the target
application running. If you used the -pd command-line option when you started the debugger, detaching occurs if the session is ended for any reason. (This technique makes pd especially useful when you are debugging a sensitive process, such as CSRSS, that you do not want to end.)
On Windows 2000, the qd command or the -pd option generates a warning message and has no effect. These operating systems do not allow a debugger to detach from its
target application. (If the target must not be ended, you should use noninvasive debugging and exit by using the Q command. For more information, see Attaching to a
Running Process (User Mode).)
If the debugger is not responding, you can exit by pressing CTRL+B and then ENTER. This method is a secondary exit mechanism. It abruptly ends the debugger and is
similar to ending a process through Task Manager or by closing the window.
Exiting KD
There are two different ways to exit KD.

Issue a q (Quit) command in KD to save the log file, end the debugging session, and exit the debugger. The target computer remains locked.
Press CTRL+B and then press ENTER to end the debugger abruptly. If you want the target computer to continue to run after the debugger is ended, you must use this
method. Because CTRL+B does not remove breakpoints, you should use the following commands first.
kd>
kd>
kd>

bc *
g
<CTRL+B> <ENTER>

Exiting the debugger by using CTRL+B does not clear kernel-mode breakpoints, but attaching a new kernel debugger does clear these breakpoints.
When you are perfomring remote debugging, q ends the debugging session. CTRL+B exits the debugger but leaves the session active. This situation enables another debugger
to connect to the session.
If the q command does not work, press CTRL+R and then press ENTER on the host computer's keyboard, and then retry the q command. If this procedure does not work, you
must use CTRL+B to exit the debugger.
Exiting WinDbg
You can exit WinDbg by clicking Exit on the File menu or by pressing ALT+F4.
If you are performing user-mode debugging, these commands close the application that you are debugging, unless you used the -pd command-line option when you started the
debugger.
If you are performing kernel-mode debugging, the target computer remains in its current state. This situation enables you to leave the target running or frozen. (If you leave
the target frozen, any future connection from a kernel debugger can resume debugging where you left it.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 131 of 1651

Ending a User-Mode Session Without Exiting

To end a user-mode debugging session, return the debugger to dormant mode, and close the target application, you can use the following methods:

The .kill (Kill Process) command

(WinDbg only) The q (Quit) command (unless you started the debugger with the -pd option)
(WinDbg only) The Debug | Stop Debugging command
(WinDbg only) The SHIFT+F5 shortcut keys

(WinDbg only) The Stop debugging (Shift+F5) button (

) on the toolbar

To end a user-mode debugging session, return the debugger to dormant mode, and set the target application running again, you can use the following methods:

(Windows XP and later versions of Windows) The .detach (Detach from Process) command. If you are debugging multiple targets, this command detaches from the
current target and continues the debugging session with the remaining targets.
(Windows XP and later versions of Windows, WinDbg only) The Debug | Detach Debuggee command. If you are debugging multiple targets, this command detaches
from all current targets.
(Windows XP and later versions of Windows) The qd (Quit and Detach) command.
(Windows XP and later versions of Windows) The q (Quit) command, if you started the debugger with the -pd option.

You can detach from a target only in Windows XP and later versions of Windows. On Windows 2000, the qd command or the -pd option generates a warning message and
has no effect. These operating systems do not allow a debugger to detach from its target application. If the target must not end, you should use noninvasive debugging instead.
For more information, see Noninvasive Debugging (User Mode).
To end a user-mode debugging session, return the debugger to dormant mode, but leave the target application in the debugging state, you can use the following method:

(Windows XP and later versions of Windows) The .abandon (Abandon Process) command

For more information about reattaching to the target, see Reattaching to the Target Application.
Ending a Kernel-Mode Session Without Exiting
To end a kernel-mode debugging session, return the debugger to dormant mode, and leave the target computer frozen, you can use the following methods:

(WinDbg only) The Q (Quit) command (unless you started the debugger with the -pd option)
(WinDbg only) The Debug | Stop Debugging menu command
(WinDbg only) The SHIFT+F5 shortcut key

(WinDbg only) The Stop debugging (Shift+F5) button (

) on the toolbar

When a WinDbg session ends, you are prompted to save the workspace for the current session, and then WinDbg returns to dormant mode. At this point, you can use all
starting options. That is, you can start to debug a running process, spawn a new process, attach to a target computer, open a crash dump, or connect to a remote debugging
session. For more information about all of these options, see Starting the Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug Privilege
Debug privilege is a security policy setting that allows users to attach a debugger to a process or to the kernel. An administrator can modify a security policy for a user group
to include or to remove this functionality. Developers who are debugging their own applications do not need this user privilege. Developers who are debugging system
components or who are debugging remote components will need this user privilege. This user privilege provides complete access to sensitive and critical operating system
components. By default, this property is enabled for users with Administrator rights. A user with Administrator privileges can enable this property for other user groups.
Modifying Debug Privilege for a Process
A developer can programmatically alter the debug privilege for a specific process to prevent anyone from debugging that process. Disabling this privilege from within a
process prevents anyone from attaching a debugger to the process. The following example illustrates how one can disable the debug privilege.
//
// SetPrivilege enables/disables process token privilege.
//
BOOL SetPrivilege(HANDLE hToken, LPCTSTR lpszPrivilege, BOOL bEnablePrivilege)
{
LUID luid;
BOOL bRet=FALSE;
if (LookupPrivilegeValue(NULL, lpszPrivilege, &luid))
{
TOKEN_PRIVILEGE tp;
tp.PrivilegeCount=1;
tp.Privileges[0].Luid=luid;
tp.Privileges[0].Attributes=(bEnablePrivilege) ? SE_PRIVILEGE_ENABLED: 0;
//
// Enable the privilege or disable all privileges.
//
if (AdjustTokenPrivileges(hToken, FALSE, &tp, NULL, (PTOKEN_PRIVILEGES)NULL, (PDWORD)NULL))
{

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 132 of 1651

//
// Check to see if you have proper access.
// You may get "ERROR_NOT_ALL_ASSIGNED".
//
bRet=(GetLastError() == ERROR_SUCCESS);
}
}
return bRet;
}
The following example shows how to use this function:
HANDLE hProcess=GetCurrentProcess();
HANDLE hToken;
if (OpenProcessToken(hProcess, TOKEN_ADJUST_PRIVILEGES, &hToken))
{
SetPrivilege(hToken, SE_DEBUG_NAME, FALSE);
CloseHandle(hToken);
}

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Operation (User Mode)

This section includes the following topics:
Behavior of Spawned Processes
Controlling Processes and Threads
Reattaching to the Target Application
Debugging Managed Code
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Behavior of Spawned Processes

Processes that the debugger creates (also known as spawned processes) behave slightly differently than processes that the debugger does not create.
Instead of using the standard heap API, processes that the debugger creates use a special debug heap. On Microsoft Windows XP and later versions of Windows, you can
force a spawned process to use the standard heap instead of the debug heap by using the _NO_DEBUG_HEAP environment variable or the -hd command-line option.
Also, because the target application is a child process of the debugger, it inherits the debugger's permissions. This permission might enable the target application to perform
certain actions that it could not perform otherwise. For example, the target application might be able to affect protected processes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling Processes and Threads

When you are performing user-mode debugging, you activate, display, freeze, unfreeze, suspend, and unsuspend processes and threads.
The current or active process is the process that is currently being debugged. Similarly, the current or active thread is the thread that the debugger is currently controlling. The
actions of many debugger commands are determined by the identity of the current process and thread. The current process also determines the virtual address mappings that
the debugger uses.
When debugging begins, the current process is the one that the debugger is attached to or that caused the exception that broke into the debugger. Similarly, the current thread
is the one that was active when the debugger attached to the process or that caused the exception. However, you can use the debugger to change the current process and thread
and to freeze or unfreeze individual threads.
In kernel-mode debugging, processes and threads are not controlled by the methods that are described in this section. For more information about how processes and threads

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 133 of 1651

are manipulated in kernel mode, see Changing Contexts.

Displaying Processes and Threads
To display process and thread information, you can use the following methods:

The | (Process Status) command

The ~ (Thread Status) command
(WinDbg only) The Processes and Threads window

Setting the Current Process and Thread

To change the current process or thread, you can use the following methods:

The |s (Set Current Process) command

The ~s (Set Current Thread) command
(WinDbg only) The Processes and Threads window

Freezing and Suspending Threads

The debugger can change the execution of a thread by suspending the thread or by freezing the thread. These two actions have somewhat different effects.
Each thread has a suspend count that is associated with it. If this count is one or larger, the system does not run the thread. If the count is zero or lower, the system runs the
thread when appropriate.
Typically, each thread has a suspend count of zero. When the debugger attaches to a process, it increments the suspend counts of all threads in that process by one. If the
debugger detaches from the process, it decrements all suspend counts by one. When the debugger executes the process, it temporarily decrements all suspend counts by one.
You can control the suspend count of any thread from the debugger by using the following methods:

The ~n (Suspend Thread) command increments the specified thread's suspend count by one.
The ~m (Resume Thread) command decrements the specified thread's suspend count by one.

The most common use for these commands is to raise a specific thread's suspend count from one to two. When the debugger executes or detaches from the process, the thread
then has a suspend count of one and remains suspended, even if other threads in the process are executing.
You can suspend threads even when you are performing noninvasive debugging.
The debugger can also freeze a thread. This action is similar to suspending the thread in some ways. However, "frozen" is only a debugger setting. Nothing in the Windows
operating system recognizes that anything is different about this thread.
By default, all threads are unfrozen. When the debugger causes a process to execute, threads that are frozen do not execute. However, if the debugger detaches from the
process, all threads unfreeze.
To freeze and unfreeze individual threads, you can use the following methods:

The ~f (Freeze Thread) command freezes the specified thread.

The ~u (Unfreeze Thread) command unfreezes the specified thread.

In any event, threads that belong to the target process never execute when the debugger has broken into the target. The suspend count of a thread affects the thread's behavior
only when the debugger executes the process or detaches. The frozen status affects the thread's behavior only when the debugger executes the process.
Threads and Processes in Other Commands
You can add thread specifiers or process specifiers before many other commands. For more information, see the individual command topics.
You can add the ~e (Thread-Specific Command) qualifier before many commands and extension commands. This qualifier causes the command to be executed with respect
to the specified thread. This qualifier is especially useful if you want to apply a command to more than one thread. For example, the following command repeats the !gle
extension command for every thread that is being debugged.
~*e !gle
Multiple Systems
The debugger can attach to multiple targets at the same time. When these processes include dump files or include live targets on more than one computer, the debugger
references a system, process, and thread for each action. For more information about this kind of debugging, see Debugging Multiple Targets.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reattaching to the Target Application

If the debugger freezes or otherwise stops responding (that is, crashes) while you perform user-mode debugging, you can attach a new debugger to the existing process.
Note This method is supported only on Microsoft Windows XP and later versions of Windows. This method does not depend on whether the debugger originally created the
process or attached to an existing process. This method does not depend on whether you used the -pd option.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 134 of 1651

To reattach a debugger to an existing target application, do the following:

1. Determine the process ID of the target application.
2. Start a new instance of CDB or WinDbg. Use the -pe command-line option.
Debugger -pe -p PID
You can also use other command-line options.
You can also connect from a dormant debugger by using the .attach (Attach to Process) command together with the -e option.
3. After the attach is complete, end the original debugger process.
4. If the process does not respond properly, it might have a suspend count that is too high. You can use the ~m (Resume Thread) command to reduce the suspend count.
For more information about suspend counts, see Controlling Processes and Threads.
If the original debugger is still operating properly, this method might not work. The two debuggers are competing for debugging events, and the Windows operating system
does not necessarily assign all of the debugging events to the new debugger.
If the original debugger is ended before you attach the new debugger, the target application is also closed. (However, if the debugger attached with the -pd option and then
exits normally, the target application continues running. In this situation, a second debugger can attach to the target application without using the -pe option.)
If you are already debugging a process and want to detach from the process but leave it frozen in a debugging state, you can use the .abandon (Abandon Process) command.
After this command, any Windows debugger can reattach to the process by using the procedure that is described in this topic.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Managed Code

You can also use the WinDbg, CDB, and NTSD to perform limited debugging of target applications that contain managed code.
Introduction to Managed Code
Managed code is code that is executed together with the Microsoft .NET common language runtime (CLR). The .NET CLR manages raw code and data for the application
and provides enhanced services such as garbage collection and platform-independent code.
Compiled code that requires this runtime is called managed code. Code that does not require this runtime is called unmanaged code. An application that consists of only
managed code is called a managed application.
A managed .NET application can execute on any platform that supports the .NET CLR because the binary code that the compiler produces is not platform-specific. Binary
code in a managed application is in Microsoft intermediate language (MSIL). The binary also includes object information and other references (known as metadata).
A managed application differs from a traditional application because many details of the application's execution are determined by the runtime, such as how data structures are
laid out in memory, and how native code is generated and used. When the application is run, the runtime makes decisions about data usage and code usage while the
application is running, producing native code that is specific to the platform. The process of generating native code from MSIL is called managing or just-in-time (JIT)
compiling (or sometimes JITting). The component of the runtime that performs this translation step is called the JIT compiler.
After the JIT compiler has compiled the MSIL for a specific method, that method's stub is replaced with the address of the compiled code. Whenever this method is later
called, the native code executes and the JIT compiler does not have to be involved in the process.
Building Managed Code
You can build managed code by using several compilers that are manufactured by a variety of software producers. In particular, Microsoft Visual Studio .NET can build
managed code from four different languages:

C++ with managed extensions

C#
Visual Basic
JScript

By default, Microsoft Visual C++ .NET does not build managed applications. You must request this kind of build through a command-line switch or through the graphical
interface.
Debugging Managed Code
You can debug managed code by using the Sos.dll extension. This extension is located in the \clr10 subdirectory of the Debugging Tools for Windows installation.
To use this extension, load it and then type !clr10\sos.help..
This command lists all available extension commands and their parameters.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 135 of 1651

Debugging Tools for Windows

Debugger Operation (Kernel Mode)

This section includes the following topics:
Crashing and Rebooting the Target Computer
Synchronizing with the Target Computer
Changing Contexts
Mapping Driver Files
Performing Local Kernel Debugging
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Crashing and Rebooting the Target Computer

When you perform kernel debugging, you can cause the target computer to stop responding (that is, crash or bug check) by issuing the .crash (Force System Crash)
command. This command immediately causes the target computer to stop responding. The debugger writes a kernel-mode dump file if you have enabled crash dumps. (For
more information about these files, see Creating a Kernel-Mode Dump File.)
To restart the target computer, use the .reboot (Reboot Target Computer) command.
If you want the target computer to create a crash dump file and then restart, you should issue the .crash command, followed by the .reboot command. If you want only to
restart, the .crash command is not required.
In the early stages of the boot process, the connection between the host computer and the target computer is lost. No information about the target computer is available to the
debugger.
After the connection is broken, the debugger closes all symbol files and unloads all debugger extensions. At this point, all breakpoints are lost if you are running KD or CDB.
In WinDbg, you can save the current workspace. This action saves all breakpoints.
If you want to end the debugging session at this point, use the CTRL+B command (in KD) or click Exit on the File menu (in WinDbg).
If you do not exit the debugger, the connection is reestablished after enough of the boot process has completed. Symbols and extensions are reloaded at this point. If you are
running WinDbg, the kernel-mode workspace is reloaded.
You can tell the debugger to automatically break into the target computer during the restart process at two possible times:

When the first kernel module is loaded into memory

When the kernel initializes

To set an automatic breakpoint when the first kernel module loads, use the -d command-line option.
To set an automatic breakpoint when the kernel initializes, use the -b command-line option.
You can also change the break state after the debugger is running:

Control the initial module load and kernel initialization breakpoints like all exceptions and events. You can break into the debugger when these events occur, or ignore
them. You can also have a specified command automatically execute when these breakpoints are hit. For more information, see Controlling Exceptions and Events.
Use the CTRL+K shortcut keys in KD, the CTRL+ALT+K shortcut keys in WinDbg, and the Debug | Kernel Connection | Cycle Initial Break command in WinDbg
to change the break state. Every time that you use these commands, the debugger switches between three states: no automatic break, break upon kernel initialization,
and break on first kernel module load. This method cannot activate both automatic breakpoints at the same time.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Synchronizing with the Target Computer

Sometimes during kernel-mode debugging, the target computer stops responding to the debugger.
In KD, you can press CTRL+R (Re-synchronize) and then press ENTER to synchronize with the target computer. In WinDbg, use CTRL+ALT+R or Debug | Kernel
Connection | Resynchronize.
These commands frequently restore communication between the host and the target. However, resynchronization might not always be successful, especially if you are using a
1394 kernel connection.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 136 of 1651

The .restart (Restart Kernel Connection) command provides a more powerful method of resynchronization. This command is equivalent to exiting the debugger and then
attaching a new debugger to the existing session. This command is available only in KD, not in WinDbg.
The .restart command is most useful when you are performing remote debugging through remote.exe. (In this kind of debugging, it might be difficult to end and restart the
debugger.) However, you cannot use .restart from a debugging client if you are performing remote debugging through the debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Changing Contexts
In kernel-mode debugging, there are many processes, threads, and sometimes user sessions that are executing at the same time. Therfore, phrases such as "virtual address
0x80002000" or "the eax register" are ambiguous. You must specify the context in which such phrases can be understood.
The debugger has five different contexts that you can set while you are debugging:
1. The session context indicates the default user session. (This context applies to only Microsoft Windows XP and later versions of Windows. These operating systems
allow multiple logon sessions to coexist.)
2. The process context determines how the debugger interprets virtual addresses.
3. The user-mode address context is almost never set directly. This context is automatically set when you change the process context.
4. The register context determines how the debugger interprets registers and also controls the results of a stack trace. This context is also known as the thread context,
although that term is not completely accurate. An explicit context is also a type of register context. If you specify an explicit context, that context is used instead of the
current register context.
5. The local context determines how the debugger interprets local variables. This context is also known as the scope.

Session Context
In Windows XP and later versions of Windows, multiple logon sessions can run at the same time. Each logon session has its own processes.
The !session extension displays all logon sessions or changes the current session context.
The session context is used by the !sprocess and !spoolused extensions when the session number is entered as "-2".
When the session context is changed, the process context is automatically changed to the active process for that session.

Process Context
Each process has its own page directory that records how virtual addresses are mapped to physical addresses. When any thread within a process is executing, the Windows
operating system uses this page directory to interpret virtual addresses.
During user-mode debugging, the current process determines the process context. Virtual addresses that are used in debugger commands, extensions, and debugging
information windows are interpreted by using the page directory of the current process.
During kernel-mode debugging, you can set the process context by using the .process (Set Process Context) command. Use this command to select which process's page
directory is used to interpret virtual addresses. After you set the process context, you can use this context in any command that takes addresses. You can even set breakpoints
at this address. By including a /i option in the .process command to specify invasive debugging, you can also use the kernel debugger to set breakpoints in user space.
You can also set user-mode breakpoints from the kernel debugger by using a process-specific breakpoint on a kernel-space function. Set strategic breakpoints and wait for the
appropriate context to come up.
The user-mode address context is part of the process context. Typically, you do not have to set the user-mode address context directly. If you set the process context, the usermode address context automatically changes to the directory base of the relevant page table for the process. However, on an Itanium-based processor, a single process might
have more than one page directory. In this situation, you can use the .context (Set User-Mode Address Context) command to change the user-mode address context.
When you set the process context during kernel-mode debugging, that process context is retained until another .process command changes the context. The user-mode address
context is also retained until a .process or .context command changes it. These contexts are not changed when the target computer executes, and they are not affected by
changes to the register context or the local context.

Register Context
Each thread has its own register values. These values are stored in the CPU registers when the thread is executing and are stored in memory when another thread is executing.
During user-mode debugging, the current thread typically determines the register context. Any reference to registers in debugger commands, extensions, and debugging
information windows is interpreted according to the current thread's registers.
You can change the register context to a value other than the current thread while you are performing user-mode debugging by using one of the following commands:
.cxr (Display Context Record)
.ecxr (Display Exception Context Record)
During kernel-mode debugging, you can control the register context by using a variety of debugger commands, including the following commands:
.thread (Set Register Context)
.cxr (Display Context Record)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 137 of 1651

.trap (Display Trap Frame)

These commands do not change the values of the CPU registers. Instead, the debugger retrieves the specified register context from its location in memory. Actually, the
debugger can retrieve only the saved register values. (Other values are set dynamically and are not saved. The saved values are sufficient to re-create a stack trace.
After the register context is set, the new register context is used for any commands that use register values, such as k (Display Stack Backtrace) and r (Registers).
However, when you are debugging multiprocessor computers, some commands enable you to specify a processor. (For more information about such commands, see
Multiprocessor Syntax.) If you specify a processor for a command, the command uses the register context of the active thread on the specified processor instead of the current
register context, even if the specified processor is the currently-active processor.
Also, if the register context does not match the current processor mode setting, these commands produce incorrect or meaningless output. To avoid the output errors,
commands that depend on the register state fail until you change the processor mode to match the register context. To change the processor mode, use the .effmach (Effective
Machine) command,
Changing the register context can also change the local context. In this manner, the register context can affect the display of local variables.
If any application execution, stepping, or tracing occurs, the register context is immediately reset to match the program counter's position. In user mode, the register context is
also reset if the current process or thread is changed.
The register context affects stack traces, because the stack trace begins at the location that the stack pointer register (esp on an x86-based processor or sp on an Itanium-based
processor) points to. If the register context is set to an invalid or inaccessible value, stack traces cannot be obtained.
You can apply a processor breakpoint (data breakpoint) to a specific register context by using the .apply_dbp (Apply Data Breakpoint to Context) command.

Local Context
When a program is executing, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the function
that they are defined in.
When you are performing user-mode or kernel-mode debugging, the debugger uses the scope of the current function (the current frame on the stack) as the local context. To
change this context, use the .frame (Set Local Context) command, or double-click the desired frame in the Calls window.
In user-mode debugging, the local context is always a frame within the stack trace of the current thread. In kernel-mode debugging, the local context is always a frame within
the stack trace of the current register context's thread.
You can use only one stack frame at a time for the local context. Local variables in other frames cannot be accessed.
The local context is reset if any of the following events occur:

Any program execution, stepping or tracing

Any use of the thread delimiter (~) in any command
Any change to the register context

The !for_each_frame extension enables you to execute a single command repeatedly, once for each frame in the stack. This command changes the local context for each
frame, executes the specified command, and then returns the local context to its original value.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Mapping Driver Files

Replacing driver files can be difficult. Frequently, you have to boot to the Microsoft Windows safe build, replace the driver binary, and then boot again.
However, Windows XP and later versions of Windows support a simpler method of replacing driver files. You can use this method to replace any kernel-mode driver
(including display drivers), any Windows subsystem driver, or any other kernel-mode module. For simplicity, these files are called drivers in this topic, even though you can
use this method for any kernel-mode module.
You can use this method whenever WinDbg or KD is attached as a kernel debugger. You can also use this method on a boot driver, but it is more difficult. For more
information about how to use this method with boot drivers, see Replacing Boot Drivers.
To use a driver replacement map to replace driver files, do the following:
1. Create a driver replacement map file. This file is a text file that lists the drivers on the target computer and their replacement drivers on the host computer. You can
replace any number of drivers. For example, you might create a file that is named Mymap.ini in the d:\Map_Files directory of your host computer that contains the
following information.
map
\Systemroot\system32\drivers\videoprt.sys
\\myserver\myshare\new_drivers\videoprt.sys
For more information about the syntax of this file, see Driver Replacement Map File Format.
2. Set up a kernel debugging connection to the target computer, and start the kernel debugger (KD or WinDbg) on your host computer. (You do not have to actually break
in to the target computer.)
3. Load the driver replacement map file by doing one of the following:
Set the _NT_KD_FILES environment variable before you start the kernel debugger.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 138 of 1651

D:\Debugging Tools for Windows> set _NT_KD_FILES=d:\Map_Files\mymap.ini

D:\Debugging Tools for Windows> kd

Use the .kdfiles (Set Driver Replacement Map) command after you start the kernel debugger.
D:\Debugging Tools for Windows> kd
kd> .kdfiles d:\Map_Files\mymap.ini
KD file associations loaded from 'd:\Map_Files\mymap.ini'
You can also use the .kdfiles command to display the current driver replacement map file or to delete the driver replacement map. If you do not use this
command, the map persists until you exit the debugger.

After you complete this procedure, the driver replacement map takes effect.
Whenever the target computer is about to load a driver, it queries the kernel debugger to determine whether this driver has been mapped. If the driver has been mapped, the
replacement file is sent over the kernel connection and copied over the old driver file. The new driver is then loaded.

Driver Replacement Map File Format

Each driver file replacement is indicated by three lines in the driver replacement map file.

The first line consists of the word "map".

The second line specifies the path and file name of the old driver on the target computer.
The third line specifies the full path of the new driver. This driver can be located on the host computer or on some other server.

You can repeat this pattern of information any number of times.

Paths and file names are case insensitive, and the actual driver file names can be different. The file that you specify on the third line is copied over the file that you specify on
the second line when the target computer is about to load that driver.
Warning The old driver's path and file name must be an exact case-insensitive match for the path and file name that is stored in the Service Control Manager (SCM)
database. This path frequently begins with \SystemRoot\system32\drivers. However, several variations are possible (for example, a path that begins with \??
\c:\windows\system32\drivers). The name in the SCM database is identical to the name that was passed to MmLoadSystemImage.
The file can include blank lines and can include comment lines that begin with a number sign (#). However, after "map" appears in the file, the next two lines must be the old
driver and the new driver. The blank lines and comment lines cannot break up the three-line map blocks.
The following example shows a driver replacement map file.
map
\Systemroot\system32\drivers\videoprt.sys
e:\MyNewDriver\binaries\videoprt.sys
map
\Systemroot\system32\mydriver.sys
\\myserver\myshare\new_drivers\mydriver0031.sys
# Here is a comment
map
\??\c:\windows\system32\beep.sys
\\myserver\myshare\new_drivers\new_beep.sys
The driver replacement map file must be a text file, but you can use any file name and file name extension (.ini, .txt, .map, and so on).
Additional Notes
When driver substitution occurs, a message appears in the kernel debugger.
If you use CTRL+D (in KD) or CTRL+ALT+D (in WinDbg), you see verbose information about the replacement request. This information can be useful if you are not sure
whether the name that you have listed matches the one in the SCM database.
If the kernel debugger exits, no more driver replacement occurs. However, any drivers that have already been replaced do not revert to their old binaries, because the driver
files are actually overwritten.
This driver replacement feature automatically bypasses Windows File Protection (WFP).
You do not have to restart the target computer. Driver replacement occurs any time that the target computer loads a driver, regardless of whether it has been restarted. Of
course, most drivers are loaded during the boot process, so in practice you should restart the target computer after the map file has been loaded.
If the _NT_KD_FILES variable is defined, the specified driver replacement map file is read when the kernel debugger is started. If you issue the .kdfiles command, the
specified file is read immediately. At this point, the debugger verifies that the file has the basic map/line/line format. But the actual paths and file names are not verified until
substitution occurs.
After the map file has been read, the debugger stores its contents. If you change this file after this point, the changes have no effect (unless you reissue the .kdfiles command).
For large driver files, we recommend 1394 kernel connections. A kernel connection through a COM port might result in a long copying time.

Replacing Boot Drivers

If you want to replace a boot driver file by using this driver replacement method, you must connect the kernel debugger to the Windows boot loader (Ntldr), not to the
Windows kernel. Before you can make this connection, you must install a special debugger-enabled version of Ntldr. You can find this version of Ntldr in the Windows
Driver Kit (WDK), in the %DDKROOT%\debug directory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 139 of 1651

Because the target computer bypasses its Boot.ini file, you cannot set the kernel connection protocol in the typical manner. You must make the connection through the COM1
port on the target computer. The baud rate is 115200. Therefore, the kernel debugger on the host computer should be configured to use a COM connection at the 115200
speed.
This special method applies only to boot drivers (that is, Acpi.sys, Classpnp.sys, Disk.sys, and anything else that lm t n displays at the initial Windows breakpoint). If you
have to replace a standard driver that MmLoadSystemImage loads after the boot has been completed, you should use the standard method described earlier.
You cannot replace boot drivers on a computer that uses EFI firmware instead of the Boot.ini file (for example, an Itanium-based computer).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Performing Local Kernel Debugging

KD and WinDbg can perform local kernel debugging. This kind of debugging is kernel debugging on a single computer. In other words, the debugger is debugging the
computer that it is running on.
Local kernel debugging is supported only on Microsoft Windows XP and later versions of Windows. Only users who have debug permissions can start local kernel
debugging.
Starting Local Kernel Debugging
To enable local kernel debugging, you must use the /debug boot switch. For more information about this switch, see Configuring Software on the Target Computer.
To start a local kernel debugging session, start a debugger with the -kl command-line option, click the Local tab in the Kernel Debugging dialog box (File | Kernel Debug),
or use the .attach -k command. For more information about starting such a session, see Attaching to a Target Computer (Kernel Mode).
Commands That Are Not Available
Not all commands are available in a local kernel debugging session. Typically, you cannot use any command that causes the target computer to stop, even momentarily,
because you cannot resume operation.
In particular, you cannot use the following commands:

Execution commands, such as g (Go), p (Step), t (Trace), wt (Trace and Watch Data), tb (Trace to Next Branch), gh (Go with Exception Handled), and gn (Go
with Exception Not Handled)
Shutdown and dump file commands, such as .crash, .dump, and .reboot
Breakpoint commands, such as bp, bu, ba, bc, bd, be, and bl
Register display commands, such as r and variations
Stack trace commands, such as k and variations

If you are performing local kernel debugging with WinDbg, all of the equivalent menu commands and buttons are also unavailable.
Commands That Are Available
All memory input and output commands are available. You can freely read from user memory and kernel memory. You can also write to memory. Make sure that you do not
write to the wrong part of kernel memory, because it can corrupt data structures and frequently causes the computer to stop responding (that is, crash).
Difficulties in Performing Local Kernel Debugging
Local kernel debugging is a very delicate operation. Be careful that you do not corrupt or crash the system.
One of the most difficult aspects of local kernel debugging is that the machine state is constantly changing. Memory is paged in and out, the active process constantly changes,
and virtual address contexts do not remain constant. However, under these conditions, you can effectively analyze things that change slowly, such as certain device states.
Kernel-mode drivers and the Windows operating system frequently send messages to the kernel debugger by using DbgPrint and related functions. These messages are not
automatically displayed during local kernel debugging. You can display them by using the !dbgprint extension.
LiveKD
The LiveKD tool simulates local kernel debugging. This tool creates a "snapshot" dump file of the kernel memory, without actually stopping the kernel while this snapshot is
made. (Therefore, the snapshot might not actually show a single instant state of the computer.)
LiveKD is not part of the Debugging Tools for Windows package. You can download

LiveKd from the Windows Sysinternals site.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Extensions
CDB, KD, and WinDbg all allow the use of debugger extension commands. These extensions give these three Microsoft debuggers a great degree of power and flexibility.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 140 of 1651

Debugger extension commands are used much like the standard debugger commands. However, while the built-in debugger commands are part of the debugger binaries
themselves, debugger extension commands are exposed by DLLs distinct from the debugger.
This allows you to write new debugger commands which are tailored to your specific need. In addition, a number of debugger extension DLLs are shipped with the debugging
tools themselves.
This section includes:
Loading Debugger Extension DLLs
Using Debugger Extension Commands
Writing New Debugger Extensions
For information about specific extension commands, see the Debugger Extension Commands reference section.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Loading Debugger Extension DLLs

There are several methods of loading debugger extension DLLs, as well as controlling the default debugger extension DLL and the default debugger extension path:

(Before starting the debugger) Use the _NT_DEBUGGER_EXTENSION_PATH environment variable to set the default path for extension DLLs. This can be a
number of directory paths, separated by semicolons.
Use the .load (Load Extension DLL) command to load a new DLL.
Use the .unload (Unload Extension DLL) command to unload a DLL.
Use the .unloadall (Unload All Extension DLLs) command to unload all debugger extensions.
(Before starting the debugger; CDB only) Use the tools.ini file to set the default extension DLL.
(Before starting the debugger) Use the -a command-line option to set the default extension DLL.
Use the .extpath (Set Extension Path) command to set the extension DLL search path.
Use the .setdll (Set Default Extension DLL) command to set the default extension DLL.
Use the .chain (List Debugger Extensions) command to display all loaded debugger extension modules, in their default search order.

You can also load an extension DLL simply by using the full !module.extension syntax the first time you issue a command from that module. See Using Debugger Extension
Commands for details.
The extension DLLs that you are using must match the operating system of the target computer. The extension DLLs that ship with the Debugging Tools for Windows
package are each placed in a different subdirectory of the installation directory:

The w2kfre directory contains extensions that can be used with the free build of Microsoft Windows 2000.
The w2kchk directory contains extensions that can be used with the checked build of Windows 2000.
The winxp directory contains extensions that can be used with Windows XP and later versions of Windows.
The winext directory contains extensions that can be used with any version of Windows. The dbghelp.dll module, located in the base directory of Debugging Tools for
Windows, also contains extensions of this type.

If you write your own debugger extensions, you can place them in any directory. However, it is advised that you place them in a new directory and add that directory to the
debugger extension path.
There can be as many as 32 extension DLLs loaded.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Debugger Extension Commands

The use of debugger extension commands is very similar to the use of debugger commands. The command is typed in the Debugger Command window, producing either
output in this window or a change in the target application or target computer.
An actual debugger extension command is an entry point in a DLL called by the debugger.
Debugger extensions are invoked by the following syntax:
![module.]extension [arguments]
The module name should not be followed with the .dll file name extension. If module includes a full path, the default string size limit is 255 characters.
If the module has not already been loaded, it will be loaded into the debugger using a call to LoadLibrary(module). After the debugger has loaded the extension library, it
calls the GetProcAddress function to locate the extension name in the extension module. The extension name is case-sensitive and must be entered exactly as it appears in
the extension module's .def file. If the extension address is found, the extension is called.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 141 of 1651

Search Order
If the module name is not specified, the debugger will search the loaded extension modules for this export.
The default search order is as follows:
1. The extension modules that work with all operating systems and in both modes: dbghelp.dll and winext\ext.dll.
2. The extension module that works in all modes but is operating-system-specific. For Windows XP and later versions of Windows, this is winxp\exts.dll. There is no
corresponding module for Windows 2000.
3. The extension module that works with all operating systems but is mode-specific. For kernel mode, this is winext\kext.dll. For user mode, this is winext\uext.dll.
4. The extension module that is both operating-system-specific and mode-specific. The following table specifies this module.
Windows Build
User Mode
Kernel Mode
Windows 2000
w2kfre \ ntsdexts.dll w2kfre \ kdextx86.dll
(free build)
Windows 2000
w2kchk \ ntsdexts.dll w2kchk \ kdextx86.dll
(checked build)
Windows XP and later winxp \ ntsdexts.dll winxp \ kdexts.dll
When an extension module is unloaded, it is removed from the search chain. When an extension module is loaded, it is added to the beginning of the search order.
The .setdll (Set Default Extension DLL) command can be used to promote any module to the top of the search chain. By using this command repeatedly, you can completely
control the search chain.
Use the .chain (List Debugger Extensions) command to display a list of all loaded extension modules in their current search order.
If you attempt to execute an extension command that is not in any of the loaded extension modules, you will get an Export Not Found error message.
Additional Information
For information about specific extension commands, see the Debugger Extension Commands reference section.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Writing New Debugger Extensions

You can create your own debugging commands by writing an extension DLL. For example, you might want to write a command to display a complex data structure, or a
command that will stop and start the target depending on the value of certain variables or memory locations.
There are two different types of debugger extensions:

DbgEng extensions. These are based on the prototypes in the dbgeng.h header file, and also those in the wdbgexts.h header file.
WdbgExts extensions. These are based on the prototypes in the wdbgexts.h header file alone.

For information about how to write debugger extensions, see Writing DbgEng Extensions and Writing WdbgExts Extensions.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Debugging
This section includes:
Choosing the Best Remote Debugging Method
Remote Debugging Through the Debugger
Remote Debugging Through Remote.exe
Other Methods of Remote Debugging
Remote user-mode debugging involves two computers: the client and the server. The server is the machine that has the application to be debugged and the user-mode
debugger. The client is the machine that will remotely control the debugging session.
Remote kernel-mode debugging involves three computers: the client, the server, and the target computer. The target computer is the machine to be debugged. The server is a
machine with a kernel debugger, located at the same physical location as the target computer. The client is the machine that will remotely control the debugging session. See
Configuring Hardware for Kernel-Mode Debugging for details on the connection between the server and the target computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 142 of 1651

December 09, 2009

Debugging Tools for Windows

Choosing the Best Remote Debugging Method

There are two primary methods of performing remote debugging, as well as several additional methods and a huge number of combination methods.
Here are some tips to help you choose the best technique.

Remote debugging through the debugger is usually the best method. If you simply have one server and one client and they can freely connect to each other, the same
debugger binaries are installed on both the client and the server, and the debugging technician who will be operating the client will be able to talk to someone in the
room with the server, this is the recommended method.
The client and the server can be running any version of Windows. They do not have to be running the same version as each other.
If the client is unable to send a connection request to the server, but the server is able to send a request to the client, you can use remote debugging through the debugger
with a reverse connection by using the clicon parameter.

Remote debugging through remote.exe is used to remotely control a Command Prompt window. It can be used to remotely control KD, CDB, or NTSD. It cannot be
used with WinDbg.
If your client does not have copies of the debugger binaries, you must use the remote.exe method.

A process server or a KD connection server can be used if the debugging technician will not be able to talk to someone in the room with the server. All the actual
debugging work is done by the client (called the smart client); this removes the need to have a second person present at the server itself.
Process servers are used for user-mode debugging; KD connection servers are used for kernel-mode debugging. Other than this distinction, they behave in similar ways.
This method is also useful if the computer where the server will be running cannot handle heavy process loads, or if the technician running the client has access to
symbol files or source files that are confidential and cannot be accessed by the server. However, this method is not as fast or efficient as remote debugging through the
debugger. This method cannot be used for dump-file debugging.
See Process Servers (User Mode) and KD Connection Servers (Kernel Mode) for details.

A repeater is a lightweight proxy server that relays data between two computers. You can add a repeater between the client and the server if you are performing remote
debugging through the debugger or if you are using a process server.
Using a repeater may be necessary if your client and your server are unable to talk directly to each other, but can each access an outside computer. You can use reverseconnections with repeaters as well. It is even possible to use two repeaters in a row, but this is rarely necessary.
See Repeaters for details.

It is also possible to control CDB (or NTSD) from the kernel debugger. This is yet another form of remote debugging. See Controlling the User-Mode Debugger from
the Kernel Debugger for details.

Variations on all of these methods are possible.

It is possible to chain several computers together to take advantage of more than one transport method. You can create complicated transport sequences that take into account
where the technician is, where the symbols are located, and whether there are firewalls preventing connections in certain directions. See Advanced Remote Debugging
Scenarios for some examples.
You can even perform remote debugging on a single computer. For example, it might be useful to start a low-privilege process server and then connect to it with a highprivilege smart client. And on a Windows 2000 terminal server computer you can debug one session from another.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Debugging Through the Debugger

Remote debugging directly through the debugger is usually the best and easiest method of performing remote debugging.
This technique involves running two debuggers at different locations. The debugger that is actually doing the debugging is called the debugging server. The debugger that is
controlling the session from a distance is called the debugging client.
The two computers do not have to be running the same version of Windows; they can be running any version of Windows. The actual debuggers used need not be the same; a
WinDbg debugging client can connect to a CDB debugging server, and so on.
However, it is best that the debugger binaries on the two computers both be from the same release of the Debugging Tools for Windows package, or at least both from recent
releases.
To set up this remote session, the debugging server is set up first, and then the debugging client is activated. Any number of debugging clients can connect to a debugging
server. A single debugger can turn itself into several debugging servers at the same time, to facilitate different kinds of connections.
However, no single debugger can be a debugging client and a debugging server simultaneously. If you need to chain together three debuggers, see Other Methods of Remote
Debugging.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 143 of 1651

This section includes:

Activating a Debugging Server
Searching for Debugging Servers
Activating a Debugging Client
Client and Server Examples
Controlling a Remote Debugging Session
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating a Debugging Server

There are two ways to activate the debugging server. It can be activated when the debugger is started by using the -server command-line option. It can also be activated after
the debugger is running by using the .server command.
The debuggers support several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL).
The general syntax for starting a debugging client depends on the protocol used. The following options exist:
Debugger -server npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] [-noio] [Options]
Debugger -server tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] [-noio] [Options]
Debugger -server tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] [-noio] [Options]
Debugger -server com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] [-noio] [Options]
Debugger -server spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] [-noio
Debugger -server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] [-noio] [Options
Debugger -server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] [-noio
Another method of starting a debugging server is to use the .server (Create Debugging Server) command after the debugger has already been started. The syntax for this
command is similar to that of the command line:
.server npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable]
.server tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable]
.server tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6]
.server com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password]
.server spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password]
.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password]
.server ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password]
The parameters in the previous commands have the following possible values:
Debugger
Can be KD, CDB, NTSD, or WinDbg.
pipe=PipeName
When NPIPE or SPIPE protocol is used, PipeName is a string that will serve as the name of the pipe. Each pipe name should identify a unique debugging server. If you
attempt to reuse a pipe name, you will receive an error message. PipeName must not contain spaces or quotation marks. PipeName can include a numerical printf-style
format code, such as %x or %d. The debugger will replace this with the process ID of the debugger. A second such code will be replaced with the thread ID of the
debugger.
port=Socket
When TCP or SSL protocol is used, Socket is the socket port number.
It is also possible to specify a range of ports separated by a colon. The debugger will check each port in this range to see if it is free. If it finds a free port and no error
occurs, the debugging server will be created. The debugging client will have to specify the actual port being used to connect to the server. To determine the actual port,
use any of the methods described in Searching for Debugging Servers; when this debugging server is displayed, the port will be followed by two numbers separated by a
colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the
search results will show "port=53:60". (If you are using the clicon parameter to establish a reverse connection, the debugging client can specify a range of ports in this
manner, while the server must specify the actual port used.)
clicon=Client
When TCP or SSL protocol is used and the clicon parameter is specified, a reverse connection will be opened. This means that the debugging server will try to connect to
the debugging client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. Client

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 144 of 1651

specifies the network name or IP address of the computer on which the debugging client exists or will be created. The two initial backslashes (\\) are optional.
Since the server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or is broken you
will have to restart the server connection. A reverse-connection server will not appear when another debugger displays all active servers.
Note When clicon is used, it is best to start the debugging client before the debugging server is created, although the usual order (server before client) is also permitted.
port=COMPort
When COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
When COM protocol is used, BaudRate specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted.
channel=COMChannel
If COM protocol is used, COMChannel specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254,
inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable
in that situation you cannot use channels within a COM port.)
proto=Protocol
If SSL or SPIPE protocol is used, Protocol specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3.
Cert
If SSL or SPIPE protocol is used, Cert specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits
given by the certificate's snapin). If the syntax certuser=Cert is used, the debugger will look up the certificate in the system store (the default store). If the syntax
machuser=Cert is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication.
hidden
Prevents the server from appearing when another debugger displays all active servers.
password=Password
Requires a client to supply the specified password in order to connect to the debugging session. Password can be any alphanumeric string.
Caution Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is
used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol!
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
-noio
If the debugging server is created with the -noio option, no input or output can be done through the server itself. The debugger will only accept input from the debugging
client (plus any initial command or command script specified by the -c command-line option). All output will be directed to the debugging client. The -noio option is
only available with KD, CDB, and NTSD. If NTSD is used for the server, no console window will be created at all.
IcfEnable
(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet
Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When IcfEnable is used with a TCP connection,
the debugger causes Windows to open the port specified by the Socket parameter. When IcfEnable is used with a named pipe connection, the debugger causes Windows
to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates.
Options
Any additional command-line parameters can be placed here. See Command-Line Options for a full list.
You can use the .server command to start multiple servers using different protocol options. This allows different kinds of debugging clients to join the session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Searching for Debugging Servers

You can use KD or CDB with the -QR command-line option to obtain a list of available debugging servers that are running on a network server.
This list may include servers that no longer exist but which were not shut down properly connecting to one of these generates an error message. The list will also include
process servers and KD connection servers. The server type will be indicated in each case.
The syntax for this is as follows:
Debugger -QR \\Server
Debugger can be either KD or CDB the display will be the same in either case. The two backslashes (\\) preceding Server are optional.
In WinDbg, you can use the Connect to Remote Debugger Session dialog box to browse a list of available servers. See File | Connect to Remote Session for details.
Each debugging server is listed with the complete connection string that can be used to start a debugging client (except that any password will be replaced with an asterisk).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating a Debugging Client

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 145 of 1651

Once the debugging server has been activated, you can start a debugging client on another computer and connect to the debugging session.
There are two ways to start a debugging client: by using the -remote command-line option, or by using the WinDbg graphical interface.
The protocol of the client must match the protocol of the server. The general syntax for starting a debugging client depends on the protocol used. The following options exist:
Debugger -remote npipe:server=Server,pipe=PipeName[,password=Password]
Debugger -remote tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
Debugger -remote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
Debugger -remote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
Debugger -remote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
To use the graphical interface to connect to a remote debugging session, WinDbg must be in dormant mode it must either have been started with no command-line
parameters, or it must have ended the previous debugging session. Select the File | Connect to Remote Session menu command, or press the CTRL+R shortcut key. When
the Connect to Remote Debugger Session dialog box appears, enter one of the following strings into the Connection string text box:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
Alternatively, you can use the Browse button to locate active debugging servers. See File | Connect to Remote Session for details.
The parameters in the preceding commands have the following possible values:
Debugger
This does not have to be the same debugger as the one used by the debugging client WinDbg, KD, and CDB are all interchangeable for purposes of remote debugging
through the debugger.
Server
This is the network name or IP address of the computer on which the debugging server was created. The two initial backslashes (\\) are optional on the command line, but
are not permitted in the WinDbg dialog box.
pipe=PipeName
If NPIPE or SPIPE protocol is used, PipeName is the name that was given to the pipe when the server was created.
port=Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the server was created.
clicon
Specifies that the debugging server will try to connect to the client through a reverse connection. The client must use clicon if and only if the server is using clicon. In
most cases, the debugging client is started before the debugging server when a reverse connection is used.
port=COMPort
If COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
If COM protocol is used, BaudRate should match the baud rate chosen when the server was created.
channel=COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the server was created.
proto=Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the server was created.
Cert
If SSL or SPIPE protocol is used, you should use the identical certuser=Cert or machuser=Cert parameter that was used when the server was created.
password=Password
If a password was used when the server was created, Password must be supplied in order to create the debugging client. It must match the original password. Passwords
are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005."
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
Command-line options used to start new debugging sessions (like -p) cannot be used by the debugging client, but only by the server. Configuration options (like -n) will work
from either the client or the server.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 146 of 1651

Client and Server Examples

Suppose one person is running an application on a computer named \\BOX17. This application has problems, but the debugging technician is at a different site.
The first person sets up a debugging server using CDB on \\BOX17. The target application has a process ID of 122. TCP protocol is chosen, with a socket port number of
1025. The server is started with the following command:
E:\Debugging Tools for Windows> cdb -server tcp:port=1025 -p 122
On the other computer, the technician decides to use WinDbg as the debugging client. It can be started with this command:
G:\Debugging Tools> windbg -remote tcp:server=BOX17,port=1025
Here is another example. In this case, NPIPE protocol is chosen, and CDB is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric
string in this example, "MainPipe". The debugging server is started with this command:
E:\Debugging Tools for Windows> cdb -server npipe:pipe=MainPipe -v winmine.exe
The technician is not sure what name was used, so he or she queries the network for pipe names:
G:\Debugging Tools> cdb -QR \\BOX17
Servers on \\BOX17:
Debugger Server - npipe:Pipe=MainPipe
Remote Process Server - npipe:Pipe=AnotherPipe
Two pipes are shown. However, only one is a debugging server the other is a process server, and we are not interested in that. So MainPipe must be the correct name.
Then the following command can be used to start the debugging client:
G:\Debugging Tools> cdb -remote npipe:server=BOX17,pipe=MyPipe
Using a Secure Server
Here is an example of a secure server. This server uses secure sockets layer with an S-Channel protocol of TLS1. The debugger will look for the certificate in the machine
store. The certificate is specified by its hexadecimal thumbprint.
D:\> cdb -server "ssl:proto=tls1,machuser=ab 38 f7 ae 13 20 ac da 05 14 65 60 30 83 7b 83 09 2c d2 34,port=1234" notepad.exe

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling a Remote Debugging Session

Once the remote session has been started, commands can be entered into either the debugging server or the debugging client. If there are multiple clients, any of them can
enter commands. Once ENTER is pressed, the command is transmitted to the debugging server and executed.
Whenever one user enters a command, all users will see the command itself and its output. If this command was issued from a debugging client, all other users will see an
identification, preceding the command, of which user issued the command. Commands issued from the debugging server do not have this prefix.
After a command is executed by one user, other users who are connected through KD or CDB will not see a new command prompt. On the other hand, users of WinDbg will
see the prompt in the bottom panel of the Debugger Command window continuously, even when the debugger engine is running. Neither of these should be a cause for alarm;
any user can enter a command at any time, and the engine will execute these commands in the order they were received.
Actions made through the WinDbg interface will also be executed by the debugging server.
Communication Between Users
Whenever a new debugging client connects to the session, all other users will see a message that this client has connected. No message is displayed when a client disconnects.
The .clients (List Debugging Clients) command will list all clients currently connected to the debugging session.
The .echo (Echo Comment) command is useful for sending messages from one user to another.
WinDbg Workspaces
When WinDbg is being used as a debugging client, its workspace will only save values set through the graphical interface. Changes made through the Debugger Command
window will not be saved. (This guarantees that only changes made by the local client will be reflected, since the Debugger Command window will accept input from all
clients as well as the debugging server.)
File Paths
The symbol path, executable image path, and extension DLL path are all interpreted as file paths relative to the Debugging Tools for Windows installation folder on the
debugging server.
When WinDbg is used as a debugging client, it has its own local source path as well. All source-related commands will access the source files on the local computer.
Therefore, the proper paths have to be set on any client or server that will use source commands.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Remote debugging through a process server involves running a small application called a process server on the server. Then a user-mode debugger is started on the client.
Since this debugger will be doing all of the actual processing, it is called the smart client.
The Debugging Tools for Windows package includes a process server called DbgSrv (dbgsrv.exe) for use in user mode.
The two computers do not have to be running the same version of Windows; they can be running any version of Windows. However, the debugger binaries used on the client
and the DbgSrv binary used on the server must be from the same release of the Debugging Tools for Windows package. This method cannot be used for dump-file debugging.
To set up this remote session, the process server is set up first, and then the smart client is activated. Any number of smart clients can operate through a single process server
these debugging sessions will remain separate and will not interfere with each other. If a debugging session is ended, the process server will continue to run and can be
used for new debugging sessions.
This section includes:
Activating a Process Server
Searching for Process Servers
Activating a Smart Client
Process Server Examples
Controlling a Process Server Session
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 150 of 1651

December 09, 2009

Debugging Tools for Windows

Activating a Process Server

The process server that is included in Debugging Tools for Windows is called DbgSrv (dbgsrv.exe).
DbgSrv supports several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL).
The syntax for the DbgSrv command line depends on the protocol used. The following options exist:
dbgsrv -t npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable] [[-sifeo Executable] -c[s] AppCmdLine] [-x | dbgsrv -t tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable] [[-sifeo Executable] -c[s] AppCmdLine
dbgsrv -t tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6] [[-sifeo Executable] -c[s] AppCmdLine] [-x |
dbgsrv -t com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password] [[-sifeo Executable] -c[s] AppCmdLine
dbgsrv -t spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password] [[-sifeo Executable
dbgsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password] [[-sifeo Executable
dbgsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password] [[-sifeo Executable
The parameters in the previous commands have the following possible values:
pipe=PipeName
When NPIPE or SPIPE protocol is used, PipeName is a string that will serve as the name of the pipe. Each pipe name should identify a unique process server. If you
attempt to reuse a pipe name, you will receive an error message. PipeName must not contain spaces or quotation marks. PipeName can include a numerical printf-style
format code, such as %x or %d. The process server will replace this with the process ID of DbgSrv. A second such code will be replaced with the thread ID of DbgSrv.
port=Socket
When TCP or SSL protocol is used, Socket is the socket port number.
It is also possible to specify a range of ports separated by a colon. DbgSrv will check each port in this range to see if it is free. If it finds a free port and no error occurs,
the process server will be created. The smart client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the
methods described in Searching for Process Servers; when this process server is displayed, the port will be followed by two numbers separated by a colon. The first
number will be the actual port used; the second can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the search results
will show "port=53:60". (If you are using the clicon parameter to establish a reverse connection, the smart client can specify a range of ports in this manner, while the
process server must specify the actual port used.)
clicon=Client
When TCP or SSL protocol is used and the clicon parameter is specified, a reverse connection will be opened. This means that the process server will try to connect to
the smart client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. Client
specifies the network name or IP address of the computer on which the smart client exists or will be created. The two initial backslashes (\\) are optional.
Since the process server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or is
broken you will have to restart the process server. A reverse-connection process server will not appear when someone uses the -QR command-line option to display all
active servers.
Note When clicon is used, it is best to start the smart client before the process server is created, although the usual order (server before client) is also permitted.
port=COMPort
When COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
When COM protocol is used, BaudRate specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted.
channel=COMChannel
If COM protocol is used, COMChannel specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254,
inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable
in that situation you cannot use channels within a COM port.)
proto=Protocol
If SSL or SPIPE protocol is used, Protocol specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3.
Cert
If SSL or SPIPE protocol is used, Cert specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits
given by the certificate's snapin). If the syntax certuser=Cert is used, the debugger will look up the certificate in the system store (the default store). If the syntax
machuser=Cert is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication.
hidden
Prevents the process server from appearing when someone uses the -QR command-line option to display all active servers.
password=Password
Requires a smart client to supply the specified password in order to connect to the process server. Password can be any alphanumeric string.
Caution Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is
used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol!
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
IcfEnable
(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet
Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When IcfEnable is used with a TCP connection,
the debugger causes Windows to open the port specified by the Socket parameter. When IcfEnable is used with a named pipe connection, the debugger causes Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 151 of 1651

to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates.
-sifeo Executable
Suspends the Image File Execution Option (IFEO) value for the given image. Executable should include the file name of the executable image, including the file name
extensions. The -sifeo option allows DbgSrv to be set as the IFEO debugger for an image created by the -c option, without causing recursive invocation due to the IFEO
setting. This option can be used only if -c is used.
-c
Causes DbgSrv to create a new process. You can use this to create a process that you intend to debug. This is similar to spawning a new process from the debugger,
except that this process will not be debugged when it is created. To debug this process, determine its PID and use the -p option when starting the smart client to debug
this process.
s
Causes the newly-created process to be immediately suspended. If you are using this option, it is recommended that you use CDB as your smart client, and that you start
the smart client with the -pb command-line option, in conjunction with -p PID. If you include the -pb option on the command line, the process will resume when the
debugger attaches to it; otherwise you can resume the process with the ~*m command.
AppCmdLine
Specifies the full command line of the process to be created. AppCmdLine can be either a Unicode or ASCII string, and can include any printable character. All text that
appears after the -c[s] parameter will be taken to form the string AppCmdLine.
-x
Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its
command line.
-pc
Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its
command line. A syntax error results if -pc is the final element on the DbgSrv command line. Aside from this restriction, -pc is identical to -x.
You can start any number of process servers on one computer. However, this is generally unnecessary, since one process server can be used by any number of smart clients
(each engaged in a different debugging session).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Searching for Process Servers

You can use KD or CDB with the -QR command-line option to obtain a list of available process servers that are running on a network server.
This list may include servers that no longer exist but which were not shut down properly connecting to one of these generates an error message. The list will also include
debugging servers and KD connection servers. The server type will be indicated in each case.
The syntax for this is as follows:
Debugger -QR \\Server
Debugger can be either KD or CDB the display will be the same in either case. The two backslashes (\\) preceding Server are optional.
In WinDbg, you can use the Connect to Remote Stub Server dialog box to browse a list of available process servers.
Each process server is listed with the complete connection string that can be used to start a debugging client (except that any password will be replaced with an asterisk). KD
connection servers are also included in this list. See File | Connect to Remote Stub for more details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating a Smart Client

Once the DbgSrv process server has been activated, you can create a smart client on another computer and begin a debugging session.
There are two ways to start a smart client: by starting CDB or WinDbg with the -premote command-line option, or by using the WinDbg graphical interface.
The protocol of the smart client must match the protocol of the process server. The general syntax for starting a smart client depends on the protocol used. The following
options exist:
Debugger -premote npipe:server=Server,pipe=PipeName[,password=Password] [Options]
Debugger -premote tcp:server=Server,port=Socket[,password=Password][,ipversion=6] [Options]
Debugger -premote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] [Options]
Debugger -premote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] [Options]
Debugger -premote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] [
Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] [Options

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 152 of 1651

Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] [Options

To use the graphical interface to connect to a process server, WinDbg must be in dormant mode it must either have been started with no command-line parameters, or it
must have ended the previous debugging session. Select the File | Connect to Remote Stub menu command. When the Connect to Remote Stub Server dialog box appears,
enter one of the following strings into the Connection string text box:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
Alternatively, you can use the Browse button to locate active process servers. See File | Connect to Remote Stub for details.
The parameters in the preceding commands have the following possible values:
Debugger
This can be CDB or WinDbg.
Server
This is the network name or IP address of the computer on which the process server was created. The two initial backslashes (\\) are optional on the command line, but
are not permitted in the WinDbg dialog box.
pipe=PipeName
If NPIPE or SPIPE protocol is used, PipeName is the name that was given to the pipe when the process server was created.
port=Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the process server was created.
clicon
Specifies that the process server will try to connect to the smart client through a reverse connection. The client must use clicon if and only if the server is using clicon. In
most cases, the smart client is started before the process server when a reverse connection is used.
port=COMPort
If COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
If COM protocol is used, BaudRate should match the baud rate chosen when the process server was created.
channel=COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the process server was created.
proto=Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the process server was created.
Cert
If SSL or SPIPE protocol is used, you should use the identical certuser=Cert or machuser=Cert parameter that was used when the process server was created.
password=Password
If a password was used when the process server was created, Password must be supplied in order to create the smart client. It must match the original password.
Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005."
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
Options
Any additional command-line parameters can be placed here. See Command-Line Options for a full list. If you are using CDB, this must specify the process you wish to
debug. If you are using WinDbg, you can specify the process on the command line or through the graphical interface.
Since the process server simply acts as a gateway for the smart client, the additional Options will be the same as those you would use if you were starting a user-mode
debugger on the same machine as the target application. See Starting the Debugger for instructions.
If you are using the -premote option with .attach (Attach to Process) or .create (Create Process), the parameters are the same as those listed above.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Process Server Examples

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 153 of 1651

Here is another example. In this case, NPIPE protocol is chosen, and CDB is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric
string in this example, "AnotherPipe". The process server is started with this command:
E:\Debugging Tools for Windows> dbgsrv -t npipe:pipe=AnotherPipe
The technician is not sure what name was used, so he or she queries the network for pipe names:
G:\Debugging Tools> cdb -QR \\BOX17
Servers on \\BOX17:
Debugger Server - npipe:Pipe=MainPipe
Remote Process Server - npipe:Pipe=AnotherPipe
Two pipes are shown. However, only one is a process server the other is a debugging server, and we are not interested in that. So AnotherPipe must be the correct name.
Then the following command can be used to start the smart client:
G:\Debugging Tools> cdb -premote npipe:server=BOX17,pipe=AnotherPipe -v sol.exe
For a more complicated example using a process server, see Symbols in the Middle.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling a Process Server Session

Once the remote session has been started, the smart client can be used as if it were debugging a target application on a single machine. All commands will behave as they
would in this situation, except that paths are relative to the smart client's computer.
Using WinDbg as a Smart Client
After WinDbg is started as a smart client for a user-mode process server, it will remain attached to the process server permanently. If the debugging session is ended, the
File | Attach to a Process menu command or the .tlist (List Process IDs) command will display all processes running on the computer running the process server. WinDbg
can attach to any of these processes.
The File | Open Executable command cannot be used. A new process can only be spawned if it is included on the WinDbg command line.
In this situation, WinDbg will not be able to debug processes on the computer where it is running, nor will it be able to start a kernel debugging session.
Ending the Session
CDB or WinDbg can exit or end the debugging session in the normal fashion. See Ending the Debugging Session for details. The process server will remain in operation and
can be re-used as many times as desired. (It can also be used by for any number of simultaneous debugging sessions.)
The process server can be terminated from either computer. To terminate it from the smart client, use the .endpsrv (End Process Server) command. To terminate the process
server from the computer it is running on, use Task Manager to end the dbgsrv.exe process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KD Connection Servers (Kernel Mode)

Kernel-mode remote debugging through a KD connection server involves running a small application called a KD connection server on the server. Then a kernel-mode
debugger is started on the client. Since this debugger will be doing all of the actual processing, it is called the smart client.
The Debugging Tools for Windows package includes a KD connection server called KdSrv (kdsrv.exe).
The two computers do not have to be running the same version of Windows; they can be running any version of Windows. However, the debugger binaries used on the client
and the KdSrv binary used on the server must be from the same release of the Debugging Tools for Windows package. This method cannot be used for dump-file debugging.
To set up this remote session, the KD connection server is set up first, and then the smart client is activated. Any number of smart clients can operate through a single KD
connection server, but they must each be connected to a different kernel debugging session.
This section includes:
Activating a KD Connection Server
Searching for KD Connection Servers
Activating a Smart Client (Kernel Mode)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 154 of 1651

KD Connection Server Examples

Controlling a KD Connection Server Session
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating a KD Connection Server

The KD connection server that is included in Debugging Tools for Windows is called KdSrv (kdsrv.exe).
KdSrv supports several transport protocols: named pipe (NPIPE), TCP, COM port, secure pipe (SPIPE), and secure sockets layer (SSL).
The syntax for the KdSrv command line depends on the protocol used. The following options exist:
kdsrv -t npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable]
kdsrv -t tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable]
kdsrv -t tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6]
kdsrv -t com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password]
kdsrv -t spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password]
kdsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password]
kdsrv -t ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password]
The parameters in the previous commands have the following possible values:
pipe=PipeName
When NPIPE or SPIPE protocol is used, PipeName is a string that will serve as the name of the pipe. Each pipe name should identify a unique process server. If you
attempt to reuse a pipe name, you will receive an error message. PipeName must not contain spaces or quotation marks. PipeName can include a numerical printf-style
format code, such as %x or %d. This will be replaced by the process ID of KdSrv. A second such code will be replaced by the thread ID of KdSrv.
port=Socket
When TCP or SSL protocol is used, Socket is the socket port number.
It is also possible to specify a range of ports separated by a colon. KdSrv will check each port in this range to see if it is free. If it finds a free port and no error occurs, the
KD connection server will be created. The smart client will have to specify the actual port being used to connect to the server. To determine the actual port, use any of the
methods described in Searching for KD Connection Servers; when this KD connection server is displayed, the port will be followed by two numbers separated by a
colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the
search results will show "port=53:60". (If you are using the clicon parameter to establish a reverse connection, the smart client can specify a range of ports in this manner,
while the KD connection server must specify the actual port used.)
clicon=Client
When TCP or SSL protocol is used and the clicon parameter is specified, a reverse connection will be opened. This means that the KD connection server will try to
connect to the smart client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction.
Client specifies the network name or IP address of the computer on which the smart client exists or will be created. The two initial backslashes (\\) are optional.
Since the KD connection server is looking for one specific client, you cannot connect multiple clients to the server if you use this method. If the connection is refused or
is broken you will have to restart the process server. A reverse-connection KD connection server will not appear when someone uses the -QR command-line option to
display all active servers.
Note When clicon is used, it is best to start the smart client before the KD connection server is created, although the usual order (server before client) is also permitted.
port=COMPort
When COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
When COM protocol is used, BaudRate specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted.
channel=COMChannel
If COM protocol is used, COMChannel specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254,
inclusive. You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable
in that situation you cannot use channels within a COM port.)
proto=Protocol
If SSL or SPIPE protocol is used, Protocol specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3.
Cert
If SSL or SPIPE protocol is used, Cert specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits
given by the certificate's snapin). If the syntax certuser=Cert is used, the debugger will look up the certificate in the system store (the default store). If the syntax
machuser=Cert is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication.
hidden
Prevents the KD connection server from appearing when someone uses the -QR command-line option to display all active servers.
password=Password
Requires a smart client to supply the specified password in order to connect to the KD connection server. Password can be any alphanumeric string.
Caution Using a password with TCP, NPIPE, or COM protocol only offers a small amount of protection, because the password is not encrypted. When a password is
used with SSL or SPIPE protocol, it is encrypted. If you want to establish a secure remote session, you must use SSL or SPIPE protocol!

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 155 of 1651

ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
IcfEnable
(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet
Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When IcfEnable is used with a TCP connection,
the debugger causes Windows to open the port specified by the Socket parameter. When IcfEnable is used with a named pipe connection, the debugger causes Windows
to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Searching for KD Connection Servers

You can use KD or CDB with the -QR command-line option to obtain a list of available KD connection servers that are running on a network server.
This list may include servers that no longer exist but which were not shut down properly connecting to one of these generates an error message. The list will also include
debugging servers and user-mode process servers. The server type will be indicated in each case.
The syntax for this is as follows:
Debugger -QR \\Server
Debugger can be either KD or CDB the display will be the same in either case. The two backslashes (\\) preceding Server are optional.
In WinDbg, you can use the Connect to Remote Stub Server dialog box to browse a list of available KD connection servers.
Each KD connection server is listed with the complete connection string that can be used to start a debugging client (except that any password will be replaced with an
asterisk). Process servers are also included in this list. See File | Connect to Remote Stub for more details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating a Smart Client (Kernel Mode)

Once the KD connection server has been activated, you can create a smart client on another computer and begin a debugging session.
There are two ways to start a smart client: by starting KD or WinDbg with the kernel protocol kdsrv, or by using the WinDbg graphical interface.
You need to specify the remote transfer protocol used by the KD connection server. You can also specify the protocol for the actual kernel connection between the KD
connection server and the target computer, or you can use the default.
The general syntax for starting a smart client depends on the protocol used. The following options exist:
Debugger -k kdsrv:server=@{npipe:server=Server,pipe=PipeName[,password=Password]},trans=@{ConnectType} [Options]
Debugger -k kdsrv:server=@{tcp:server=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options
Debugger -k kdsrv:server=@{tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options
Debugger -k kdsrv:server=@{com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]},trans=@{ConnectType
Debugger -k kdsrv:server=@{spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password
Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password
Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password
To use the graphical interface to connect to a KD connection server, WinDbg must be in dormant mode it must either have been started with no command-line parameters,
or it must have ended the previous debugging session. Select the File | Connect to Remote Stub menu command. When the Connect to Remote Stub Server dialog box
appears, enter one of the following strings into the Connection string text box:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 156 of 1651

ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
Alternatively, you can use the Browse button to locate active KD connection servers. See File | Connect to Remote Stub for details.
The parameters in the preceding commands have the following possible values:
Debugger
This can be KD or WinDbg.
Server
This is the network name or IP address of the computer on which the KD connection server was created.The two initial backslashes (\\) are optional on the command line,
but are not permitted in the WinDbg dialog box.
pipe=PipeName
If NPIPE or SPIPE protocol is used, PipeName is the name that was given to the pipe when the KD connection server was created.
port=Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the KD connection server was created.
clicon
Specifies that the KD connection server will try to connect to the smart client through a reverse connection. The client must use clicon if and only if the server is using
clicon. In most cases, the smart client is started before the KD connection server when a reverse connection is used.
port=COMPort
If COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
If COM protocol is used, BaudRate should match the baud rate chosen when the KD connection server was created.
channel=COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the KD connection server was created.
proto=Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the KD connection server was created.
Cert
If SSL or SPIPE protocol is used, you should use the identical certuser=Cert or machuser=Cert parameter that was used when the KD connection server was created.
password=Password
If a password was used when the KD connection server was created, Password must be supplied in order to create the smart client. It must match the original password.
Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005."
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
trans=@{ConnectType}
Tells the debugger how to connect to the target. The following kernel connection protocols are permitted:
com:port=ComPort,baud=BaudRate
1394:channel=1394Channel[,symlink=1394Protocol]
usb2:targetname=String
com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect]
com:modem
For information about these protocols, see Choosing Kernel Debugging Settings. You can omit any of the parameters for these protocols for example, you can say
trans=@{com:} and the debugger will default to the values specified by the environment variables on the computer where KdSrv is running.
Options
Any additional command-line parameters can be placed here. See Command-Line Options for a full list.
Since the KD connection server simply acts as a gateway for the smart client, the additional Options will be the same as those you would use if you were starting a kernel
debugger on computer where KdSrv is running. The exception to this is any option that specifies a path or filename will be taken as a path on the computer where the smart
client is running.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KD Connection Server Examples

Suppose a debugging technician is not present at the site where the computer to be debugged is located. The debugging technician asks someone at this site to connect this
target computer to some other computer with a debug cable.
Let this other computer be at IP address 127.0.0.42. The debug cable connects COM1 on this computer to whichever port has been debug-enabled on the target computer. The
KD connection server is started with this command:
E:\Debugging Tools for Windows> kdsrv -t tcp:port=1027
Then at the other location, the technician starts WinDbg as a smart client with this command:
G:\Debugging Tools> windbg -k kdsrv:server=@{tcp:server=127.0.0.42,port=1027},trans=@{com:port=com1,baud=57600} -y SymbolPath
The symbol path will be relative to the computer where the smart client is running.
Here is another example. In this case, NPIPE protocol is chosen, and KD is used instead of WinDbg. The first user chooses a pipe name. This can be any alphanumeric string

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 157 of 1651

in this example, "KernelPipe".

E:\Debugging Tools for Windows> set _NT_DEBUG_PORT=com1
E:\Debugging Tools for Windows> kdsrv -t npipe:pipe=KernelPipe
The technician is not sure what name was used, so he or she queries the network for pipe names:
G:\Debugging Tools> cdb -QR 127.0.0.42
Servers on 127.0.0.42:
Debugger Server - npipe:Pipe=MainPipe
Remote Process Server - npipe:Pipe=AnotherPipe
Remote Kernel Debugger Server - npipe:Pipe=KernelPipe
Three pipes are shown. However, only one is a KD connection server the others are a debugging server and a user-mode process server. So the following command can be
used to start the smart client:
G:\Debugging Tools> kd -k kdsrv:server=@{npipe:server=127.0.0.42,pipe=KernelPipe},trans=@{com:baud=57600} -y SymbolPath
Notice that although the baud rate is specified, the port is not. This causes the debugger to default to the port specified by _NT_DEBUG_PORT on the computer where KdSrv
is running.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling a KD Connection Server Session

Once the remote session has been started, the smart client can be used as if it were debugging the target computer from the computer where the KD connection server is
running. All commands will behave as they would in this situation, except that paths are relative to the smart client's computer.
Using WinDbg as a Smart Client
After WinDbg is started as a smart client for a KD connection server, you can use the Debug | Stop Debugging command to end the debugging session. At that point,
WinDbg will enter dormant mode and will no longer be connected to the KD connection server. All subsequent debugging will be done on the computer where WinDbg is
running. You cannot reattach to the KD connection serve by using File | Kernel Debug this can only be done from the command line.
Ending the Session
KD or WinDbg can exit or end the debugging session in the normal fashion. See Ending the Debugging Session for details. The KD connection server will remain in
operation and can be re-used as many times as desired. (It can also be used by for any number of simultaneous debugging sessions.)
The KD connection server can be terminated from either computer. To terminate it from the smart client, use the .endpsrv (End Process Server) command. To terminate the
KD connection server from the computer it is running on, use Task Manager to end the kdsrv.exe process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Repeaters
A repeater is a lightweight proxy server that runs on a computer and relays data between two other computers. The repeater does not process the data in any way. The two
other computers barely notice the repeater; from their perspective it seems as if they are directly connected to each other.
The processes running on these two other computers are called the server and the client. There is not any fundamental difference between them from the repeater's point of
view, except that in most cases the server is started first, then the repeater, and finally the client.
The Debugging Tools for Windows package includes a repeater called DbEngPrx (dbengprx.exe).
This section includes:
Activating a Repeater
Using a Repeater
Repeater Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 158 of 1651

Debugging Tools for Windows

Activating a Repeater
To activate the repeater connection, you will usually first start the server, then start the repeater, then start the client.
It is also possible to start the repeater first and then the server. But unless you are using the clicon parameter to establish a reverse connection, the client must always be
started last.
Step One: Starting the Server
The server can be a debugging server, a process server, or a KD connection server. You start this as you normally would, except that the transport protocol settings will be
used to connect to the repeater, not the client. For details, see Activating a Debugging Server, Activating a Process Server, or Activating a KD Connection Server.
If you use a password when creating the server, this password will be required when the client attaches, but not when the repeater is created.
If you use the hidden parameter, the server will be hidden as usual. The repeater itself is always hidden.
Step Two: Starting the Repeater
The repeater that is included in Debugging Tools for Windows is called DbEngPrx (dbengprx.exe).
DbEngPrx understands the following transport protocols: named pipe (NPIPE), TCP, and COM port.
If your client and server are using secure sockets layer (SSL) protocol, you should use TCP protocol for the repeater. If your client and server are using secure pipe (SPIPE)
protocol, you should use NPIPE protocol for the repeater. The repeater will pass on whatever data it receives it does not interpret, encrypt, or decrypt any information. All
encryption and decryption will be done by the client and the server.
The syntax for the DbEnPrx command line is as follows:
dbengprx [-p] -c ClientTransport -s ServerTransport
The parameters in the previous commands have the following possible values:
-p
Causes DbEngPrx to continue existing even after all connections to it are dropped.
ClientTransport
Specifies the protocol settings to be used in connecting to the server. The protocol should match that used when the server was created. The protocol syntaxes are as
follows:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
The protocol parameters have the following meanings:
Server
This is the network name or IP address of the computer on which the server was created. The two initial backslashes (\\) are optional.
pipe=PipeName
If NPIPE or SPIPE protocol is used, PipeName is the name that was given to the pipe when the server was created.
port=Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the server was created.
clicon
Specifies that the server will try to connect to the repeater through a reverse connection. ClientTransport must use clicon if and only if the server is using clicon. In
most cases, the repeater is started before the server when a reverse connection is used.
port=COMPort
If COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable.
baud=BaudRate
If COM protocol is used, BaudRate should match the baud rate chosen when the server was created.
channel=COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the server was created.
password=Password
If a password was used when the server was created, Password must be supplied in order to create the debugging client. It must match the original password.
Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005."
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In
Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
ServerTransport
Specifies the protocol settings that will be used when the client connects to the repeater. The possible protocol syntaxes are:
npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable]
tcp:port=Socket[,hidden][,password=Password][,IcfEnable]
tcp:port=Socket,clicon=Client[,password=Password]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password]
The protocol parameters have the following meanings:
pipe=PipeName
When NPIPE or SPIPE protocol is used, PipeName is a string that will serve as the name of the pipe. Each pipe name should identify a unique repeater. If you
attempt to reuse a pipe name, you will receive an error message. PipeName must not contain spaces or quotation marks. PipeName can include a numerical printf-

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 159 of 1651

style format code, such as %x or %d. The repeater will replace this with the process ID of DbEngPrx. A second such code will be replaced with the thread ID of
DbEngPrx.
port=Socket
When TCP or SSL protocol is used, Socket is the socket port number.
It is also possible to specify a range of ports separated by a colon. DbEngPrx will check each port in this range to see if it is free. If it finds a free port and no error
occurs, the repeater will be created. The client will have to specify the actual port being used to connect to the repeater. To determine the actual port, search for the
repeater; when this repeater is displayed, the port will be followed by two numbers separated by a colon. The first number will be the actual port used; the second
can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the search results will show "port=53:60". (If you are using the
clicon parameter to establish a reverse connection, the client can specify a range of ports in this manner, while the repeater must specify the actual port used.)
clicon=Client
When TCP or SSL protocol is used and the clicon parameter is specified, a reverse connection will be opened. This means that the repeater will try to connect to the
client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. Client specifies
the network name or IP address of the computer on which the client exists or will be created. The two initial backslashes (\\) are optional.
Since the repeater is looking for one specific client, you cannot connect multiple clients to the repeater if you use this method. If the connection is refused or is
broken you will have to restart the repeater.
When clicon is used, it is best to start the client before the repeater is created, although the usual order (repeater before client) is also permitted.
port=COMPort
When COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional for example, both "com2" and "2" are acceptable. You
cannot use the same COM port in the ClientTransport and the ServerTransport.
baud=BaudRate
When COM protocol is used, BaudRate specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted. If you
are using COM protocol in both the ClientTransport and the ServerTransport you may specify different baud rates, but naturally the slower rate will be the limit on
how fast the client and server can communicate with each other.
channel=COMChannel
If COM protocol is used, COMChannel specifies the COM channel to be used in communicating with the client. This can be any value between 0 and 254, inclusive.
You can use a single COM port for multiple connections using different channel numbers. (This is different from the use of a COM ports for a debug cable in that
situation you cannot use channels within a COM port.)
hidden
Prevents the server from appearing when another debugger displays all active servers.
password=Password
Requires a client to supply the specified password in order to connect to the debugging session. Password can be any alphanumeric string.
IcfEnable
(Windows XP and later versions only) Causes the debugger to enable the necessary port connections for TCP or named pipe communication when the Internet
Connection Firewall is active. By default, the Internet Connection Firewall disables the ports used by these protocols. When IcfEnable is used with a TCP
connection, the debugger causes Windows to open the port specified by the Socket parameter. When IcfEnable is used with a named pipe connection, the debugger
causes Windows to open the ports used for named pipes (ports 139 and 445). The debugger does not close these ports after the connection terminates.
Step Three: Starting the Client
The client should be a debugging client or a smart client whichever corresponds to your server type. For details, see Activating a Debugging Client, Activating a Smart
Client, or Activating a Smart Client (Kernel Mode).
If the server rejects the connection (for example, if you supply an incorrect password), both the repeater and the client will be shut down. You will have to restart both of them
to reestablish contact with the server.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using a Repeater
A repeater connection obeys very simple rules:

Any communication that the server and client intend for each other passes through the repeater without alteration.
Any action that the server performs with respect to the transport connection affects the repeater (and only indirectly affects the client).
Any action that the client performs with respect to the transport connection affects the repeater (and only indirectly affects the server).

This means that any debugging commands, debugger output, control keys, and file access will take place exactly as if the client and server were directly connected. The
repeater will be invisible to all these commands.
Actions that terminate the connection itself will affect the repeater. For example, if you issue a qq (Quit) command from the client, the server will shut down and will send a
shutdown signal to the transport. This will cause the repeater to exit (unless it was started with the -p option). As another example, the .clients (List Debugging Clients)
command will list the client's computer name, but it will show the connection protocol used to connect the server with the repeater.
If the server is shut down, the repeater will automatically exit (unless it was started with the -p option). When the repeater shuts down, this will cause a debugging client to
exit as well, although a smart client will not. If for some reason you need to terminate the repeater directly, you can use Task Manager or the kill.exe tool.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 160 of 1651

Repeater Examples
Let us suppose you have three computers, \\BOXA, \\BOXB, and \\BOXC, and you wish to use them as the server, the repeater, and the client, respectively.
You can start a debugging server on \\BOXA, using process 122 as the target, in the following manner:
E:\Debugging Tools for Windows> cdb -server tcp:port=1025,password=wrought -p 122
Then you can start a repeater on \\BOXB as follows:
C:\Misc> dbengprx -c tcp:server=BOXA,port=1025 -s npipe:pipe=MyPipe
Finally, start a debugging client on \\BOXC in the following manner:
G:\Debugging Tools> windbg -remote npipe:server=BOXB,pipe=MyPipe,password=wrought
Here is another example. Your symbols are at the remote location, 127.0.0.30. So you decide to use a process server on the computer where the target is, 127.0.0.10. You put
a repeater at 127.0.0.20.
You also decide to use reverse connections. So you begin by starting the client on 127.0.0.30:
G:\Debugging Tools> windbg -premote tcp:clicon=127.0.0.20,port=1033 notepad.exe
Then start the repeater on 127.0.0.20:
C:\Misc> dbengprx -c tcp:clicon=127.0.0.10,port=1025 -s tcp:port=1033,clicon=127.0.0.10
And finally start the process server on 127.0.0.10:
E:\Debugging Tools for Windows> dbgsrv -t tcp:port=1025,clicon=127.0.0.20
For a more complicated example using repeaters, see Two Firewalls.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Advanced Remote Debugging Scenarios

This section includes:
Debugging Targets on Multiple Computers
Symbols in the Middle
Two Firewalls
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Targets on Multiple Computers

The debugger can debug multiple dump files or live user-mode applications at the same time. See Debugging Multiple Targets for details.
You can debug multiple live targets even if the processes are on different systems. Simply start a process server on each system, and then use the -premote parameter
with .attach (Attach to Process) or .create (Create Process) to identify the proper process server.
The current or active system is the system currently being debugged. If you use the .attach or .create command again without specifying the -premote parameter, the
debugger will attach to, or create, a process on the current system.
For details on how to control such a debugging session, see Debugging Multiple Targets.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 161 of 1651

Symbols in the Middle

In this scenario, you have three computers. The first has the target application, the second has the symbols, and the third has the technician.
Since the smart client behaves like a regular debugger in every way, it can be used as a debugging server at the same time. This allows you to link three machines together
with the smart client in the middle.
First, you start a process server on the computer \\BOXA:
dbgsrv -t npipe:pipe=FarPipe
The middle machine, named \\BOXB, starts the debugger with both the -premote and -server parameters. Suppose the PID of the target application is 400 and the symbol
path is G:\MySymbols:
cdb -server npipe:pipe=NearPipe -premote npipe:server=BOXA,pipe=FarPipe -v -y g:\mysymbols -p 400
Then a debugging client on a third machine can be started as follows:
windbg -remote npipe:server=BOXB,pipe=NearPipe
The third machine is then used to control the debugging, while the second machine is where the actual processing is done and the symbols are accessed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Two Firewalls
In this scenario, you need to perform kernel debugging on a computer in Building A. Your technician is located in Building C, and he or she has access to symbols there.
However, both buildings have firewalls that will not allow incoming connections.
You need to set up a repeater at a neutral site say, Building B. Then you can connect A outward to B, and connect C outward to B.
There will be four computers involved in this scenario:

The target computer, located in Building A.

The local host computer, located in Building A. This computer will run a KD connection server. It will be connected to the target computer by a debug cable or 1394
cable, and will connect outward to the repeater. Let this computer's IP address be 127.0.10.10.
The computer in Building B. This will run the repeater. Let its IP address be 127.0.20.20.
The computer in Building C where the technician is located. This computer will run WinDbg as a smart client. Let its IP address be 127.0.30.30.

First, make sure the target computer is configured for debugging and is attached to the local host computer. In this example, a 1394 cable is used.
Second, start the repeater on 127.0.20.20:
dbengprx -p -s tcp:port=9001 -c tcp:port=9000,clicon=127.0.10.10
Third, start the KD connection server on 127.0.10.10 in Building A as follows:
kdsrv -t tcp:port=9000,clicon=127.0.20.20,password=longjump
Finally, start the smart client on 127.0.30.30 in Building C. (This can actually be done before or after starting the server in Building A.)
windbg -k kdsrv:server=@{tcp:server=127.0.20.20,port=9001,password=longjump},trans=@{1394:channel=9} -y SymbolPath
Five-Computer Scenario
This scenario can be made even more complicated if you suppose that the symbols are on one computer in Building C, but the technician is at a different computer.
Suppose that 127.0.30.30 has the symbols, as before, and that its local name is \\BOXC. The smart client can be started with the same command as above but with an
additional -server parameter. Since no one will be using this machine, it will take less processing time if you use KD instead of WinDbg:
kd -server npipe:pipe=randomname -k kdsrv:server=@{tcp:server=127.0.20.20,port=9001,password=longjump},trans=@{1394:channel=9}
Then the technician, elsewhere in the building, can start a debugging client as follows:
windbg -remote npipe:server=\\BOXC,pipe=randomname
Notice that the password must be supplied by the first non-repeater in the chain (the smart client on \\BOXC), not by the final debugger in the chain.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 162 of 1651

Debugging Tools for Windows

Symbols
This section includes:
Introduction to Symbols
Accessing Symbols for Debugging
How the Debugger Recognizes Symbols
Symbol Problems While Debugging
These topics explain what symbols are, how to access them during a debugging session, how to control the debugger's symbol options and symbol matching, and how to
respond to various symbol-related problems during debugging.
If you simply want to configure your debugger to access symbols for your own programs and for Windows, you may find it quicker to read the less-detailed introductory
topics Symbol Path and Using a Symbol Server.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Introduction to Symbols
This section includes:
Symbols and Symbol Files
Public and Private Symbols
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbols and Symbol Files

When applications, libraries, drivers, or operating systems are linked, the linker that creates the .exe and .dll files also creates a number of additional files known as symbol
files.
Symbol files hold a variety of data which are not actually needed when running the binaries, but which could be very useful in the debugging process.
Typically, symbol files might contain:

Global variables
Local variables
Function names and the addresses of their entry points
Frame pointer omission (FPO) records
Source-line numbers

Each of these items is called, individually, a symbol. For example, a single symbol file Myprogram.pdb might contain several hundred symbols, including global variables and
function names and hundreds of local variables. Often, software companies release two versions of each symbol file: a full symbol file containing both public symbols and
private symbols, and a reduced (stripped) file containing only public symbols. For details, see Public and Private Symbols.
When debugging, you must make sure that the debugger can access the symbol files that are associated with the target you are debugging. Both live debugging and debugging
crash dump files require symbols. You must obtain the proper symbols for the code that you wish to debug, and load these symbols into the debugger.
Windows Symbols
Microsoft Windows 2000 keeps its symbols in files with the extensions .pdb and .dbg. Windows XP and later versions of Windows use .pdb files exclusively. Windows
drivers can follow either model.
The compiler and the linker control the symbol format. The Visual C++ 5.0 Linker creates both .pdb and .dbg symbol files the .dbg files it creates are essentially pointers
to the .pdb files. The Visual C++ 6.0 Linker, as well as the linkers of later versions of Visual Studio, places all symbols into .pdb files.
The Windows operating system is built in two versions. The free build (or retail build) has relatively small binaries, and the checked build (or debug build) has larger binaries,
with more debugging symbols in the code itself. Each of these builds has its own symbol files. When debugging a target on Windows, you must use the symbol files that
match the build of Windows on the target.
The following table lists several of the directories which exist in a standard Windows symbol tree:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 163 of 1651

Directory
Contains Symbol Files for
ACM
Microsoft Audio Compression Manager files
COM
Executable files (.com)
CPL
Control Panel programs
DLL
Dynamic-link library files (.dll)
DRV
Driver files (.drv)
EXE
Executable files (.exe)
SCR
Screen-saver files
SYS
Driver files (.sys)
Data Types
All types created by typedefs within your own code will be present, as long as they have actually been used in your program. However, types that are defined in your headers
but never actually used will not be stored in the .pdb symbol files and will not be accessible to the debugger. If you wish to make such a type available to the debugger, you
should use it as the input of a typedef statement. For example, if the following appears in your code, the structure MY_DATA will be stored in the .pdb symbol file and can
be displayed by the debugger:
typedef struct _MY_DATA {
. . .
} MY_DATA;
typedef MY_DATA *PMY_DATA;
On the other hand, the following code would not suffice, because both MY_DATA and PMY_DATA are defined by the initial typedef, and therefore MY_DATA has not
itself been used as the input of any typedef statement:
typedef struct _MY_DATA {
. . .
} MY_DATA, *PMY_DATA;
In any event, type information is included only in a full symbol file, not a symbol file that has been stripped of all private symbol information. For more information, see
Public and Private Symbols.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Public and Private Symbols

When a full-sized .pdb or .dbg symbol file is built by a linker, it contains two distinct collections of information: the private symbol data and a public symbol table. These
collections differ in the list of items they contain and the information they store about each item.
The private symbol data includes the following items:

Functions
Global variables
Local variables
Information about user-defined structures, classes, and data types
The name of the source file and the line number in that file corresponding to each binary instruction

The public symbol table contains fewer items:

Functions (except for functions declared static)

Global variables specified as extern (and any other global variables visible across multiple object files)

As a general rule, the public symbol table contains exactly those items that are accessible from one source file to another. Items visible in only one object filesuch as static
functions, variables that are global only within a single source file, and local variablesare not included in the public symbol table.
These two collections of data also differ in what information they include for each item. The following information is typically included for each item contained in the private
symbol data:

Name of the item

Address of the item in virtual memory
Frame pointer omission (FPO) records for each function
Data type of each variable, structure, and function
Types and names of the parameters for each function
Scope of each local variable
Symbols associated with each line in each source file

On the other hand, the public symbol table stores only the following information about each item included in it:

The name of the item.

The address of the item in the virtual memory space of its module. For a function, this is the address of its entry point.
Frame pointer omission (FPO) records for each function.

In other words, the public symbol data can be thought of as a subset of the private symbol data in two ways: it contains a shorter list of items, and it also contains less
information about each item. For example, the public symbol data does not include local variables at all. Each local variable is included only in the private symbol data, with

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 164 of 1651

its address, data type, and scope. Functions, on the other hand, are included both in the private symbol data and public symbol table, but while the private symbol data
includes the function name, address, FPO records, input parameter names and types, and output type, the public symbol table includes just the function name, address, and
FPO record.
There is one other difference between the private symbol data and the public symbol table. Many of the items in the public symbol table have names that are decorated with a
prefix, a suffix, or both. These decorations are added by the C compiler, the C++ compiler, and the MASM assembler. Typical prefixes include a series of underscores or the
string __imp_ (designating an imported function). Typical suffixes include one or more at signs ( @ ) followed by addresses or other identifying strings. These decorations
are used by the linker to disambiguate the symbol, since it is possible that function names or global variable names could be repeated across different modules. These
decorations are an exception to the general rule that the public symbol table is a subset of the private symbol data.
Full Symbol Files and Stripped Symbol Files
A full symbol file contains both the private symbol data and the public symbol table. This kind of file is sometimes referred to as a private symbol file, but this name is
misleading, for such a file contains both private and public symbols.
A stripped symbol file is a smaller file that contains only the public symbol table or, in some cases, only a subset of the public symbol table. This file is sometimes referred
to as a public symbol file.
Creating Full and Stripped Symbol Files
If you build your binaries with Visual Studio, you can create either full or stripped symbol files. When building a "debug build" of a binary, Visual Studio typically will create
full symbol files. When building a "retail build", Visual Studio typically creates no symbol files, but a full or stripped symbol file will be created if the proper options are set.
If you build your binaries with the Build utility, the utility will create full symbol files.
Using the BinPlace tool, you can create a stripped symbol file from a full symbol file. When the most common BinPlace options are used (-a -x -s -n), the stripped symbol
files are placed in the directory that is listed after the -s switch, and the full symbol files are placed in the directory that is listed after the -n switch. When BinPlace strips a
symbol file, the stripped and full versions of the file are given identical signatures and other identifying information. This allows you to use either version for debugging.
Using the PDBCopy tool, you can create a stripped symbol file from a full symbol file by removing the private symbol data. PDBCopy can also remove a specified subset of
the public symbol table. For details, see PDBCopy.
Using the SymChk tool, you can determine whether a symbol file contains private symbols. For details, see SymChk.
Viewing Public and Private Symbols in the Debugger
You can use WinDbg, KD, or CDB to view symbols. When one of these debuggers has access to a full symbol file, it has both the information listed in the private symbol
data and the information listed in the public symbol table. The private symbol data is more detailed, while the public symbol data contains symbol decorations.
When accessing private symbols, private symbol data is always used because these symbols are not included in the public symbol table. These symbols are never decorated.
When accessing public symbols, the debugger's behavior depends on certain symbol options:

When the SYMOPT_UNDNAME option is on, decorations are not included when the name of a public symbol is displayed. Moreover, when searching for symbols,
decorations are ignored. When this option is off, decorations are displayed when displaying public symbols, and decorations are used in searches. Private symbols are
never decorated in any circumstances. This option is on by default in all debuggers.
When the SYMOPT_PUBLICS_ONLY option is on, private symbol data is ignored, and only the public symbol table is used. This option is off by default in all
debuggers.
When the SYMOPT_NO_PUBLICS option is on, the public symbol table is ignored, and searches and symbol information use the private symbol data alone. This
option is off by default in all debuggers.
When the SYMOPT_AUTO_PUBLICS option is on (and both SYMOPT_PUBLICS_ONLY and SYMOPT_NO_PUBLICS are off), the first symbol search is
performed in the private symbol data. If the desired symbol is found there, the search terminates. If not, the public symbol table is searched. Since the public symbol
table contains a subset of the symbols in the private data, normally this results in the public symbol table being ignored.
When the SYMOPT_PUBLICS_ONLY, SYMOPT_NO_PUBLICS, and SYMOPT_AUTO_PUBLICS options are all off, both private symbol data and the public
symbol table are searched each time a symbol is needed. However, when matches are found in both places, the match in the private symbol data is used. Therefore, the
behavior in this instance is the same as when SYMOPT_AUTO_PUBLICS is on, except that using SYMOPT_AUTO_PUBLICS may cause symbol searches to happen
slightly faster.

Here is an example in which the command x (Examine Symbols) is used three times. The first time, the default symbol options are used, and so the information is taken from
the private symbol data. Note that this includes information about the address, size, and data type of the array typingString. Next, the command .symopt+ 4000 is used,
causing the debugger to ignore the private symbol data. When the x command is then run again, the public symbol table is used; this time there is no size and data type
information for typingString. Finally, the command .symopt- 2 is used, which causes the debugger to include decorations. When the x command is run this final time, the
decorated version of the function name, _typingString, is shown.
0:000> x /t /d *!*typingstring*
00434420 char [128] TimeTest!typingString = char [128] ""
0:000> .symopt+ 4000
0:000> x /t /d *!*typingstring*
00434420 <NoType> TimeTest!typingString = <no type information>
0:000> .symopt- 2
0:000> x /t /d *!*typingstring*
00434420 <NoType> TimeTest!_typingString = <no type information>
Viewing Public and Private Symbols with the DBH Tool
Another way to view symbols is by using the the DBH tool. DBH uses the same symbol options as the debugger. Like the debugger, DBH leaves
SYMOPT_PUBLICS_ONLY and SYMOPT_NO_PUBLICS off by default, and turns SYMOPT_UNDNAME and SYMOPT_AUTO_PUBLICS on by default. These
defaults can be overridden by a command-line option or by a DBH command.
Here is an example in which the DBH command addr 414fe0 is used three times. The first time, the default symbol options are used, and so the information is taken from the

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 165 of 1651

private symbol data. Note that this includes information about the address, size, and data type of the function fgets. Next, the command symopt +4000 is used, which causes
DBH to ignore the private symbol data. When the addr 414fe0 is then run again, the public symbol table is used; this time there is no size and data type information for the
function fgets. Finally, the command symopt -2 is used, which causes DBH to include decorations. When the addr 414fe0 is run this final time, the decorated version of the
function name, _fgets, is shown.
pid:4308 mod:TimeTest[400000]: addr 414fe0
fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

fgets
414fe0
113
0
7e
400000
0
0
SymTagNull (0)
SymTagFunction (5)
7d

pid:4308 mod:TimeTest[400000]: symopt +4000

Symbol Options: 0x10c13
Symbol Options: 0x14c13
pid:4308 mod:TimeTest[400000]: addr 414fe0
fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

fgets
414fe0
0
0
0
400000
0
0
SymTagNull (0)
SymTagPublicSymbol (a)
7f

pid:4308 mod:TimeTest[400000]: symopt -2

Symbol Options: 0x14c13
Symbol Options: 0x14c11
pid:4308 mod:TimeTest[400000]: addr 414fe0
_fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

_fgets
414fe0
0
0
0
400000
0
0
SymTagNull (0)
SymTagPublicSymbol (a)
7f

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Accessing Symbols for Debugging

Setting up symbols correctly for debugging can be a challenging task, particularly for kernel debugging. It often requires that you know the names and releases of all products
on your computer. The debugger must be able to locate each of the symbol files corresponding to the product releases and service packs.
This can result in an extremely long symbol path consisting of a long list of directories.
To simplify these difficulties in coordinating symbol files, the symbol files can be gathered into a symbol store, which is then accessed by a symbol server.
A symbol store is a collection of symbol files, an index, and a tool that can be used by an administrator to add and delete files. The files are indexed according to unique
parameters such as the time stamp and image size. A symbol store can also hold executable image files which can be extracted using a symbol server. Debugging Tools for
Windows contains a symbol store creation tool called SymStore.
A symbol server enables the debuggers to automatically retrieve the correct symbol files from a symbol store without the user needing to know product names, releases, or

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 166 of 1651

build numbers. Debugging Tools for Windows contains a symbol server called SymSrv. The symbol server is activated by including a certain text string in the symbol path.
Each time the debugger needs to load symbols for a newly loaded module, it calls the symbol server to locate the appropriate symbol files.
If you wish to use a different method for your symbol search than that provided by SymSrv, you can create your own symbol server DLL. For details on implementing such a
symbol server, see Other Symbol Servers.
If you are performing user-mode debugging, you will need symbols for the target application. If you are performing kernel-mode debugging, you will need symbols for the
driver you are debugging, as well as the Windows public symbols. Microsoft has created a symbol store with public symbols for Microsoft products; this symbol store is
available on the internet. These symbols can be loaded using the .symfix (Set Symbol Store Path) command, as long as you have access to the internet while your debugger
is running. For more information or to determine how to manually install these symbols, see Installing Windows Symbol Files.
This section includes:
Installing Windows Symbol Files
Symbol Stores and Symbol Servers
Deferred Symbol Loading
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing Windows Symbol Files

Before you debug the Windows kernel or a driver or application running on Windows, you need access to the proper symbol files.
If you have access to the internet while your debugger is running, you may wish to use Microsoft's public symbol store. You can connect to this with one simple use of
the .symfix (Set Symbol Store Path) command. For full details, see Microsoft Public Symbols.
If you plan to install symbols manually, it is crucial that you remember this basic rule: the symbol files on the host computer are required to match the version of Windows
installed on the target computer. If you are planning to do a kernel mode debug of a Windows XP target from a Windows 2000 host, you need to install the Windows XP
symbol files on the Windows 2000 system. If you plan to perform user-mode debugging on the same computer as the target application, then install the symbol files that
match the version of Windows running on that system. If you are analyzing a memory dump file, then the version of symbol files needed on the debug computer are those that
match the version of the operating system that produced the dump file, not necessarily those matching the version of the operating system on the machine running the debug
session.
Note If you are going to use your host computer to debug several different target computers, you may need symbols for more than one build of Windows. In this case, be sure
to install each symbol collection in a distinct directory path.
If you are debugging from a Windows computer attached to a network, it may be useful to install symbols for a variety of different builds on a network server. Microsoft
debuggers will accept a network path (\\server\share\dir) as a valid symbol directory path. This avoids the need for each debugging computer on the network to install the
symbol files separately.
Symbol files stored on a crashed target computer are not useable by the debugger on the host computer.
To install symbol files for Windows XP or later
1. Make sure you have at least 1000 MB of available space on the disk drive of the host computer.
2. Open the Windows Symbols Web site in your internet browser.
3. Follow the links to download the appropriate symbol package.
To install symbol files for Windows 2000 from the Web
1. Make sure you have at least 1000 MB of available space on the disk drive of the host computer.
2. Open the Windows Symbols Web site in your internet browser.
3. Follow the links to download Windows 2000 symbols.
To install symbol files for Windows 2000 from the Support CD
1.
2.
3.
4.

Make sure you have at least 500 MB of available space on the disk drive of the host computer.
Insert the Windows 2000 Customer Support Diagnostics CD.
Click on Install Symbols.
Select either Install Retail Symbols (free build) or Install Debug Symbols (checked build). The symbols must match the version of the operating system being
debugged.
5. Enter the path where the symbols are to be stored, or accept the default path. The default path is %windir%\symbols.

Sequence of Symbol File Installation

If you intend to keep your symbols in a single directory tree, the installation sequence of symbol files should mirror the installation sequence of operating system files:
To install the symbol files in correct sequence
1. Install the operating system symbol files.
2. Install the symbol files for the currently installed Service Pack (if any).
3. Install the symbol files for any Hot Fixes that were installed after the current Service Pack was installed (if any).
However, a superior setup would be to install the symbols from each Service Pack and Hot Fix in a separate directory tree, and put all these directories in your symbol search
path. The debugger will then find the proper symbols. (Since the symbol files have date and time stamps, the debugger will be able to tell which are the most recent.) See

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 167 of 1651

Symbol Path for details.

Installing User-Mode Symbols
If you are going to debug a user-mode application, you need to install the symbols for this application as well.
You can debug an application if you have its symbols but not Windows symbols. However, your results will be much more limited. You will still be able to step through the
application code, but any debugger activity which requires analysis of the kernel (such as getting a stack trace) is likely to fail.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Stores and Symbol Servers

A symbol store is a collection of symbol files, an index, and a tool for adding and deleting files. A symbol store may also contain executable image files. The debugger
accesses the files in a symbol store by using a symbol server. Debugging Tools for Windows includes both a symbol store creation tool, SymStore, and a symbol server,
SymSrv. It also includes a tool, SymProxy, for setting up an HTTP symbol store on a network to serve as a proxy for all symbol stores that the debugger may need to access.
It is also possible to build your own symbol store creation tool and symbol server, but this is not recommended.
This section includes:
SymStore
SymSrv
HTTP Symbol Stores
SymProxy
Other Symbol Stores
Other Symbol Servers
If you are not setting up your own symbol store, but just intend to use the public Microsoft symbol store, see Microsoft Public Symbols.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymStore
SymStore (symstore.exe) is a tool for creating symbol stores. It is included in the Debugging Tools for Windows package.
SymStore stores symbols in a format that enables the debugger to look up the symbols based on the time stamp and size of the image (for a .dbg or executable file), or
signature and age (for a .pdb file). The advantage of the symbol store over the traditional symbol storage format is that all symbols can be stored or referenced on the same
server and retrieved by the debugger without any prior knowledge of which product contains the corresponding symbol.
Note that multiple versions of .pdb symbol files (for example, public and private versions) cannot be stored on the same server, because they each contain the same signature
and age.
This section includes:
SymStore Transactions
File System References and Symbol Files
SymStore Compressed Files
Symbol Storage Format
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymStore Transactions

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 168 of 1651

Every call to SymStore is recorded as a transaction. There are two types of transactions: add and delete.
When the symbol store is created, a directory, called "000admin", is created under the root of the server. The 000admin directory contains one file for each transaction, as well
as the log files server.txt and history.txt. The server.txt file contains a list of all transactions that are currently on the server. The history.txt file contains a chronological history
of all transactions.
Each time SymStore stores or removes symbol files, a new transaction number is created. Then, a file, whose name is this transaction number, is created in 000admin. This
file contains a list of all the files or pointers that have been added to the symbol store during this transaction. If a transaction is deleted, SymStore will read through its
transaction file to determine which files and pointers it should delete.
The add and del options specify whether an add or delete transaction is to be performed. Including the /p option with an add operation specifies that a pointer is to be added;
omitting the /p option specifies that the actual symbol file is to be added.
It is also possible to create the symbol store in two separate stages. In the first stage, you use SymStore with the /x option to create an index file. In the second stage, you use
SymStore with the /y option to create the actual store of files or pointers from the information in the index file.
This can be a useful technique for a variety of reasons. For instance, this allows the symbol store to be easily recreated if the store is somehow lost, as long as the index file
still exists. Or perhaps the computer containing the symbol files has a slow network connection to the computer on which the symbol store will be created. In this case, you
can create the index file on the same machine as the symbol files, transfer the index file to the second machine, and then create the store on the second machine.
For a full listing of all SymStore parameters, see SymStore Command-Line Options.
Note SymStore does not support simultaneous transactions from multiple users. It is recommended that one user be designated "administrator" of the symbol store and be
responsible for all add and del transactions.
Transaction Examples
Here are two examples of SymStore adding symbol pointers for build 2195 of Windows 2000 to \\MyDir\symsrv:

symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 free"
symstore add /r /p /f \\BuildServer\BuildShare\2195free\symbols\*.* /s \\MyDir\symsrv /t "Windows 2000" /v "Build 2195 x86 checke
In the following example, SymStore adds the actual symbol files for an application project in \\largeapp\appserver\bins to \\MyDir\symsrv:
symstore add /r /f \\largeapp\appserver\bins\*.* /s \\MyDir\symsrv /t "Large Application" /v "Build 432" /c "Sample add"
Here is an example of how an index file is used. First, SymStore creates an index file based on the collection of symbol files in \\largeapp\appserver\bins\. In this case, the
index file is placed on a third computer, \\hubserver\hubshare. You use the /g option to specify that the file prefix "\\largeapp\appserver" might change in the future:
symstore add /r /p /g \\largeapp\appserver /f \\largeapp\appserver\bins\*.* /x \\hubserver\hubshare\myindex.txt
Now suppose you move all the symbol files off of the machine \\largeapp\appserver and put them on \\myarchive\appserver. You can then create the symbol store itself from
the index file \\hubserver\hubshare\myindex.txt as follows:

symstore add /y \\hubserver\hubshare\myindex.txt /g \\myarchive\appserver /s \\MyDir\symsrv /p /t "Large Application" /v "Build 4

Finally, here is an example of SymStore deleting a file added by a previous transaction. See The server.txt and history.txt Files section below for an explanation of how to
determine the transaction ID (in this case, 0000000096).
symstore del /i 0000000096 /s \\MyDir\symsrv
The server.txt and history.txt Files
When a transaction is added, several items of information are added to server.txt and history.txt for future lookup capability. The following is an example of a line in server.txt
and history.txt for an add transaction:
0000000096,add,ptr,10/09/99,00:08:32,Windows Vista SP 1,x86 fre 1.156c-RTM-2,Added from \\mybuilds\symbols,
This is a comma-separated line. The fields are explained as follows:
Field
Description
0000000096
Transaction ID number, as created by SymStore.
add
Type of transaction. This field can be either add or del.
ptr
Whether files or pointers were added. This field can be either file or ptr.
10/09/99
Date when transaction occurred.
00:08:32
Time when transaction started.
Windows Vista SP 1 Product.
x86 fre
Version (optional).
Added from
Comment (optional)
Unused
(Reserved for later use.)
Here are some sample lines from the transaction file 0000000096. Each line records the directory and the location of the file or pointer that was added to the directory.
canon800.dbg\35d9fd51b000,\\mybuilds\symbols\sp4\dll\canon800.dbg
canonlbp.dbg\35d9fd521c000,\\mybuilds\symbols\sp4\dll\canonlbp.dbg
certadm.dbg\352bf2f48000,\\mybuilds\symbols\sp4\dll\certadm.dbg
certcli.dbg\352bf2f1b000,\\mybuilds\symbols\sp4\dll\certcli.dbg
certcrpt.dbg\352bf04911000,\\mybuilds\symbols\sp4\dll\certcrpt.dbg
certenc.dbg\352bf2f7f000,\\mybuilds\symbols\sp4\dll\certenc.dbg

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 169 of 1651

If you use a del transaction to undo the original add transactions, these lines will be removed from server.txt, and the following line will be added to history.txt:
0000000105,del,0000000096
The fields for the delete transaction are described as follows.
Field
Description
0000000105 Transaction ID number, as created by SymStore.
del
Type of transaction. This field can be either add or del.
0000000096 Transaction that was deleted.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File System References and Symbol Files

Files on disk can have both long file names and automatically generated abbreviated MS-DOS compatible 8.3 short file names. After adding a symbol file to a symbol store, it
is possible that the symbols in that symbol file may not be accessible during debug if the symbol file contains any abbreviated MS-DOS 8.3 file names.
When the tools create a symbol file, the version of the file name that is recorded in the symbol file debug record depends on the tools and how they are run. If a symbol file
has an abbreviated MS-DOS 8.3 file name instead of the actual file name embedded in the record, symbol loading at debug time may experience problems because the
abbreviated file names vary from system to system. If this problem occurs, the contents of these symbol files may not be accessible during debug. Whenever possible, the user
should refrain from using abbreviated file path names when creating symbol files. Some ways to use abbreviated file names inadvertently are to use the abbreviated file path
name for a source file, an include directory, or an included library file.
For further information, see Matching Symbol Names.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymStore Compressed Files

SymStore can be used with compressed files in two different ways:
1. Use SymStore with the /p option to store pointers to the symbol files. After SymStore finishes, compress the files that the pointers refer to.
2. Use SymStore with the /x option to create an index file. After SymStore finishes, compress the files listed in the index file. Then, use SymStore with the /y option (and,
if you wish, the /p option) to store the files or pointers to the files in the symbol store. (SymStore will not need to uncompress the files to perform this operation.)
Your symbol server will be responsible for uncompressing the files at the proper time.
If you are using SymSrv as your symbol server, any compression should be done using the compress.exe tool that is distributed with the Microsoft Windows SDK.
Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details, see SymSrv.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Storage Format

SymStore uses the file system itself as a database. It creates a large tree of directories, with directory names based on such things as the symbol file time stamps, signatures,
age, and other data.
For example, after several different acpi.dbgs have been added to the server, the directories could look like this:
Directory of \\mybuilds\symsrv\acpi.dbg
10/06/1999 05:46p
<DIR>
.
10/06/1999 05:46p
<DIR>
..
10/04/1999 01:54p
<DIR>
37cdb03962040
10/04/1999 01:49p
<DIR>
37cdb04027740
10/04/1999 12:56p
<DIR>
37e3eb1c62060
10/04/1999 12:51p
<DIR>
37e3ebcc27760
10/04/1999 12:45p
<DIR>
37ed151662060
10/04/1999 12:39p
<DIR>
37ed15dd27760
10/04/1999 11:33a
<DIR>
37f03ce962020

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

10/04/1999
10/06/1999
10/06/1999

11:21a
05:38p
05:46p

Page 170 of 1651

37f03cf7277c0
37fa7f00277e0
37fa7f01620a0

In this example, the lookup path for the acpi.dbg symbol file might look like this: \\mybuilds\symsrv\acpi.dbg\37cdb03962040.
Three files may exist inside the lookup directory:
1. acpi.dbg, if the file was stored
2. file.ptr with a path to the actual symbol file, if a pointer was stored
3. refs.ptr, which contains a list of all the current locations for acpi.dbg with this timestamp and image size that are currently added to the symbol store
Displaying the directory listing of \\mybuilds\symsrv\acpi.dbg\37cdb03962040 gives the following:
10/04/1999
10/04/1999

01:54p
01:54p

52 file.ptr
67 refs.ptr

The file file.ptr contains the text string "\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg". Since there is no file called acpi.dbg in this directory, the debugger will try
to find the file at \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg.
The contents of refs.ptr are used only by SymStore, not the debugger. This file contains a record of all transactions that have taken place in this directory. A sample line from
refs.ptr might be:
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg
This shows that a pointer to \\mybuilds\symbols\x86\2128.chk\symbols\sys\acpi.dbg was added with transaction "0000000026".
Some symbol files stay constant through various products or builds or a particular product. One example of this is the Windows 2000 file msvcrt.pdb. A directory listing of
\\mybuilds\symsrv\msvcrt.pdb shows that only two versions of msvcrt.pdb have been added to the symbols server:
Directory of \\mybuilds\symsrv\msvcrt.pdb
10/06/1999 05:37p
<DIR>
.
10/06/1999 05:37p
<DIR>
..
10/04/1999 11:19a
<DIR>
37a8f40e2
10/06/1999 05:37p
<DIR>
37f2c2272
However, a directory listing of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2 shows that refs.ptr has several pointers in it.
Directory of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2
10/05/1999 02:50p
54
file.ptr
10/05/1999 02:50p
2,039
refs.ptr
The contents of \\mybuilds\symsrv\msvcrt.pdb\37a8f40e2\refs.ptr are the following:
0000000001,ptr,\\mybuilds\symbols\x86\2137\symbols\dll\msvcrt.pdb
0000000002,ptr,\\mybuilds\symbols\x86\2137.chk\symbols\dll\msvcrt.pdb
0000000003,ptr,\\mybuilds\symbols\x86\2138\symbols\dll\msvcrt.pdb
0000000004,ptr,\\mybuilds\symbols\x86\2138.chk\symbols\dll\msvcrt.pdb
0000000005,ptr,\\mybuilds\symbols\x86\2139\symbols\dll\msvcrt.pdb
0000000006,ptr,\\mybuilds\symbols\x86\2139.chk\symbols\dll\msvcrt.pdb
0000000007,ptr,\\mybuilds\symbols\x86\2140\symbols\dll\msvcrt.pdb
0000000008,ptr,\\mybuilds\symbols\x86\2140.chk\symbols\dll\msvcrt.pdb
0000000009,ptr,\\mybuilds\symbols\x86\2136\symbols\dll\msvcrt.pdb
0000000010,ptr,\\mybuilds\symbols\x86\2136.chk\symbols\dll\msvcrt.pdb
0000000011,ptr,\\mybuilds\symbols\x86\2135\symbols\dll\msvcrt.pdb
0000000012,ptr,\\mybuilds\symbols\x86\2135.chk\symbols\dll\msvcrt.pdb
0000000013,ptr,\\mybuilds\symbols\x86\2134\symbols\dll\msvcrt.pdb
0000000014,ptr,\\mybuilds\symbols\x86\2134.chk\symbols\dll\msvcrt.pdb
0000000015,ptr,\\mybuilds\symbols\x86\2133\symbols\dll\msvcrt.pdb
0000000016,ptr,\\mybuilds\symbols\x86\2133.chk\symbols\dll\msvcrt.pdb
0000000017,ptr,\\mybuilds\symbols\x86\2132\symbols\dll\msvcrt.pdb
0000000018,ptr,\\mybuilds\symbols\x86\2132.chk\symbols\dll\msvcrt.pdb
0000000019,ptr,\\mybuilds\symbols\x86\2131\symbols\dll\msvcrt.pdb
0000000020,ptr,\\mybuilds\symbols\x86\2131.chk\symbols\dll\msvcrt.pdb
0000000021,ptr,\\mybuilds\symbols\x86\2130\symbols\dll\msvcrt.pdb
0000000022,ptr,\\mybuilds\symbols\x86\2130.chk\symbols\dll\msvcrt.pdb
0000000023,ptr,\\mybuilds\symbols\x86\2129\symbols\dll\msvcrt.pdb
0000000024,ptr,\\mybuilds\symbols\x86\2129.chk\symbols\dll\msvcrt.pdb
0000000025,ptr,\\mybuilds\symbols\x86\2128\symbols\dll\msvcrt.pdb
0000000026,ptr,\\mybuilds\symbols\x86\2128.chk\symbols\dll\msvcrt.pdb
0000000027,ptr,\\mybuilds\symbols\x86\2141\symbols\dll\msvcrt.pdb
0000000028,ptr,\\mybuilds\symbols\x86\2141.chk\symbols\dll\msvcrt.pdb
0000000029,ptr,\\mybuilds\symbols\x86\2142\symbols\dll\msvcrt.pdb
0000000030,ptr,\\mybuilds\symbols\x86\2142.chk\symbols\dll\msvcrt.pdb
This shows that the same msvcrt.pdb was used for multiple builds of symbols for Windows 2000 stored on \\mybuilds\symsrv.
Here is an example of a directory that contains a mixture of file and pointer additions:
Directory of E:\symsrv\dbghelp.dbg\38039ff439000
10/12/1999 01:54p
141,232
dbghelp.dbg
10/13/1999 04:57p
49
file.ptr

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

10/13/1999

04:57p

Page 171 of 1651

306

refs.ptr

In this case, refs.ptr has the following contents:

0000000043,file,e:\binaries\symbols\retail\dll\dbghelp.dbg
0000000044,file,f:\binaries\symbols\retail\dll\dbghelp.dbg
0000000045,file,g:\binaries\symbols\retail\dll\dbghelp.dbg
0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg
Thus, transactions 43, 44, and 45 added the same file to the server, and transactions 46 and 47 added pointers. If transactions 43, 44, and 45 are deleted, then the file
dbghelp.dbg will be deleted from the directory. The directory will then have the following contents:
Directory of e:\symsrv\dbghelp.dbg\38039ff439000
10/13/1999 05:01p
49 file.ptr
10/13/1999 05:01p
130 refs.ptr
Now file.ptr contains "\\foo2\bin\symbols\retail\dll\dbghelp.dbg", and refs.ptr contains
0000000046,ptr,\\MyDir\bin\symbols\retail\dll\dbghelp.dbg
0000000047,ptr,\\foo2\bin\symbols\retail\dll\dbghelp.dbg
Whenever the final entry in refs.ptr is a pointer, the file file.ptr will exist and contain the path to the associated file. Whenever the final entry in refs.ptr is a file, no file.ptr will
exist in this directory. Therefore, any delete operation that removes the final entry in refs.ptr may result in file.ptr being created, deleted, or changed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymSrv
SymSrv (symsrv.dll) is a symbol server that is included in the Debugging Tools for Windows package.
Many users of Debugging Tools for Windows use the public symbol store on the Microsoft Web site to access symbols for Microsoft products. If this is your goal, you only
need to read the first topic listed below.
This section includes:
Microsoft Public Symbols
Advanced SymSrv Use
Firewalls and Proxy Servers
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Microsoft Public Symbols

Microsoft has a Web site that makes Windows symbols publicly available. You can refer directly to this site in your symbol path in the following manner:
set _NT_SYMBOL_PATH=srv*DownstreamStore*http://msdl.microsoft.com/download/symbols
DownstreamStore must specify a directory on your local computer or network that will be used to cache symbols. This downstream store holds symbols that the debugger has
accessed; the vast majority of symbols that have never been accessed remain on the symbol store at Microsoft. This keeps your downstream store relatively small and allows
the symbol server to work quickly, only downloading each file once.
To avoid typing this long symbol path, use the .symfix (Set Symbol Store Path) command. The following command appends the public symbol store to your existing symbol
path:
.symfix+ DownstreamStore
Note To successfully access Microsoft's public symbol store, you will need a fast internet connection. If your internet connection is only 56 Kps or slower, you should install
Windows symbols directly onto your hard drive. For details, see Installing Windows Symbol Files.
For more information about the public symbol store, see the

Windows Symbols Web site.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 172 of 1651

December 09, 2009

Debugging Tools for Windows

Advanced SymSrv Use

SymSrv can deliver symbol files from a centralized symbol store. This store can contain any number of symbol files, corresponding to any number of programs or operating
systems. The store can also contain binary files (this is useful when debugging minidumps).
The store can contain the actual symbol and binary files, or it can simply contain pointers to symbol files. If the store contains pointers, SymSrv will retrieve the actual files
directly from their sources.
SymSrv can also be used to separate a large symbol store into a smaller subset that is appropriate for a specialized debugging task.
Finally, SymSrv can obtain symbol files from an HTTP or HTTPS source using the logon information provided by the operating system. SymSrv supports HTTPS sites
protected by smartcards, certificates, and regular logins and passwords. For more information, see HTTP Symbol Stores.
Setting the Symbol Path
To use this symbol server, symsrv.dll must be installed in the same directory as the debugger. The symbol path must be set in one of the following ways:
set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share
set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share
set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share
set _NT_SYMBOL_PATH = srv*\\Server\Share
The parts of this syntax are explained as follows:
symsrv
This keyword must always appear first. It indicates to the debugger that this item is a symbol server, not just a normal symbol directory.
ServerDLL
Specifies the name of the symbol server DLL. If you are using the SymSrv symbol server, this will always be symsrv.dll.
srv
This is shorthand for symsrv*symsrv.dll.
DownstreamStore
Specifies the downstream store. This is a local directory or network share that will be used to cache individual symbol files.
You can specify more than one downstream store, separated by asterisks. Multiple downstream stores are explained in Cascading Downstream Stores further down on
this page.
If you include two asterisks in a row where a downstream store would normally be specified, then the default downstream store is used. This store will be located in the
sym subdirectory of the home directory. The home directory defaults to the debugger installation directory; this can be changed by using the !homedir extension or by
setting the DBGHELP_HOMEDIR environment variable.
If DownstreamStore specifies a directory that does not exist, SymStore will attempt to create it.
If the DownstreamStore parameter is omitted and no extra asterisk is included in other words, if you use srv with exactly one asterisk or symsrv with exactly two
asterisks then no downstream store will be created. The debugger will load all symbol files directly from the server, without caching them locally.
Note If you are accessing symbols from an HTTP or HTTPS site, or if the symbol store uses compressed files, a downstream store is always used. If no downstream
store is specified, one will be created in the sym subdirectory of the home directory.
\\Server\Share
Specifies the server and share of the remote symbol store.
If a downstream store is used, the debugger will first look for a symbol file in this store. If the symbol file is not found, the debugger will locate the symbol file from the
specified Server and Share, and then cache a copy of this file in the downstream store. The file will be copied to a subdirectory in the tree under DownstreamStore which
corresponds to its location in the tree under \\Server\Share.
The symbol server does not have to be the only entry in the symbol path. If the symbol path consists of multiple entries, the debugger checks each entry for the needed symbol
files, in order (from left to right), regardless of whether a symbol server or an actual directory is named.
Here are some examples. To use SymSrv as the symbol server with a symbol store on \\mybuilds\mysymbols, set the following symbol path:
set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\mybuilds\mysymbols
To set the symbol path so that the debugger will copy symbol files from a symbol store on \\mybuilds\mysymbols to your local directory c:\localsymbols, use:
set _NT_SYMBOL_PATH=symsrv*symsrv.dll*c:\localsymbols*\\mybuilds\mysymbols
To set the symbol path so that the debugger will copy symbol files from the HTTP site www.company.com/manysymbols to a local network directory
\\localserver\myshare\mycache, use:
set _NT_SYMBOL_PATH=symsrv*symsrv.dll*\\localserver\myshare\mycache*http://www.company.com/manysymbols
This last example can also be shortened as such:
set _NT_SYMBOL_PATH=srv*\\localserver\myshare\mycache*http://www.company.com/manysymbols

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 173 of 1651

In addition, the symbol path can contain several directories or symbol servers, separated by semicolons. This allows you to locate symbols from multiple locations (or even
multiple symbol servers). If a binary has a mismatched symbol file, the debugger cannot locate it using the symbol server because it checks only for the exact parameters.
However, the debugger may find a mismatched symbol file with the correct name, using the traditional symbol path, and successfully load it. Even though the file is
technically not the correct symbol file, it might provide useful information.
Compressed Files
SymSrv is compatible with symbol stores that contain compressed files, as long as this compression has been done with the compress.exe tool that is distributed with the
Microsoft Windows SDK. Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details,
see SymStore.
If the files on the store are compressed, you must use a downstream store. SymSrv will uncompress all files before caching them on the downstream store.
Deleting the Cache
If you are using a DownstreamStore as a cache, you can delete this directory at any time to save disk space.
It is possible to have a vast symbol store that includes symbol files for many different programs or Windows versions. If you upgrade the version of Windows used on your
target computer, the cached symbol files will all match the earlier version. These cached files will not be of any further use, and therefore this might be a good time to delete
the cache.
Cascading Downstream Stores
You can specify any number of downstream stores, separated by asterisks. These stores are known as cascading symbol stores.
After the initial srv* or symsrv*ServerDLL*, each subsequent token represents a symbol location. The token furthest left is checked first. An empty token indicated by
two asterisks in a row, or by an asterisk at the end of the string represents the default downstream store.
Here is an example of a symbol path that uses two downstream stores to hold information from the main symbol store being accessed. These could be called the master store,
the mid-level store, and the local cache:
srv*c:\localcache*\\interim\store*http://msdl.microsoft.com/download/symbols
In this scenario, SymSrv will first look in c:\localcache for a symbol file. If it is found there, it will return a path to it. If it is not found there, it will look in \\interim\store. If
the symbol file is found there, SymSrv will copy it to c:\localcache and return the path. If it is not found there, SymSrv will look in the Microsoft public symbol store at
http://msdl.microsoft.com/download/symbols; if the file is found there, SymSrv will copy it to both \\interim\store and c:\localcache.
A similar behavior would be obtained by using the following path:
srv**\\interim\store*http://internetsite
In this case, the local cache is the default downstream store and the master store is an internet site. A mid-level store of \\interim\store has been specified for use in between
the other two.
When SymSrv processes a path that contains cascading stores, it will skip any store that it cannot read or write to. So if a share goes down, it will copy the file to the store
downstream from the missing store without any error. A nice side effect of this error is that the user can specify more than one master store that feeds a single stream of
downstream stores as long as the master stores are not writable.
When a compressed symbol file is retrieved from the master store, it will be stored in compressed form in any mid-level store. The file will be uncompressed in the bottommost store in the path.
cache*localsymbolcache
Another way to create a local cache of symbols is by using the cache*localsymbolcache string in your symbol path. This is not part of the symbol server element, but a
separate element in your symbol path. The debugger will use the specified directory localsymbolcache to store any symbols loaded from any element that appears in your
symbol path to the right of this string. This allows you to use a local cache for symbols downloaded from any location, not just those downloaded by a symbol server.
For example, the following symbol path will not cache symbols taken from \\someshare. It will use c:\mysymbols to cache symbols taken from \\anothershare, because the
element beginning with \\anothershare appears to the right of the cache*c:\mysymbols element. It will also use c:\mysymbols to cache symbols taken from the Microsoft
public symbol store, because of the usual syntax used by the symbol server (srv with two or more asterisks). Moreover, if you subsequently use the .sympath+ command to
add additional locations to this path, these new elements will also be cached, since they will be appended to the right side of the path.

_NT_SYMBOL_PATH=\\someshare\that\cachestar\ignores;srv*c:\mysymbols*http://msdl.microsoft.com/download/symbols;cache*c:\mysymbols
How SymSrv Locates Files
SymSrv creates a fully-qualified UNC path to the desired symbol file. This path begins with the path to the symbol store recorded in the _NT_SYMBOL_PATH environment
variable. The SymbolServer routine is then used to identify the name of the desired file; this name is appended to the path as a directory name. Another directory name,
consisting of the concatenation of the id, two, and three parameters passed to SymbolServer, is then appended. If any of these values is zero, they are omitted.
The resulting directory is searched for the symbol file, or a symbol store pointer file.
If this search is successful, SymbolServer passes the path to the caller and returns TRUE. If the file is not found, SymbolServer returns FALSE.
Using AgeStore to Reduce the Cache Size
The AgeStore tool can be used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. This can be useful if
your downstream store is too large. For details, see AgeStore.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 174 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Firewalls and Proxy Servers

If you are using SymSrv to access symbols, and your computer is on a network that uses a proxy server or the symbol store is outside your firewall, authentication may be
required for data transmission to take place.
When SymSrv receives authentication requests, the debugger can either display the authentication request or automatically refuse the request, depending on how it has been
configured.
SymSrv has integrated support for a proxy server. It can either use the default proxy server, SymProxy, or it can use another proxy server of your choice.
Authentication Requests
The debugger can be configured to allow authentication requests. When a firewall or proxy server requests authorization, a dialog box will appear. You will have to enter
some sort of information (usually a user name and password) before the debugger can download symbols. If you enter incorrect information, the dialog box will be
redisplayed. If you select the Cancel button, the dialog box will vanish and no symbol information will be transferred.
If the debugger is configured to refuse all authentication requests, no dialog box will appear, and no symbols will be transferred if authentication is required.
If you refuse an authentication request, or if the debugger automatically refuses an authentication request, SymSrv will make no further attempts to contact the symbol store. If
you wish to renew contact, you must either restart the debugging session or use !symsrv close.
Note If you are using KD or CDB, the authentication dialog box may appear behind an open window. If this occurs, you may have to move or minimize some windows in
order to find this dialog box.
In WinDbg, authentication requests are allowed by default. In KD and CDB, authentication requests are automatically refused by default.
To allow authentication requests, use either !sym prompts or .symopt-0x80000. To refuse all requests, use either !sym prompts off or .symopt+0x80000. To display the
current setting, use !sym.
You must use .reload (Reload Module) after making any changes to the authentication permission status.
Choosing a Proxy Server
To select a default proxy server for Windows, open Internet Options in Control Panel, select the Connections tab, and then select the LAN Settings button. You can then
enter the proxy server name and port number, or select Advanced to configure multiple proxy servers. For more details, see Internet Explorer's help file.
To select a specific proxy server for symsrv to use, set the _NT_SYMBOL_PROXY environment variable equal to the name or IP of the proxy server, followed by a colon
and then the port number. For example:
set _NT_SYMBOL_PROXY=myproxyserver:80
When a proxy server is chosen in this way, it will be used by any Windows debugger that is using SymSrv to access a symbol server. It will also be used by any other
debugging tool that uses DbgHelp as its symbol handler. No other programs will be affected by this setting.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

HTTP Symbol Stores

In order to make a symbol store accessible over the Internet, you must configure both the directories containing the symbol files and Internet Information Services (IIS).
Configuring the Directories
Begin by selecting the directory you will use as your symbol store. In our examples, we call this directory c:\symstore and the name of the server on the network is
\SymMachineName. Permissions must be set so that users can access the site and you must add the security groups that must access the symbol content over the network. The
amount of security to enable varies from environment to environment. For some installations, this group is Everyone.
To set up the permissions for the directory
1.
2.
3.
4.
5.
6.
7.
8.
9.

Open Windows Explorer.

Expand My Computer.
Expand the C drive.
Right-click c:\symstore and choose Sharing and Security.
Check Share this folder.
Click Permissions.
To ensure that the desired security groups have read access, add them under Group or user names and check the Allow box in the Read row.
To exit Permissions, click OK.
To exit Symstore Properties, click OK.

The symbol store can now be used for debugging by another computer with a symbol path of srv*\\SymMachineName\symstore, or it can be further configured for use with
authentication or with SymProxy.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 175 of 1651

For details on how to populate your symbol store, see SymStore.

Configuring IIS
Internet Information Services (IIS) must be configured to serve the symbols by creating a virtual directory and configuring MIME types. After this has been done, the
authentication method may be chosen.
To create a virtual directory
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

From Administrative Tools open Internet Information Services (IIS) Manager.

Expand Web Sites.
Right-click Default Web Site or the name of the site being used.
Select New Virtual Director....
Click Next on the Welcome screen.
Type Symbols for Alias and click Next.
For the Path enter c:\SymStore and click Next.
Uncheck Run scripts (recommended).
Check Browse (optional).
To complete the virtual directory wizard, click Next and Finish.

To configure MIME types

1.
2.
3.
4.
5.
6.
7.
8.

Right-click the Symbols virtual directory and choose Properties.

Select HTTP Headers.
Click MIME Types.
Click New.
For Extension, type *.
For MIME type, type application/octet-stream.
To exit the MIME Types dialog box, click OK.
To exit Symbols Properties, click OK.

At this point, IIS is now ready to serve the files in your symbol store using anonymous authentication. It is also possible to configure IIS to use Integrated Windows
Authentication (IWA) so that clients such as WinDbg can automatically authenticate against IIS without prompting the end-user for credetials. However, SymSrv does not
currently support Kerberos authentication when connecting to IIS, so Kerberos must be removed as an option.
To configure the authentication method
1.
2.
3.
4.
5.
6.
7.
8.

From Administrative Tools, open Internet Information Services (IIS) Manager.

Right-click the Symbols virtual directory and select Properties.
Click the Directory Security tab.
Under Authentication and access control click Edit.
Verify that only Integrated Windows Authentication is checked.
Verify that Enable anonymous acceess is unchecked.
To exit the Authentication Methods dialog box, click OK.
To exit Symbols Properties, click OK.

To remove the option for Kerberos authentication, the Web site identifier is needed. If you are not using the default Web site (which is site "1"), you must determine the
correct Web site identifier by highlighting the Web Sites folder and looking at the identifier listed in the right-hand panel for the appropriate Web site. Replace "1" in these
directions with the correct identifier number.
To force NTLM authentication, thus removing Kerberos authentication
1. Open a Command Prompt window
2. Navigate to the directory c:\inetpub\AdminScripts.
3. Type the following, including the quotation marks:
cscript adsutil.vbs set W3SVC/1/root/Symbols/NtAuthenticationProviders "NTLM"
IIS is now ready to serve files from the symbol store.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymProxy
You can configure your HTTP-based symbol store to act as a proxy between client computers and other symbol stores. The implementation is through an Internet Server
Application Programming Interface (ISAPI) filter called SymProxy (Symproxy.dll). The SymProxy server can be used as a gateway computer to the Internet or other sources
within your company network.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 176 of 1651

Example of SymProxy Configuration

SymProxy is useful in many situations. For example:

You are debugging many systems within a lab environment in which the computers are not attached to the company network, but the symbols are stored in the network
and must be accessed using Integrated Windows Authentication (IWA).
Your corporate computing environment includes a firewall that prevents access to the Internet from computers that are debugging and you must obtain symbols from an
internet Web site.
You want to present a single symbol path for all users in your company so that they need not know or care about where symbols are located, and you can add new
symbol stores without user intervention.
You have a remote site that is physically far from the rest of your company resources, and network access is slow. This system can be used to acquire symbols and
cache them to the remote site.

To install SymProxy, you must manually copy the files to the correct location, configure the registry, choose network security credentials, and configure Internet Information
Services (IIS). To ensure that your HTTP symbol store is properly configured, see HTTP Symbol Stores.
This section includes:
Installing SymProxy
Configuring the Registry
Choosing Network Security Credentials
Configuring IIS for SymProxy
Setting Up Exclusion Lists
Dealing with Unavailable Symbol Stores
Checking and Updating Status
Handling File Pointers
Caching Acquired Symbol Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing SymProxy
To install SymProxy on the server, copy Symproxy.dll and Symsrv.dll to %WINDIR%\system32\inetsrv.
In order to prevent problems that could occur in accessing the Microsoft Symbol Store at http://msdl.microsoft.com/downloads/symbols, you must also create a file called %
WINDIR%\system32\inetsrv\symsrv.yes. The contents of this file are of no consequence.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 177 of 1651

Debugging Tools for Windows

Configuring the Registry

SymProxy stores its settings in the registry key
HKLM/Software/Microsoft/Symbol Server Proxy
This registry key controls the location from which to find symbols to store in the Web site, the logging level, and whether or not SymProxy operates with a direct connection
to the network. You can create this key by running the SymProxy registration tool (Symproxy.reg) provided with Debugging Tools for Windows. Type symproxy.reg at the
command prompt or double-click it from Windows Explorer.
Web Directories
For each virtual directory generated in IIS that you are using as a symbol store, you must setup a registry key below the Web Directories subkey of the following registry
key.
HKLM/Software/Microsoft/Symbol Server Proxy
To set up a registry key for a symbol store virtual directory
1. Create the registry key under the Web Directories key that has the same name as the virtual directory.
2. Create a new String Value or Expandable String Value called SymbolPath for the registry key that you just created.
3. Edit the contents of SymbolPath to contain all of the symbol stores used by the SymProxy symbol store. If there is more than one symbol store being used, separate
them with semicolons. A maximum of 10 stores is supported for each value. HTTP paths must include the http:// prefix, and UNC paths must include the \\ prefix.
For example, if one of the virtual directories is called Symbols, and the symbols stores that it accesses are located at the UNC store \\symbols\symbols and the HTTP store
http://msdl.microsoft.com/download/symbols, create the following registry key.
HKLM/Software/Microsoft/Symbol Server Proxy/Web Directories/symbols
After this key is created, edit its SymbolPath to be \\symbols\symbols;http://msdl.microsoft.com/download/symbols. This can be seen in the following screenshot of the
Registry Editor.

Registry Example
In this example, SymProxy first searches for symbols in \\symbols\symbols. If the files are not found there, the Microsoft Symbol Store will be used.
You can also define a global source for all symbol files by generating a SymbolPath value directly in the Web Directories key. However, we do not recommend this because
it causes malformed symbol requests from debugging clients to generate spurious directories and files in the root of your Web site.
Logging
SymProxy reports its activity to the Application Event Viewer. The value stored in Loglevel determines the level of reporting. This is a REG_DWORD located in the
Symbol Server Proxy key. Typically, the default setting is 0, but you can change this to any of the following values:
Loglevel Reporting Level
0
quiet
1
error
2
succss
3
info
4
warning
5
debug
If you have trouble moving files into the symbol store, you can adjust these values to determine what is happening. If you set Loglevel to 5, all activity is available in the
Event Viewer. To determine where files come from and to examine the initialization, set Loglevel to 3.
In order to complete the logging configuration, you must register SymProxy with the Application Event Viewer.
To register SymProxy with the Application Event Viewer
1. Create the registry key
HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\SymProxy
2. Within this key, create a new Expandable String Value (REG_EXPAND_SZ) named EventMessageFile.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 178 of 1651

3. Set the contents of this string to %WINDIR%\system32\inetsrv\symproxy.dll.

SymProxy is now labeled as a message source in the registry, and logging is activated.
Accessing Outside Network Resources
When SymSrv is used in conjunction with SymProxy, it runs as a service and uses the WinHTTP API to access symbols over an HTTP connection. This differs from its usual
behavior of using WinInet for this purpose.
Consequently, you may need to set up HTTP proxy settings so that this service can access outside network resources. Use one of the following methods to configure these
settings:

In Windows 2000, Windows XP, and Windows Server 2003, use the ProxyCfg tool (Proxycfg.exe). For instructions, type the following in a Command Prompt window:
proxycfg -?

In Windows Vista, Windows Server 2008, and later versions of Windows, use the Netsh tool (netsh.exe). For instructions, type the following in a Command Prompt
window:
netsh winhttp -?

The default behavior of SymProxy is to use whatever HTTP proxy is designated by either ProxyCfg or Netsh. If no HTTP proxy is configured, SymProxy uses a dummy
proxy to allow access to secure HTTP sites within your intranet. As a side effect, this technique prevents SymProxy from working with direct connections to the external
Internet. If you wish to permit SymProxy to operate with a direct connection to the Internet, create a REG_DWORD value named NoInternetProxy in the Symbol Server
Proxy key of your registry. Set the value of NoInternetProxy to 1 and verify that there is no HTTP proxy indicated by ProxyCfg.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Choosing Network Security Credentials

The symbol proxy server must run from a security context with the appropriate privileges for access to the symbol stores that you plan to use. If you obtain symbols from an
external Web store such as http://msdl.microsoft.com/download/symbols, the symbol proxy server must access the Web from outside of any firewalls. If you obtain files from
other computers on your network, the symbol proxy server must have appropriate privileges to read files from those locations. Two possible choices are to set the symbol
proxy server to authenticate as the Network Service account or to create a user account that is managed within Active Directory Domain Services along with other user
accounts.
Authenticate as a Network Service
The Network Service account is built in to Windows, so there is no extra step of creating a new account. For this example, we name the computer where the symbol proxy
server is being configured SymMachineName on a domain named corp.
External symbol stores or Internet proxies must be configured to allow this computer's Network Service account (Machine Account) to authenticate successfully. There are
two ways to achieve this:

Allow access to the Authenticated Users group on the external store or Internet proxy.
Allow access to the Machine Account corp\SymMachineName$. This option is more secure because it limits access to just the symbol proxy server's "Network Service"
account.

Authenticate as a Domain User

For this example, the user account is named SymProxyUser on a domain named corp. To authenticate this user account, it must be added to the IIS_WPG group.
Note It is a good practice to limit privileges of this account to only those necessary to read files and copy them to c:\symstore. This restriction prevents clients that access
your HTTP store from corrupting the system .
To add the user account to the IIS_WPG group
1.
2.
3.
4.
5.
6.
7.
8.
9.

From Administrative Tools open Computer Management.

Expand Local Users and Groups.
Click Groups.
Double-click IIS_WPG in the right pane.
Click Add.
Type corp\SymProxyUser in the pane labeled Enter the object name to select.
To exit the Select Users, Computer, or Groups dialog box, click OK.
To exit IIS_WPG Properties, click OK.
Close the Computer Management console.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 179 of 1651

Configuring IIS for SymProxy

Internet Information Services (IIS) must be configured to use SymProxy as an Internet Server Application Programming Interface (ISAPI) filter. Furthermore, permissions
must be set so that IIS can obtain symbols.
To configure the application pool
From Administrative Tools open Internet Information Services (IIS) Manager.
Right-click Application Pools and choose New -> Application Pool.
For the Application ID type SymSrv Pool.
To exit Add New Application Pool, click OK.
Right-click the SymSrv Pool application pool and select Properties.
Click the Identity tab.
a. If you are authenticating as a network service, select Predefined for the Application Pool Identity and then select Network Service.
b. If you are authenticating as a domain user, select Configurable for the Application Pool Identity, type the credentials of the account that has permissions to
access the remote symbol server store (for example, corp\SymProxyUser), and click OK.
7. To exit SymSrv Pool Properties, click OK.

1.
2.
3.
4.
5.
6.

To set up the Virtual Directory

1.
2.
3.
4.
5.
6.

Expand Web Sites.

Expand Default Web Site.
Right-click the Symbols virtual directory and choose Properties.
In the Virtual Directory tab, click Create.
From the Application Pool drop-down menu, choose SymSrv Pool.
To exit Symbols Properties, click OK.

To configure the ISAPI filter

1.
2.
3.
4.
5.
6.
7.

Right-click the Default Web Site and select Properties.

Click the ISAPI Filters tab.
Click Add.
For Filter Name type SymProxy or some other meaningful name.
For Executable type c:\\windows\system32\inetsrv\symproxy.dll.
To exit the Filter Properties dialog, click OK.
To exit Default Web Site Properties, click OK.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Up Exclusion Lists

In some environments, you may find yourself debugging systems that have a large quantity of modules loaded for which you cannot obtain symbols. This is often the case if
you have code that is called by a third-party vendor. This can result in a lot of failed attempts to find symbols, which is time-consuming and clogs up network resources. To
alleviate this situation, you can use an exclusion list to specify symbols that should be excluded from the search. This feature exists in the client debugger, but you can also
configure the SymProxy filter to use its own the exclusion list and prevent such network activity where it is most likely to take up resources.
The exclusion list is made up of the names of the files for which you want to prevent processing. The file names can contain wildcards. For example:
dbghelp.pdb
symsrv.*
mso*
The list can be implemented in two ways. The first is in an .ini file, %WINDIR%\system32\inetsrv\Symsrv.ini. A section called exclusions should contain the list:
[exclusions]
dbghelp.pdb
symsrv.*
mso*
Alternatively, you can store the exclusions in the registry. Create a key named
HKLM\ Software\Microsoft\Symbol Server\Exclusions
Store the file name list as string values (REG_SZ) within this key. The name of the string value acts as the file name to exclude. The contents of the string value can be used
as a comment describing why the file is being excluded.
SymProxy reads from the exclusion list every half-hour so that you do not need to restart the Web service to see changes take effect. Add files to the list in the registry or .ini
file and wait a short period for the exclusions to be used.
Note SymProxy does not support the use of both Symsrv.ini and the registry. If the .ini file exists, it is used. Otherwise, the registry is checked.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 180 of 1651

December 09, 2009

Debugging Tools for Windows

Dealing with Unavailable Symbol Stores

If one of the symbol stores that SymSrv is configured to obtain files from is down or otherwise unavailable, the result can be long waits from the client for every file request.
When SymSrv is called from SymProxy, you can avoid most of these waits by setting up SymSrv to stop trying to access the store in question. When this feature is engaged,
SymSrv stops trying to use the store for a set period of time after it experiences a specified number of timeouts from the same store during a set interval. The values of these
variables can be controlled either by an .ini file or from the registry.
To control symbol store access using a .ini file
1. In %WINDIR%\system32\inetsrv\Symsrv.ini, create a section called timeouts.
2. Add the values trigger, count, and blackout to this section.
Trigger indicates the amount of time in minutes to watch for timeouts. Count indicates the number of timeouts to look for during the trigger period. Blackout indicates the
length of time in minutes to disable the store after the threshhold is reached.
For example, we recommend the following settings:
[timeouts]
trigger=10
count=5
blackout=15
In this example, the store access is turned off if five timeouts are experienced in a 10-minute period. At the completion of a 15-minute blackout, the store is reactivated.
To control symbol store access using the registry
1. Create a key named
HKLM\ Software\Microsoft\Symbol Server\Timeouts
2. Add three REG_DWORD values trigger, count, and blackout to this key. Set these values as you would in the .ini file.
Whether using the registry or an .ini file, if any of the trigger, count, or blackout values are set to 0 or if any of the keys or values do not exist, this functionality is disabled.
This feature of SymSrv is currently available only when running as a service. This means that the only practical application of this feature is when it is called from SymProxy.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Checking and Updating Status

It is possible to see where SymProxy is configured to acquire symbols by using any browser software. Bring up status to get the information. For example, if the symbols Web
site is http://server/symbols, go to http://server/symbols/status. You can also use this to cause symproxy to re-read its configuration information after making a change to the
registry. This changes the paths without having to restart the IIS service.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Handling File Pointers

A UNC symbol store supports placing the actual files to be served in a separate location, with the client code finding the location of the files through file pointers. These
pointers are generated in the symbol store using SymStore with the /p option. This handling is supported with other HTTP-based symbol stores only if the file pointers point
to a UNC location that is directly accessible by the client. When SymProxy is loaded into the Web server, file-pointer handling is automatically enhanced. The client no
longer needs to be able to directly access the target files because SymProxy serves them through the HTTP interface.
Because this feature is automatically applied, an option exists to turn it off in case you must use the proxy for serving some files and regular file pointer implementation for
others. To do this, create a REG_DWORD called NoFilePointerHandler in HKLM\Software\Microsoft\Symbol Server. Set this value to 1 (or anything other than 0) to turn
off the internal file pointer handler in SymProxy.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 181 of 1651

Debugging Tools for Windows

Caching Acquired Symbol Files

Typically, SymProxy caches the files that it acquires in the directory designated within Internet Information Services (IIS) as the virtual root for the associated Web site. Then
IIS makes the file available to the client debugger. Because the debugger cannot open a file directly from HTTP, it copies the file to a local cache, specified by the symbol
path:
srv*c:\localcache*http://server/symbols
In this example, the client debugger copies the file to c:\localcache. In a situation such as this, the file is copied twice once by SymProxy to the virtual root of the Web site,
and again by the debugger to its local cache.
It is possible to avoid the second copy operation and speed up processing. To do this, you must first share the virtual root of the Web site as a UNC path that can be accessed
by the debuggers. For sake of example, this path is named \\server\symbols. You must then remove the IIS configuration for MIME types:
To remove the IIS configuration for MIME types
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

From Administrative Tools open Internet Information Services (IIS) Manager.

Expand Web Sites.
Right-click Default Web Site.
Right-click the Symbols virtual directory and select Properties.
Click the HTTP Headers tab.
Click MIME Types .
Select all types in the list box labelled Registered MIME Types.
Click Remove .
To exit the MIME Types dialog, click OK.
To exit Symbols Properties, click OK.

This causes IIS to return file not found to the debugging client for all transactions on the Web site. However, it does not prevent SymProxy from populating the virtual root
with the file.
After you remove the IIS configuration for MIME types, configure the debugger clients to look for symbols first in the HTTP store and in the share that maps to the virtual
root of the store with the command:
srv**http://server/symbols;srv*\\server\symbols
In the preceding example, the first element of the symbol path (srv**http://server/symbols) says to get files from the HTTP store and copy them to the default symbol store as
a local cache. The specified cache is of no importance because no file is ever received from the HTTP store. After this failure, it attempts to obtain the file from the actual
location of the virtual root of the store (srv*\\server\symbols). This attempt succeeds because the file is copied to that location as a side effect of the previous path processing.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Other Symbol Stores

It is possible to write your own symbol store creation program, rather than using SymStore.
Since SymStore transactions are all logged in CSV-format text files, you can leverage any existing SymStore log files for use in your own database program.
If you plan to use the SymSrv program provided with Debugging Tools for Windows package, it is recommended that you use SymStore as well. Updates to these two
programs will always be released together, and therefore their versions will always match.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Other Symbol Servers

If you wish to use a different method for your symbol search, you can provide your own symbol server DLL rather than using SymSrv.
Setting the Symbol Path
When implementing a symbol server other than SymSrv, the debugger's symbol path is set in the same way as with SymSrv. See SymSrv for an explanation of the symbol
path syntax. The only change you need to make is to replace the string symsrv.dll with the name of your own symbol server DLL.
If you wish, you are free to use a different syntax within the parameters to indicate the use of different technologies such as UNC paths, SQL database identifiers, or Internet
specifications.
Implementing Your Own Symbol Server

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 182 of 1651

The central portion of the server is the code that communicates with DbgHelp to find the symbols. Every time DbgHelp requires symbols for a newly loaded module, it calls
the symbol server to locate the appropriate symbol files. The symbol server locates each file according to unique parameters such as the time stamp or image size. The server
returns a validated path to the requested file. To implement this, the server must export the SymbolServer function.
The server should also support the SymbolServerSetOptions and SymbolServerGetOptions functions. And DbgHelp will call the SymbolServerClose function, if it is
exported by the server. See Symbol Server API for information about where these routines are documented.
You must not change the actual symbol file name returned by your symbol server. DbgHelp stores the name of a symbol file in multiple locations. Therefore, the server must
return a file of the same name as that specified when the symbol was requested. This restriction is needed to assure that the symbol names displayed during symbol loading
are the ones that the programmer will recognize.
Restrictions on Multiple Symbol Servers
DbgHelp supports the use of only one symbol server at a time. Your symbol path can contain multiple instances of the same symbol server DLL, but not two different symbol
server DLLs. This is not much of a restriction, since you are still free to include multiple instances of a symbol server in your symbol path, each pointing to a different symbol
store. But if you want to switch between two different symbol server DLLs, you will have to change the symbol path each time.
Installing Your Symbol Server
The details of your symbol server installation will depend on your situation. You might wish to set up an installation process that copies your symbol server DLL and sets the
_NT_SYMBOL_PATH environment variable automatically.
Depending on the technology used in your server, you may also need to install or access the symbol data itself.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Deferred Symbol Loading

By default, symbol information is not actually loaded when the target modules are loaded. Instead, symbols are loaded by the debugger as they are needed. This is called
deferred symbol loading or lazy symbol loading. When this option is enabled, the debugger loads symbols whenever it encounters an unrecognized symbol.
When deferred symbol loading is disabled, process startup can be much slower, because all symbols are read whenever a module is loaded.
In WinDbg, the deferred symbol loading behavior can be modified for symbols that have no module prefix by using the Resolve Unqualified Symbols option on the Debug
menu.
You can override deferred symbol loading by using the ld (Load Symbols) command or the .reload (Reload Module) command with the /f option. These force the specified
symbols to be loaded immediately, although the loading of other symbols is deferred. If the symbol path is changed, symbols are not automatically reloaded.
By default, deferred symbol loading is enabled. In CDB and KD, the -s command-line option will turn this option off. It can also be turned off in CDB by using the LazyLoad
variable in the tools.ini file. Once the debugger is running, this option can be turned on or off by using .symopt+0x4 or .symopt-0x4, respectively.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

How the Debugger Recognizes Symbols

This section includes:
Symbol Syntax and Symbol Matching
Symbol Options
Symbol Status Abbreviations
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Syntax and Symbol Matching

Symbols allow you to directly manipulate tokens that are used by the program being debugged. For example, you can set a breakpoint at the function main with the command
bp main, or display the integer variable MyInt with the command dd MyInt L1.
In many cases, symbols can be used as parameters in debugger commands. This is supported for most numerical parameters, and is also supported in some text parameters. In

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 183 of 1651

addition to general rules for symbol syntax, there are also symbol syntax rules that apply in each of these cases.
General Symbol Syntax Rules
A symbol name consists of one or more characters, but always begins with a letter, underscore (_), question mark (?), or dollar sign ($).
A symbol name may be qualified by a module name. An exclamation mark (!) separates the module name from the symbol (for instance, mymodule!main). If no module
name is used, the symbol can still be prefixed with an exclamation mark. Using an exclamation mark with no module name can be especially useful, even for local variables,
to indicate to a debugger command that a parameter is a name and not a hexadecimal number. For example, the variable fade will be read by the dt (Display Type) command
as an address, unless it is prefixed by an exclamation mark or the -n option is used. However, to specify that a symbol is local, precede it with a dollar sign ( $ ) and an
exclamation point ( ! ), as in $!lime.
Symbol names are completely case-insensitive. This means that the presence of a myInt and a MyInt in your program will not be correctly understood by the debuggers; any
command that references one of these may access the other one, regardless of how the command is capitalized.
Symbol Syntax in Numerical Expressions
The debugger understands two different kinds of expressions: Microsoft Macro Assembler (MASM) expressions and C++ expressions. As far as symbols are concerned, these
two forms of syntax differ as follows:

In MASM expressions, each symbol is interpreted as an address. Depending on what the symbol refers to, this will be the address of a global variable, local variable,
function, segment, module, or any other recognized label.
In C++ expressions, each symbol is interpreted according to its type. Depending on what the symbol refers to, it may be interpreted as an integer, a data structure, a
function pointer, or any other data type. A symbol that does not correspond to a C++ data type (such as an unmodified module name) will result in a syntax error.

For an explanation of when and how to use each type of syntax, see Evaluating Expressions.
If you are using MASM expression syntax, any symbol that could be interpreted as a hexadecimal number or as a register (e.g., BadFeed, ebX) should always be prefixed by
an exclamation point. This makes sure the debugger recognizes it as a symbol.
The ss (Set Symbol Suffix) command can be used to set the symbol suffix. This instructs the debugger to automatically append "A" or "W" to any symbol name it cannot find
otherwise.
Many Win32 routines exist in both ASCII and Unicode versions. These routines often have an "A" or "W" appended to the end of their names, respectively. Using a symbol
suffix will aid the debugger when searching for these symbols.
Suffix matching is not active by default.
Symbol Syntax in Text Expressions
Symbols can be used in the text parameters of some commands for example, bm (Set Breakpoint) and x (Examine Symbols).
These text parameters support a variety of wildcards and specifiers. See String Wildcard Syntax for details. In addition to the standard string wildcards, a text expression used
to specify a symbol can be prefixed with a leading underscore. When matching this to a symbol, the debugger will treat this as any quantity of underscores, even zero.
The symbol suffix is not used when matching symbols in text expressions.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Options
A number of options are available to control how symbols are loaded and used. These options can be set in a variety of ways.
The following table lists these symbol options:
Flag
0x1
0x2
0x4
0x8
0x10

Option Name
SYMOPT_CASE_INSENSITIVE
SYMOPT_UNDNAME
SYMOPT_DEFERRED_LOADS
SYMOPT_NO_CPP
SYMOPT_LOAD_LINES

Default in debugger Default in DBH

On
On
On
On
On
Off
Off
Off
Off in KD and CDB On
On in WinDbg

0x20
0x40
0x80
0x100
0x200
0x400
0x800
0x1000
0x2000

SYMOPT_OMAP_FIND_NEAREST
On
SYMOPT_LOAD_ANYTHING
Off
SYMOPT_IGNORE_CVREC
Off
SYMOPT_NO_UNQUALIFIED_LOADS
Off
SYMOPT_FAIL_CRITICAL_ERRORS
On
SYMOPT_EXACT_SYMBOLS
Off
SYMOPT_ALLOW_ABSOLUTE_SYMBOLS Off
SYMOPT_IGNORE_NT_SYMPATH
Off
SYMOPT_INCLUDE_32BIT_MODULES
Off

Off
Off
Off
Off
Off
On
On
Off
Off

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x4000
0x8000
0x10000
0x20000
0x40000
0x80000

SYMOPT_PUBLICS_ONLY
SYMOPT_NO_PUBLICS
SYMOPT_AUTO_PUBLICS
SYMOPT_NO_IMAGE_SEARCH
SYMOPT_SECURE
SYMOPT_NO_PROMPTS

Page 184 of 1651

Off
Off
On
On
Off
On in KD and CDB

Off
Off
On
Off
Off
Off

Off in WinDbg
0x80000000 SYMOPT_DEBUG

Off

Changing the Symbol Option Settings

The .symopt (Set Symbol Options) command can be used to change or display the symbol option settings. In addition, a number of command-line parameters and commands
are available to change these settings; these are listed in the individual SYMOPT_XXX sections.
You can also control all the settings at once with the -sflags command-line option. This option can be followed with a decimal number, or with a hexadecimal number
prefixed by 0x. It is recommended that you use hexadecimal, since the symbol flags are aligned properly that way. Be cautious in using this method, since it sets the entire
bitfield and will override all the symbol handler defaults. For example, -sflags 0x401 will not only turn on SYMOPT_EXACT_SYMBOLS and
SYMOPT_CASE_INSENSITIVE, but will also turn off all the other options that normally are on by default!
The default value for the total flag bits is 0x30237 in WinDbg, 0xB0227 in CDB and KD, and 0x10C13 in the DBH tool, when these programs are launched without any
symbol-related command line options.

SYMOPT_CASE_INSENSITIVE
This symbol option causes all searches for symbol names to be case-insensitive.
This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x1 or .symopt-0x1, respectively.
This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +1 or symopt -1, respectively.

SYMOPT_UNDNAME
This symbol option causes public symbol names to be undecorated when they are displayed, and causes searches for symbol names to ignore symbol decorations. Private
symbol names are never decorated, regardless of whether this option is active. For information on symbol name decorations, see Public and Private Symbols.
This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x2 or .symopt-0x2, respectively.
This option is on by default in DBH. It is turned off if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +2 or symopt -2,
respectively.

SYMOPT_DEFERRED_LOADS
This symbol option is called deferred symbol loading or lazy symbol loading. When it is active, symbols are not actually loaded when the target modules are loaded. Instead,
symbols are loaded by the debugger as they are needed. See Deferred Symbol Loading for details.
This option is on by default in all debuggers. In CDB and KD, the -s command-line option will turn this option off. It can also be turned off in CDB by using the LazyLoad
variable in the tools.ini file. Once the debugger is running, this option can be turned on or off by using .symopt+0x4 or .symopt-0x4, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +4 or symopt -4, respectively.

SYMOPT_NO_CPP
This symbol option turns off C++ translation. When this symbol option is set, :: is replaced by __ in all symbols.
This option is off by default in all debuggers. It can be activated by using the -snc command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x8 or .symopt-0x8, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +8 or symopt -8, respectively.

SYMOPT_LOAD_LINES
This symbol option allows line number information to be read from source files. This option must be on for source debugging to work correctly.
In KD and CDB, this option is off by default; in WinDbg, this option is on by default. In CDB and KD, the -lines command-line option will turn this option on. Once the
debugger is running, it can be turned on or off by using .symopt+0x10 or .symopt-0x10, respectively. It can also be toggled on and off by using the .lines (Toggle Source
Line Support) command.
This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +10 or symopt -10, respectively.

SYMOPT_OMAP_FIND_NEAREST
When code has been optimized and there is no symbol at the expected location, this option causes the nearest symbol to be used instead.
This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x20 or .symopt-0x20, respectively.
This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +20 or symopt -20, respectively.

SYMOPT_LOAD_ANYTHING

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 185 of 1651

This symbol option reduces the pickiness of the symbol handler when it is attempting to match symbols.
This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x40 or .symopt-0x40, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +40 or symopt -40, respectively.

SYMOPT_IGNORE_CVREC
This symbol option causes the symbol handler to ignore the CV record in the loaded image header when searching for symbols.
This option is off by default in all debuggers. It can be activated by using the -sicv command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x80 or .symopt-0x80, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +80 or symopt -80, respectively.

SYMOPT_NO_UNQUALIFIED_LOADS
This symbol option disables the symbol handler's automatic loading of modules. When this option is set and the debugger attempts to match a symbol, it will only search
modules which have already been loaded.
This option can be used as a defense against mistyping a symbol name. Normally, a mistyped symbol will cause the debugger to pause while it searches all unloaded symbol
files. When this option is active, a mistyped symbol will not be found in the loaded modules, and then the search will terminate.
This option is off by default in all debuggers. It can be activated by using the -snul command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x100 or .symopt-0x100, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +100 or symopt -100, respectively.

SYMOPT_FAIL_CRITICAL_ERRORS
This symbol option causes file access error dialog boxes to be suppressed.
If this option is off, file access errors, such as "drive not ready", encountered during symbol loading, will result in dialog boxes appearing. If this option is on, these boxes are
suppressed and all access errors receive a "fail" response.
This option is on by default in all debuggers. It can be deactivated by using the -sdce command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x200 or .symopt-0x200, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +200 or symopt -200, respectively.

SYMOPT_EXACT_SYMBOLS
This symbol option causes the debugger to perform a strict evaluation of all symbol files.
When this option is on, even the slightest discrepancy between the symbol files and the symbol handler's expectations will cause the symbols to be ignored.
This option is off by default in all debuggers. It can be activated by using the -ses command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x400 or .symopt-0x400, respectively.
The -failinc command-line option also turns on SYMOPT_EXACT_SYMBOLS. In addition, if you are debugging a user-mode minidump or a kernel-mode minidump,
-failinc will prevent the debugger from loading any modules whose images can't be mapped.
This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +400 or symopt -400, respectively.

SYMOPT_ALLOW_ABSOLUTE_SYMBOLS
This symbol option allows DbgHelp to read symbols that are stored at an absolute address in memory. This option is not needed in the vast majority of cases.
This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x800 or .symopt-0x800, respectively.
This option is on by default in DBH. Once DBH is running, it can be turned on or off by using symopt +800 or symopt -800, respectively.

SYMOPT_IGNORE_NT_SYMPATH
This symbol option causes the debugger to ignore the environment variable settings for the symbol path and the executable image path.
This option is off by default in all debuggers. It can be activated by using the -sins command-line option. However, it cannot be controlled by .symopt once the debugger is
running, because the environment variables are only read at startup.
This option is off by default in DBH, and is ignored by DBH in all cases.

SYMOPT_INCLUDE_32BIT_MODULES
This symbol option forces DbgHelp and ImageHlp to enumerate 32-bit modules on an Intel Itanium processor.
This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x2000 or .symopt-0x2000, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +2000 or symopt -2000, respectively.

SYMOPT_PUBLICS_ONLY
This symbol option causes DbgHelp to ignore private symbol data, and search only the public symbol table for symbol information. This emulates the behavior of DbgHelp

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 186 of 1651

before support for these types was added. see Public and Private Symbols.
This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x4000 or .symopt-0x4000, respectively.
This option is off by default in DBH. It is turned on if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +4000 or
symopt -4000, respectively.

SYMOPT_NO_PUBLICS
This symbol option prevents DbgHelp from searching the public symbol table. This can make symbol enumeration and symbol searches much faster. If you are concerned
solely with search speed, the SYMOPT_AUTO_PUBLICS option is generally preferable to this one. For information on the public symbol table, see Public and Private
Symbols.
This option is off by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x8000 or .symopt-0x8000, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +8000 or symopt -8000, respectively.

SYMOPT_AUTO_PUBLICS
This symbol option causes DbgHelp to search the public symbol table in a .pdb file only as a last resort. If any matches are found when searching the private symbol data, the
public symbols will not be searched. This improves symbol search speed.
This option is on by default in all debuggers. It can be deactivated by using the -sup command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x10000 or .symopt-0x10000, respectively.
This option is on by default in DBH. It is turned off if the -d command-line option is used. Once DBH is running, it can be turned on or off by using symopt +10000 or
symopt -10000, respectively.

SYMOPT_NO_IMAGE_SEARCH
This symbol option prevents DbgHelp from searching the disk for a copy of the image when symbols are loaded.
This option is on by default in all debuggers. Once the debugger is running, it can be turned on or off by using .symopt+0x20000 or .symopt-0x20000, respectively.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +20000 or symopt -20000, respectively.

SYMOPT_SECURE
(Kernel mode only) This symbol option indicates whether Secure Mode is active.
Secure Mode is off by default in all debuggers. It can be activated by using the -secure command-line option. If the debugger is running, is in dormant mode, and has not
established any Debugging Servers, Secure Mode can be turned on by using .symopt+0x40000 or .secure (Activate Secure Mode).
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +40000 or symopt -40000, respectively.
Secure mode can never be turned off once it has been activated.

SYMOPT_NO_PROMPTS
This symbol option suppresses authentication dialog boxes from the proxy server. This may result in SymSrv being unable to access a symbol store on the internet.
For details, see Firewalls and Proxy Servers.
In KD and CDB, this option is on by default; in WinDbg, this option is off by default. Once the debugger is running, it can be turned on or off by using .symopt+0x80000 or
.symopt-0x80000, respectively, followed by the .reload (Reload Module) command. It can also be turned on and off by using the !sym prompts off and !sym prompts
extension commands, followed by the .reload (Reload Module) command.
This option is off by default in DBH. Once DBH is running, it can be turned on or off by using symopt +80000 or symopt -80000, respectively.

SYMOPT_DEBUG
This symbol option turns on noisy symbol loading. This instructs the debugger to display information about its search for symbols.
The name of each symbol file will be displayed as it is loaded. If the debugger cannot load a symbol file, it will display an error message. Error messages for .pdb files will be
displayed in text. Error messages for .dbg files will be in the form of an error code; these codes are explained in the winerror.h file.
If an image file is loaded solely to recover symbolic header information, this will be displayed as well.
This option is off by default in all debuggers. It can be activated by using the -n command-line option. Once the debugger is running, it can be turned on or off by
using .symopt+0x80000000 or .symopt-0x80000000, respectively. It can also be turned on and off by using the !sym noisy and !sym quiet extension commands.
Note This option should not be confused with noisy source loading that is controlled by the .srcnoisy (Noisy Source Loading) command.
This option is off by default in DBH. It can be activated by using the -n command-line option. Once DBH is running, it can be turned on or off by using symopt +80000000
or symopt -80000000, respectively. It can also be turned on and off by using the verbose on and verbose off commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 187 of 1651

Symbol Status Abbreviations

Symbol file types and their loading status can be determined by using the lm (List Loaded Modules) command, the !lmi extension, or WinDbg's Debug | Modules menu
command.
Each of these displays information about loaded modules and their symbols.
The following abbreviations are used in the displays generated by these commands:
Abbreviation
Meaning
deferred
The module has been loaded, but the debugger has not attempted to load the symbols. Symbols will be loaded when needed. See Deferred Symbol Loading for
details.
#
There is a mismatch between the symbol file and the executable, either in their timestamps or in their checksums.
T
The timestamp is missing, not accessible, or equal to zero.
C
The checksum is missing, not accessible, or equal to zero.
DIA
Symbol files were loaded through Debug Interface Access (DIA).
Export
No actual symbol files were found, so symbol information was extracted from the binary file's export table.
M
There is a mismatch between the symbol file and the executable, either in their timestamps or in their checksums. However, symbol files have been loaded
anyway due to the symbol option settings.
PERF
This binary contains performance-optimized code. Standard address arithmetic may not produce correct results.
Stripped
Debug information was stripped from the image file.
PDB
The symbols are in .pdb format.
COFF
The symbols are in common object file format (COFF) symbol format.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Problems While Debugging

Invalid or missing symbols are one of the most common causes of debugger problems. When you see some sort of problem, you need to find out if you have a symbol issue.
In some cases, the solution involves acquiring the correct symbol files. In other cases, you simply need to reconfigure the debugger to recognize symbol files you already
have. But if you are not able to get the correct symbol files, you will need to work around this problem and debug the target in a more limited manner.
This section includes:
Verifying Symbols
Matching Symbol Names
Reading Symbols from Paged-Out Headers
Mapping Symbols When the PEB is Paged Out
Debugging User-Mode Processes Without Symbols
Debugging Performance-Optimized Code
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Verifying Symbols
Symbol problems can show up in a variety of ways. Perhaps a stack trace shows incorrect information or fails to identify the names of the functions in the stack. Or perhaps a
debugger command failed to understand the name of a module, function, variable, structure, or data type.
If you suspect that the debugger is not loading symbols correctly, there are several steps you can take to investigate this problem.
First, use the lm (List Loaded Modules) command to display the list of loaded modules with symbol information. The most useful form of this command is the following:
0:000> lml
If you are using WinDbg, the Debug | Modules menu command will let you see this information as well.
Pay particular attention to any notes or abbreviations you may see in these displays. For an interpretation of these, see Symbol Status Abbreviations.
If you don't see the proper symbol files, the first thing to do is to check the symbol path:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 188 of 1651

0:000> .sympath
Current Symbol Path is: d:\MyInstallation\i386\symbols\retail
If your symbol path is wrong, fix it. If you are using the kernel debugger make sure your local %WINDIR% is not on your symbol path.
Then reload symbols using the .reload (Reload Module) command:
0:000> .reload ModuleName
If your symbol path is correct, you should activate noisy mode so you can see which symbol files dbghelp is loading. Then reload your module. See Setting Symbol Options
for information about how to activate noisy mode.
Here is an example of a "noisy" reload of the Microsoft Windows symbols:
kd>
kd>
1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:

!sym noisy
.reload nt
Kernel Version 2081 MP Checked
Kernel base = 0x80400000 PsLoadedModuleList = 0x80506fa0
DBGHELP: FindExecutableImageEx-> Looking for D:\MyInstallation\i386\ntkrnlmp.exe...mismatched timestamp
DBGHELP: No image file available for ntkrnlmp.exe
DBGHELP: FindDebugInfoFileEx-> Looking for
d:\MyInstallation\i386\symbols\retail\symbols\exe\ntkrnlmp.dbg... no file
DBGHELP: FindDebugInfoFileEx-> Looking for
d:\MyInstallation\i386\symbols\retail\symbols\exe\ntkrnlmp.pdb... no file
DBGHELP: FindDebugInfoFileEx-> Looking for d:\MyInstallation\i386\symbols\retail\exe\ntkrnlmp.dbg... OK
DBGHELP: LocatePDB-> Looking for d:\MyInstallation\i386\symbols\retail\exe\ntkrnlmp.pdb... OK
*** WARNING: symbols checksum and timestamp is wrong 0x0036a4ea 0x00361a83 for ntkrnlmp.exe

The symbol handler first looks for an image that matches the module it is trying to load (lines three and four). The image itself is not always necessary, but if an incorrect one
is present, the symbol handler will often fail. These lines show that the debugger found an image at D:\MyInstallation\i386\ntkrnlmp.exe, but the time-date stamp didn't
match. Because the time-date stamp didn't match, the search continues. Next, the debugger looks for a .dbg file and a .pdb file that match the loaded image. These are on lines
6 through 10. Line 11 indicates that even though symbols were loaded, the time-date stamp for the image did not match (that is, the symbols were wrong).
If the symbol-search encountered a catastrophic failure, you would see a message of the form:
ImgHlpFindDebugInfo(00000000, module.dll, c:\MyDir;c:\SomeDir, 0823345, 0) failed
This could be caused by items such as file system failures, network errors, and corrupt .dbg files.
Diagnosing Symbol Loading Errors
When in noisy mode, the debugger may print out error codes when it cannot load a symbol file. The error codes for .dbg files are listed in winerror.h. The .pdb error codes
come from another source and the most common errors are printed in plain English text.
Some common error codes for .dbg files from winerror.h are:
0xB
ERROR_BAD_FORMAT
0x3
ERROR_PATH_NOT_FOUND
0x35
ERROR_BAD_NETPATH
It's possible that the symbol file cannot be loaded because of a networking error. If you see ERROR_BAD_FORMAT or ERROR_BAD_NETPATH and you are loading
symbols from another machine on the network, try copying the symbol file to your host computer and put its path in your symbol path. Then try to reload the symbols.
Verifying Your Search Path and Symbols
Let "c:\MyDir;c:\SomeDir" represent your symbol path. Where should you look for debug information?
In cases where the binary has been stripped of debug information, such as the free builds of Windows, first look for a .dbg file in the following locations:
c:\MyDir\symbols\exe\ntoskrnl.dbg
c:\SomeDir\symbols\exe\ntoskrnl.dbg
c:\MyDir\exe\ntoskrnl.dbg
c:\SomeDir\exe\ntoskrnl.dbg
c:\MyDir\ntoskrnl.dbg
c:\SomeDir\ntoskrnl.dbg
current-working-directory\ntoskrnl.dbg
Next, look for a .pdb file in the following locations:
c:\MyDir\symbols\exe\ntoskrnl.pdb
c:\MyDir\exe\ntoskrnl.pdb
c:\MyDir\ntoskrnl.pdb
c:\SomeDir\symbols\exe\ntoskrnl.pdb
c:\SomeDir\exe\ntoskrnl.pdb
c:\SomeDir\ntoskrnl.pdb
current-working-directory\ntoskrnl.pdb
Note that in the search for the .dbg file, the debugger interleaves searching through the MyDir and SomeDir directories, but in the .pdb search it does not.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 189 of 1651

Windows XP and later versions of Windows do not use any .dbg symbol files. See Symbols and Symbol Files for details.
Mismatched Builds
One of the most common problems in debugging failures on a machine that is often updated is mismatched symbols from different builds. Three common causes of this
problem are: pointing at symbols for the wrong build, using a privately built binary without the corresponding symbols, and using the uniprocessor hardware abstraction level
(HAL) and kernel symbols on a multiprocessor machine. The first two are simply a matter of matching your binaries and symbols; the third can be corrected by renaming your
hal*.dbg and ntkrnlmp.dbg to hal.dbg and ntoskrnl.dbg.
To find out what build of Windows is installed on the target computer, use the vertarget (Show Target Computer Version) command:
kd> vertarget
Windows XP Kernel Version 2505 UP Free x86 compatible
Built by: 2505.main.010626-1514
Kernel base = 0x804d0000 PsLoadedModuleList = 0x80548748
Debug session time: Mon Jul 02 14:41:11 2001
System Uptime: 0 days 0:04:53
Testing the Symbols
Testing the symbols is more difficult. It involves verifying a stack trace on the debugger and seeing if the debug output is correct. Here's one example to try:
kd> u videoprt!videoportfindadapter2
Loading symbols for 0xf2860000
videoprt.sys ->
VIDEOPRT!VideoPortFindAdapter2:
f2856f42 55
push
f2856f43 8bec
mov
f2856f45 81ecb8010000
sub
f2856f4b 8b4518
mov
f2856f4e 53
push
f2856f4f 8365f400
and
f2856f53 8065ff00
and
f2856f57 56
push

videoprt.sys

ebp
ebp,esp
esp,0x1b8
eax,[ebp+0x18]
ebx
dword ptr [ebp-0xc],0x
byte ptr [ebp-0x1],0x0
esi

The u command unassembles the videoportfindadapter string in videoprt.sys. The symbols are correct on the debugger because common stack commands like push and mov
show up on the stack. Most functions begin with an add, sub, or push operation using either the base pointer (ebp) or the stack pointer (esp).
It's usually obvious when the symbols aren't working correctly. Glintmp.sys doesn't have symbols in this example because a function isn't listed next to Glintmp:
kd> kb
Loading symbols for 0xf28d0000
videoprt.sys ->
videoprt.sys
Loading symbols for 0xf9cdd000
glintmp.sys ->
glintmp.sys
*** ERROR: Symbols could not be loaded for glintmp.sys
ChildEBP RetAddr Args to Child
f29bf1b0 8045b5fa 00000001 0000a100 00000030 ntoskrnl!RtlpBreakWithStatusInstruction
f29bf1b0 8044904e 00000001 0000a100 00000030 ntoskrnl!KeUpdateSystemTime+0x13e
f29bf234 f28d1955 f9b7d000 ffafb2dc f9b7d000 ntoskrnl!READ_REGISTER_ULONG+0x6
f29bf248 f9cde411 f9b7d000 f29bf2b0 f9ba0060 VIDEOPRT!VideoPortReadRegisterUlong+0x27
00000002 00000000 00000000 00000000 00000000 glintMP+0x1411 [No function listed.]
The wrong build symbols were loaded for this stack trace. Notice how there are no functions listed for the first two calls. This stack trace looks like a problem with win32k.sys
drawing rectangles:
1: kd>
1: kd> kb
[Local
9:50 AM]
Loading symbols for 0xf22b0000
agpcpq.sys ->
agpcpq.sys
*** WARNING: symbols checksum is wrong 0x0000735a 0x00000000 for agpcpq.sys
*** ERROR: Symbols could not be loaded for agpcpq.sys
Loading symbols for 0xa0000000
win32k.sys ->
win32k.sys
*** WARNING: symbols checksum is wrong 0x00191a41 0x001995a9 for win32k.sys
ChildEBP RetAddr Args to Child
be682b18 f22b372b 82707128 f21c1ffc 826a70f8 agpCPQ+0x125b [No function listed.]
be682b4c a0140dd4 826a72f0 e11410a8 a0139605 agpCPQ+0x372b [No function listed.]
be682b80 a00f5646 e1145100 e1cee560 e1cee560 win32k!vPatCpyRect1_6x6+0x20b
00000001 00000000 00000000 00000000 00000000 win32k!RemoteRedrawRectangle+0x32
Here's the correct stack trace. The problem is really with AGP440.sys. The first item appearing on a stack trace is usually at fault. Notice that the win32k.sys rectangle error is
gone:
1: kd> kb
ChildEBP RetAddr
be682b18 f22b372b
be682b30 f20a385c
be682b4c a0140dd4
be682b58 a0139605
be682b64 a00e5f0a
be682b80 a00f5646
be682b9c a00f5c20
be682bac a00da510
be682bc4 a00da787
be682bec a00d59fb

[Local
Args to Child
82707128 f21c1ffc 826a70f8
82703638 e183ec68 00000000
826a72f0 e11410a8 a0139605
e1cee560 e11410a8 a00e5f0a
e1cee560 e11410a8 e1cee560
e1145100 e1cee560 e1cee560
e1cee008 e1cee008 be682c0c
e1cee008 00000000 be682c0c
00000000 e1843df8 e1843de8
00000000 e1843de8 00000000

9:49 AM]
agpCPQ!AgpReleaseMemory+0x88
agpCPQ!AgpInterfaceReleaseMemory+0x8b
VIDEOPRT!AgpReleasePhysical+0x44
win32k!OsAGPFree+0x14
win32k!AGPFree+0xd
win32k!HeapVidMemFini+0x49
win32k!vDdDisableDriver+0x3a
win32k!vDdDisableDirectDraw+0x2d
win32k!PDEVOBJ__vDisableSurface+0x27
win32k!PDEVOBJ__vUnreferencePdev+0x204

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

be682c04
be682ce0
be682d20
be682d48
be682d48

a00d7421
a00a9e7f
a008b543
8045d119
77e63660

Page 190 of 1651

e1cee008
e1843e10
00000000
00000000
00000000

82566a98
e184a008
00000000
00000000
00000000

00000001
00000000
00000000
00000000
00000000

win32k!DrvDestroyMDEV+0x30
win32k!DrvChangeDisplaySettings+0x8b3
win32k!xxxUserChangeDisplaySettings+0x106
win32k!NtUserChangeDisplaySettings+0x48
ntkrnlmp!KiSystemService+0xc9

Useful Commands and Extensions

The following commands and extensions may be useful in tracking down symbol problems:
lm (List Loaded Modules)
Lists all modules and gives the loading status of all symbols in these modules.
!dh image-header-base
Displays header information for a loaded image beginning at image-header-base.
.reload /n
Reloads all kernel symbols.
.reload [image-name]
(CDB or WinDbg only) Reloads symbols for the image image-name. If no image-name is specified, reloads symbols for all images. (It is necessary to reload symbols
after the symbol path has been changed.)
!sym noisy
Turns on verbose mode for symbol loads. This can be used to get information about the module loads. See Setting Symbol Options for details.
.sympath [new-symbol-path]
Sets a new symbol path, or displays the current symbol path. See Symbol Path for details.
If the kernel symbols are correct, but you aren't getting a complete stack, the following commands may also be useful:
X *!
This will list the modules which currently have symbols loaded. This is useful if the kernel symbols are correct.
.reload /user
This will attempt to reload all user-mode symbols. This is needed while performing kernel debugging if symbols were loaded while one process was running, and a break
later occurred in another process. In this case, the user-mode symbols from the new process will not be loaded unless this command is executed.
X wdmaud!*start*
This will list only the symbols in the wdmaud module whose names contain the "start" string. This has the advantage that it forces the reloading of all the symbols in
wdmaud, but only displays those with "start" in them. (This means a shorter listing, but since there are always some symbols with "start" in them, there will be some
verification that the load has taken place.)
One other useful technique for verifying symbols is unassembling code. Most functions begin with an add, sub, or push operation using either the base pointer (ebp) or the
stack pointer (esp or sp). Try unassembling (U Function) some of the functions on the stack (from offset zero) to verify the symbols.
Network and Port Problems
Problems will occur with the symbol files and while connecting to the debugger. Here are a few things to keep in mind if you encounter problems:

Determine which COM port the debug cable is connected to on the test system.
Check the boot.ini settings of the test system. Look for the /debug switch and check the baud rate and COM port settings.
Network problems can interfere with debugging if the symbols files are accessed through the network.
.dll and .sys files with the same name (for example mga64.sys and mga64.dll) will confuse the debugger if they aren't separated into the proper directories of the
symbol tree.
The kernel debugger doesn't always like replacing the build symbol files with private symbol files. Double check the symbol path and do a .reload FileName on the
misbehaving symbol. The !dlls command is sometimes useful.

Questions and Misconceptions

Q: I've successfully loaded symbols, but the stack seems to be wrong. Is the debugger broken?
A: Not necessarily. The most likely cause of your problem is that you've got incorrect symbols. Go through the steps outlined in this section to determine whether you've
loaded valid symbols or not. Do not assume that because some things work you have valid symbols. For example, you very well may be able to execute dd nt!
ntbuildnumber or u nt!KeInitializeProcess with incorrect symbols. Verify that they are correct using the procedures outlined above.
Q: Will the debugger still work with incorrect symbols?
A: Yes and no. Often you can get away with symbols that don't strictly match. For example, symbols from a previous Windows build will often work in certain cases, but
there is no rule as to when this will work and when it will not.
Q: I'm stopped in the kernel debugger and I want to view symbols for my user-mode process. Can I do it?
A: Mostly. The support for this scenario is poor because the kernel debugger doesn't keep enough information around to track the module loads for each process, but there's a
reasonable workaround. To load symbols for a user-mode module, execute a .reload -user command. This will load the user-mode modules for the current context.
Q: What does the following message mean?
*** WARNING: symbols checksum and timestamp is wrong 0x0036d6bf 0x0036ab55 for ntkrnlmp.exe
A: It means your symbols for ntkrnlmp.exe are wrong.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 191 of 1651

Matching Symbol Names

In certain situations, the actual name of a symbol is replaced with an alternative form which can then result in symbol matching problems. This most commonly happens when
changing between public and private symbols or when using MS-DOS compatability 8.3 short names for files.
Public vs. Private Symbol Matching
Switching between public symbols and private symbols can sometimes cause symbol matching problems. Typically, a public symbol and the corresponding private symbol
have the same name with different symbol decorations. But in some cases, they may have entirely different names. In such cases, you might have to explicitly reference both
names. For example, you could set up two breakpoints: one on the public symbol, and a second one on the private symbol. For more details, see Public and Private Symbols.
MS-DOS Compatability 8.3 Short Name Symbol Matching
Files that have very long names are sometimes given auto-generated MS-DOS compatibility 8.3 short names. Depending on the tools and options used for creating symbol
files and for debugging, the file name stored in the image's debug record can be either the long name or one of these short names. If the short names is used, this can cause
symbol matching problems because the short name assigned is system dependent.
For example, suppose there are two files, Longfilename1.pdb and Longfilename2.pdb. If they are put in the same directory one will have an MS-DOS compatability 8.3 name
of Longfi~1.pdb and the other will be Longfi~2.pdb. If they are not put in the same directory they will both be Longfi~1.pdb. Thus, if the associated .pdb files are copied
carelessly, the short filenames can change, causing symbol matching problems. For more details, see File System References and Symbol Files.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading Symbols from Paged-Out Headers

The kernel debugger must read the header for each loaded module's image in order to know which symbols correspond to that module.
If a module's header is paged out to disk, the debugger will not load symbols for this module. If this happens with a module that is essential to the debugging process, it can be
a critical problem.
The following procedure can be used to solve this problem.
To acquire symbols for paged-out headers
1.
2.
3.
4.

Make a second copy of the kernel itself. It is probably easiest to put this on a network share.
Append the root directory of this share to the symbol path. See Symbol Path for the ways to change the symbol path.
Use the .reload (Reload Module) command.
Use the !sym noisy extension command to see more verbose output. If this is used, you will be able to see which symbols are loaded from the module images on the
target computer, and which are loaded from the copy of the kernel modules.

This technique must be used with care, since the debugger has no way of verifying whether the file copies actually match the originals. So it is crucial that the version of
Windows used on the network share matches the version used on the target computer.
This technique is only used for kernel-mode debugging. The operating system is capable of paging in any headers required during user-mode debugging (unless the disk
holding the paging file is dismounted or otherwise inaccessible).
Here is an example of this technique being used:
kd> .reload
Connected to Windows XP 2268 x86 compatible target, ptr64 FALSE
Loading Kernel Symbols
..........Unable to read image header for dmload.sys at fe0be000 - NTSTATUS 0xC0000001
..........Unable to read image header for dmboot.sys at fda93000 - NTSTATUS 0xC0000001
.....................................Unable to read image header for fdc.sys at fdfc2000 - NTSTATUS 0xC0000001
...Unable to read image header for flpydisk.sys at fde4a000 - NTSTATUS 0xC0000001
.Unable to read image header for Fs_Rec.SYS at fe0c8000 - NTSTATUS 0xC0000001
.Unable to read image header for Null.SYS at fe2c4000 - NTSTATUS 0xC0000001
...................Unable to read image header for win32k.sys at a0000000 - NTSTATUS 0xC0000001
..Unable to read image header for dxg.sys at a0194000 - NTSTATUS 0xC0000001
.......Unable to read image header for ati2draa.dll at a01a4000 - NTSTATUS 0xC0000001
..Unable to read image header for ParVdm.SYS at fe116000 - NTSTATUS 0xC0000001
.......
Loading unloaded module list
..............
Loading User Symbols
Unable to retrieve the PEB address. This is usually caused
by being in the wrong process context or by paging
Notice that many images have inaccessible headers. Check the symbols from one of these files (in this example, fs_rec.sys):
kd> x fs_rec!*
*** ERROR: Module load completed but symbols could not be loaded for fs_rec.sys
These headers are apparently paged out. So you need to add the proper images to the symbol path:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 192 of 1651

kd> .sympath+ \\myserver\myshare\symbols\x86fre\symbols

Symbol search path is: symsrv*symsrv.dll*c:\localcache*http://msdl.microsoft.com/download/symbols;\\myserver\myshare\symbols\x86f
kd> .reload
Connected to Windows XP 2268 x86 compatible target, ptr64 FALSE
Loading Kernel Symbols
..........Unable to read image header for dmload.sys at fe0be000 - NTSTATUS 0xC0000001
..........Unable to read image header for dmboot.sys at fda93000 - NTSTATUS 0xC0000001
.....................................Unable to read image header for fdc.sys at fdfc2000 - NTSTATUS 0xC0000001
...Unable to read image header for flpydisk.sys at fde4a000 - NTSTATUS 0xC0000001
.Unable to read image header for Fs_Rec.SYS at fe0c8000 - NTSTATUS 0xC0000001
.Unable to read image header for Null.SYS at fe2c4000 - NTSTATUS 0xC0000001
...................Unable to read image header for win32k.sys at a0000000 - NTSTATUS 0xC0000001
..Unable to read image header for dxg.sys at a0194000 - NTSTATUS 0xC0000001
.......Unable to read image header for ati2draa.dll at a01a4000 - NTSTATUS 0xC0000001
..Unable to read image header for ParVdm.SYS at fe116000 - NTSTATUS 0xC0000001
.......
Loading unloaded module list
..............
Loading User Symbols
Unable to retrieve the PEB address. This is usually caused
by being in the wrong process context or by paging
The same warnings have appeared, but the symbols themselves are now accessible:
kd> x fs_Rec!*
fe0c8358 Fs_Rec!_imp___allmul
fe0c8310 Fs_Rec!_imp__IoCreateDevice
fe0c835c Fs_Rec!_imp___allshr
........
fe0c8360 Fs_Rec! ntoskrnl_NULL_THUNK_DATA
fe0c832c Fs_Rec!_imp__KeSetEvent
fe0c9570 Fs_Rec!_NULL_IMPORT_DESCRIPTOR

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Mapping Symbols When the PEB is Paged Out

To load symbols, the debugger looks at the list of modules loaded by the operating system. The pointer to the user-mode module list is one of the items stored in the process
environment block (PEB).
In order to reclaim memory, the Memory Manager may page out user-mode data to make space for other process or kernel mode components. The user-mode data that is
paged out may include the PEB data structure. Without this data structure, the debugger cannot determine for which images to load symbols.
Note This affects symbol files only for the user-mode modules. Kernel-mode modules and symbols are not affected, as they are tracked in a different list.
The following examples demonstrates how to use the !vad extension to map symbols when the PEB is paged out. The basic idea is to find the starting address and size of the
relevant DLL so that you can then use the .reload command to load the necessary symbols.
Suppose that the address of the current process is 0xE0000126`01BA0AF0 and you want to fix the symbols for it. First, use the !process command to obtain the virtual
address descriptor (VAD) root address:
kd> !process e000012601ba0af0 1
PROCESS e000012601ba0af0
SessionId: 2 Cid: 0b50
Peb: 6fbfffde000 ParentCid: 0efc
DirBase: 079e8461 ObjectTable: e000000600fbceb0 HandleCount: 360.
Image: explorer.exe
VadRoot e000012601a35e70 Vads 201 Clone 0 Private 917. Modified 2198. Locked 0.

Then use the !vad extension to list the VAD tree associated with the process. Those VADs labelled "EXECUTE_WRITECOPY" belong to DLLs.
kd> !vad e000012601a35e70
VAD
level
start
end
commit

e0000126019f9790 ( 6)
3fff0
3fff7
e000012601be1080 ( 7)
37d9bd30 37d9bd3e
e000012600acd970 ( 5)
37d9bec0 37d9bece
e000012601a5cba0 ( 7)
37d9c910 37d9c924

-1
2
2
2

Private
Mapped Exe
Mapped Exe
Mapped Exe

READONLY
EXECUTE_WRITECOPY
EXECUTE_WRITECOPY
EXECUTE_WRITECOPY

<-- these are DLLs

Then use the !vad extension again to find the starting address and size of the paged out memory which holds the DLL of interest. This confirms that you have found the
correct DLL:
kd> !vad e000012601be1080 1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

VAD @ e000012601be1080
Start VPN:
37d9bd30 End VPN: 37d9bd3e Control Area: e00001260197b8d0
First ProtoPte: e0000006013e00a0 Last PTE fffffffffffffffc Commit Charge
Secured.Flink
0 Blink
0 Banked/Extend:
0
File Offset
0
ImageMap ViewShare EXECUTE_WRITECOPY

Page 193 of 1651

2 (2.)

File: \Windows\System32\ExplorerFrame.dll
The "Start VPN" field in this case, 0x37D9BD30 indicates the starting virtual page number. This must be converted to an actual address, by multiplying it by the page
size. You can use the ? (Evaluate Expression) command to multiply this value by 0x2000, which is the page size for the Itanium-based machine the example comes from.
kd> ? 37d9bd3e*2000
Evaluate expression: 7676040298496 = 000006fb`37a7c000
Then the size of the range can be converted to bytes:
kd> ? 37d9bd3e-37d9bd30+1
<-computes the number of pages
Evaluate expression: 15 = 00000000`0000000f
kd> ? f*2000
Evaluate expression: 122880 = 00000000`0001e000
So ExplorerFrame.dll starts at address 0x000006Fb`37A7C000 and is 0x1E000 bytes large. You can load its symbols with:
kd> .reload /f ExplorerFrame.dll=6fb`37a7c000,1e000

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging User-Mode Processes Without Symbols

It is important to have symbols on the faulting machine before starting the debugger for a user-mode failure. However, sometimes the debugger is started without symbols. If
the problem is easily reproducible, you can just copy symbols and rerun. If, however, the problem may not occur again, some information can still be gleaned from the failure:
1. To figure out what the addresses mean, you'll need a computer which matches the one with the error. It should have the same platform (x86, Intel Itanium, or x64) and
be loaded with the same version of Windows.
2. When you have the computer configured, copy the user-mode symbols and the binaries you want to debug onto the new machine.
3. Start CDB or WinDbg on the symbol-less machine.
4. If you don't know which application failed on the symbol-less machine, issue an | (Process Status) command. If that doesn't give you a name, break into KD on the
symbol-less machine and do a !process 0 0, looking for the process ID given by the CDB command.
5. When you have the two debuggers set up one with symbols which hasn't hit the error, and one which has hit the error but is without symbols issue a k (Display
Stack Backtrace) command on the symbol-less machine.
6. On the machine with symbols, issue a u (Unassemble) command for each address given on the symbol-less stack. This will give you the stack trace for the error on the
symbol-less machine.
7. By looking at a stack trace you can see the module and function names involved in the call.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Performance-Optimized Code

Microsoft has certain techniques that it uses to re-arrange compiled and linked code so that it executes with more efficiency. These techniques optimize the component for
memory hierarchies, and are based on training scenarios.
The resulting optimization reduces paging (and page faults), and increases spatial locality between code and data. It addresses a key performance bottleneck that would be
introduced by poor positioning of the original code. A component that has gone through this optimization may have its code or data block within a function moved to different
locations of the binary.
In modules that have been optimized by these techniques, the locations of code and data blocks will often be found at memory addresses different than the locations where
they would reside after normal compilation and linking. Furthermore, functions may have been split into many non-contiguous blocks, in order that the most commonly-used
code paths can be located close to each other on the same pages.
Therefore, a function (or any symbol) plus an offset will not necessarily have the same meaning it would have in non-optimized code.
Debugging Performance-Optimized Code
When debugging, you can see if a module has been performance-optimized by using the !lmi extension command on any module for which symbols have been loaded:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 194 of 1651

0:000> !lmi ntdll

Loaded Module Info: [ntdll]
Module: ntdll
Base Address: 77f80000
Image Name: ntdll.dll
Machine Type: 332 (I386)
Time Stamp: 394193d2 Fri Jun 09 18:03:14 2000
CheckSum: 861b1
Characteristics: 230e stripped perf
Debug Data Dirs: Type Size
VA Pointer
MISC 110,
0,
76c00 [Data not mapped]
Image Type: DBG
- Image read successfully from symbol server.
c:\symbols\dll\ntdll.dbg
Symbol Type: DIA PDB - Symbols loaded successfully from symbol server.
c:\symbols\dll\ntdll.pdb
In this output, notice the term perf on the "Characteristics" line. This indicates that this performance optimization has been applied to ntdll.dll.
The debugger is able to understand a function or other symbol without an offset; this allows you to set breakpoints on functions or other labels without any problem. However,
the output of a dissassembly operation may be confusing, because this disassembly will reflect the changes made by the optimizer.
Since the debugger will try to stay close to the original code, you might see some amusing results. The rule of thumb when working with performance-optimized codes is
simply that you cannot perform reliable address arithmetic on optimized code.
Here is an example:
kd> bl
0 e f8640ca6
1 e f8672660

0001 (0001) tcpip!IPTransmit

0001 (0001) tcpip!IPFragment

kd> u f864b4cb
tcpip!IPTransmit+e48:
f864b4cb f3a4
f864b4cd 8b75cc
f864b4d0 8b4d10
f864b4d3 8b7da4
f864b4d6 8bc6
f864b4d8 6a10
f864b4da 034114
f864b4dd 57

rep
mov
mov
mov
mov
push
add
push

movsb
esi,[ebp-0x34]
ecx,[ebp+0x10]
edi,[ebp-0x5c]
eax,esi
0x10
eax,[ecx+0x14]
edi

You can see from the breakpoint list that the address of IPTransmit is 0xF8640CA6.
When you unassemble a section of code within this function at 0xF864B4CB, the output indicates that this is 0xE48 bytes past the beginning of the function. However, if you
subtract the base of the function from this address, the actual offset appears to be 0xA825.
What is happening is this: The debugger is indeed showing a disassembly of the binary instructions beginning at 0xF864B4CB. But instead of computing the offset by simple
subtraction, the debugger displays as best it can the offset to the function entry as it existed in the original code before the optimizations were performed. That value is
0xE48.
On the other hand, if you try to look at IPTransmit+0xE48, you will see this:
kd> u tcpip!iptransmit+e48
tcpip!ARPTransmit+d8:
f8641aee 0856ff
or
f8641af1 75fc
jnz
f8641af3 57
push
f8641af4 e828eeffff
call
f8641af9 5f
pop
f8641afa 5e
pop
f8641afb 5b
pop
f8641afc c9
leave

[esi-0x1],dl
tcpip!ARPTransmit+0xd9 (f8641aef)
edi
tcpip!ARPSendData (f8640921)
edi
esi
ebx

What is happening here is that the debugger recognizes the symbol IPTransmit as equivalent to the address 0xF8640CA6, and the command parser performs a simple
addition to find that 0xF8640CA6 + 0xE48 = 0xF8641AEE. This address is then used as the argument for the u (Unassemble) command. But once this location is analyzed,
the debugger discovers that this is not IPTransmit plus an offset of 0xE48. Indeed, it is not part of this function at all. Rather, it corresponds to the function ARPTransmit
plus an offset of 0xD8.
The reason this happens is that performance optimization is not reversible through address arithmetic. While the debugger can take an address and deduce its original symbol
and offset, it does not have enough information to take a symbol and offset and translate it to the correct address. Consequently, disassembly is not useful in these cases.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Crash Dump Files

This section includes:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 195 of 1651

Kernel-Mode Dump Files

User-Mode Dump Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel-Mode Dump Files

When a kernel-mode error occurs, the default behavior of Microsoft Windows is to display the blue screen with bug check data.
However, there are several alternative behaviors that can be selected:

A kernel debugger (such as WinDbg or KD) can be contacted.

A memory dump file can be written.
The system can automatically reboot.
A memory dump file can be written, and the system can automatically reboot afterwards.

This section covers how to create and analyze a kernel-mode memory dump file. There are three different varieties of crash dump files. However, it should be remembered
that no dump file can ever be as useful and versatile as a live kernel debugger attached to the system that has failed.
This section includes:
Varieties of Kernel-Mode Dump Files
Creating a Kernel-Mode Dump File
Analyzing a Kernel-Mode Dump File
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Varieties of Kernel-Mode Dump Files

There are three kinds of kernel-mode crash dump files:
Complete Memory Dump
Kernel Memory Dump
Small Memory Dump
The difference between these dump files is one of size. The Complete Memory Dump is the largest and contains the most information, the Kernel Memory Dump is somewhat
smaller, and the Small Memory Dump is only 64 KB in size.
The advantage to the larger files is that, since they contain more information, they are more likely to help you find the cause of the crash.
The advantage of the smaller files is that they are smaller and written more quickly. Speed is often valuable; if you are running a server, you may want the server to reboot as
quickly as possible after a crash, and the reboot will not take place until the dump file has been written.
After a Complete Memory Dump or Kernel Memory Dump has been created, it is possible to create a Small Memory Dump file from the larger dump file. See
the .dump (Create Dump File) command for details.
Note Much information can be obtained by analyzing a kernel-mode dump file. However, no kernel-mode dump file can provide as much information as actually debugging
the crash directly with a kernel debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Complete Memory Dump

A Complete Memory Dump is the largest kernel-mode dump file. This file contains all the physical memory for the machine at the time of the fault.
This dump file requires a pagefile on your boot drive that is at least as large as your main system memory; it should be able to hold a file whose size equals your entire RAM
plus one megabyte.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 196 of 1651

The Complete Memory Dump file is written to %SystemRoot%\Memory.dmp by default.

If a second bug check occurs and another Complete Memory Dump (or Kernel Memory Dump) is created, the previous file will be overwritten.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel Memory Dump

A Kernel Memory Dump contains all the memory in use by the kernel at the time of the crash.
This kind of dump file is significantly smaller than the Complete Memory Dump. Typically, the dump file will be around one-third the size of the physical memory on the
system. Of course, this quantity will vary considerably, depending on your circumstances.
This dump file will not include unallocated memory, or any memory allocated to user-mode applications. It only includes memory allocated to the Windows kernel and
hardware abstraction level (HAL), as well as memory allocated to kernel-mode drivers and other kernel-mode programs.
For most purposes, this crash dump is the most useful. It is significantly smaller than the Complete Memory Dump, but it only omits those portions of memory that are
unlikely to have been involved in the crash.
Since this kind of dump file does not contain images of any user-mode executables residing in memory at the time of the crash, you may also need to set the executable image
path if these executables turn out to be important.
The Kernel Memory Dump file is written to %SystemRoot%\Memory.dmp by default.
If a second bug check occurs and another Kernel Memory Dump (or Complete Memory Dump) is created, the previous file will be overwritten.
To suppress missing page error messages when debugging a Kernel Memory Dump, use the .ignore_missing_pages command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Small Memory Dump

A Small Memory Dump is much smaller than the other two kinds of kernel-mode crash dump files. It is exactly 64 KB in size, and requires only 64 KB of pagefile space on
the boot drive.
This dump file includes the following:

The bug check message and parameters, as well as other blue-screen data.
The processor context (PRCB) for the processor that crashed.
The process information and kernel context (EPROCESS) for the process that crashed.
The thread information and kernel context (ETHREAD) for the thread that crashed.
The kernel-mode call stack for the thread that crashed. If this is longer than 16 KB, only the topmost 16 KB will be included.
A list of loaded drivers.

In Windows XP and later versions of Windows, the following items are also included:

A list of loaded modules and unloaded modules.

The debugger data block. This contains basic debugging information about the system.
Any additional memory pages that Windows identifies as being useful in debugging failures. This includes the data pages that the registers were pointing to when the
crash occurred, and other pages specifically requested by the faulting component.
(Intel Itanium processor only) The backing store.
(Windows Server 2003 and later) The Windows SKU for example, "Professional" or "Server".

This kind of dump file can be useful when space is greatly limited. However, due to the limited amount of information included, errors that were not directly caused by the
thread executing at time of crash may not be discovered by an analysis of this file.
Since this kind of dump file does not contain images of any executables residing in memory at the time of the crash, you may also need to set the executable image path if
these executables turn out to be important.
If a second bug check occurs and a second Small Memory Dump file is created, the previous file will be preserved. Each additional file will be given a distinct name, which
contains the date of the crash encoded in the filename. For example, mini022900-01.dmp is the first memory dump file generated on February 29, 2000. A list of all Small
Memory Dump files is kept in the directory %SystemRoot%\Minidump.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 197 of 1651

Debugging Tools for Windows

Creating a Kernel-Mode Dump File

There are three ways in which a kernel-mode dump file can be created:
1. You can enable the dump file from the Control Panel, and then the system can crash on its own.
2. You can enable the dump file from the Control Panel, and then force the system to crash.
3. You can use the debugger to create a dump file without crashing the system.
This section includes:
Enabling a Kernel-Mode Dump File
Forcing a System Crash
Creating a Dump File Without a System Crash
Verifying the Creation of a Kernel-Mode Dump File
Using an NMI Switch
It is also possible to use an NMI switch to create a crash dump file. Contact your hardware vendor to determine whether your machine has this switch.
The usage of NMI switches is not covered in this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enabling a Kernel-Mode Dump File

During a system crash, the Windows crash dump settings determine whether a dump file will be created, and if so, what size the dump file will be.
The Windows Control Panel controls the kernel-mode crash dump settings. Only a system administrator can modify these settings.
To change these settings, go to Control Panel and click on the System icon. Select the Advanced panel. In Windows 2000, click on Startup and Recovery. In Windows XP
and later versions of Windows, click on the Settings button in the Startup and Recovery section.
You will see the following dialog box:

Control Panel: Startup and Recovery Dialog Box

Under Write Debugging Information, you can select which of the three sizes of dump files you wish to have as the default. Only one dump file can be created for any given
crash. The default crash dump size is Small Memory Dump. See Varieties of Kernel-Mode Dump Files for a description of the three file types.
After selecting the dump file size, you can accept or change the default dump file path and file name.
You can also select or deselect any of the Write an event to the system log, Send an administrative alert, and Automatically reboot options.
If you make any changes, the system will reboot after you click OK.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 198 of 1651

The settings that you select will apply to any kernel-mode dump file created by a system crash, regardless of whether the system crash was accidental or whether it was caused
by the debugger. See Forcing a System Crash for details on causing a deliberate crash.
However, these settings do not affect dump files created by the .dump command. See Creating a Dump File Without a System Crash for details on using this command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Forcing a System Crash

Once kernel-mode dump files have been enabled, most system crashes should cause a crash file to be written and the blue screen to be displayed.
However, there are times that a system freezes without actually initiating a kernel crash. Possible symptoms of such a freeze include:

The mouse pointer moves, but can't do anything.

All video is frozen, the mouse pointer does not move, but paging continues.
There is no response at all to the mouse or keyboard, and no use of the disk.

If an experienced debugging technician is present, he or she can hook up a kernel debugger and analyze the problem. For some tips on what to look for when this situation
occurs, see Debugging a Stalled System.
However, if no technician is present, you may wish to create a kernel-mode dump file and send it to an off-site technician. This dump file can be used to analyze the cause of
the error.
There are two ways to deliberately cause a system crash:
Forcing a System Crash from the Debugger
Forcing a System Crash from the Keyboard
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Forcing a System Crash from the Debugger

If KD or WinDbg is performing kernel-mode debugging, it can force a system crash to occur. This is done by entering the .crash (Force System Crash) command at the
command prompt. (If the target computer does not crash immediately, follow this with the g (Go) command.)
When this command is issued, the system will call KeBugCheck and issue bug check 0xE2 (MANUALLY_INITIATED_CRASH). Unless crash dumps have been disabled,
a crash dump file is written at this point.
After the crash dump file has been written, the kernel debugger on the host computer will be alerted and can be used to actively debug the crashed target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Forcing a System Crash from the Keyboard

Most of the following keyboards can cause a system crash directly:
PS/2 keyboards connected on i8042prt ports
This feature is available in Windows 2000 and later versions of Windows operating system.
USB keyboards
This feature is available in:
Windows Server 2003 Service Pack 1 if the hotfix available with
KB 244139 is installed.
Windows Server 2003 (with Service Pack 2 or later).
Windows 7 and later versions of Windows operating system.
You must ensure the following three settings before the keyboard can cause a system crash:
1. If you wish a crash dump file to be written, you must enable such dump files, choose the path and file name, and select the size of the dump file. For more information,
see Enabling a Kernel-Mode Dump File.
2. With PS/2 keyboards, you must enable the keyboard-initiated crash in the registry. In the registry key
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters, create a value named CrashOnCtrlScroll, and set it equal to a
REG_DWORD value of 0x01.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 199 of 1651

3. With USB keyboards, you must enable the keyboard-initiated crash in the registry. In the registry key
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\kbdhid\Parameters, create a value named CrashOnCtrlScroll, and set it equal to a
REG_DWORD value of 0x01.
You must restart the system for these settings to take effect.
After this is completed, the keyboard crash can be initiated by using the following hotkey sequence: Hold down the rightmost CTRL key, and press the SCROLL LOCK key
twice.
The system then calls KeBugCheck and issues bug check 0xE2 (MANUALLY_INITIATED_CRASH). Unless crash dumps have been disabled, a crash dump file is written
at this point.
If a kernel debugger is attached to the crashed machine, the machine will break into the kernel debugger after the crash dump file has been written.
For more information on using this feature, refer to the article

Generate a memory dump file by using the keyboard (KB 244139).

Defining Alternate Keyboard Shortcuts to Force a System Crash from the Keyboard
You can configure values under the following registry subkeys for different keyboard shortcut sequences to generate the memory dump file:

For PS/2 keyboards:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\i8042prt\crashdump

For USB keyboards:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\kbdhid\crashdump

You must create the following registry REG_DWORD values under these subkeys:
Dump1Keys
The Dump1Keys registry value is a bit map of the first hot key to use. For example, instead of using the rightmost CTRL key to initiate the hot key sequence, you can set
the first hot key to be the leftmost SHIFT key.
The values for the first hot key are described in the following table.
Value First key used in the keyboard shortcut sequence
0x01 Rightmost SHIFT key
0x02 Rightmost CTRL key
0x04 Rightmost ALT key
0x10 Leftmost SHIFT key
0x20 Leftmost CTRL key
0x40 Leftmost ALT key
Note You can assign Dump1Keys a value that enables one or more keys as the first key used in the keyboard shortcut sequence. For example, assign Dump1Keys a
value of 0x11 to define both the rightmost and leftmost SHIFT keys as the first key in the keyboard shortcut sequence.
Dump2Key
The Dump2Key registry value is the index into the scancode table for the keyboard layout of the target computer. The following is the actual table in the driver.
const UCHAR keyToScanTbl[134] = {
0x00,0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,
0x0A,0x0B,0x0C,0x0D,0x7D,0x0E,0x0F,0x10,0x11,0x12,
0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B,0x00,
0x3A,0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,
0x27,0x28,0x2B,0x1C,0x2A,0x00,0x2C,0x2D,0x2E,0x2F,
0x30,0x31,0x32,0x33,0x34,0x35,0x73,0x36,0x1D,0x00,
0x38,0x39,0xB8,0x00,0x9D,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0xD2,0xD3,0x00,0x00,0xCB,
0xC7,0xCF,0x00,0xC8,0xD0,0xC9,0xD1,0x00,0x00,0xCD,
0x45,0x47,0x4B,0x4F,0x00,0xB5,0x48,0x4C,0x50,0x52,
0x37,0x49,0x4D,0x51,0x53,0x4A,0x4E,0x00,0x9C,0x00,
0x01,0x00,0x3B,0x3C,0x3D,0x3E,0x3F,0x40,0x41,0x42,
0x43,0x44,0x57,0x58,0x00,0x46,0x00,0x00,0x00,0x00,
0x00,0x7B,0x79,0x70 };
Note Index 124 (sysreq) is a special case because an 84-key keyboard has a different scan code.
If you define alternate keyboard shortcuts to force a system crash from a USB or PS/2 keyboard, you must either set the CrashOnCtrlScroll registry value to 0 or remove it
from the registry.
Limitations
It is possible for a system to freeze in such a way that the keyboard shortcut sequence will not work. However, this should be a very rare occurrence. Using the keyboard
shortcut sequence to initiate a crash will work even in many instances where CTRL+ALT+DELETE does not work.
Forcing a system crash from the keyboard does not work if the computer stops responding at a high interrupt request level (IRQL). This limitation exists because the
Kbdhid.sys driver, which allows the memory dump process to run, operates at a lower IRQL than the i8042prt.sys driver.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 200 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Creating a Dump File Without a System Crash

If KD or WinDbg is performing kernel-mode debugging, it can cause a kernel-mode dump file to be written without crashing the target computer.
This dump file can be either a Complete Memory Dump or a Small Memory Dump. The Control Panel settings are not relevant to this action.
Whereas dump files caused by a system crash are written to the computer that has crashed, this dump file will be written to the host computer.
For details, see the .dump (Create Dump File) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Verifying the Creation of a Kernel-Mode Dump File

If you have a machine that has broken into the debugger, but you are unsure whether the crash dump file was successfully written, execute the following command:
dd nt!IopFinalCrashDumpStatus L1
This displays the value of the IopFinalCrashDumpStatus variable.
If this value equals zero, the process was successful. If it equals -1 (0xFFFFFFFF), the dump process has not started.
Any other value is a status code indicating an error during the dump process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Kernel-Mode Dump File

This section includes:
Analyzing a Kernel-Mode Dump File with KD
Analyzing a Kernel-Mode Dump File with WinDbg
Analyzing a Kernel-Mode Dump File with KAnalyze
Installing Symbol Files
Regardless of which tool you use, you need to install the symbol files for the version of Windows that generated the dump file. These files will be used by the debugger you
choose to use to analyze the dump file. For more information about the proper installation of symbol files, see Installing Windows Symbol Files.

DumpExam
The DumpExam tool is obsolete. It is no longer needed in the analysis of a crash dump file.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Kernel-Mode Dump File with KD

Kernel-mode memory dump files can be analyzed by KD. The processor or Windows version that the dump file was created on does not need to match the platform on which
KD is being run.
Starting KD
To analyze a dump file, start KD with the -z command-line option:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 201 of 1651

kd -y SymbolPath -i ImagePath -z DumpFileName

The -v option (verbose mode) is also useful. For a full list of options, see KD Command-Line Options.
You can also open a dump file after the debugger is running by using the .opendump (Open Dump File) command, followed with g (Go).
It is possible to debug multiple dump files at the same time. This can be done by including multiple -z switches on the command line (each followed by a different file name),
or by using .opendump to add additional dump files as debugger targets. For information about how to control a multiple-target session, see Debugging Multiple Targets.
Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file.
It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the -z option or as the argument to
an .opendump command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will
only be able to read one of them. The debugger will not read any additional files from the CAB, even if they were symbol files or other files associated with the dump file.
Analyzing the Dump File
If you are analyzing a Kernel Memory Dump or a Small Memory Dump, you may need to set the executable image path to point to any executable files which may have been
loaded in memory at the time of the crash. See Executable Image Path for details.
Analysis of a dump file is similar to analysis of a live debugging session. See the Debugger Commands reference section for details on which commands are available for
debugging dump files in kernel mode.
In most cases, you should begin by using !analyze. This extension command performs automatic analysis of the dump file and can often result in a lot of useful information.
The .bugcheck (Display Bug Check Data) shows the bug check code and its parameters. Look up this bug check in the Bug Check Code Reference for information about the
specific error.
The following debugger extensions are especially useful for analyzing a kernel-mode crash dump:
!drivers
!kdext*.locks
!memusage
!vm
!errlog
!process 0 0
!process 0 7
For techniques that can be used to read specific kinds of information from a dump file, see Extracting Information from a Dump File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Kernel-Mode Dump File with WinDbg

Kernel-mode memory dump files can be analyzed by WinDbg. The processor or Windows version that the dump file was created on does not need to match the platform on
which KD is being run.
Starting WinDbg
To analyze a dump file, start WinDbg with the -z command-line option:
windbg -y SymbolPath -i ImagePath -z DumpFileName
The -v option (verbose mode) is also useful. For a full list of options, see WinDbg Command-Line Options.
If WinDbg is already running and is in dormant mode, you can open a crash dump by selecting the File | Open Crash Dump menu command or pressing the CTRL+D
shortcut key. When the Open Crash Dump dialog box appears, enter the full path and name of the crash dump file in the File name text box, or use the dialog box to select
the proper path and file name. When the proper file has been chosen, click Open.
You can also open a dump file after the debugger is running by using the .opendump (Open Dump File) command, followed with g (Go).
It is possible to debug multiple dump files at the same time. This can be done by including multiple -z switches on the command line (each followed by a different file name),
or by using .opendump to add additional dump files as debugger targets. For information about how to control a multiple-target session, see Debugging Multiple Targets.
Dump files generally end with the extension .dmp or .mdmp. You can use network shares or Universal Naming Convention (UNC) file names for the memory dump file.
It is also common for dump files to be packed into a CAB file. If you specify the file name (including the .cab extension) after the -z option or as the argument to
an .opendump command, the debugger can read the dump files directly out of the CAB. However, if there are multiple dump files stored in a single CAB, the debugger will
only be able to read one of them. The debugger will not read any additional files from the CAB, even if they were symbol files or other files associated with the dump file.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 202 of 1651

Analyzing the Dump File

If you are analyzing a Kernel Memory Dump or a Small Memory Dump, you may need to set the executable image path to point to any executable files that may have been
loaded in memory at the time of the crash. See Executable Image Path for details.
Analysis of a dump file is similar to analysis of a live debugging session. See the Debugger Commands reference section for details on which commands are available for
debugging dump files in kernel mode.
In most cases, you should begin by using !analyze. This extension command performs automatic analysis of the dump file and can often result in a lot of useful information.
The .bugcheck (Display Bug Check Data) shows the bug check code and its parameters. Look up this bug check in the Bug Check Code Reference for information about the
specific error.
The following debugger extensions are especially useful for analyzing a kernel-mode crash dump:
!drivers
!kdext*.locks
!memusage
!vm
!errlog
!process 0 0
!process 0 7
For techniques that can be used to read specific kinds of information from a dump file, see Extracting Information from a Dump File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Kernel-Mode Dump File with KAnalyze

Kernel Memory Space Analyzer (KAnalyze, Kanalyze.exe) is another tool that can examine kernel-mode dump files.
KAnalyze and its documentation are part of the OEM Support Tools package.
To download these tools, go to

Knowledge Base Article Q253066 and follow the instructions on that page.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User-Mode Dump Files

This section includes:
Varieties of User-Mode Dump Files
Creating a User-Mode Dump File
Analyzing a User-Mode Dump File
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Varieties of User-Mode Dump Files

There are several kinds of user-mode crash dump files, but they are divided into two categories:
Full User-Mode Dumps
Minidumps

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 203 of 1651

The difference between these dump files is one of size. Minidumps are usually more compact, and can be easily sent to an analyst.
Note Much information can be obtained by analyzing a dump file. However, no dump file can provide as much information as actually debugging the crash directly with a
debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Full User-Mode Dumps

A full user-mode dump is the basic user-mode dump file.
This dump file includes the entire memory space of a process, the program's executable image itself, the handle table, and other information that will be useful to the
debugger.
It is possible to "shrink" a full user-mode dump file into a minidump. Simply load the dump file into the debugger and then use the .dump (Create Dump File) command to
save a new dump file in minidump format.
Note Despite their names, the largest "minidump" file actually contains more information than the full user-mode dump. For example, .dump /mf or .dump /ma will create a
larger and more complete file than .dump /f.
In user mode, .dump /m[MiniOptions] is the best choice. The dump files created with this switch can vary in size from very small to very large. By specifying the proper
MiniOptions you can control exactly what information is included.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Minidumps
A user-mode dump file that includes only selected parts of the memory associated with a process is called a minidump.
The size and contents of a minidump file vary depending on the program being dumped and the application doing the dumping. Sometimes, a minidump file is fairly large and
includes the full memory and handle table. Other times, it is much smaller for example, it might only contain information about a single thread, or only contain information
about modules that are actually referenced in the stack.
The name "minidump" is misleading, because the largest minidump files actually contain more information than the "full" user-mode dump. For example, .dump /mf
or .dump /ma will create a larger and more complete file than .dump /f. For this reason, .dump /m[MiniOptions] recommended over .dump /f for all user-mode dump file
creation.
If you are creating a minidump file with the debugger, you can choose exactly what information to include. A simple .dump /m command will include basic information
about the loaded modules that make up the target process, thread information, and stack information. This can be modified by using any of the following options:
.dump option
Effect on dump file
/ma
Creates a minidump with all optional additions. The /ma option is equivalent to /mfFhut it adds full memory data, handle data, unloaded module
information, basic memory information, and thread time information to the minidump.
/mf
Adds full memory data to the minidump. All accessible committed pages owned by the target application will be included.
/mF
Adds all basic memory information to the minidump. This adds a stream to the minidump that contains all basic memory information, not just information
about valid memory. This allows the debugger to reconstruct the complete virtual memory layout of the process when the minidump is being debugged.
/mh
Adds data about the handles associated with the target application to the minidump.
/mu
Adds unloaded module information to the minidump. This is only available in Windows Server 2003 and later versions of Windows.
/mt
Adds additional thread information to the minidump. This includes thread times, which can be displayed by using .ttime (Display Thread Times) when
debugging the minidump.
/mi
Adds secondary memory to the minidump. Secondary memory is any memory referenced by a pointer on the stack or backing store, plus a small region
surrounding this address.
/mp
Adds process environment block (PEB) and thread environment block (TEB) data to the minidump. This can be useful if you need access to Windows system
information regarding the application's processes and threads.
/mw
Adds all committed read-write private pages to the minidump.
/md
Adds all read-write data segments within the executable image to the minidump.
/mc
Adds code sections within images.
/mr
Deletes from the minidump those portions of the stack and store memory that are not useful for recreating the stack trace. Local variables and other data type
values are deleted as well. This option does not make the minidump smaller (since these memory sections are simply zeroed), but it is useful if you wish to
protect the privacy of other applications.
/mR
Deletes the full module paths from the minidump. Only the module names will be included. This is a useful option if you wish to protect the privacy of the
user's directory structure.
/mk
(Windows Vista only) Creates a kernel-mode minidump in addition to the user-mode minidump. The kernel-mode minidump will be restricted to the same
"FileName" threads that are stored in the user-mode minidump. FileName must be enclosed in quotation marks.
These options can be combined. For example, the command .dump /mfiu can be used to create a fairly large minidump, or the command .dump /mrR can be used to create a

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 204 of 1651

minidump that preserves the user's privacy. For full syntax details, see .dump (Create Dump File).
For details on the internals of minidump files, see the DbgHelp Reference in the Microsoft Windows SDK.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Creating a User-Mode Dump File

There are five different tools that can be used to create a user-mode dump file: CDB, WinDbg, Dr. Watson, UserDump, and ADPlus.
This section includes:
Choosing the Best Tool
CDB and WinDbg
UserDump
For information about creating a user-mode dump file through ADPlus, see ADPlus.
For information about creating a user-mode dump file through Dr. Watson, see Dr. Watson.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Choosing the Best Tool

There are five different tools that can create user-mode dump files. In most cases, ADPlus is the best tool to use.
The following table shows the features of each tool.
Feature

ADPlus Dr. Watson

Creating a dump file when an application crashes (postmortem debugging)

Yes
Creating a dump file when an application "hangs" (stops responding but does not actually crash) Yes
Creating a dump file when an application encounters an exception
Yes
Creating a dump file while an application is running normally
No
Creating a dump file from an application that fails during startup
No
Shrinking an existing dump file
No

Yes
No
Yes
No
No
No

CDB UserDump
and
WinDbg
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
Yes
No

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CDB and WinDbg

CDB and WinDbg can create user-mode dump files in a variety of ways.
Creating a Dump File Automatically
When an application error occurs, Windows can respond in several different ways, depending on the postmortem debugging settings. If these settings instruct a debugging tool
to create a dump file, a user-mode memory dump file will be created.
The default postmortem setting is for a dump file to be written by Dr. Watson. If you wish to use WinDbg as the postmortem debugger, use the following command to
automatically configure the registry:
windbg -I
If you wish to use CDB as the postmortem debugger, you will have to configure the registry manually. For details, see Enabling Postmortem Debugging.
Creating Dump Files While Debugging

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Security Considerations
This section includes:
Security Vulnerabilities
Secure Mode
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Security Vulnerabilities
This section includes:
Security During Kernel-Mode Debugging
Security During User-Mode Debugging
Security During Postmortem Debugging
Security During Remote Debugging
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Security During Kernel-Mode Debugging

Security during kernel-mode debugging is never about protecting the target computer. The target is completely vulnerable to the debugger this is the very nature of
debugging.
If a debugging connection was enabled during boot (see Configuring Software on the Target Computer), it will remain vulnerable through the debugging port until its next
boot.
However, you should be concerned about security on the host computer. In an ideal situation, the debugger runs as an application on your host computer, but does not interact
with other applications on this computer. There are three possible ways in which security problems could arise:

If you use corrupt or destructive extension DLLs, they could cause your debugger to take unexpected actions, possibly affecting the host computer.
It is possible that corrupt or destructive symbol files could also cause your debugger to take unexpected actions, possibly affecting the host computer.
If you are running a remote debugging session, an unexpected client might attempt to link to your server. Or perhaps the client you are expecting might attempt to
perform actions that you do not anticipate.

If you want to prevent a remote user from performing actions on your host computer, use Secure Mode.
For suggestions on how to guard against unexpected remote connections, see Security During Remote Debugging.
If you are not performing remote debugging, you should still beware of bad symbol files and extension DLLs. Do not load symbols or extensions that you distrust!
Local Kernel Debugging
Only users who have debug privileges can start a local kernel debugging session. If you are the administrator of a machine that has multiple user accounts, you should be
aware that any user with these privileges can start a local kernel debugging session, effectively giving them control of all processes on the computer and therefore giving
them access to all peripherals as well.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 208 of 1651

Security During User-Mode Debugging

When a user-mode debugger is active, it can effectively control any of the processes on the computer.
There are three possible ways in which security problems could arise during user-mode debugging:

If you use corrupt or destructive extension DLLs, they could cause your debugger to take unexpected actions, possibly affecting applications other than your target.
It is possible that corrupt or destructive symbol files could also cause your debugger to take unexpected actions, possibly affecting applications other than your target.
If you are running a remote debugging session, an unexpected client might attempt to link to your server. Or perhaps the client you are expecting might attempt to
perform actions that you do not anticipate.

For suggestions on how to guard against unexpected remote connections, see Security During Remote Debugging. After a remote client has joined a user-mode debugging
session, there is no way to restrict its access to processes on your computer.
If you are not performing remote debugging, you should still beware of bad symbol files and extension DLLs. do not load symbols or extensions that you distrust!
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Security During Postmortem Debugging

Only an administrator can enable postmortem debugging.
However, postmortem debugging is enabled for the entire system, not just for one user. Thus, after it has been enabled, any application crash will activate the debugger that
has been chosen even if the current user does not have administrative privileges.
Also, a postmortem debugger inherits the same privileges as the application that crashed. Thus, if a Windows service such as CSRSS and LSASS crashes, the debugger will
have very high-level privileges.
You should take this into account when choosing to enable postmortem debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Security During Remote Debugging

There are two ways to increase security during remote debugging: by restricting who can connect to your session and by restricting the powers of someone who does connect.
Controlling Access to the Debugging Session
If you are performing remote debugging through the debugger, or using a process server or KD connection server, any computer on your local network can attempt to attach
to your debugging session.
If you are using the TCP, 1394, COM, or named pipe protocols, you can require the Debugging Client to supply a password. However, this password is not encrypted during
transmission, and therefore these protocols are not secure.
If you want your Debugging Server to be secure, you must use secure sockets layer (SSL) or secure pipe (SPIPE) protocol.
If you are performing remote debugging through remote.exe, you can use the /u parameter to prohibit connections from unauthorized users.
Restricting the Powers of the Client
If you are setting up a kernel-mode debugging session, you can restrict the debugger's ability to interfere with the host machine by using Secure Mode.
In user mode, Secure Mode is not available. You can stop an intrusive client from issuing Microsoft MS-DOS commands and running external programs by issuing
the .noshell (Prohibit Shell Commands) command. However, there are many other ways for a client to interfere with your computer.
Note that both Secure Mode and .noshell will prevent both the Debugging Client and the Debugging Server from taking certain actions. There is no way to place a restriction
on the client but not on the server.
Forgotten Process Servers
When you start a process server on a remote machine, the process server runs silently.
If you perform remote debugging through this process server and then end the session, the process server continues to run.
A forgotten process server is a potential target for an attack. You should always shut down an unneeded process server. Use the Kill.exe utility or Task Manager to terminate
the process server.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 209 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Secure Mode
When you are performing kernel-mode debugging, you can run the debugger in Secure Mode. This prevents the debugger from affecting the host computer, yet does not
significantly decrease its freedom to debug the target computer.
Secure Mode is recommended if you are going to allow remote clients to join your debugging session.
This section includes:
Features of Secure Mode
Activating Secure Mode
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Features of Secure Mode

When Secure Mode is active, all commands that could be used to affect the host computer are deactivated, and there are some restrictions on symbol servers and debugger
extensions.
The specific effects of Secure Mode are as follows:

The .attach (Attach to Process), .create (Create Process), .detach (Detach from Process), .abandon (Abandon Process), .kill (Kill Process), .tlist (List Process
IDs), .dump (Create Dump File), .opendump (Open Dump File), .writemem (Write Memory to File), .netuse (Control Network Connections),
and .quit_lock (Prevent Accidental Quit) commands are not available.
The File | Attach to a Process, File | Open Executable, Debug | Detach Debuggee, Debug | Stop Debugging, File | Open Crash Dump WinDbg menu commands
are not available.
The .shell (Command Shell) command is not available.
Extension DLLs must be loaded from a local disk; they cannot be loaded from UNC paths.
Only the two standard types of extension DLLs (wdbgexts.h and dbgeng.h) are permitted. Other types of DLLs cannot be loaded as extensions.
If you are using a symbol server, there are several restrictions. Only SymSrv (symsrv.dll) is permitted; other symbol server DLLs will not be accepted. You may not use
a downstream store for your symbols, and any existing downstream store will be ignored. HTTP and HTTPS connections are not permitted.
The source server is disabled.

After it has been activated, Secure Mode cannot be turned off.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Activating Secure Mode

Secure Mode is only available for kernel-mode debugging. It must be activated before the debugging session has begun either on the debugger's command line, or when
the debugger is completely dormant and is not yet being used as a server.
To activate Secure Mode, use one of the following methods:

The -secure command-line option

The .secure 1 command
The .symopt+0x40000 command

If you have an existing kernel debugging session and need to discover whether you are already in Secure Mode, use the .secure command with no arguments. This will tell
you the current status of Secure Mode.
After Secure Mode has been activated, it cannot be turned off. Even ending the debugging session will not turn it off. Secure Mode persists as long as the debugger itself is
running.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 210 of 1651

Debugging Tools for Windows

Debugger Reference
This reference section includes:
Command-Line Options
Environment Variables
Debugger Commands
Debugger Extension Commands
Debugger-Related APIs
Debugger Error and Warning Messages
WinDbg Graphical Interface Features
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Command-Line Options
This reference section includes:
CDB Command-Line Options
KD Command-Line Options
WinDbg Command-Line Options
DbgSrv Command-Line Options
KdSrv Command-Line Options
DbEngPrx Command-Line Options
KDbgCtrl Command-Line Options
DbgRpc Command-Line Options
SymStore Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CDB Command-Line Options

First-time users of CDB or NTSD should begin with the Debugger Operation section.
The CDB command line uses the following syntax:
cdb

[ -server ServerTransport | -remote ClientTransport ]

[ -premote SmartClientTransport ] [-log{a|au|o|ou} LogFile]
[-2] [-d] [-ddefer] [-g] [-G] [-hd] [-lines] [-myob] [-bonc]
[-n] [-o] [-s] [-v] [-w] [-cf "filename"] [-cfr "filename"] [-c "command"]
[-robp] [-r BreakErrorLevel] [-t PrintErrorLevel]
[ -x{e|d|n|i} Exception ] [-x] [-clines lines]
[-i ImagePath] [-y SymbolPath] [-srcpath SourcePath]
[-aExtension] [-failinc] [-noio] [-noinh] [-noshell]
[-sdce] [-ses] [-sicv] [-sins] [-snc] [-snul] [-zp PageFile]
[-sup] [-sflags 0xNumber] [-ee {masm|c++}] [-vf[:Flags]]
[-e Event] [-pb] [-pd] [-pe] [-pr] [-pt Seconds] [-pv]
[ -- | -p PID | -pn Name | -psn ServiceName | -z DumpFile | executable ]
[-cimp] [-isd] [-kqm] [-pvr] [-version]

cdb -iae

Causes sleep mode to end for the user-mode debugger whose process ID is specified by PID. This command must be issued on the target machine during sleep mode. See
Controlling the User-Mode Debugger from the Kernel Debugger for details.
The -wake parameter should not be used with any other parameters. This command will not actually start CDB.
-x{e|d|n|i} Exception
Controls the debugger's behavior when the specified event occurs. The Exception can be either an exception number or an event code. You can specify this option
multiple times to control different events. See Controlling Exceptions and Events for details and for other methods of controlling these settings.
-x
Disables first-chance break on access violation exceptions. The second occurrence of an access violation will break into the debugger. This is the same as -xd av.
-y SymbolPath
Specifies the symbol search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and for
other ways to change this path, see Symbol Path.
-z DumpFile
Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several
dump files at once by including multiple -z options, each followed by a different DumpFile value. For details, see Analyzing a User-Mode Dump File with CDB.
-zp PageFile
Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the .pagein (Page In Memory) command. You cannot use -zp
with a standard Windows page file only specially-modified page files can be used.
executable
Specifies the command line of an executable process. This is used to launch a new process and debug it. This has to be the final item on the command line. All text after
the executable name is passed to the executable as its argument string. For details, see Spawning a New Process (User Mode).
-?
Displays command-line help text.
When you are starting the debugger from Start | Run or from a Command Prompt window, specify arguments for the target application after the application's file name.
For instance:
cdb myexe arg1 arg2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KD Command-Line Options
First-time users of KD should begin with the Debugger Operation section.
The KD command line uses the following syntax.
kd [ -server ServerTransport | -remote ClientTransport ]
[-b | -x] [-d] [-bonc] [-m] [-myob] [-lines] [-n] [-r] [-s]
[-v] [-clines lines] [-failinc] [-noio] [-noshell]
[-secure] [-sdce] [-ses] [-sicv] [-sins] [-snc] [-snul]
[-sup] [-sflags 0xNumber] [-log{a|au|o|ou} LogFile]
[-aExtension] [-zp PageFile]
[-i ImagePath] [-y SymbolPath] [-srcpath SourcePath]
[-k ConnectType | -kl | -kqm | -kx ExdiOptions] [-ee {masm|c++}]
[-z DumpFile] [-cf "filename"] [-cfr "filename"] [-c "command"]
[-t PrintErrorLevel] [-version]
kd -iu KeyString
kd -QR Server
kd -wake PID
kd -?
Descriptions of the KD command-line options follow. Only the -remote and -server options are case-sensitive. The initial hyphen can be replaced with a forward-slash (/).
Options which do not take any additional parameters can be concatenated so kd -r -n -v can be written as kd -rnv.
If the -remote or -server option is used, it must appear before any other options on the command line.
Parameters
-server ServerTransport
Creates a debugging server that can be accessed by other debuggers. For an explanation of the possible ServerTransport, see Activating a Debugging Server. When this
parameter is used, it must be the first parameters on the command line.
-remote ClientTransport
Creates a debugging client, and connects to a debugging server that is already running. For an explanation of the possible ClientTransport values, see Activating a
Debugging Client. When this parameter is used, it must be the first parameters on the command line.
-aExtension
Sets the default extension DLL. The default is kdextx86.dll or kdexts.dll. There must be no space after the "a", and the .dll file name extension must not be included. For
details, and other methods of setting this default, see Loading Debugger Extension DLLs.
-b
This option has two effects:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 215 of 1651

1. The debugger will break into the target computer immediately upon connection.
2. After a reboot, the debugger will break into the target computer once the kernel is initialized. See Crashing and Rebooting the Target Computer for details and for
other methods of changing this status.
-bonc
If this option is specified, the debugger will break into the target as soon as the session begins. This is especially useful when connecting to a debugging server that might
not be currently broken into the target.
-c "command"
Specifies the initial debugger command to run at start-up. This command must be surrounded with quotation marks. Multiple commands can be separated with
semicolons. (If you have a long command list, it may be easier to put them in a script and then use the -c option with the $<, $><, $><, $$>< (Run Script File)
command.)
If you are starting a debugging client, this command must be intended for the debugging server. Client-specific commands, such as .lsrcpath, are not allowed.
-cf "filename"
Specifies the path and name of a script file. This script file is executed as soon as the debugger is started. If filename contains spaces it must be enclosed in quotation
marks. If the path is omitted, the current directory is assumed. If the -cf option is not used, the file ntsd.ini in the current directory is used as the script file. If the file does
not exist, no error occurs. For details, see Using Script Files.
-cfr "filename"
Specifies the path and name of a script file. This script file is executed as soon as the debugger is started, and any time the target is restarted. If filename contains spaces it
must be enclosed in quotation marks. If the path is omitted, the current directory is assumed. If the file does not exist, no error occurs. For details, see Using Script Files.
-clines lines
Sets the approximate number of commands in the command history which can be accessed during remote debugging. For details, and for other ways to change this
number, see Using Debugger Commands.
-d
After a reboot, the debugger will break into the target computer as soon as a kernel module is loaded. (This break is earlier than the break from the -b option.) See
Crashing and Rebooting the Target Computer for details and for other methods of changing this status.
-ee {masm|c++}
Sets the default expression evaluator. If masm is specified, MASM expression syntax will be used. If c++ is specified, C++ expression syntax will be used. If the -ee
option is omitted, MASM expression syntax is used as the default. See Evaluating Expressions for details.
-failinc
Causes the debugger to ignore any questionable symbols. When debugging a user-mode or kernel-mode minidump file, this option will also prevent the debugger from
loading any modules whose images can't be mapped. For details and for other methods of controlling this, see SYMOPT_EXACT_SYMBOLS.
-i ImagePath
Specifies the location of the executables that generated the fault. If the path contains spaces, it should be enclosed in quotation marks. For details, and for other ways to
change this path, see Executable Image Path.
-iu KeyString
Registers debugger remoting as an URL type so that users can auto-launch a debugger remote client with an URL. KeyString has the format
remdbgeng://RemotingOption. RemotingOption is a string that defines the transport protocol as defined in the topic Activating a Debugging Client. If this action
succeeds, no message is displayed; if it fails, an error message is displayed.
The -iu parameter must not be used with any other parameters. This command will not actually start KD.
-k ConnectType
Tells the debugger how to connect to the target. For details, see Choosing Kernel Debugging Settings.
-kl
(Windows XP and later) Starts a kernel debugging session on the same machine as the debugger. For more details, see Attaching to a Target Computer (Kernel Mode).
-kqm
Starts KD in quiet mode.
-kx ExdiOptions
Starts a kernel debugging session using an EXDI driver. EXDI drivers are not described in this documentation. If you have an EXDI interface to your hardware probe or
hardware simulator, please contact Microsoft for debugging information.
-lines
Enables source line debugging. If this option is omitted, the .lines (Toggle Source Line Support) command will have to be used before source debugging will be
allowed. For other methods of controlling this, see SYMOPT_LOAD_LINES.
-log{a|au|o|ou} LogFile
Begins logging information to a log file. If LogFile already exists, it will be overwritten if -logo is used, or output will be appended to the file if -loga is used. The -logau
and -logou options operate similar to -loga and -logo respectively, except that the log file is a Unicode file. For more details, see Keeping a Log File.
-m
Indicates that the serial port is connected to a modem. Instructs the debugger to watch for the carrier-detect signal.
-myob
If there is a version mismatch with dbghelp.dll, the debugger will continue to run. (Without the -myob switch, this is considered a fatal error.)
A secondary effect of this option is that the warning that normally appears when breaking into the target computer is suppressed.
-n
Noisy symbol load: Enables verbose output from symbol handler. For details and for other methods of controlling this, see SYMOPT_DEBUG.
-noio
Prevents the debugging server from being used for input or output. Input will only be accepted from the debugging client (plus any initial command or command script
specified by the -c command-line option). All output will be directed to the debugging client. For more details, see Activating a Debugging Server.
-noshell
Prohibits all .shell commands. This prohibition will last as long as the debugger is running, even if a new debugging session is begun. For details, and for other ways to
disable shell commands, see Using Shell Commands.
-QR Server
Lists all debugging servers running on the specified network server. The double backslash (\\) preceding Server is optional. See Searching for Debugging Servers for
details.
The -QR parameter must not be used with any other parameters. This command will not actually start KD.
-r
Displays registers.
-s
Disables lazy symbol loading. This will slow down process startup. For details and for other methods of controlling this, see SYMOPT_DEFERRED_LOADS.
-sdce

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 216 of 1651

Causes the debugger to display File access error dialog boxes during symbol load. For details and for other methods of controlling this, see
SYMOPT_FAIL_CRITICAL_ERRORS.
-secure
Activates Secure Mode.
-ses
Causes the debugger to perform a strict evaluation of all symbol files and ignore any questionable symbols. For details and for other methods of controlling this, see
SYMOPT_EXACT_SYMBOLS.
-sflags 0xNumber
Sets all the symbol handler options at once. Number should be a hexadecimal number prefixed with 0x a decimal without the 0x is permitted, but the symbol options
are binary flags and therefore hexadecimal is recommended. This option should be used with care, since it will override all the symbol handler defaults. For details, see
Setting Symbol Options.
-sicv
Causes the symbol handler to ignore the CV record. For details and for other methods of controlling this, see SYMOPT_IGNORE_CVREC.
-sins
Causes the debugger to ignore the symbol path and executable image path environment variables. For details, see SYMOPT_IGNORE_NT_SYMPATH.
-snc
Causes the debugger to turn off C++ translation. For details and for other methods of controlling this, see SYMOPT_NO_CPP.
-snul
Disables automatic symbol loading for unqualified names. For details and for other methods of controlling this, see SYMOPT_NO_UNQUALIFIED_LOADS.
-srcpath SourcePath
Specifies the source file search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and
for other ways to change this path, see Source Path.
-sup
Causes the symbol handler to search the public symbol table during every symbol search. For details and for other methods of controlling this, see
SYMOPT_AUTO_PUBLICS.
-t PrintErrorLevel
Specifies the error level that will cause the debugger to display an error message. This is a decimal number equal to 0, 1, 2, or 3. The values are described as follows:
Value
Constant
Meaning
0
NONE
Do not display any errors.
1
ERROR
Display ERROR level debugging events.
2
MINORERROR Display MINORERROR and ERROR level debugging events.
3
WARNING
Display WARNING, MINORERROR, and ERROR level debugging events.
This error level only has meaning in checked builds of Microsoft Windows. The default value is 1.
-v
Generates verbose messages for loads, deferred loads, and unloads.
-version
Prints the debugger version string.
-wake PID
Causes sleep mode to end for the user-mode debugger whose process ID is specified by PID. This command must be issued on the target machine during sleep mode. See
Controlling the User-Mode Debugger from the Kernel Debugger for details.
The -wake parameter must not be used with any other parameters. This command will not actually start KD.
-x
Causes the debugger to break in when an exception first occurs, rather than letting the application or module that caused the exception deal with it. (Same as -b, except
with an initial eb nt!NtGlobalFlag 9;g command.)
-y SymbolPath
Specifies the symbol search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and for
other ways to change this path, see Symbol Path.
-z DumpFile
Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several
dump files at once by including multiple -z options, each followed by a different DumpFile value. For details, see Analyzing a Kernel-Mode Dump File with KD.
-zp PageFile
Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the .pagein (Page In Memory) command. You cannot use -zp
with a standard Windows page file only specially-modified page files can be used.
-?
Displays command-line help text.
KD will automatically detect the platform on which the target is running. You do not need to specify the target on the KD command line. The older syntax (using the
name I386KD or IA64KD) is obsolete.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WinDbg Command-Line Options

First-time users of WinDbg should begin with the Debugger Operation section.
The WinDbg command line uses the following syntax:
windbg [ -server ServerTransport | -remote ClientTransport ] [-lsrcpath ]
[ -premote SmartClientTransport ] [-?] [-ee {masm|c++}]
[-clines lines] [-b] [-d] [-aExtension] [-e Event]
[-failinc] [-g] [-G] [-hd] [-j] [-n] [-noshell] [-o]
[-Q | -QY] [-QS | -QSY] [-robp] [-secure] [-ses] [-sdce]

-sins
Causes the debugger to ignore the symbol path and executable image path environment variables. For details, see SYMOPT_IGNORE_NT_SYMPATH.
-snc
Causes the debugger to turn off C++ translation. For details and for other methods of controlling this, see SYMOPT_NO_CPP.
-snul
Disables automatic symbol loading for unqualified names. For details and for other methods of controlling this, see SYMOPT_NO_UNQUALIFIED_LOADS.
-srcpath SourcePath
Specifies the source file search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and
for other ways to change this path, see Source Path.
-sup
Causes the symbol handler to search the public symbol table during every symbol search. For details and for other methods of controlling this, see
SYMOPT_AUTO_PUBLICS.
-T Title
Sets WinDbg window title.
-v
Enables verbose output from debugger.
-W Workspace
Loads the given named workspace. If the workspace name contains spaces, enclose it in quotation marks. If no workspace of this name exists, you will be given the
option of creating a new workspace with this name or abandoning the load attempt. For details, see Using Workspaces.
-WF Filename
Loads the workspace from the given file. Filename should include the file and the extension (usually .wew). If the workspace name contains spaces, enclose it in
quotation marks. If no workspace file with this name exists, you will be given the option of creating a new workspace file with this name or abandoning the load attempt.
For details, see Using Workspaces.
-WX
Disables automatic workspace loading. For details, see Using Workspaces.
-y SymbolPath
Specifies the symbol search path. Separate multiple paths with a semicolon (;). If the path contains spaces, it should be enclosed in quotation marks. For details, and for
other ways to change this path, see Symbol Path.
-z DumpFile
Specifies the name of a crash dump file to debug. If the path and file name contain spaces, this must be surrounded by quotation marks. It is possible to open several
dump files at once by including multiple -z options, each followed by a different DumpFile value. For details, see Analyzing a User-Mode Dump File with WinDbg or
Analyzing a Kernel-Mode Dump File with WinDbg.
-zp PageFile
Specifies the name of a modified page file. This is useful if you are debugging a dump file and want to use the .pagein (Page In Memory) command. You cannot use -zp
with a standard Windows page file only specially-modified page files can be used.
executable
Specifies the command line of an executable process. This is used to launch a new process and debug it. This has to be the final item on the command line. All text after
the executable name is passed to the executable as its argument string. For details, see Spawning a New Process (User Mode).
-?
Pops up this HTML Help window.
When you are running the debugger from the command line, specify arguments for the target application after application's file name. For instance:
windbg myexe arg1 arg2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DbgSrv Command-Line Options

The DbgSrv command line uses the following syntax.
dbgsrv -t ServerTransport [-sifeo image.ext] -c[s] AppCmdLine [-x | -pc]
dbgsrv -?
All options are case-sensitive.
Parameters
-t ServerTransport
Specifies the transport protocol. For a list of the possible protocols and the syntax for ServerTransport in each case, see Activating a Process Server.
-sifeo Executable
Suspends the Image File Execution Option (IFEO) value for the given image. Executable should include the file name of the executable image, including the file name
extensions. The -sifeo option allows DbgSrv to be set as the IFEO debugger for an image created by the -c option, without causing recursive invocation due to the IFEO
setting. This option can be used only if -c is used.
-c
Causes DbgSrv to create a new process. You can use this to create a process that you intend to debug. This is similar to spawning a new process from the debugger,
except that this process will not be debugged when it is created. To debug this process, determine its PID and use the -p option when starting the smart client to debug
this process.
s
Causes the newly-created process to be immediately suspended. If you are using this option, it is recommended that you use CDB as your smart client, and that you start
the smart client with the -pb command-line option, in conjunction with -p PID. If you include the -pb option on the command line, the process will resume when the
debugger attaches to it; otherwise you can resume the process with the ~*m command.
AppCmdLine
Specifies the full command line of the process to be created. AppCmdLine can be either a Unicode or ASCII string, and can include any printable character. All text that
appears after the -c[s] parameter will be taken to form the string AppCmdLine.
-x

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 220 of 1651

Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its
command line.
-pc
Causes the remainder of the command line to be ignored. This option is useful if you are launching DbgSrv from an application that may append unwanted text to its
command line. A syntax error results if -pc is the final element on the DbgSrv command line. Aside from this restriction, -pc is identical to -x.
-?
Displays a message box with help text for the DbgSrv command line.
For information about using DbgSrv, see Process Servers (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KdSrv Command-Line Options

The KdSrv command line uses the following syntax.
kdsrv -t ServerTransport
Parameters
-t ServerTransport
Specifies the transport protocol. For a list of the possible protocols and the syntax for ServerTransport in each case, see Activating a KD Connection Server.
If you type kdsrv with no parameters, a message box with help text appears.
For information about using KdSrv, see KD Connection Servers (Kernel Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DbEngPrx Command-Line Options

The DbEngPrx command line uses the following syntax.
dbengprx [-p] -c ClientTransport -s ServerTransport
dbengprx -?
Parameters
-p
Causes DbEngPrx to continue existing even after all connections to it are dropped.
-c ClientTransport
Specifies the protocol settings to be used in connecting to the server. The protocol should match that used when the server was created. For details, see Activating a
Repeater.
-s ServerTransport
Specifies the protocol settings that will be used when the client connects to the repeater. For details, see Activating a Repeater.
-?
Displays a message box with help text for the DbEngPrx command line.
For information about using DbEngPrx, see Repeaters.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KDbgCtrl Command-Line Options

The KDbgCtrl command line uses the following syntax:
kdbgctrl [-e|-d|-c] [-ea|-da|-ca] [-eu|-du|-cu] [-sdb Size | -cdb]
kdbgctrl -cx

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 221 of 1651

kdbgctrl -?
Parameters
-e
Enables the Full Kernel Debugging setting.
-d
Disables the Full Kernel Debugging setting.
-c
Displays the current Full Kernel Debugging setting.
-ea
Enables the Automatic Kernel Debugging setting.
-da
Disables the Automatic Kernel Debugging setting.
-ca
Displays the Automatic Full Kernel Debugging setting.
-eu
Enables the User-Mode Error Handling setting.
-du
Disables the User-Mode Error Handling setting.
-cu
Displays the User-Mode Error Handling setting.
-sdb Size
Sets the size of the DbgPrint buffer. If Size is prefixed with 0x it will be interpreted as a hexadecimal number. If it is prefixed with 0 (zero), it will be interpreted as octal.
Otherwise, it will be interpreted as decimal.
-cdb
Displays the current size of the DbgPrint buffer, in bytes.
-cx
Determines the current Full Kernel Debugging setting and returns an appropriate value. This option cannot be combined with other options, and it does not display any
output. It is designed for use in a batch file where the return value of the KDbgCtrl program can be tested. Possible return values are as follows:
Value
Meaning
0x10001
Full Kernel Debugging is enabled.
0x10002
Full Kernel Debugging is disabled.
Any other value An error occurred. KDbgCtrl was unable to determine the current status of Full Kernel Debugging.
-?
Displays command-line help for KDbgCtrl.
Additional Information
For a description of all the KDbgCtrl settings, see Using KDbgCtrl.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DbgRpc Command-Line Options

The DbgRpc command line must always contain exactly one of the -l, -e, -t, -c, or -a switches. The options following these switches depend on the switch used. The -s, -p,
and -r options can be used with any other options.
dbgrpc [-s Server -p ProtSeq] [-r Radix] -l -P ProcessID -L CellID1.CellID2
dbgrpc [-s Server -p ProtSeq] [-r Radix] -e [-E EndpointName]
dbgrpc [-s Server -p ProtSeq] [-r Radix] -t -P ProcessID [-T ThreadID]
dbgrpc [-s Server -p ProtSeq] [-r Radix] [-c|-a] [-C CallID] [-I IfStart] [-N ProcNum] [-P ProcessID]
dbgrpc -?
Parameters
-s Server
Allows DbgRpc to view information from a remote machine. The server name should not be preceded by slash marks. For more information about using DbgRpc
remotely, see Using the DbgRpc Tool.
-p ProtSeq
Specifies the remote transport to be used. The possible values of ProtSeq are ncacn_ip_tcp (TCP protocol) and ncacn_np (named pipe protocol). TCP protocol is
recommended. For more information about using DbgRpc remotely, see Using the DbgRpc Tool.
-r Radix
Specifies the radix to be used for the command parameters. The default is base 16. If the -r parameter is used, it should be placed first on the line, since it only affects
parameters listed after itself. It does not affect the output of the DbgRpc tool.
-l
Displays RPC state information for the specified cell. For an example, see Get RPC Cell Information.
ProcessID
Specifies the process ID (PID) of a process. When the -l option is being used, this should be the process whose server contains the desired cell. When the -t option is
being used, this should be the process containing the desired thread. When the -c or -a options are being used, this parameter is optional; it should be the server process
that owns the calls you wish to display.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 222 of 1651

CellID1.CellID2
Specifies the number of the cell to be displayed.
-e
Searches the system's RPC state information for endpoint information. For an example, see Get RPC Endpoint Information.
EndpointName
Specifies the number of the endpoint to be displayed. If omitted, the endpoints for all processes on the system are displayed.
-t
Searches the system's RPC state information for thread information. For an example, see Get RPC Thread Information.
ThreadID
Specifies the thread ID of the thread to be displayed. If omitted, all threads in the specified process will be displayed.
-c
Searches the system's RPC state information for server-side call (SCALL) information. For an example, see Get RPC Call Information.
-a
Searches the system's RPC state information for client call (CCALL) information. For an example, see Get RPC Client Call Information. This option requires full RPC
state information.
CallID
Specifies the call ID. This parameter is optional; include it only if you want to display calls matching a specific CallID value.
IfStart
Specifies the first DWORD of the interface's universally unique identifier (UUID) on which the call was made. This parameter is optional; include it only if you want to
display calls matching a specific IfStart value.
ProcNum
Specifies the procedure number of this call. (The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file the
first routine in the interface is 0, the second 1, and so on.) This parameter is optional; include it only if you want to display calls matching a specific ProcNum value.
Additional Information
For more information about debugging Microsoft Remote Procedure Call (RPC), see RPC Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymStore Command-Line Options

The following syntax forms are supported for SymStore transactions. The first parameter must always be add or del. The order of the other parameters is immaterial.
symstore add [/r] [/p [/l] [-:MSG Message] [-:REL] [-:NOREFS]] /f File /s Store /t Product [/v Version] [/o] [/c Comment
symstore add [/r] [/p [/l] [-:REL] [-:NOREFS]] /g Share /f File /x IndexFile [/a] [/o] [/d LogFile]
symstore add /y IndexFile /g Share /s Store [/p [-:MSG Message] [-:REL] [-:NOREFS]] /t Product [/v Version] [/o] [/c
symstore query [/r] /f File /s Store [/o] [/d LogFile]
symstore del /i ID /s Store [/o] [/d LogFile]
symstore /?
Parameters
/f File
Specifies the network path of files or directories to add.
/g Share
Specifies the server and share where the symbol files were originally stored. When used with /f, Share should be identical to the beginning of the File specifier. When
used with /y, Share should be the location of the original symbol files (not the index file). This allows you to later change this portion of the file path in case you move
the symbol files to a different server and share.
/s Store
Specifies the root directory for the symbol store.
/m Prefix
Causes SymStore to prefer using symbols from paths beginning with Prefix when storing files or updating pointers. This option cannot be used with the /x option.
/h { PUB | PRI }
Causes SymStore to prefer using public symbols (if PUB is specified), or private symbols (if PRI is specified) when storing or updating symbols. This option has no
effect on binary files.
/i ID
Specifies the transaction ID string.
/p
Causes SymStore to store a pointer to the file, rather than the file itself.
/l
Allows the file specified by File to be in a local directory rather than a network path. (This option can only be used when both /f and /p are used.)
-:MSG Message
Adds the specified Message to each file. (This option can only be used when /p is used.)
-:REL
Allows the paths in the file pointers to be relative. This option implies the /l option. (This option can only be used when /p is used.)
-:NOREFS
Omits the creation of reference pointer files for the files and pointers being stored. This option is only valid during the initial creation of a symbol store if the store being
changed was created with this option.
/r
Causes SymStore to add files or directories recursively.
/t Product

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 223 of 1651

Specifies the name of the product.

/v Version
Specifies the version of the product.
/c Comment
Specifies a comment for the transaction.
/d LogFile
Specifies a log file to be used for command output. If this is not included, transaction information and other output is sent to stdout.
/o
Causes SymStore to display verbose output.
/x IndexFile
Causes SymStore not to store the actual symbol files. Instead, SymStore records information in the IndexFile that will enable SymStore to access the symbol files at a
later time.
/a
Causes SymStore to append new indexing information to an existing index file. (This option is only used with the /x option.)
/y IndexFile
Causes SymStore to read the data from a file created with /x.
/yi IndexFile
Appends a comment with the transaction ID to the end of an index file created with the /x option.
/z { PUB | PRI }
Causes SymStore to index only the type of symbols specified. If PUB is specified, then only the symbols that have had the full source information stripped will be
indexed. If PRI is specified, then only the symbols that contain the full source information will be indexed. SymStore will always index binary symbols.
/compress
Causes SymStore to create a compressed version of each file copied to the symbol store instead of using an uncompressed copy of the file. This option is only valid when
storing files and not pointers, and consequently cannot be used when the /p option is used.
/?
Displays help text for the SymStore command.
Additional Information
For more information about SymStore, see Using Symbol Servers and Symbol Stores.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Environment Variables
This reference section includes:
General Environment Variables
Kernel-Mode Environment Variables
For information about using environment variables for kernel-mode debugging, see Configuring Software on the Host Computer. For information about using environment
variables for user-mode debugging, see Basic User-Mode Configuration.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

General Environment Variables

The following table lists the environment variables that can be used in both user-mode and kernel-mode debugging.
Variable
_NT_DEBUGGER_EXTENSION_PATH =
Path
_NT_EXECUTABLE_IMAGE_PATH =
Path
_NT_SOURCE_PATH = Path
_NT_SYMBOL_PATH = Path
_NT_ALT_SYMBOL_PATH = Path

_NT_SYMBOL_PROXY = Proxy:Port
_NT_DEBUG_HISTORY_SIZE = Number

_NT_DEBUG_LOG_FILE_OPEN =
Filename

Meaning
Specifies the path that the debugger will first search for extension DLLs. Path can contain a drive letter followed by a colon
(:). Separate multiple directories with semicolons (;). For details, see Loading Debugger Extension DLLs.
Specifies the path containing the binary executable files. Path can contain a drive letter followed by a colon (:). Separate
multiple directories with semicolons (;). For details, and for other ways to change this path, see Executable Image Path.
Specifies the path containing the source files for the target. Path can contain a drive letter followed by a colon (:). Separate
multiple directories with semicolons (;). For details, and for other ways to change this path, see Source Path.
Specifies the root of a directory tree containing the symbol files. Path can contain a drive letter followed by a colon (:).
Separate multiple directories with semicolons (;). For details, and for other ways to change this path, see Symbol Path.
Specifies an alternate symbol path searched before _NT_SYMBOL_PATH. This is useful for keeping private versions of
symbol files. Path can contain a drive letter followed by a colon (:). Separate multiple directories with semicolons (;). For
details, see Symbol Path.
Specifies the proxy server to be used by SymSrv. For details, see Firewalls and Proxy Servers.
Specifies the number of commands in the command history that can be accessed during remote debugging. Because commands
vary in length, the number of lines available may not exactly match Number. For details, and for other ways to change this
number, see Using Debugger Commands.
(CDB and KD only) Specifies the log file to which the debugger should send output. For details, and for other methods of
writing to log files, see Keeping a Log File.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

_NT_DEBUG_LOG_FILE_APPEND =
Filename
_NT_EXPR_EVAL = {masm | c++}
_NO_DEBUG_HEAP
DBGENG_NO_DEBUG_PRIVILEGE
DBGHELP_HOMEDIR
SRCSRV_INI_FILE

Page 224 of 1651

(CDB and KD only) Specifies the log file to which the debugger should append output. For details, and for other methods of
appending to log files, see Keeping a Log File.
Specifies the default expression evaluator. If masm is specified, MASM expression syntax will be used. If c++ is specified,
C++ expression syntax will be used. MASM expression syntax is the default. See Evaluating Expressions for details.
(Windows XP and later) Specifies that the debug heap should not be used for user-mode debugging. See Behavior of Spawned
Processes for details.
Prevents processes spawned by the debugger from inheriting SeDebugPrivilege.
Specifies the path for the root of the default downstream store used by SymSrv and SrcSrv. Path can contain a drive letter
followed by a colon (:). Separate multiple directories with semicolons (;).
Specifies the path and name of the configuration file used by SrcSrv. By default, the path is the srcsrv subdirectory of the
Debugging Tools for Windows installation directory, and the file name is Srcsrv.ini. See Source Indexing for details.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel-Mode Environment Variables

The following table lists the environment variables that are used only in kernel-mode debugging.
Variable
_NT_DEBUG_PORT = ComPort
_NT_DEBUG_BAUD_RATE = BaudRate
_NT_DEBUG_BUS = 1394
_NT_DEBUG_1394_CHANNEL =
1394Channel
_NT_DEBUG_1394_SYMLINK = Protocol
KDQUIET =Anything

Meaning
Specifies the COM port to be used in a kernel connection. For details, see Choosing Kernel Debugging Settings.
Specifies the baud rate to be used over the COM port connection. For details, see Choosing Kernel Debugging Settings.
Specifies that kernel debugging will be done over a 1394 cable connection.
Specifies the channel to be used for the 1394 kernel connection. For details, see Choosing Kernel Debugging Settings.
Specifies the connection protocol to be used for the 1394 kernel connection. For details, see Choosing Kernel Debugging
Settings.
If KDQUIET is defined, the debugger will run in quiet mode. Quiet mode involves three distinct effects:
1. The debugger does not display messages each time an extension DLL is loaded or unloaded.
2. The r (Registers) command no longer requires an equal sign in its syntax.
3. The debugger will not display a warning message when breaking into the target computer.
Quiet mode can also be controlled by using the sq (Set Quiet Mode) command.

_NT_DEBUG_CACHE_SIZE
= Size
_NT_DEBUG_OPTIONS = Option

Specifies the maximum kernel debugging cache size, in bytes. This cache holds data received by the host computer from the
serial connection. The default is 1,024,000.
Specifies one of the following two values:
NOEXTWARNING tells the debugger not to output a warning when it cannot find an extension command.
NOVERSIONCHECK tells the debugger not to check the version of debugger extensions.

These options can be modified or displayed by using the so (Set Kernel Options) command.
_NT_KD_FILES = MapFile

Specifies a driver replacement map file. For details and for other methods of controlling driver replacement, see Mapping
Driver Files.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Commands
This section includes the following topics:
Syntax Rules
Command Tokens
Commands
Meta-Commands
Control Keys

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 225 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Syntax Rules
This section describes the syntax rules that you must follow to use debugger commands.
When you are debugging, you should obey the following general syntax rules:

You can use any combination of uppercase and lowercase letters in commands and arguments, except when specifically noted in the topics in this section.
You can separate multiple command parameters by one or more spaces or by a comma (,).
You can typically omit the space between a command and its first parameter . You can frequently omit other spaces if this omission does not cause any ambiguity.

The command reference topics in this section use the following items:

Characters in bold font style indicate items that you must literally type.
Characters in italic font style indicate parameters that are explained in the Parameters section of the reference topic.
Parameters in brackets ([ xxx ]) are optional. Brackets with a vertical bar ([ xxx | yyy ]) indicate that you can use one, or none, of the enclosed parameters.
Braces with vertical bars ({ xxx | yyy }) indicate that you must use exactly one of the enclosed parameters .

The following topics describe the syntax that the following parameter types use:
Numerical Expression Syntax
String Wildcard Syntax
Register Syntax
Pseudo-Register Syntax
Source Line Syntax
Address and Address Range Syntax
Thread Syntax
Process Syntax
System Syntax
Multiprocessor Syntax
Syntax also plays an important role in using symbols. For further details, see Symbol Syntax and Symbol Matching.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Numerical Expression Syntax

The debugger accepts two different kinds of numeric expressions: C++ expressions and MASM expressions. Each of these expressions follows its own syntax rules for input
and output.
For more information about when each syntax type is used, see Evaluating Expressions.
This section includes the following topics:
MASM Numbers and Operators
C++ Numbers and Operators
MASM Expressions vs. C++ Expressions
Expression Examples
Sign Extension
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 226 of 1651

Debugging Tools for Windows

MASM Numbers and Operators

Before version 4.0 of the Debugging Tools for Windows package, NTSD, CDB, KD, and WinDbg used only Microsoft Macro Assembler (MASM) expression syntax.
Numbers in MASM Expressions
You can put numbers in MASM expressions in base 16, 10, 8, or 2.
Use the n (Set Number Base) command to set the default radix to 16, 10, or 8. All unprefixed numbers are then interpreted in this base. You can override the default radix by
specifying the 0x prefix (hexadecimal), the 0n prefix (decimal), the 0t prefix (octal), or the 0y prefix (binary).
You can also specify hexadecimal numbers by adding an h after the number. You can use uppercase or lowercase letters within numbers. For example, "0x4AB3", "0X4aB3",
"4AB3h", "4ab3h", and "4aB3H" have the same meaning.
If you do not add a number after the prefix in an expression, the number is read as 0. Therefore, you can write 0 as 0, the prefix followed by 0, and only the prefix. For
example, in hexadecimal, "0", "0x0", and "0x" have the same meaning.
You can enter hexadecimal 64-bit values in the xxxxxxxx`xxxxxxxx format. You can also omit the grave accent ( ` ). If you include the grave accent, automatic sign extension
is disabled.
Symbols in MASM Expressions
In MASM expressions, the numeric value of any symbol is its memory address. Depending on what the symbol refers to, this address is the address of a global variable, local
variable, function, segment, module, or any other recognized label.
To specify which module the address is associated with, include the module name and an exclamation point ( ! ) before the name of the symbol. If the symbol could be
interpreted as a hexadecimal number, include the module name and an exclamation point, or just an exclamation point, before the symbol name. For more information about
symbol recognition, see Symbol Syntax and Symbol Matching.
Use two colons ( :: ) or two underscores ( __ ) to indicate the members of a class.
Use a grave accent ( ` ) or an apostrophe ( ' ) in a symbol name only if you add a module name and exclamation point before the symbol.
Numeric Operators in MASM Expressions
You can modify any component of an expression by using a unary operator. You can combine any two components by using a binary operator. Unary operators take
precedence over binary operators. When you use multiple binary operators, the operators follow the fixed precedence rules that are described in the following tables.
You can always use parentheses to override precedence rules.
If part of an MASM expression is enclosed in parentheses and two at signs (@@) appear before the expression, the expression is interpreted according to C++ expression
rules. You cannot add a space between the two at signs and the opening parenthesis. You can also specify the expression evaluator by using @@c++( ... ) or @@masm( ... ).
When you perform arithmetic computations, the MASM expression evaluator treats all numbers and symbols as ULONG64 types.
Unary address operators assume DS as the default segment for addresses. Expressions are evaluated in order of operator precedence. If adjacent operators have equal
precedence, the expression is evaluated from left to right.
You can use the following unary operators.
Operator
Meaning
+
Unary plus
Unary minus
not
Returns 1 if the argument is zero. Returns zero for any nonzero argument.
hi
High 16 bits
low
Low 16 bits
by
Low-order byte from the specified address.
$pby
Same as by except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.
wo
Low-order word from the specified address.
$pwo
Same as wo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.
dwo
Double-word from the specified address.
$pdwo Same as dwo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.
qwo
Quad-word from the specified address.
$pqwo Same as qwo except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.
poi
Pointer-sized data from the specified address. The pointer size is 32 bits or 64 bits. In kernel debugging, this size is based on the processor of the target computer.
In user-mode debugging on an Itanium-based computer, this size is 32 bits or 64 bits, depending on the target application. Therefore, poi is the best operator to use
if you want pointer-sized data.
$ppoi
Same as poi except that it takes a physical address. Only physical memory that uses the default caching behavior can be read.
You can use the following binary operators. The operators in each cell take precedence over those in lower cells. Operators in the same cell are of the same precedence and
are parsed from left to right.
Operator
Meaning
*
Multiplication
/

Integer division

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 227 of 1651

mod (or %) Modulus (remainder)

Addition

Subtraction

Left shift

Logical right shift

>>>

Arithmetic right shift

= (or ==)

Equal to

Less than

Greater than

Less than or equal to

Greater than or equal to

Not equal to

and (or &) Bitwise AND

xor (or ^) Bitwise XOR (exclusive OR)
or (or |)
Bitwise OR
The <, >, =, ==, and != comparison operators evaluate to 1 if the expression is true or zero if the expression is false. A single equal sign (=) is the same as a double equal sign
(==). You cannot use side effects or assignments within a MASM expression.
An invalid operation (such as division by zero) results in an "Operand error" is returned to the Debugger Command window.
Non-Numeric Operators in MASM Expressions
You can also use the following additional operators in MASM expressions.
Operator
$fnsucc
(FnAddress,
RetVal, Flag)

Meaning
Interprets the RetVal value as a return value for the function that is located at the FnAddress address. If this return value qualifies as a success code,
$fnsucc returns TRUE. Otherwise, $fnsucc returns FALSE.
If the return type is BOOL, bool, HANDLE, HRESULT, or NTSTATUS, $fnsucc correctly understands whether the specified return value qualifies as a
success code. If the return type is a pointer, all values other than NULL qualify as success codes. For any other type, success is defined by the value of
Flag. If Flag is 0, a nonzero value of RetVal is success. If Flag is 1, a zero value of RetVal is success.

$iment (Address)

Returns the address of the image entry point in the loaded module list. Address specifies the Portable Executable (PE) image base address. The entry is
found by looking up the image entry point in the PE image header of the image that Address specifies.
You can use this function for both modules that are already in the module list and to set unresolved breakpoints by using the bu command.

$scmp("String1",
"String2")
$sicmp("String1",
"String2")
$spat("String",
"Pattern")
$vvalid(Address,
Length)

Evaluates to 1, 0, or 1, like the strcmp C function.

Evaluates to 1, 0, or 1, like the stricmp Microsoft Win32 function .
Evaluates to TRUE or FALSE depending on whether String matches Pattern. Pattern can contain a variety of wildcard characters and specifiers. For
more information about the syntax, see String Wildcard Syntax.
Determines whether the memory range that begins at Address and extends for Length bytes is valid. If the memory is valid, $vvalid evaluates to 1. If the
memory is invalid, $vvalid evaluates to 0.

Registers and Pseudo-Registers in MASM Expressions

You can use registers and pseudo-registers within MASM expressions. You can add an at sign (@) before all registers and pseudo-registers. The at sign causes the debugger
to access the value more quickly. This at sign is unnecessary for the most common x86-based registers. For other registers and pseudo-registers, we recommend that you add
the at sign, but it is not actually required. If you omit the at sign for the less common registers, the debugger tries to parse the text as a hexadecimal number, then as a symbol,
and finally as a register.
You can also use a period ( . ) to indicate the current instruction pointer. You should not add an at sign before this period, and you cannot use a period as the first parameter of
the r command. This period has the same meaning as the $ip pseudo-register.
For more information about registers and pseudo-registers, see Register Syntax and Pseudo-Register Syntax.
Source Line Numbers in MASM Expressions
You can use source file and line number expressions within MASM expressions. You must enclose these expressions by using grave accents ( ` ). For more information about
the syntax, see Source Line Syntax.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 228 of 1651

December 09, 2009

Debugging Tools for Windows

C++ Numbers and Operators

The C++ expression parser supports all forms of C++ expression syntax. The syntax includes all data types (including pointers, floating-point numbers, and arrays) and all
C++ unary and binary operators.
Numbers in C++ Expressions
Numbers in C++ expressions are interpreted as decimal numbers, unless you specify them in another manner. To specify a hexadecimal integer, add 0x before the number. To
specify an octal integer, add 0 (zero) before the number.
The default debugger radix does not affect how you enter C++ expressions. You cannot directly enter a binary number (except by nesting a MASM expression within the C++
expression).
You can enter a hexadecimal 64-bit value in the xxxxxxxx`xxxxxxxx format. (You can also omit the grave accent ( ` ).) Both formats produce the same value.
You can use the L, U, and I64 suffixes with integer values. The actual size of the number that is created depends on the suffix and the number that you enter. For more
information about this interpretation, see a C++ language reference.
The output of the C++ expression evaluator keeps the data type that the C++ expression rules specify. However, if you use this expression as an argument for a command, a
cast is always made. For example, you do not have to cast integer values to pointers when they are used as addresses in command arguments. If the expression's value cannot
be validly cast to an integer or a pointer, a syntax error occurs.
You can use the 0n (decimal) prefix for some output, but you cannot use it for C++ expression input.
Characters and Strings in C++ Expressions
You can enter a character by surrounding it with single quotation marks ( ' ). The standard C++ escape characters are permitted.
You can enter string literals by surrounding them with double quotation marks ( " ). You can use \" as an escape sequence within such a string. However, strings have no
meaning to the expression evaluator.
Symbols in C++ Expressions
In a C++ expression, each symbol is interpreted according to its type. Depending on what the symbol refers to, it might be interpreted as an integer, a data structure, a function
pointer, or any other data type. If you use a symbol that does not correspond to a C++ data type (such as an unmodified module name) within a C++ expression, a syntax error
occurs.
If the symbol might be ambiguous, you can add a module name and an exclamation point ( ! ) or only an exclamation point before the symbol. For more information about
symbol recognition, see Symbol Syntax and Symbol Matching.
You can use a grave accent ( ` ) or an apostrophe ( ' ) in a symbol name only if you add a module name and exclamation point before the symbol name.
When you add the < and > delimiters after a template name, you can add spaces between these delimiters.
Operators in C++ Expressions
You can always use parentheses to override precedence rules.
If you enclose part of a C++ expression in parentheses and add two at signs (@@) before the expression, the expression is interpreted according to MASM expression rules.
You cannot add a space between the two at signs and the opening parenthesis. The final value of this expression is passed to the C++ expression evaluator as a ULONG64
value. You can also specify the expression evaluator by using @@c++( ... ) or @@masm( ... ).
Data types are indicated as usual in the C++ language. The symbols that indicate arrays ( [ ] ), pointer members ( -> ), UDT members ( . ), and members of classes ( :: ) are all
recognized. All arithmetic operators are supported, including assignment and side-effect operators. However, you cannot use the new, delete, and throw operators, and you
cannot actually call a function.
Pointer arithmetic is supported and offsets are scaled correctly. Note that you cannot add an offset to a function pointer. (If you have to add an offset to a function pointer, cast
the offset to a character pointer first.)
As in C++, if you use operators with invalid data types, a syntax error occurs. The debugger's C++ expression parser uses slightly more relaxed rules than most C++
compilers, but all major rules are enforced. For example, you cannot shift a non-integer value.
You can use the following operators. The operators in each cell take precedence over those in lower cells. Operators in the same cell are of the same precedence and are
parsed from left to right. As with C++, expression evaluation ends when its value is known. This ending enables you to effectively use expressions such
as ?? myPtr && *myPtr.
Operator
Expression // Comment
Class :: Member

Ignore all subsequent text

Member of class

Meaning

Class ::~Member

Member of class (destructor)

:: Name

Global

Structure . Field

Field in a structure

Pointer -> Field

Field in referenced structure

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 229 of 1651

Name [integer]

Array subscript

LValue ++

Increment (after evaluation)

LValue --

Decrement (after evaluation)

dynamic_cast <type>(Value)

Typecast (always performed)

static_cast <type>(Value)

Typecast (always performed)

reinterpret_cast <type>(Value) Typecast (always performed)

const_cast <type>(Value)

Typecast (always performed)

(type) Value

Typecast (always performed)

sizeof value

Size of expression

sizeof( type )

Size of data type

++ LValue

Increment (before evaluation)

-- LValue

Decrement (before evaluation)

~ Value

Bit complement

! Value

Not (Boolean)

- Value

Unary minus

+ Value

Unary plus

& LValue

Address of data type

* Value

Dereference

Structure . * Pointer

Pointer to member of structure

Pointer -> * Pointer

Pointer to member of referenced structure

Value * Value

Multiplication

Value / Value

Division

Value % Value

Modulus

Value + Value

Addition

Value - Value

Subtraction

Value << Value

Bitwise shift left

Value >> Value

Bitwise shift right

Value < Value

Less than (comparison)

Value <= Value

Less than or equal (comparison)

Value > Value

Greater than (comparison)

Value >= Value

Greater than or equal (comparison)

Value == Value

Equal (comparison)

Value != Value

Not equal (comparison)

Value & Value

Value ^ Value
Value | Value
Value && Value
Value || Value
LValue = Value

Bitwise AND
Bitwise XOR (exclusive OR)
Bitwise OR
Logical AND
Logical OR
Assign

LValue *= Value

Multiply and assign

LValue /= Value

Divide and assign

LValue %= Value

Modulo and assign

LValue += Value

Add and assign

LValue -= Value

Subtract and assign

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 230 of 1651

LValue <<= Value

Shift left and assign

LValue >>= Value

Shift right and assign

LValue &= Value

AND and assign

LValue |= Value

OR and assign

LValue ^= Value

XOR and assign

Value ? Value : Value

Value , Value

Conditional evaluation
Evaluate all values, and then discard all except the rightmost value

Registers and Pseudo-Registers in C++ Expressions

Registers and pseudo-registers are never sign extended.

All other values are treated exactly like C++ would treat values of their type.

Displaying Sign-Extended and 64-Bit Numbers

Other than 32-bit and 16-bit registers, all numbers are stored internally within the debugger as 64-bit values. However, when a number satisfies certain criteria, the debugger
displays it as a 32-bit number in command output.
The debugger uses the following criteria to determine how to display numbers:

If the high 32 bits of a number are all zeros (that is, if the number is from 0x00000000`00000000 through 0x00000000`FFFFFFFF), the debugger displays the number
as a 32-bit number.
If the high 32 bits of a number are all ones and if the highest bit of the low 32 bits is also a one (that is, if the number is from 0xFFFFFFFF`80000000 through
0xFFFFFFFF`FFFFFFFF), the debugger assumes the number is a sign-extended 32-bit number and displays it as a 32-bit number.
If the previous two condition do not apply (that is, if the number is from 0x00000001`00000000 through 0xFFFFFFFF`7FFFFFFF) the debugger displays the number as
a 64-bit number.

Because of these display rules, when a number is displayed as a 32-bit number from 0x80000000 through 0xFFFFFFFF, you cannot confirm whether the high 32 bits are all
ones or all zeros. To distinguish between these two cases, you must perform an additional computation on the number (such as masking one or more of the high bits and
displaying the result).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

String Wildcard Syntax

Some debugger commands have string parameters that accept a variety of wildcard characters. These parameters are noted on their respective reference pages.
These kinds of parameters support the following syntax features:

An asterisk ( * ) represents zero or more characters.

A question mark ( ? ) represents any single character.
Brackets ( [ ] ) that contain a list of characters represent any single character in the list. Exactly one character in the list is matched. Within these brackets, you can use a
hyphen ( - ) to specify a range. For example, Prog[er-t7]am matches "Progeam", "Program", "Progsam", "Progtam", and "Prog7am".
A number sign ( # ) represents zero or more of the preceding characters. For example, Lo#p matches "Lp", "Lop", "Loop", "Looop", and so on. You can also combine a
number sign with brackets, so m[ia]#n matches "mn", "min", "man", "maan", "main", "mian", "miin", "miain", and so on.
A plus sign ( + ) represents one or more of the preceding characters. For example, Lo+p is the same as Lo#p, except that Lo+p does not match "Lp". Similarly, m[ia]
+n is the same as m[ia]#n, except that m[ia]+n does not match "mn". a?+b is also the same as a*b, except that a?+b does not match "ab".
If you have to specify a literal number sign (#), question mark (?), opening bracket ([), closing bracket (]), asterisk (*), or plus sign (+) character, you must add a
backslash ( \ ) in front of the character. Hyphens are always literal when you do not enclose them in brackets. But you cannot specify a literal hyphen within a bracketed
list.

Parameters that specify symbols also support some additional features. In addition to the standard string wildcard characters, you can use an underscore (_) before a text
expression that you use to specify a symbol. When matching this expression to a symbol, the debugger treats the underscore as any quantity of underscores, even zero. This
feature applies only when you are matching symbols. It does not apply to string wildcard expressions in general. For more information about symbol syntax, see Symbol
Syntax and Symbol Matching.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 233 of 1651

Debugging Tools for Windows

Register Syntax
The debugger can control registers and floating-point registers. (For more information about commands that can control registers, see Reading and Writing Registers and
Flags.)
When you use a register in an expression, you should add an at sign ( @ ) before the register. This at sign tells the debugger that the following text is the name of a register.
If you are using MASM expression syntax, you can omit the at sign for certain very common registers. On x86-based systems, you can omit the at sign for the eax, ebx, ecx,
edx, esi, edi, ebp, eip, and efl registers. However, if you specify a less common register without an at sign, the debugger first tries to interpret the text as a hexadecimal
number. If the text contains non-hexadecimal characters, the debugger next interprets the text as a symbol. Finally, if the debugger does not find a symbol match, the debugger
interprets the number as a register.
If you are using C++ expression syntax, the at sign is always required.
The r (Registers) command is an exception to this rule. The debugger always interprets its first argument as a register. (An at sign is not required or permitted.) If there is a
second argument for the r command, it is interpreted according to the default expression syntax. If the default expression syntax is C++, you must use the following command
to copy the ebx register to the eax register.
0:000> r eax = @ebx
For more information about the registers and instructions that are specific to each processor, see Processor Architecture.
Flags on an x86-based Processor
x86-based processors also use several 1-bit registers known as flags. For more information about these flags and the syntax that you can use to view or change them, see x86
Flags.
Registers and Threads
Each thread has its own register values. These values are stored in the CPU registers when the thread is executing and in memory when another thread is executing.
In user mode, any reference to a register is interpreted as the register that is associated with the current thread. For more information about the current thread, see Controlling
Processes and Threads.
In kernel mode, any reference to a register is interpreted as the register that is associated with the current register context. You can set the register context to match a specific
thread, context record, or trap frame. You can display only the most important registers for the specified register context, and you cannot change their values.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Pseudo-Register Syntax
The debugger supports several pseudo-registers that hold certain values.
The debugger sets automatic pseudo-registers to certain useful values. User-defined pseudo-registers are integer variables that you can write to or read.
All pseudo-registers begin with a dollar sign ($). If you are using MASM syntax, you can add an at sign ( @ ) before the dollar sign. This at sign tells the debugger that the
following token is a register or pseudo-register, not a symbol. If you omit the at sign, the debugger responds more slowly, because it has to search the whole symbol table.
For example, the following two commands produce the same output, but the second command is faster.
0:000> ?
Evaluate
0:000> ?
Evaluate

$exp
expression: 143 = 0000008f
@$exp
expression: 143 = 0000008f

If a symbol exists with the same name as the pseudo-register, you must add the at sign.
If you are using C++ expression syntax, the at sign ( @ ) is always required.
The r (Registers) command is an exception to this rule. The debugger always interprets its first argument as a register or pseudo-register. (An at sign is not required or
permitted.) If there is a second argument for the r command, it is interpreted according to the default expression syntax. If the default expression syntax is C++, you must use
the following command to copy the $t2 pseudo-register to the $t1 pseudo-register.
0:000> r $t1 = @$t2
Automatic Pseudo-Registers
The debugger automatically sets the following pseudo-registers.
Pseudoregister

Description

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

$ea
$ea2
$exp
$ra

Page 234 of 1651

The effective address of the last instruction that was executed. If this instruction does not have an effective address, the debugger displays "Bad register
error". If this instruction has two effective addresses, the debugger displays the first address.
The second effective address of the last instruction that was executed. If this instruction does not have two effective addresses, the debugger displays "Bad
register error".
The last expression that was evaluated.
The return address that is currently on the stack.
This address is especially useful in execution commands. For example, g @$ra continues until the return address is found (although gu (Go Up) is a more
precise effective way of "stepping out" of the current function).

$ip

The instruction pointer register.

x86-based processors: The same as eip.
Itanium-based processors: Related to iip. (For more information, see the note following this table.)
x64-based processors: The same as rip.

$eventip
$previp
$relip
$scopeip
$exentry
$retreg

The instruction pointer at the time of the current event. This pointer typically matches $ip, unless you switched threads or manually changed the value of the
instruction pointer.
The instruction pointer at the time of the previous event. (Breaking into the debugger counts as an event.)
An instruction pointer that is related to the current event. When you are branch tracing, this pointer is the pointer to the branch source.
The instruction pointer for the current local context (also known as the scope).
The address of the entry point of the first executable of the current process.
The primary return value register.
x86-based processors: The same as eax.
Itanium-based processors: The same as ret0.
x64-based processors: The same as rax.

$retreg64

The primary return value register, in 64-bit format.

x86 processor: The same as the edx:eax pair.

$csp

The current call stack pointer. This pointer is the register that is most representative of call stack depth.
x86-based processors: The same as esp.
Itanium-based processors: The same as bsp.
x64-based processors: The same as rsp.

$p
$proc
$thread
$peb
$teb
$tpid
$tid
$bpNumber
$frame
$dbgtime
$callret
$lastclrex
$ptrsize
$pagesize

The value that the last d* (Display Memory) command printed.

The address of the current process (that is, the address of the EPROCESS block).
The address of the current thread. In kernel-mode debugging, this address is the address of the ETHREAD block. In user-mode debugging, this address is the
address of the thread environment block (TEB).
The address of the process environment block (PEB) of the current process.
The address of the thread environment block (TEB) of the current thread.
The process ID (PID) for the process that owns the current thread.
The thread ID for the current thread.
The address of the corresponding breakpoint. For example, $bp3 (or $bp03) refers to the breakpoint whose breakpoint ID is 3. Number is always a decimal
number. If no breakpoint has an ID of Number, $bpNumber evaluates to zero. For more information about breakpoints, see Using Breakpoints.
The current frame index. This index is the same frame number that the .frame (Set Local Context) command uses.
The current time, according to the computer that the debugger is running on.
The return value of the last function that .call (Call Function) called or that is used in an .fnret /s command. The data type of $callret is the data type of this
return value.
Managed debugging only: The address of the last-encountered common language runtime (CLR) exception object.
The size of a pointer. In kernel mode, this size is the pointer size on the target computer.
The number of bytes in one page of memory. In kernel mode, this size is the page size on the target computer.

Some of these pseudo-registers might not be available in certain debugging scenarios. For example, you cannot use $peb, $tid, and $tpid when you are debugging a usermode minidump or certain kernel-mode dump files. There will be situations where you can learn thread information from ~ (Thread Status) but not from $tid. You cannot
use the $previp pseudo-register on the first debugger event. You cannot use the $relip pseudo-register unless you are branch tracing. If you use an unavailable pseudoregister, a syntax error occurs.
A pseudo-register that holds the address of a structure such as $thread, $proc, $teb, $peb, and $lastclrex will be evaluated according to the proper data type in the C++
expression evaluator, but not in the MASM expression evaluator. For example, the command ? $teb displays the address of the TEB, while the command ?? @$teb displays
the entire TEB structure. For more information, see Evaluating Expressions.
On an Itanium-based processor, the iip register is bundle-aligned, which means that it points to slot 0 in the bundle containing the current instruction, even if a different slot is
being executed. So iip is not the full instruction pointer. The $ip pseudo-register is the actual instruction pointer, including the bundle and the slot. The other pseudo-registers
that hold address pointers ($ra, $retreg, $eventip, $previp, $relip, and $exentry) have the same structure as $ip on all processors.
You can use the r command to change the value of $ip. This change also automatically changes the corresponding register. When execution resumes, it resumes at the new
instruction pointer address. This register is the only automatic pseudo-register that you can change manually.
Note In MASM syntax, you can indicate the $ip pseudo-register with a period ( . ). You do not add an at sign (@) before this period, and do not use the period as the first
parameter of the r command. This syntax is not permitted within a C++ expression.
Automatic pseudo-registers are similar to automatic aliases. But you can use automatic aliases together with alias-related tokens (such as ${ }), and you cannot use pseudoregisters with such tokens.
User-Defined Pseudo-Registers

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 235 of 1651

There are 20 user-defined pseudo-registers ($t0, $t1, ..., $t19). These pseudo-register are variables that you can read and write through the debugger. You can store any
integer value in these pseudo-registers. They can be especially useful as loop variables.
To write to one of these pseudo-registers, use the r (Registers) command, as the following example shows.
0:000> r $t0 = 7
0:000> r $t1 = 128*poi(MyVar)
Like all pseudo-registers, you can use the user-defined pseudo-register in any expression, as the following example shows.
0:000> bp $t3
0:000> bp @$t4
0:000> ?? @$t1 + 4*@$t2
A pseudo-register is always typed as an integer, unless you use the ? switch together with the r command. If you use this switch, the pseudo-register acquires the type of
whatever is assigned to it. For example, the following command assigns the UNICODE_STRING** type and the 0x0012FFBC value to $t15.
0:000> r? $t15 = * (UNICODE_STRING*) 0x12ffbc
User-defined pseudo-registers use zero as the default value when the debugger is started.
Note The aliases $u0, $u1, ..., $u9 are not pseudo-registers, despite their similar appearance. For more information about these aliases, see Using Aliases.
Example
The following example sets a breakpoint that is hit every time that the current thread calls NtOpenFile. But this breakpoint is not hit when other threads call NtOpenFile.
kd> bp /t @$thread nt!ntopenfile
Example
The following example executes a command until the register holds a specified value. First, put the following code for conditional stepping in a script file named eaxstep.
.if (@eax == 1234) { .echo 1234 } .else { t "$<eaxstep" }
Next, issue the following command.
t "$<eaxstep"
The debugger performs a step and then runs your command. In this case, the debugger runs the script, which either displays 1234 or repeats the process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Source Line Syntax

You can specify source file line numbers as all or part of an MASM expression. These numbers evaluate to the offset of the executable code that corresponds to this source
line.
Note You cannot use source line numbers as part of a C++ expression. For more information about when MASM and C++ expression syntax is used, see Evaluating
Expressions.
You must enclose source file and line number expressions by grave accents ( ` ). The following example shows the full format for source file line numbers.
`[[Module!]Filename][:LineNumber]`
If you have multiple files that have identical file names, Filename should include the whole directory path and file name. This directory path should be the one that is used at
compilation time. If you supply only the file name or only part of the path and if there are multiple matches, the debugger uses the first match that it finds.
If you omit Filename, the debugger uses the source file that corresponds to the current program counter.
LineNumber is read as a decimal number unless you precede it with 0x, regardless of the current default radix. If you omit LineNumber, the expression evaluates to the initial
address of the executable that corresponds to the source file.
Source line expressions are not evaluated in CDB unless you issue a .lines (Toggle Source Line Support) command or you include the -lines command-line option when you
start WinDbg..
For more information about source debugging, see Debugging in Source Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 236 of 1651

Debugging Tools for Windows

Introduction

Page 239 of 1651

that the expression should be interpreted as a processor, use the following syntax.
||[Expression]
In this syntax, the square brackets are required, and Expression stands for any numerical expression that resolves to an integer that corresponds to a processor ID.
In the following example, the processor changes depending on the value of a user-defined pseudo-register.
||[@$t0]
Examples
The following example uses the k (Display Stack Backtrace) command to display a stack trace from processor two.
1: kd> 2k
The following example uses the r (Registers) command to display the eax register of processor three.
1: kd> 3r eax
However, the following command gives a syntax error, because you cannot change the state of a processor other than the current processor.
1: kd> 3r eax=808080
Breakpoints
During kernel debugging, the bp, bu, bm (Set Breakpoint) and ba (Break on Access) commands apply to all processors of a multiple processor computer.
For example, if the current processor is three, you can enter the following command to put a breakpoint at SomeAddress.
1: kd> bp SomeAddress
Then, any processor (not only processor one) that executes at that address causes a breakpoint trap.
Displaying Processor Information
You can use the !running extension to display the status of each processor on the target computer. For each processor, !running can also display the current and next thread
fields from the process control block (PRCB), the state of the 16 built-in queued spinlocks, and a stack trace.
You can use the !cpuinfo and !cpuid extensions to display information about the processors themselves.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Command Tokens
This section of the reference discusses the various tokens used within debugger commands and meta-commands.
These tokens include:
; (Command Separator)
{ } (Block Delimiter)
${ } (Alias Interpreter)
$$ (Comment Specifier)
* (Comment Line Specifier)
.block
.break
.catch
.continue
.do
.else
.elsif
.for

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 240 of 1651

.foreach
.if
.leave
.printf
.while
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

; (Command Separator)
The semicolon ( ; ) character is used to separate multiple commands on a single line.
Syntax
Command1 ; Command2 [; Command3 ...]
Parameters
Command1, Command2, ...
The commands to be executed.
Comments
Commands are executed sequentially from left to right. All commands on a single line refer to the current thread, unless otherwise specified. If a command causes the thread
to execute, the remaining commands on the line will be deferred until that thread stops on a debug event.
A small number of commands cannot be followed by a semicolon, because they automatically take the entire remainder of the line as their argument. These include as (Set
Alias), $< (Run Script File), $>< (Run Script File), and any command beginning with the * (Comment Line Specifier) token.
Here is an example. This executes the current program to source line 123, prints the value of counter, then resumes execution:
0:000> g `:123`; ? poi(counter); g

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

{ } (Block Delimiter)
A pair of braces ( { } ) is used to surround a block of statements within a debugger command program.
Syntax
Statements { Statements } Statements
Comments
When each block is entered, all aliases within the block are evaluated. If you alter the value of an alias at some point within a command block, commands subsequent to that
point will not use the new alias value unless they are within a subordinate block.
Each block must begin with a control flow token. If you wish to create a block for the sole purpose of evaluating aliases, you should prefix it with the .block token.
Additional Information
For information about debugger command programs and control flow tokens, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

${ } (Alias Interpreter)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 241 of 1651

A dollar sign followed by a pair of braces ( ${ } ) evaluates to a variety of values related to the specified user-named alias.
Syntax
Text
Text
Text
Text
Text

${Alias} Text
${/d:Alias} Text
${/f:Alias} Text
${/n:Alias} Text
${/v:Alias} Text

Parameters
Alias
Specifies the name of the alias to be expanded or evaluated. Alias must be a user-named alias or the Variable value used by the .foreach token.
/d
Evaluates to one or zero depending on whether the alias is currently defined. If the alias is defined, ${/v:Alias} is replaced by 1; if the alias is not defined, ${/v:Alias} is
replaced by 0.
/f
Evaluates to the alias equivalent if the alias is currently defined. If the alias is defined, ${/f:Alias} is replaced by the alias equivalent; if the alias is not defined, ${/f:Alias}
is replaced by an empty string.
/n
Evaluates to the alias name if the alias is currently defined. If the alias is defined, ${/n:Alias} is replaced by the alias name; if the alias is not defined, ${/n:Alias} is not
replaced but retains its literal value of ${/n:Alias}.
/v
Prevents any alias evaluation. Regardless of whether Alias is defined, ${/v:Alias} always retains its literal value of ${/v:Alias}.
Comments
If no switches are used and the alias is currently defined, ${Alias} is replaced by the alias equivalent. If no switches are used and the alias is not defined, ${Alias} always
retains its literal value of ${Alias}.
One advantage of using the ${ } token is that the alias will be evaluated even if it is adjacent to other characters. Without this token, the debugger only replaces aliases that are
separated from other tokens by a space.
As indicated, there are circumstances where the ${ } token is not replaced by anything but retains its literal value. This occurs when no switch is used and Alias is undefined,
when the /n switch is used and Alias is undefined, and always when the /v switch is used. In these circumstances, the token retains its literal value, including the dollar sign
and the braces. Therefore, if this is used as the parameter of a command, a syntax error will result, unless that parameter accepts arbitrary text strings.
There is, however, one exception to this. If you use ${/v:Alias} as the first parameter to the as (Set Alias) or aS (Set Alias) command, this token will be treated as the string
Alias alone, not as the string ${/v:Alias}. This only works with the as, aS, and ad commands, and it only works when the /v switch is used it will not work with ${/n:Alias}
or ${Alias} when they retain their literal values.
Alias must be a user-named alias or the Variable value used by the .foreach token not a fixed-name alias. If there is a fixed-name alias within the string Alias, it will be
replaced before the ${ } token is evaluated.
Additional Information
For an explanation of how to use aliases, see Using Aliases.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

$$ (Comment Specifier)
If two dollar signs ( $$ ) appear at the start of a command, then the rest of the line is treated as a comment, unless the comment is terminated by a semicolon.
Syntax
$$ [any text]
Comments
The $$ token is parsed like any other debugger command. Therefore, if you want to create a comment after another command, you must precede the $$ token with a
semicolon.
The $$ token will cause the text after it to be ignored until the end of the line or until a semicolon is encountered. A semicolon terminates the comment; text after the
semicolon is parsed as a standard command. This differs from * (Comment Line Specifier), which makes the remainder of the line a comment even if a semicolon is
present.
For example, the following command will display eax and ebx, but not ecx:
0:000> r eax; $$ some text; r ebx; * more text; r ecx
Text prefixed by the * or $$ tokens is not processed in any way. If you are performing remote debugging, a comment entered in the debugging server will not be visible in the
debugging client, nor vice-versa. If you wish to make comment text appear in the Debugger Command window in a way visible to all parties, you should use .echo (Echo
Comment).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 242 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

* (Comment Line Specifier)

If the asterisk ( * ) character is at the start of a command, then the rest of the line is treated as a comment, even if a semicolon appears after it.
Syntax
* [any text]
Comments
The * token is parsed like any other debugger command. Therefore, if you want to create a comment after another command, you must precede the * token with a semicolon.
The * token will cause the remainder of the line to be ignored, even if a semicolon appears after it. This differs from $$ (Comment Specifier), which creates a comment that
can be terminated by a semicolon.
For example, the following command will display eax and ebx, but not ecx:
0:000> r eax; $$ some text; r ebx; * more text; r ecx
Text prefixed by the * or $$ tokens is not processed in any way. If you are performing remote debugging, a comment entered in the debugging server will not be visible in the
debugging client, nor vice-versa. If you wish to make comment text appear in the Debugger Command window in a way visible to all parties, you should use .echo (Echo
Comment).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.block
The .block token performs no action; it is used solely to introduce a block of statements.
Syntax
Commands ; .block { Commands } ; Commands
Comments
Blocks of commands are surrounded by braces. When each block is entered, all aliases within the block are evaluated. If you alter the value of an alias at some point within a
command block, commands subsequent to that point will not use the new alias value unless they are within a subordinate block.
Each block must begin with a control flow token. If you wish to create a block for the sole purpose of evaluating aliases, you should prefix it with the .block token, since this
token has no effect other than to allow a block to be introduced.
Additional Information
For information about using a new block to evaluate an alias, see Using Aliases and as, aS (Set Alias).
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.break
The .break token behaves like the break keyword in C.
Syntax
.for (...) { ... ; .if (Condition) .break ; ... }
.while (...) { ... ; .if (Condition) .break ; ... }

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 243 of 1651

.do { ... ; .if (Condition) .break ; ... } (...)

Comments
The .break token can be used within any .for, .while, or .do loop.
Since there is no control flow token equivalent to the C goto statement, you will usually use the .break token within an .if conditional, as shown in the syntax examples
above. However, this is not actually required.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.catch
The .catch token is used to prevent a program from terminating if an error occurs.
It does not behave like the catch keyword in C++.
Syntax
Commands ; .catch { Commands } ; Commands
Comments
The .catch token is followed by braces enclosing one or more commands.
If a command within a .catch block generates an error, the error message is displayed, all remaining commands within the braces are ignored, and execution resumes with the
first command after the closing brace.
If .catch is not used, an error will terminate the entire debugger command program.
You can use .leave to exit from a .catch block.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.continue
The .continue token behaves like the continue keyword in C.
Syntax
.for (...) { ... ; .if (Condition) .continue ; ... }
.while (...) { ... ; .if (Condition) .continue ; ... }
.do { ... ; .if (Condition) .continue ; ... } (...)
Comments
The .continue token can be used within any .for, .while, or .do loop.
Since there is no control flow token equivalent to the C goto statement, you will usually use the .continue token within an .if conditional, as shown in the syntax examples
above. However, this is not actually required.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 244 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

.do
The .do token behaves like the do keyword in C, except that the word "while" is not used before the condition.
Syntax
.do { Commands } (Condition)
Syntax Elements
Commands
Specifies one or more commands that will be executed repeatedly as long as the condition is true but will always be executed at least once. This block of commands
needs to be enclosed in braces, even if it consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing
brace does not need to be followed by a semicolon.
Condition
Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing Condition in parentheses is optional. Condition must be an expression,
not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Comments
The .break and .continue tokens can be used to exit or restart the Commands block.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.else
The .else token behaves like the else keyword in C.
Syntax
.if (Condition) { Commands } .else { Commands }
.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands }
Syntax Elements
Commands
Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command.
Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.elsif
The .elsif token behaves like the else if keyword combination in C.
Syntax
.if (Condition) { Commands } .elsif (Condition) { Commands }
.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands }
Syntax Elements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 245 of 1651

Condition
Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing Condition in parentheses is optional. Condition must be an expression,
not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Commands
Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command.
Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.for
The .for token behaves like the for keyword in C, except that multiple increment commands must be separated by semicolons, not by commas.
Syntax
.for (InitialCommand ; Condition ; IncrementCommands) { Commands }
Syntax Elements
InitialCommand
Specifies a command that will be executed before the loop begins. Only a single initial command is permitted.
Condition
Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing Condition in parentheses is optional. Condition must be an expression,
not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
IncrementCommands
Specifies one or more commands that will be executed at the conclusion of each loop. If you wish to use multiple increment commands, separate them by semicolons but
do not enclose them in braces.
Commands
Specifies one or more commands that will be executed repeatedly as long as the condition is true. This block of commands needs to be enclosed in braces, even if it
consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a
semicolon.
Comments
If all the work is being done by the increment commands, you can omit Commands entirely and simply use an empty pair of braces.
Here is an example of a .for statement with multiple increment commands:
0:000> .for (r eax=0; @eax < 7; reax=eax+1; rebx=ebx+1) { .... }
The .break and .continue tokens can be used to exit or restart the Commands block.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.foreach
The .foreach token parses the output of one or more debugger commands and uses each value in this output as the input to one or more additional commands.
Syntax
.foreach [Options] ( Variable

{ InCommands } ) { OutCommands }

.foreach [Options] /s ( Variable

"InString" ) { OutCommands }

.foreach [Options] /f ( Variable

"InFile" ) { OutCommands }

Syntax Elements
Options
Can be any combination of the following options:
/pS InitialSkipNumber

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 246 of 1651

Causes some initial tokens to be skipped. InitialSkipNumber specifies the number of output tokens that will not be passed to the specified OutCommands.
/ps SkipNumber
Causes tokens to be skipped repeatedly each time a command is processed. After each time a token is passed to the specified OutCommands, a number of tokens
equal to the value of SkipNumber will be ignored.
Variable
Specifies a variable name. This variable will be used to hold the output from each command in the InCommands string; you can reference Variable by name in the
parameters passed to the OutCommands. Any alphanumeric string can be used, although using a string that can also pass for a valid hexadecimal number or debugger
command is not recommended. If the name used for Variable happens to match an existing global variable, local variable, or alias, their values will not be affected by
the .foreach command.
InCommands
Specifies one or more commands whose output will be parsed; the resulting tokens will be passed to OutCommands. The output from InCommands is not displayed.
InString
Used with /s. Specifies a string that will be parsed; the resulting tokens will be passed to OutCommands.
InFile
Used with /f. Specifies a text file that will be parsed; the resulting tokens will be passed to OutCommands. The file name InFile must be enclosed in quotation marks.
OutCommands
Specifies one or more commands which will be executed for each token. Whenever the Variable string occurs it will be replaced by the current token.
Note When the string Variable appears within OutCommands, it must be surrounded by spaces. If it is adjacent to any other text even a parenthesis it will not be
replaced by the current token value, unless you use the ${ } (Alias Interpreter) token.
Comments
When the output from InCommands, the InString string, or the InFile file is parsed, any number of spaces, tabs, or carriage returns is treated as a single delimiter. Each of the
resulting pieces of text is used to replace Variable when it appears within OutCommands.
Here is an example of a .foreach statement that uses the dds command on each token found in the file myfile.txt:
0:000> .foreach /f ( place "g:\myfile.txt") { dds place }
The /pS and /ps flags can be used to pass only certain tokens to the specified OutCommands. For example, the following statement will skip the first two tokens in the
myfile.txt file and then pass the third to dds. After each token that is passed, it will skip four tokens. The result is that dds will be used with the 3rd, 8th, 13th, 18th, and 23rd
tokens, and so on:
0:000> .foreach /pS 2 /ps 4 /f ( place "g:\myfile.txt") { dds place }
For more examples that use the .foreach token, see Debugger Command Program Examples.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.if
The .if token behaves like the if keyword in C.
Syntax
.if (Condition) { Commands }
.if (Condition) { Commands } .else { Commands }
.if (Condition) { Commands } .elsif (Condition) { Commands }
.if (Condition) { Commands } .elsif (Condition) { Commands } .else { Commands }
Syntax Elements
Condition
Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing Condition in parentheses is optional. Condition must be an expression,
not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Commands
Specifies one or more commands that will be executed conditionally. This block of commands needs to be enclosed in braces, even if it consists of a single command.
Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a semicolon.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 247 of 1651

December 09, 2009

Debugging Tools for Windows

.leave
The .leave token is used to exit from a .catch block.
Syntax
.catch { ... ; .if (Condition) .leave ; ... }
Comments
When a .leave token is encountered within a .catch block, the program exits from the block, and execution resumes with the first command after the closing brace.
Since there is no control flow token equivalent to the C goto statement, you will usually use the .leave token within an .if conditional, as shown in the syntax examples above.
However, this is not actually required.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.printf
The .printf token behaves like the printf statement in C.
Syntax
.printf [Option] "FormatString" [Arguments ...]
Syntax Elements
Option
(WinDbg only) Specifies the type of text message that WinDbg should interpret the FormatString as. WinDbg assigns each type of Debugger Command window message
a background and text color; choosing one of these options causes the message to be displayed in the appropriate colors. The default is to display the text as a normallevel message. For more information on message colors and how to set them, see View | Options.
The following options are available:
Option
/od
/oD
/oe
/on
/op
/oP
/os
/ov
/ow

Type of message Title of colors in Options dialog box

debuggee
Debuggee level command window
debuggee prompt Debuggee prompt level command window
error
Error level command window
normal
Normal level command window
prompt
Prompt level command window
prompt registers Prompt registers level command window
symbols
Symbol message level command window
verbose
Verbose level command window
warning
Warning level command window

FormatString
Specifies the format string, as in printf. In general, conversion characters work exactly as in C. For the floating-point conversion characters the 64-bit argument is
interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in the target's virtual address space. It may not have any modifiers and it uses the debugger's
internal address formatting. The following additional conversion characters are supported:
Character
Argument Type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in the target's virtual address space
Pointer in the host's virtual address space

%ma

ULONG64

%mu

ULONG64

Address of a NULL-terminated ASCII string in

the target's virtual address space
Address of a NULL-terminated Unicode string in The specified string.
the target's virtual address space

Any 64-bit value

Text printed
The value of the pointer.
The value of the pointer. (This is equivalent to the standard C %p
character.)
The specified value. If this is greater than 0xFFFFFFFF it is
printed as a 64-bit address, otherwise it is printed as a 32-bit
address.
The specified string.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Page 248 of 1651

Address of an ANSI_STRING structure in the

target's virtual address space
Address of a UNICODE_STRING structure in
the target's virtual address space
Address of a debugger symbol in the target's
virtual address space.
Address of a debugger symbol in the target's
virtual address space

The specified string.

The specified string.
String containing the name of the specified symbol (and
displacement, if any).
String containing the name of the specified symbol (and
displacement, if any), as well as any available source line
information.

Arguments
Specifies arguments for the format string, as in printf. The number of arguments specified should match the number of conversion characters in FormatString. Each
argument is an expression that will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Comments
The color settings that can be chosen using the Options parameter are by default all set to black text on a white background. To make best use of these options, you must first
use View | Options to open the Options dialog box and change the color settings for Debugger Command window messages.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.while
The .while token behaves like the while keyword in C.
Syntax
.while (Condition) { Commands }
Syntax Elements
Condition
Specifies a condition. If this evaluates to zero, it is treated as false; otherwise it is true. Enclosing Condition in parentheses is optional. Condition must be an expression,
not a debugger command. It will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Commands
Specifies one or more commands that will be executed repeatedly as long as the condition is true. This block of commands needs to be enclosed in braces, even if it
consists of a single command. Multiple commands should be separated by semicolons, but the final command before the closing brace does not need to be followed by a
semicolon.
Comments
The .break and .continue tokens can be used to exit or restart the Commands block.
Additional Information
For information about other control flow tokens and their use in debugger command programs, see Using Debugger Command Programs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Commands
This section of the reference discusses the various debugger commands that you can use in CDB, KD, and WinDbg.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ENTER (Repeat Last Command)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 249 of 1651

The ENTER key repeats the last command that you typed.
Syntax
ENTER
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
In CDB and KD, pressing the ENTER key by itself at a command prompt reissues the command that you previously entered.
In WinDbg, the ENTER key can have no effect or you can use it to repeat the previous command. You can set this option in the Options dialog box. (To open the Options
dialog box, click Options on the View menu or click the Options button (

) on the toolbar.)

If you set ENTER to repeat the last command, but you want to create white space in the Debugger Command window, use the * (Comment Line Specifier) token and then
press ENTER several times.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

$<, $><, $$<, $$><, $$>a< (Run Script File)

The $<, $><, $$<, $$><, and $$>a< commands read the contents of the specified script file and use its contents as debugger command input.
Syntax
$<Filename
$><Filename
$$< Filename
$$>< Filename
$$>a< Filename [arg1 arg2 arg3 ... ]
Parameters
Filename
Specifies a file that contains valid debugger command text. The file name must follow Microsoft Windows file name conventions. The file name may contain spaces.
argn
Specifies any number of string arguments for the debugger to pass to the script. The debugger will replace any string of the form ${$argn} in the script file with the
corresponding argn before executing the script. Arguments may not contain quotation marks or semicolons. Multiple arguments must be separated by spaces; if an
argument contains a space it must be enclosed in quotation marks. All arguments are optional.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you use the $$< or $$>< token for this command, the space between the token and Filename is optional. You can add a semicolon or another command after this command.
You can enclose Filename in quotation marks, but this is not required, even if Filename contains spaces or additional commands follow on the same line.
If you use the $< or $>< token for this command, you cannot add any spaces between the token and Filename. You must not enclose Filename in quotation marks. You
cannot add a semicolon or another command after this command.
The $< and $$< tokens execute the commands that are found in the script file literally. The $>< and $$>< tokens open the script file, replace all carriage returns with
semicolons, and execute the resulting text as a single command block. These tokens are useful if you are running scripts that contain debugger command programs. For more
information about these programs, see Using Debugger Command Programs.
The $$>a< token allows the debugger to pass arguments to the script. A space between the token and Filename is optional. If Filename contains spaces, it must be enclosed in
quotations marks. If too many arguments are supplied, the excess arguments are ignored. If too few arguments are supplied, any token in the source file of the form ${$argn}
where n is larger than the number of supplied arguments will remain in its literal form and will not be replaced with anything. You can follow this command with a semicolon
and additional commands; the presence of a semicolon terminates the argument list.
When the debugger executes a script file, the commands and their output are displayed in the Debugger Command window. When the end of the script file is reached, control
returns to the debugger.
The following table summarizes how you can use these commands.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 250 of 1651

Token Space permitted before the file name? Condenses the script into a single command block?
$<
No
No
$>< No
Yes
$$< Yes
No
$$>< Yes
Yes
$$>a< Yes
Yes
When the debugger executes a script file, the commands and their output are displayed in the Debugger Command window. When the end of the script file is reached, control
returns to the debugger.
The $<, $><, $$<, and $$>< commands echo the commands contained in the script file and display the output of these commands. The $$>a< command does not echo the
commands found in the script file, but merely displays their output.
Script files can be nested. If the debugger encounters one of these tokens in a script file, execution moves to the new script file and returns to the previous location when the
new script file has been completed. Scripts can also be called recursively.
In WinDbg, you can paste the additional command text in the Debugger Command window.
Example
The following example demonstrates how to pass arguments to a script file, Myfile.txt. Assume that the file contains the following text:
.echo The first argument is ${$arg1}.
.echo The second argument is ${$arg2}.
Then you can pass arguments to this file by using a command like this:
0:000> $$>a<myfile.txt myFirstArg mySecondArg
The result of this command would be:
The first argument is myFirstArg.
The second argument is mySecondArg.
Here is an example of what happens when the wrong number of argument is supplied. Assume that the file My Script.txt contains the following text:
.echo The first argument is ${$arg1}.
.echo The fifth argument is ${$arg5}.
.echo The fourth argument is ${$arg4}.
Then the following semicolon-delimited command line produces output thus:
0:000> $$>a< "c:\binl\my script.txt" "First one" Two "Three More" Four; recx
The first argument is First one.
The fifth argument is ${$arg5}.
The fourth argument is Four.
ecx=0021f4ac
In the preceding example, the file name is enclosed in quotation marks because it contains a space, and arguments that contain spaces are enclosed in quotation marks as well.
Although a fifth argument seems to be expected by the script, the semicolon terminates the $$>a< command after the fourth argument.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

? (Command Help)
The question mark (?) character displays a list of all commands and operators.
Note A question mark by itself displays command help. The ? expression syntax evaluates the given expression.
Syntax
?
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
For more information about standard commands, use ?. For more information about meta-commands, use .help. For more information about extension commands, use !help.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 251 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

? (Evaluate Expression)
The question mark (?) command evaluates and displays the value of an expression.
Note A question mark by itself (?) displays command help. The ? expression command evaluates the given expression.
Syntax
? Expression
Parameters
Expression
Specifies the expression to evaluate.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The input and output of the ? command depend on whether you are using MASM expression syntax or C++ expression syntax. For more information about these kinds of
expression syntax, see Evaluating Expressions and Numerical Expression Syntax.
If you are using MASM syntax, the input and output depend on the current radix. To change the radix, use the n (Set Number Base) command.
The ? command evaluates symbols in the expression in the context of the current thread and process.
Some strings may contain escapes, such as \n, \", \r, and \b, that are meant to be read literally, rather than interpreted by the evaluator. If an escape within a string is
interpreted by the evaluator, errors in evaluation can occur. For example:
0:000> as AliasName c:\dir\name.txt
0:000> al
Alias
Value
------------AliasName
c:\dir\name.txt
0:001> ? $spat( "c:\dir\name.txt", "*name*" )
Evaluate expression: 0 = 00000000
0:001> ? $spat( "${AliasName}", "*name*" )
Evaluate expression: 0 = 00000000
0:001> ? $spat( "c:\dir\", "*filename*" )
Syntax error at '( "c:\dir\", "*filename*" )
In the first two examples, even though the string does match the pattern, the evaluator is returning a value of FALSE. In the third, the evaluator cannot make a comparison
because the string ends in a backslash ( \ ), and so the \" is translated by the evaluator.
To get the evaluator to interpret a string literally, you must use the @"String" syntax. The following code example shows the correct results:
0:000> ?
Evaluate
0:000> ?
Evaluate
0:001> ?
Evaluate

$spat( @"c:\dir\name.txt", "name" )

expression: 1 = 00000000`00000001
$spat( @"${AliasName}", "*name*" )
expression: 1 = 00000000`00000001
$spat( @"c:\dir\", "*filename*" )
expression: 0 = 00000000

In the preceding examples, the $spat MASM operator checks the first string to determine whether it matches the pattern of the second string. For more information about
MASM operators, see the MASM Numbers and Operators topic.
See Also
?? (Evaluate C++ Expression), .formats (Show Number Formats)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 252 of 1651

?? (Evaluate C++ Expression)

The double question mark (??) command evaluates and displays the value of an expression according to C++ expression rules.
Syntax
?? Expression
Parameters
Expression
Specifies the C++ expression to evaluate. For more information about the syntax, see C++ Numbers and Operators.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The ?? command evaluates symbols in the expression in the context of the current thread and process.
If you want to evaluate a part of the Expression expression according to MASM expression rules, enclose that part in parentheses and add two at signs ( @@ ) before it. For
more information about MASM expressions and C++ expressions, see Evaluating Expressions and Numerical Expression Syntax.
See Also
? (Evaluate Expression), .formats (Show Number Formats)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

# (Search for Disassembly Pattern)

The number sign (#) command searches for the specified pattern in the disassembly code.
Syntax
# [Pattern] [Address [ L Size ]]
Parameters
Pattern
Specifies the pattern to search for in the disassembly code. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax, see
String Wildcard Syntax. If you want to include spaces in Pattern, you must enclose the pattern in quotation marks. The pattern is not case sensitive. If you have
previously used the # command and you omit Pattern, the command reuses the most recently used pattern.
Address
Specifies the address where the search begins. For more information about the syntax, see Address and Address Range Syntax.
Size
Specifies the number of instructions to search. If you omit Size, the search continues until the first match occurs.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you previously used the # command and you omit Address, the search begins where the previous search ended.
This command works by searching the disassembled text for the specified pattern. You can use this command to find register names, constants, or any other string that appears
in the disassembly output. You can repeat the command without the Address parameter to find successive occurrences of the pattern.
You can view disassembly instructions by using the u (Unassemble) command or by using the Disassembly window in WinDbg. The disassembly display contains up to four
parts: Address offset, Binary code, Assembly language mnemonic, and Assembly language details. The following example shows a possible display.
0040116b
0040116c
0040116d

45
fc
8945b0

inc
cld
mov

ebp
eax,[ebp-0x1c]

The # command can search for text within any single part of the disassembly display. For example, you could use # eax 0040116b to find the mov eax,[ebp-0x1c] instruction
at address 0040116d. The following commands also find this instruction.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

#
#
#
#

Page 253 of 1651

[ebp?0x 0040116b
mov 0040116b
8945* 0040116b
116d 0040116b

However, you cannot search for mov eax* as a single unit, because mov and eax appear in different parts of the display.
As an additional example, you could issue the following command to search for the first reference to the strlen function after the entry point main.
# strlen main
Similarly, you could issue the following two commands to find the first jnz instruction after address 0x779F9FBA and then find the next jnz instruction after that.
# jnz 779f9fba#
When you omit Pattern or Address, their values are based on the previous use of the # command. If you omit either parameter the first time that you issue the # command, no
search is performed. However, the values of Pattern and Address are initialized even in this situation.
If you include Pattern or Address, its value is set to the entered value. If you omit Address, it is initialized to the current value of the program counter. If you omit Pattern, it is
initialized to an empty pattern.
Additional Information
For more information about assembly debugging and related commands, see Debugging in Assembly Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

|| (System Status)
The double vertical bar (||) command prints status for the specified system or for all systems that you are currently debugging.
Do not confuse this command with the | (Process Status) command.
Syntax
|| System
Parameters
System
Specifies the system to display. If you omit this parameter, all systems that you are debugging are displayed. For more information about the syntax, see System Syntax.
Environment
Modes
Multiple target debugging
Targets Live, crash dump
Platforms All
Comments
The || command is useful only when you are debugging multiple targets. Many, but not all, multiple-target debugging sessions involve multiple systems. For more information
about these sessions, see Debugging Multiple Targets.
Each system listing includes the server name and the protocol details. The system that the debugger is running on is identified as <Local>.
The following examples show you how to use this command. The following command displays all systems.
3:2:005> ||
The following command also displays all systems.
3:2:005> ||*
The following command displays the currently active system.
3:2:005> ||.
The following command displays the system that had the most recent exception or break.
3:2:005> ||#
The following command displays system number 2.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 254 of 1651

3:2:005> ||2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

||s (Set Current System)

The ||s command sets or displays the current system number.
Do not confuse this command with the s (Search Memory), ~s (Change Current Processor), ~s (Set Current Thread), or |s (Set Current Process) command.
Syntax
||System s
|| s
Parameters
System
Specifies the system to activate. For more information about the syntax, see System Syntax.
Environment
Modes
Multiple target debugging
Targets Live, crash dump
Platforms All
Comments
The ||s command is useful only when you are debugging multiple targets. Many, but not all, multiple-target debugging sessions involve multiple systems. For more
information about these kinds of sessions, see Debugging Multiple Targets.
If you use the ||s syntax, the debugger displays information about the current system.
This command also disassembles the current instruction for the current system, process, and thread.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

| (Process Status)
The pipe (|) command displays status for the specified process, or for all processes that you are currently debugging.
Do not confuse this command with the || (System Status) command.
Syntax
| Process
Parameters
Process
Specifies the process to display. If you omit this parameter, all processes that you are debugging are displayed. For more information about the syntax, see Process
Syntax.
Environment
Modes
User mode only
Targets Live, crash dump
Platforms All
Comments
You can specify processes only in user mode.
You can add a process symbol before many commands. For more information about the meaning of a pipe (|) followed by a command, see the entry for the command itself.
Unless you enabled the debugging of child processes when you started the debugging session, there is only one process that is available to the debugger.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 255 of 1651

The following examples show you how to use this command. The following command displays all processes.
2:005> |
The following command also displays all processes.
2:005> |*
The following command displays the currently active process.
2:005> |.
The following command displays the process that originally caused the exception (or that the debugger originally attached to).
2:005> |#
The following command displays process number 2.
2:005> |2
The previous command displays the following output.
0:002> |
# 0 id: 224
1 id: 228
. 2 id: 22c

name: myprog.exe
name: onechild.exe
name: anotherchild.exe

On the first line of this output, 0 is the decimal process number, 224 is the hexadecimal process ID, and Myprog.exe is the application name of the process. The period (.)
before process 2 means that this process is the current process. The number sign (#) before process 0 means that this process was the one that originally caused the exception
or that the debugger attached to.
Additional Information
For more information and other methods of displaying or controlling processes and threads, see Controlling Processes and Threads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

|s (Set Current Process)

The |s command sets or displays the current process number.
Do not confuse this command with the s (Search Memory), ~s (Change Current Processor), ~s (Set Current Thread), or ||s (Set Current System) command.
Syntax
|Process s
| s
Parameters
Process
Specifies the process to set or display. For more information about the syntax, see Process Syntax.
Environment
Modes
User mode only
Targets Live, crash dump
Platforms All
Comments
You can specify processes only in user mode.
If you use the |s syntax, the debugger displays information about the current process.
This command also disassembles the current instruction for the current system, process, and thread.
Additional Information
For more information about other methods of displaying or controlling processes and threads, see Controlling Processes and Threads.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 256 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

~ (Thread Status)
The tilde (~) command displays status for the specified thread or for all threads in the current process.
Syntax
~ Thread
Parameters
Thread
Specifies the thread to display. If you omit this parameter, all threads are displayed. For more information about the syntax, see Thread Syntax.
Environment
Modes
User mode only
Targets Live, crash dump
Platforms All
Comments
You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor.
You can add a thread symbol before many commands. For more information about the meaning of a tilde (~) followed by a command, see the entry for the command itself.
The following examples show you how to use this command. The following command displays all threads.
0:001> ~
The following command also displays all threads.
0:001> ~*
The following command displays the currently active thread.
0:001> ~.
The following command displays the thread that originally caused the exception (or that was active when the debugger attached to the process).
0:001> ~#
The following command displays thread number 2.
0:001> ~2
The previous command displays the following output.
0:001> ~
0 id: 4dc.470 Suspend: 0 Teb 7ffde000 Unfrozen
. 1 id: 4dc.534 Suspend: 0 Teb 7ffdd000 Unfrozen
# 2 id: 4dc.5a8 Suspend: 0 Teb 7ffdc000 Unfrozen
On the first line of this output, 0 is the decimal thread number, 4DC is the hexadecimal process ID, 470 is the hexadecimal thread ID, 0x7FFDE000 is the address of the TEB,
and Unfrozen is the thread status. The period (.) before thread 1 means this thread is the current thread. The number sign (#) before thread 2 means this thread was the one
that originally caused the exception or it was active when the debugger attached to the process.
Additional Information
For more information and other methods of displaying or controlling processes and threads, see Controlling Processes and Threads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

~n (Suspend Thread)
The ~n command suspends execution of the specified thread.
Do not confuse this command with the n (Set Number Base) command.
Syntax
~Thread n
Parameters
Thread
Specifies the thread or threads to suspend. For more information about the syntax, see Thread Syntax.
Environment
Modes
User mode only
Targets Live debugging only
Platforms All
Comments
You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor.
Every time that you use the ~n command, the thread's suspend count is increased by one.
The thread's start address is displayed when you use this command.
Additional Information
For more information about the suspend count and how suspended threads behave and for a list of other commands that control the suspending and freezing of threads, see
Controlling Processes and Threads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

~m (Resume Thread)
The ~m command resumes execution of the specified thread.
Do not confuse this command with the m (Move Memory) command.
Syntax
~Thread m
Parameters
Thread
Specifies the thread or threads to resume. For more information about the syntax, see Thread Syntax.
Environment
Modes
User mode only
Targets Live debugging only
Platforms All
Comments
You can specify threads only in user mode. In kernel mode, the tilde (~) refers to a processor.
Every time that you use the ~m command, the thread's suspend count is decreased by one.
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 260 of 1651

Page 263 of 1651

al (List Aliases)
The al command displays a list of all currently defined user-named aliases.
Syntax
al
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The al command lists all user-named aliases. But this command does not list fixed-name aliases ($u0 to $u9).
Additional Information
For more information about how to use aliases, see Using Aliases.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

as, aS (Set Alias)

The as and aS commands define a new alias or redefine an existing one.
Syntax
as
aS
aS
as
as
as
as
as
as
aS
as

Name EquivalentLine
Name EquivalentPhrase
Name "EquivalentPhrase"
/e Name EnvironmentVariable
/ma Name Address
/mu Name Address
/msa Name Address
/msu Name Address
/x Name Expression
/f Name File
/c Name CommandString

Parameters
Name
Specifies the alias name. This name can be any text string that does not contain a space or the ENTER keystroke and does not begin with "al", "as", "aS", or "ad". Name
is case sensitive.
EquivalentLine
Specifies the alias equivalent. EquivalentLine is case sensitive. You must add at least one space between Name and EquivalentLine. The number of spaces between these
two parameters is not important. The alias equivalent never contains leading spaces. After these spaces, EquivalentLine includes the rest of the line. Semicolons,
quotation marks, and spaces are treated as literal characters, and trailing spaces are included.
EquivalentPhrase
Specifies the alias equivalent. EquivalentPhrase is case sensitive. You must add at least one space between Name and EquivalentPhrase. The number of spaces between
these two parameters is not important. The alias equivalent never contains leading spaces.
You can enclose EquivalentPhrase in quotation marks ("). Regardless of whether you use quotation marks, EquivalentPhrase can contain spaces, commas, and single
quotation marks ('). If you enclose EquivalentPhrase in quotation marks, it can include semicolons, but not additional quotation marks. If you do not enclose
EquivalentPhrase in quotation marks, it can include quotation marks in any location other than the first character, but it cannot include semicolons. Trailing spaces are
included regardless of whether you use quotation marks.
/e
Sets the alias equivalent equal to the environment variable that EnvironmentVariable specifies.
EnvironmentVariable
Specifies the environment variable that is used to determine the alias equivalent. The debugger's environment is used, not the target's. If you started the debugger at a
Command Prompt window, the environment variables in that window are used.
/ma
Sets the alias equivalent equal to the null-terminated ASCII string that begins at Address.
/mu
Sets the alias equivalent equal to the null-terminated Unicode string that begins at Address.
/msa
Sets the alias equivalent equal to the ANSI_STRING structure that is located at Address.
/msu
Sets the alias equivalent equal to the UNICODE_STRING that is structure located at Address.
Address

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 264 of 1651

Specifies the location of the virtual memory that is used to determine the alias equivalent.
/x
Sets the alias equivalent equal to the 64-bit value of Expression.
Expression
Specifies the expression to evaluate. This value becomes the alias equivalent. For more information about the syntax, see Numerical Expression Syntax.
/f
Sets the alias equivalent equal to the contents of the File file. You should always use the /f switch together with aS, not with as.
File
Specifies the file whose contents become the alias equivalent. File can contain spaces, but you should never enclose File in quotation marks. If you specify an invalid
file, you receive an "Out of memory" error message.
/c
Sets the alias equivalent equal to the output of the commands that CommandString specify. The alias equivalent includes carriage returns if they are present within the
command display and a carriage return at the end of the display of each command (even if you specify only one command).
CommandString
Specifies the commands whose outputs become the alias equivalent. This string can include any number of commands that are separated by semicolons.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you do not use any switches, the as command uses the rest of the line as the alias equivalent.
You can end the aS command by a semicolon. This technique is useful in a script when you have to put all commands on a single line. Note that if the portion of the line after
the semicolon requires expansion of the alias, you must enclose that second portion of the line in a new block. The following example produces the expected output, 0x6.
0:001> aS /x myAlias 5 + 1; .block{.echo myAlias}
0x6
If you omit the new block, you do not get the expected output. That is because the expansion of a newly set alias does not happen until a new code block is entered. In the
following example, the new block is omitted, and the output is the text "myAlias" instead of the expected value 0x6.
0:001> aS /x myAlias 5 + 1; .echo myAlias
myAlias
For more information about using aliases in scripts, see Using Aliases.
If you use a /e, /ma, /mu, /msa, /msu, or /x switch, the as and aS commands work the same and the command ends if a semicolon is encountered.
If Name is already the name of an existing alias, that alias is redefined.
You can use the as or aS command to create or change any user-named alias. But you cannot use the command to control a fixed-name alias ($u0 to $u9).
You can use the /ma, /mu, /msa, /msu, /f, and /c switches to create an alias that contains carriage returns. However, you cannot use an alias that contains carriage returns to
execute multiple commands in sequence. Instead, you must use semicolons.
Additional Information
For more information about how to use aliases, see Using Aliases.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ba (Break on Access)
The ba command sets a processor breakpoint (often called, less accurately, a data breakpoint). This breakpoint is triggered when the specified memory is accessed.
Syntax
User-Mode
[~Thread] ba[ID] Access Size [Options] [Address [Passes]] ["CommandString"]
Kernel-Mode
ba[ID] Access Size [Options] [Address [Passes]] ["CommandString"]
Parameters
Thread
Specifies the thread that the breakpoint applies to. For more information about syntax, see Thread Syntax. You can specify threads only in user mode.
ID
Specifies an optional number that identifies the breakpoint. If you do not specify ID, the first available breakpoint number is used. You cannot add space between ba and

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 265 of 1651

the ID number. Each processor supports only a limited number of processor breakpoints, but there is no restriction on the value of the ID number. If you enclose ID in
square brackets ([]), ID can include any expression. For more information about the syntax, see Numerical Expression Syntax.
Access
Specifies the type of access that satisfies the breakpoint. This parameter can be one of the following values.
Option
Action
e (execute) Breaks into the debugger when the CPU retrieves an instruction from the specified address.
r
Breaks into the debugger when the CPU reads or writes at the specified address.
(read/write)
w (write)
Breaks into the debugger when the CPU writes at the specified address.
i (i/o)
(Microsoft Windows XP and later versions, kernel mode only, x86-based systems only) Breaks into the debugger when the I/O port at the specified Address
is accessed.
You cannot add space between Access and Size.
Note On Windows Server 2003 with Service Pack 1 (SP1), on an Itanium-based computer that uses WOW64 to emulate x86, processor breakpoints do not work with the
execute option but they do work with the read and write options.
Size
Specifies the size of the location, in bytes, to monitor for access. On an x86-based processor, this parameter can be 1, 2, or 4. However, if Access equals e, Size must be 1.
On an x64-based processor, this parameter can be 1, 2, 4, or 8. However, if Access equals e, Size must be 1.
On an Itanium-based processor, this parameter can be any power of 2, from 1 to 0x80000000.
You cannot add space between Access and Size.
Options
Specifies breakpoint options. You can use any number of the following options, except as indicated:
/1
Creates a "one-shot" breakpoint. After this breakpoint is triggered, the breakpoint is permanently removed from the breakpoint list.
/f PredNum
(Itanium only, user mode only) Specifies a predicate number. The breakpoint is predicated with the corresponding predicate register (for example, bp /f 4 address
sets a breakpoint that is predicated with the p4 predicate register). For more information about predicate registers, see Itanium Architecture.
/p EProcess
(Kernel mode only) Specifies a process that is associated with this breakpoint. EProcess should be the actual address of the EPROCESS structure, not the PID. The
breakpoint is triggered only if it is encountered in the context of this process.
/t EThread
(Kernel mode only) Specifies a thread that is associated with this breakpoint. EThread should be the actual address of the ETHREAD structure, not the thread ID.
The breakpoint is triggered only if it is encountered in the context of this thread. If you use /p EProcess and /t EThread , you can enter them in either order.
/c MaxCallStackDepth
Causes the breakpoint to be active only when the call stack depth is less than MaxCallStackDepth. You cannot combine this option together with /C.
/C MinCallStackDepth
Causes the breakpoint to be active only when the call stack depth is larger than MinCallStackDepth. You cannot combine this option together with /c.
Address
Specifies any valid address. If the application accesses memory at this address, the debugger stops execution and displays the current values of all registers and flags.
This address must be an offset and suitably aligned to match the Size parameter. (For example, if Size is 4, Address must be a multiple of 4.) If you omit Address, the
current instruction pointer is used. For more information about the syntax, see Address and Address Range Syntax.
Passes
Specifies the number of times the breakpoint is passed by until it activates. This number can be any 16-bit value. The number of times the program counter passes
through this point without breaking is one less than the value of this number. Therefore, omitting this number is the same as setting it equal to 1. Note also that this
number counts only the times that the application executes past this point. Stepping or tracing past this point does not count. After the full count is reached, you can reset
this number only by clearing and resetting the breakpoint.
CommandString
Specifies a list of commands to execute every time that the breakpoint is encountered the specified number of times. These commands are executed only if the breakpoint
is hit after you issue a g (Go) command, instead of after a t (Trace) or p (Step) command. Debugger commands in CommandString can include parameters.
You must enclose this command string in quotation marks, and you should separate multiple commands by semicolons. You can use standard C control characters (such
as \n and \"). Semicolons that are contained in second-level quotation marks (\") are interpreted as part of the embedded quoted string.
This parameter is optional.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The debugger uses the ID number to refer to the breakpoint in later bc (Breakpoint Clear), bd (Breakpoint Disable), and be (Breakpoint Enable) commands.
Use the bl (Breakpoint List) command to list all existing breakpoints, their ID numbers, and their status.
Use the .bpcmds (Display Breakpoint Commands) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them.
Each processor breakpoint has a size associated with it. For example, a w (write) processor breakpoint could be set at the address 0x70001008 with a size of four bytes. This
would monitor the block of addresses from 0x70001008 to 0x7000100B, inclusive. If this block of memory is written to, the breakpoint will be triggered.
It can happen that the processor performs an operation on a memory region that overlaps with, but is not identical to, the specified region. In this example, a single write
operation that includes the range 0x70001000 to 0x7000100F, or a write operation that includes only the byte at 0x70001009, would be an overlapping operation. In such a
situation, whether the breakpoint is triggered is processor-dependent. You should consult the processor manual for specific details. To take one specific instance, on an x86
processor, a read or write breakpoint is triggered whenever the accessed range overlaps the breakpoint range.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 266 of 1651

Similarly, if an e (execute) breakpoint is set on the address 0x00401003, and then a two-byte instruction spanning the addresses 0x00401002 and 0x00401003 is executed, the
result is processor-dependent. Again, consult the processor architecture manual for details.
The processor distinguishes between breakpoints set by a user-mode debugger and breakpoints set by a kernel-mode debugger. A user-mode processor breakpoint does not
affect any kernel-mode processes. A kernel-mode processor breakpoint might or might not affect a user-mode process, depending on whether the user-mode code is using the
debug register state and whether there is a user-mode debugger that is attached.
To apply the current process' existing data breakpoints to a different register context, use the .apply_dbp (Apply Data Breakpoint to Context) command.
On a multiprocessor computer, each processor breakpoint applies to all processors. For example, if the current processor is 3 and you use the command ba e1 MyAddress
to put a breakpoint at MyAddress, any processor not only processor 3 that executes at that address triggers the breakpoint. (This holds for software breakpoints as well.)
You cannot create multiple processor breakpoints at the same address that differ only in their CommandString values. However, you can create multiple breakpoints at the
same address that have different restrictions (for example, different values of the /p, /t, /c, and /C options).
For more details on processor breakpoints, and additional restrictions that apply to them, see Processor Breakpoints (ba Breakpoints).
The following examples show the ba command. The following command sets a breakpoint for read access on 4 bytes of the variable myVar.
0:000> ba r4 myVar
The following command adds a breakpoint on all serial ports with addresses from 0x3F8 through 0x3FB. This breakpoint is triggered if anything is read or written to these
ports.
kd> ba i4 3f8
Additional Information
For more information on processor breakpoints, see Processor Breakpoints (ba Breakpoints). For more information about and examples of using breakpoints, other breakpoint
commands and methods of controlling breakpoints, and information about how to set breakpoints in user space from a kernel debugger, see Using Breakpoints. For more
information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

bc (Breakpoint Clear)
The bc command permanently removes previously set breakpoints from the system.
Syntax
bc Breakpoints
Parameters
Breakpoints
Specifies the ID numbers of the breakpoints to remove. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can
specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (*) to indicate all breakpoints. If you want to use a numeric expression for an ID, enclose
it in brackets ([]). If you want to use a string with wildcard characters to match a breakpoint's symbolic name, enclose it in quotation marks ( " " ).
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
Use the bl (Breakpoint List) command to list all existing breakpoints, their ID numbers, and their status.
Use the .bpcmds (Display Breakpoint Commands) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them.
Additional Information
For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a
kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 267 of 1651

bd (Breakpoint Disable)
The bd command disables, but does not delete, previously set breakpoints.
Syntax
bd Breakpoints
Parameters
Breakpoints
Specifies the ID numbers of the breakpoints to disable. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can
specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (*) to indicate all breakpoints. If you want to use a numeric expression for an ID, enclose
it in brackets ([]). If you want to use a string with wildcard characters to match a breakpoint's symbolic name, enclose it in quotation marks ( " " ).
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
When a breakpoint is disabled, the system does not check whether the conditions that are specified in the breakpoint are valid.
Use the be (Breakpoint Enable) command to re-enable a disabled breakpoint.
Use the bl (Breakpoint List) command to list all existing breakpoints, their ID numbers, and their status.
Use the .bpcmds (Display Breakpoint Commands) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them.
Additional Information
For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user space from a
kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

be (Breakpoint Enable)
The be command restores one or more breakpoints that were previously disabled.
Syntax
be Breakpoints
Parameters
Breakpoints
Specifies the ID numbers of the breakpoints to enable. You can specify any number of breakpoints. You must separate multiple IDs by spaces or commas. You can
specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (*) to indicate all breakpoints. If you want to use a numeric expression for an ID, enclose
it in brackets ([]). If you want to use a string with wildcard characters to match a breakpoint's symbolic name, enclose it in quotation marks ( " " ).
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
Use the bl (Breakpoint List) command to list all existing breakpoints, their ID numbers, and their status.
Use the .bpcmds (Display Breakpoint Commands) command to list all existing breakpoints, their ID numbers, and the commands that were used to create them.
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 268 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

bl (Breakpoint List)
The bl command lists information about existing breakpoints.
Syntax
bl [/L] [Breakpoints]
Parameters
/L
Forces bl to always display breakpoint addresses instead of showing source file and line numbers.
Breakpoints
Specifies the ID numbers of the breakpoints to list. If you omit Breakpoints, the debugger lists all breakpoints. You can specify any number of breakpoints. You must
separate multiple IDs by spaces or commas. You can specify a range of breakpoint IDs by using a hyphen (-). You can use an asterisk (*) to indicate all breakpoints. If
you want to use a numeric expression for an ID, enclose it in brackets ([]). If you want to use a string with wildcard characterss to match a breakpoint's symbolic name,
enclose it in quotation marks ( " " ).
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The following example shows the output from a bl command.
0:000> bl
0 e 010049e0

0001 (0001)

0:**** stst!main

For each breakpoint, the command displays the following information:

The breakpoint ID. This ID is a decimal number that you can use to refer to the breakpoint in later commands.
The breakpoint status. The status can be e (enabled) or d (disabled).
(Unresolved breakpoints only) The letter "u" appears if the breakpoint is unresolved. That is, the breakpoint does not match a symbolic reference in any currently loaded
module. For information about these breakpoints, see Unresolved Breakpoints (bu Breakpoints).
The virtual address or symbolic expression that makes up the breakpoint location. If you enabled source line number loading, the bl command displays file and line
number information instead of address offsets. If the breakpoint is unresolved, the address is omitted here and appears at the end of the listing instead.
(Data breakpoints only) Type and size information are displayed for data breakpoints. The types can be e (execute), r (read/write), w (write), or i (input/output). These
types are followed with the size of the block, in bytes. For information about these breakpoints, see Processor Breakpoints (ba Breakpoints).
The number of passes that remain until the breakpoint is activated, followed by the initial number of passes in parentheses. For more information about this kind of
breakpoint, see the description of the Passes parameter in bp, bu, bm (Set Breakpoint).
The associated process and thread. If thread is given as three asterisks ("***"), this breakpoint is not a thread-specific breakpoint.
The module and function, with offset, that correspond to the breakpoint address. If the breakpoint is unresolved, the breakpoint address appears here instead, in
parentheses. If the breakpoint is set on a valid address but symbol information is missing, this field is blank.
The command that is automatically executed when this breakpoint is hit. This command is displayed in quotation marks.

If you are not sure what command was used to set an existing breakpoint, use .bpcmds (Display Breakpoint Commands) to list all breakpoints along with the commands
that were used to create them.
Example
The following example shows the output of a bl command.
0:000> bl
0 e 010049e0

0001 (0001)

0:**** stst!main

This output contains the following information:

The breakpoint ID is 0.
The breakpoint status is e (enabled).
The breakpoint is not unresolved (there is no u in the output).
The virtual address of the breakpoint is 010049e0.
The breakpoint is active on the first pass through the code and the code has not yet been executed under the debugger. This information is indicated by a value of 1
(0001) in the "passes remaining" counter and a value of 1 ((0001)) in the initial passes counter.
This breakpoint is not a thread-specific breakpoint (****).
The breakpoint is set on main in the stst module.

Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 269 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

bp, bu, bm (Set Breakpoint)

The bp, bu, and bm commands set one or more software breakpoints. You can combine locations, conditions, and options to set different kinds of software breakpoints.
Syntax
User-Mode
[~Thread] bp[ID] [Options] [Address [Passes]] ["CommandString"]
[~Thread] bu[ID] [Options] [Address [Passes]] ["CommandString"]
[~Thread] bm [Options] SymbolPattern [Passes] ["CommandString"]
Kernel-Mode
bp[ID] [Options] [Address [Passes]] ["CommandString"]
bu[ID] [Options] [Address [Passes]] ["CommandString"]
bm [Options] SymbolPattern [Passes] ["CommandString"]
Parameters
Thread
Specifies the thread that the breakpoint applies to. For more information about the syntax, see Thread Syntax. You can specify threads only in user mode. If you do not
specify a thread, the breakpoint applies to all threads.
ID
Specifies a decimal number that identifies a breakpoint.
The debugger assigns the ID when it creates the breakpoint, but you can change it by using the br (Breakpoint Renumber) command. You can use the ID to refer to the
breakpoint in later debugger commands. To display the ID of a breakpoint, use the bl (Breakpoint List) command.
When you use ID in a command, do not type a space between the command (bp or bu) and the ID number.
The ID parameter is always optional. If you do not specify ID, the debugger uses the first available breakpoint number. In kernel mode, you can set only 32 breakpoints.
In user mode, you can set any number of breakpoints. In either case, there is no restriction on the value of the ID number. If you enclose ID in square brackets ([]), ID can
include any expression. For more information about the syntax, see Numerical Expression Syntax.
Options
Specifies breakpoint options. You can specify any number of the following options, except as indicated:
/1
Creates a "one-shot" breakpoint. After this breakpoint is triggered, it is deleted from the breakpoint list.
/f PredNum
(Itanium-based only, user mode only) Specifies a predicate number. The breakpoint is predicated with the corresponding predicate register. (For example,
bp /f 4 address sets a breakpoint that is predicated with the p4 predicate register.) For more information about predicate registers, see Itanium Architecture.
/p EProcess
(Kernel-mode only) Specifies a process that is associated with this breakpoint. EProcess should be the actual address of the EPROCESS structure, not the PID. The
breakpoint is triggered only if it is encountered in the context of this process.
/t EThread
(Kernel-mode only) Specifies a thread that is associated with this breakpoint. EThread should be the actual address of the ETHREAD structure, not the thread ID.
The breakpoint is triggered only if it is encountered in the context of this thread. If you use /p EProcess and /t EThread, you can enter them in any order.
/c MaxCallStackDepth
Activates the breakpoint only when the call stack depth is less than MaxCallStackDepth. You cannot use this option together with /C.
/C MinCallStackDepth
Activates the breakpoint only when the call stack depth is larger than MinCallStackDepth. You cannot use this option together with /c.
/a
(For bm only) Sets breakpoints on all of the specified locations, whether they are in data space or code space. Because breakpoints on data can cause program
failures, use this option only on locations that are known to be safe.
/d
(For bm only) Converts the breakpoint locations to addresses. Therefore, if the code is moved, the breakpoints remain at the same address, instead of being set
according to SymbolPattern. Use /d to avoid reevaluating changes to breakpoints when modules are loaded or unloaded.
/(
(For bm only) Includes parameter list information in the symbol string that SymbolString defines.
This feature enables you to set breakpoints on overloaded functions that have the same name but different parameter lists. For example, bm /( myFunc sets
breakpoints on both myFunc(int a) and myFunc(char a). Without "/(", a breakpoint that is set on myFunc fails because it does not indicate which myFunc
function the breakpoint is intended for.
Address
Specifies the first byte of the instruction where the breakpoint is set. If you omit Address, the current instruction pointer is used. For more information about the syntax,
see Address and Address Range Syntax.
Passes
Specifies the number of the execution pass that the breakpoint is activated on. The debugger skips the breakpoint location until it reaches the specified pass. The value of
Passes can be any 16-bit or 32-bit value.
By default, the breakpoint is active the first time that the application executes the code that contains the breakpoint location. This default situation is equivalent to a value
of 1 for Passes. To activate the breakpoint only after the application executes the code at least one time, enter a value of 2 or more. For example, a value of 2 activates the
breakpoint the second time that the code is executed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 270 of 1651

This parameter creates a counter that is decremented on each pass through the code. To see the initial and current values of the Passes counter, use bl (Breakpoint List).
The Passes counter is decremented only when the application executes past the breakpoint in response to a g (Go) command. The counter is not decremented if you are
stepping through the code or tracing past it. When the Passes counter reaches 1, you can reset it only by clearing and resetting the breakpoint.
CommandString
Specifies a list of commands that are executed every time that the breakpoint is encountered the specified number of times. You must enclose the CommandString
parameter in quotation marks. Use semicolons to separate multiple commands.
Debugger commands in CommandString can include parameters. You can use standard C-control characters (such as \n and \"). Semicolons that are contained in secondlevel quotation marks (\") are interpreted as part of the embedded quoted string.
The CommandString commands are executed only if the breakpoint is reached while the application is executing in response to a g (Go) command. The commands are
not executed if you are stepping through the code or tracing past this point.
Any command that resumes program execution after a breakpoint (such as g or t) ends the execution of the command list.
SymbolPattern
Specifies a pattern. The debugger tries to match this pattern to existing symbols and to set breakpoints on all pattern matches. SymbolPattern can contain a variety of
wildcard characters and specifiers. For more information about this syntax, see String Wildcard Syntax. Because these characters are being matched to symbols, the
match is not case sensitive, and a single leading underscore (_) represents any quantity of leading underscores.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The bp, bu, and bm commands set new breakpoints, but they have different characteristics:

The bp (Set Breakpoint) command sets a new breakpoint at the address of the breakpoint location that is specified in the command. If the debugger cannot resolve the
address expression of the breakpoint location when the breakpoint is set, the bp breakpoint is automatically converted to a bu breakpoint. Use a bp command to create a
breakpoint that is no longer active if the module is unloaded.
The bu (Set Unresolved Breakpoint) command sets a deferred or unresolved breakpoint. A bu breakpoint is set on a symbolic reference to the breakpoint location that
is specified in the command (not on an address) and is activated whenever the module with the reference is resolved. For more information about these breakpoints, see
Unresolved Breakpoints (bu Breakpoints).
The bm (Set Symbol Breakpoint) command sets a new breakpoint on symbols that match a specified pattern. This command can create more than one breakpoint. By
default, after the pattern is matched, bm breakpoints are the same as bu breakpoints. That is, bm breakpoints are deferred breakpoints that are set on a symbolic
reference. However, a bm /d command creates one or more bp breakpoints. Each breakpoint is set on the address of a matched location and does not track module state.

If you are not sure what command was used to set an existing breakpoint, use .bpcmds (Display Breakpoint Commands) to list all breakpoints along with the commands
that were used to create them.
There are three primary differences between bp breakpoints and bu breakpoints:

The bm command is useful when you want to use wildcard characters in the symbol pattern for a breakpoint. The bm SymbolPattern syntax is equivalent to using
x SymbolPattern and then using bu on each result. For example, to set breakpoints on all of the symbols in the Myprogram module that begin with the string "mem," use the
following command.
0:000> bm myprogram!mem*
4: 0040d070 MyProgram!memcpy
5: 0040c560 MyProgram!memmove
6: 00408960 MyProgram!memset
Because the bm command sets software breakpoints (not processor breakpoints), it automatically excludes data location when it sets breakpoints to avoid corrupting the data.
It is possible to specify a data address rather than a program address when using the bp or bm /a commands. However, even if a data location is specified, these commands
create software breakpoints, not processor breakpoints. If a software breakpoint is placed in program data instead of executable code, it can lead to data corruption. Therefore
you should use these commands in a data location only if you are certain that the memory stored in that location will be used as executable code and not as program data.
Otherwise, you should use the ba (Break on Access) command instead. For more details, see Processor Breakpoints (ba Breakpoints).
For details on how to set a breakpoint on a location specified by a more complicated syntax, such as a member of a C++ public class, or an arbitrary text string containing
otherwise restricted characters, see Breakpoint Syntax.
If a single logical source line spans multiple physical lines, the breakpoint is set on the last physical line of the statement or call. If the debugger cannot set a breakpoint at the
requested position, it puts the breakpoint in the next allowed position.
If you specify Thread, breakpoints are set on the specified threads. For example, the ~*bp command sets breakpoints on all threads, ~#bp sets a breakpoint on the thread that
causes the current exception, and ~123bp sets a breakpoint on thread 123. The ~bp and ~.bp commands both set a breakpoint on the current thread.
When you are debugging a multiprocessor system in kernel mode, breakpoints that you set by using bp or ba (Break on Access) apply to all processors. For example, if the
current processor is 3 and you type bp MemoryAddress to put a breakpoint at MemoryAddress. Any processor that is executing at that address (not only processor 3) causes
a breakpoint trap.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 271 of 1651

The bp, bu, and bm commands set software breakpoints by replacing the processor instruction with a break instruction. To debug read-only code or code that cannot be
changed, use a ba e command, where e represents execute-only access.
Examples
The following command sets a breakpoint 12 bytes past the beginning of the function MyTest. This breakpoint is ignored for the first six passes through the code, but
execution stops on the seventh pass through the code.
0:000> bp MyTest+0xb 7
The following command sets a breakpoint at RtlRaiseException, displays the eax register, displays the value of the symbol MyVar, and continues.
kd> bp ntdll!RtlRaiseException "r eax; dt MyVar; g"
The following two bm commands set three breakpoints. When the commands are executed, the displayed result does not distinguish between breakpoints created with the /d
switch and those created without it. The .bpcmds (Display Breakpoint Commands) can be used to distinguish between these two types. If the breakpoint was created by bm
without the /d switch, the .bpcmds display indicates the breakpoint type as bu, followed by the evaluated symbol enclosed in the @!"" token (which indicates it is a literal
symbol and not a numeric expression or register). If the breakpoint was created by bm with the /d switch, the .bpcmds display indicates the breakpoint type as bp.
0:000> bm myprog!openf*
0: 00421200 @!"myprog!openFile"
1: 00427800 @!"myprog!openFilter"
0:000> bm /d myprog!closef*
2: 00421600 @!"myprog!closeFile"
0:000> .bpcmds
bu0 @!"myprog!openFile";
bu1 @!"myprog!openFilter";
bp2 0x00421600 ;
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

br (Breakpoint Renumber)
The br command renumbers one or more breakpoints.
Syntax
br OldID NewID [OldID2 NewID2 ...]
Parameters
OldID
Specifies the current ID number of the breakpoint.
NewID
Specifies a new number that becomes the ID of the breakpoint.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
You can use the br command to renumber any number of breakpoints at the same time. For each breakpoint, list the old ID and the new ID, in that order, as parameters to br.
If there is already a breakpoint with an ID equal to NewID, the command fails and an error message is displayed.
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 272 of 1651

December 09, 2009

Debugging Tools for Windows

bs (Update Breakpoint Command)

The bs command changes the command executed when the specified breakpoint is encountered.
Syntax
bs ID ["CommandString"]
Parameters
ID
Specifies the ID number of the breakpoint.
CommandString
Specifies the new list of commands to be executed every time that the breakpoint is encountered. You must enclose the CommandString parameter in quotation marks.
Use semicolons to separate multiple commands.
Debugger commands in CommandString can include parameters. You can use standard C-control characters (such as \n and \"). Semicolons that are contained in secondlevel quotation marks (\") are interpreted as part of the embedded quoted string.
The CommandString commands are executed only if the breakpoint is reached while the application is executing in response to a g (Go) command. The commands are
not executed if you are stepping through the code or tracing past this point.
Any command that resumes program execution after a breakpoint (such as g or t) ends the execution of the command list.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
If the CommandString is not specified, any commands already set on the breakpoint are removed.
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

bsc (Update Conditional Breakpoint)

The bsc command changes the condition under which a breakpoint occurs or changes the command executed when the specified conditional breakpoint is encountered.
Syntax
bsc ID Condition ["CommandString"]
Parameters
ID
Specifies the ID number of the breakpoint.
Condition
Specifies the condition under which the breakpoint should be triggered.
CommandString
Specifies the new list of commands to be executed every time that the breakpoint is encountered. You must enclose the CommandString parameter in quotation marks.
Use semicolons to separate multiple commands.
Debugger commands in CommandString can include parameters. You can use standard C-control characters (such as \n and \"). Semicolons that are contained in secondlevel quotation marks (\") are interpreted as part of the embedded quoted string.
The CommandString commands are executed only if the breakpoint is reached while the application is executing in response to a g (Go) command. The commands are
not executed if you are stepping through the code or tracing past this point.
Any command that resumes program execution after a breakpoint (such as g or t) ends the execution of the command list.
Environment
Modes

User mode, kernel mode

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 273 of 1651

Targets Live debugging only

Platforms All
Comments
If the CommandString is not specified, any commands already set on the breakpoint are removed.
The same effect can be achieved by using the bs (Update Breakpoint Command) command with the following syntax:
bs ID "j Condition 'CommandString'; 'gc'"
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and how to set breakpoints in user
space from a kernel debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

c (Compare Memory)
The c command compares the values held in two memory areas.
Syntax
c Range Address
Parameters
Range
The first of the two memory ranges to be compared. For more syntax details, see Address and Address Range Syntax.
Address
The starting address of the second memory range to be compared. The size of this range will be the same as that specified for the first range. For more syntax details, see
Address and Address Range Syntax.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
If the two areas are not identical, the debugger will display all memory addresses in the first range where they do not agree.
As an example, consider the following code:
void main()
{
char rgBuf1[100];
char rgBuf2[100];
memset(rgBuf1, 0xCC, sizeof(rgBuf1));
memset(rgBuf2, 0xCC, sizeof(rgBuf2));
rgBuf1[42] = 0xFF;
}
To compare rgBuf1 and rgBuf2, use either of the following commands:
0:000> c rgBuf1 (rgBuf1+0n100) rgBuf2
0:000> c rgBuf1 L 0n100 rgBuf2
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 274 of 1651

d, da, db, dc, dd, dD, df, dp, dq, du, dw, dW, dyb, dyd (Display Memory)
The d* commands display the contents of memory in the given range.
Syntax
d{a|b|c|d|D|f|p|q|u|w|W} [Options] [Range]
dy{b|d} [Options] [Range]
d [Options] [Range]
Parameters
Options
Specifies one or more display options. Any of the following options can be included, except that no more than one /p* option can be indicated:
/c Width
Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type.
/p
(Kernel-mode only) Uses physical memory addresses for the display. The range specified by Range will be taken from physical memory rather than virtual memory.
/p[c]
(Kernel-mode only) Same as /p, except that cached memory will be read. The brackets around c must be included.
/p[uc]
(Kernel-mode only) Same as /p, except that uncached memory will be read. The brackets around uc must be included.
/p[wc]
(Kernel-mode only) Same as /p, except that write-combined memory will be read. The brackets around wc must be included.
Range
Specifies the memory area to display. For more syntax details, see Address and Address Range Syntax. If you omit Range, the command will display memory starting at
the ending location of the last display command. If Range is omitted and no previous display command has been used, the display begins at the current instruction
pointer.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
Each line displayed will include the address of the first byte in the line followed by the contents of memory at that and following locations.
If you omit Range, the command will display memory starting at the ending location of the last display command. This allows you to continuously scan through memory.
This command exists in the following forms. The second characters of the dd, dD, dw, and dW commands are case-sensitive, as are the third characters of the dyb and dyd
commands.
Command
Display
d
This displays data in the same format as the most recent d* command. If no previous d* command has been issued, d has the same effect as db.
Notice that d repeats the most recent command that began with d. This includes dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu, dds, dps, dqs, ds, dS, dg, dl, dt,
and dv, as well as the display commands on this page. If the parameters given after d are not appropriate, errors may result.
da

ASCII characters.
Each line displays up to 48 characters. The display continues until the first null byte or until all characters in range have been displayed. All nonprintable
characters, such as carriage returns and line feeds, are displayed as periods (.).

Byte values and ASCII characters.

Each display line shows the address of the first byte in the line, followed by up to 16 hexadecimal byte values. The byte values are immediately followed by the
corresponding ASCII values. The eighth and ninth hexadecimal values are separated by a hyphen (-). All nonprintable characters, such as carriage returns and
line feeds, are displayed as periods (.).
The default count is 128 bytes.

Double-word values (4 bytes) and ASCII characters.

Each display line shows the address of the first word in the line and up to eight hexadecimal word values, as well as their ASCII equivalent.
The default count is 32 DWORDs (128 bytes).

Double-word values (4 bytes).

The default count is 32 DWORDs (128 bytes).

Double-precision floating-point numbers (8 bytes).

The default count is 15 numbers (120 bytes).

Single-precision floating-point numbers (4 bytes).

The default count is 16 numbers (64 bytes).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 275 of 1651

Pointer-sized values. This command is equivalent to dd or dq, depending on whether the target computer's processor architecture is 32-bit or 64-bit, respectively.
The default count is 32 DWORDs or 16 quad-words (128 bytes).

Quad-word values (8 bytes).

The default count is 16 quad-words (128 bytes).

Unicode characters.
Each line displays up to 48 characters. The display continues until the first null byte or until all characters in range have been displayed. All nonprintable
characters, such as carriage returns and line feeds, are displayed as periods (.).

Word values (2 bytes).

Each display line shows the address of the first word in the line and up to eight hexadecimal word values.
The default count is 64 words (128 bytes).

Word values (2 bytes) and ASCII characters.

Each display line shows the address of the first word in the line and up to eight hexadecimal word values.
The default count is 64 words (128 bytes).

dyb

Binary values and byte values.

The default count is 32 bytes.

dyd

Binary values and double-word values (4 bytes).

The default count is 8 DWORDs (32 bytes).

If you attempt to display an invalid address, its contents are shown as question marks (?).
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, dqu (Display Referenced Memory)
The dda, ddp, ddu, dpa, dpp, dpu, dqa, dqp, and dqu commands display the pointer at the specified location, dereference that pointer, and then display the memory at the
resulting location in a variety of formats.
Syntax
ddp
dqp
dpp
dda
dqa
dpa
ddu
dqu
dpu

[Options]
[Options]
[Options]
[Options]
[Options]
[Options]
[Options]
[Options]
[Options]

[Range]
[Range]
[Range]
[Range]
[Range]
[Range]
[Range]
[Range]
[Range]

Parameters
Options
Specifies one or more display options. Any of the following options can be included, except that no more than one /p* option can be indicated:
/c Width
Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type. Because of the way pointers are
displayed by these commands, it is usually best to use the default of only one data column.
/p
(Kernel-mode only) Uses physical memory addresses for the display. The range specified by Range will be taken from physical memory rather than virtual memory.
/p[c]
(Kernel-mode only) Same as /p, except that cached memory will be read. The brackets around c must be included.
/p[uc]
(Kernel-mode only) Same as /p, except that uncached memory will be read. The brackets around uc must be included.
/p[wc]
(Kernel-mode only) Same as /p, except that write-combined memory will be read. The brackets around wc must be included.
Range

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 276 of 1651

Specifies the memory area to display. For more syntax details, see Address and Address Range Syntax. If you omit Range, the command will display memory starting at
the ending location of the last display command. If Range is omitted and no previous display command has been used, the display begins at the current instruction
pointer. If a simple address is given, the default range length is 128 bytes.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The second and third characters of this command are case-sensitive.
The second character of this command determines the pointer size used:
Command
Display
dd*
32-bit pointers used
dq*
64-bit pointers used
dp*
Standard pointer sizes used: 32-bit or 64-bit, depending on the target's processor architecture
The third character of this command determines how the dereferenced memory is displayed:
Command
Display
d*p
Displays the contents of the memory referenced by the pointer in DWORD or QWORD format, depending on the pointer size of the target's processor
architecture. If this value matches any known symbol, this symbol is displayed as well.
d*a
Displays the contents of the memory referenced by the pointer in ASCII character format.
d*u
Displays the contents of the memory referenced by the pointer in Unicode character format.
If line number information has been enabled, source file names and line numbers will be displayed when available.
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dds, dps, dqs (Display Words and Symbols)

The dds, dps, and dqs commands display the contents of memory in the given range. This memory is assumed to be a series of addresses in the symbol table. The
corresponding symbols are displayed as well.
Syntax
dds [Options] [Range]
dqs [Options] [Range]
dps [Options] [Range]
Parameters
Options
Specifies one or more display options. Any of the following options can be included, except that no more than one /p* option can be indicated:
/c Width
Specifies the number of columns to use in the display. If this is omitted, the default number of columns depends on the display type. Because of the way symbols are
displayed by these commands, it is usually best to use the default of only one data column.
/p
(Kernel-mode only) Uses physical memory addresses for the display. The range specified by Range will be taken from physical memory rather than virtual memory.
/p[c]
(Kernel-mode only) Same as /p, except that cached memory will be read. The brackets around c must be included.
/p[uc]
(Kernel-mode only) Same as /p, except that uncached memory will be read. The brackets around uc must be included.
/p[wc]
(Kernel-mode only) Same as /p, except that write-combined memory will be read. The brackets around wc must be included.
Range
Specifies the memory area to display. For more syntax details, see Address and Address Range Syntax. If you omit Range, the command will display memory starting at
the ending location of the last display command. If Range is omitted and no previous display command has been used, the display begins at the current instruction
pointer. If a simple address is given, the default range length is 128 bytes.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 277 of 1651

Comments
The second character of dds is case-sensitive. The third character of all these commands is case-sensitive.
The dds command displays double-word (4 byte) values like the dd command. The dqs command displays quad-word (8 byte) values like the dq command. The dps
command displays pointer-sized values (4 byte or 8 byte, depending on the target computer's architecture) like the dp command.
Each of these words is treated as an address in the symbol table. The corresponding symbol information is displayed for each word.
If line number information has been enabled, source file names and line numbers will be displayed when available.
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dg (Display Selector)
The dg command shows the segment descriptor for the specified selector.
Syntax
dg FirstSelector [LastSelector]
Parameters
FirstSelector
Specifies the hexadecimal selector value of the first selector to be displayed.
LastSelector
Specifies the hexadecimal selector value of the last selector to be displayed. If this is omitted, only one selector will be displayed.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms x86, Itanium
Comments
No more than 256 selectors can be displayed by this command.
Common selector values are:
Id
decimal hex
KGDT_NULL
0
0x00
KGDT_R0_CODE 8
0x08
KGDT_R0_DATA 16
0x10
KGDT_R3_CODE 24
0x18
KGDT_R3_DATA 32
0x20
KGDT_TSS
40
0x28
KGDT_R0_PCR
48
0x30
KGDT_R3_TEB
56
0x38
KGDT_VDM_TILE 64
0x40
KGDT_LDT
72
0x48
KGDT_DF_TSS
80
0x50
KGDT_NMI_TSS 88
0x58

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dl (Display Linked List)

The dl command displays a LIST_ENTRY or SINGLE_LIST_ENTRY linked list.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 278 of 1651

dl[b] Address MaxCount Size

Parameters
b
If this is included, the list is dumped in reverse order. (In other words, the debugger follows the Blinks instead of the Flinks.) This cannot be used with a
SINGLE_LIST_ENTRY.
Address
The starting address of the list. For more syntax details, see Address and Address Range Syntax.
MaxCount
Maximum number of elements to dump.
Size
Size of each element. This is the number of consecutive ULONG_PTRs that will be displayed for each element in the list.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
This list must be a LIST_ENTRY or SINGLE_LIST_ENTRY structure. If this is embedded in a larger structure, be sure that Address points to the linked list structure and not
to the beginning of the outer structure.
The display begins with Address. Therefore, if you are supplying the address of a pointer that points to the beginning of the list, you should disregard the first element printed.
The Address, MaxCount, and Size parameters are in the current default radix. You can use the n (Set Number Base) command or the 0x prefix to change the radix.
If the list loops back on itself, the dump will stop. If a null pointer is encountered, the dump will stop.
If you want to execute some command for each element of the list, use the !list extension.
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ds, dS (Display String)

The ds and dS commands display a STRING, ANSI_STRING, or UNICODE_STRING structure. (These commands do not display null-delimited character strings.)
Syntax
d{s|S} [/c Width] [Address]
Parameters
s
Specifies that a STRING or ANSI_STRING structure is to be displayed. (This s is case-sensitive.)
S
Specifies that a UNICODE_STRING structure is to be displayed. (This S is case-sensitive.)
/c Width
Specifies the number of characters to display on each line. This number includes null characters, which will not be visible.
Address
The memory address where the string begins. For more syntax details, see Address and Address Range Syntax. If omitted, the last address used in a display command is
assumed.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
If you want to display Unicode strings in the Locals window or Watch window of WinDbg, you need to use the .enable_unicode (Enable Unicode Display) command first.
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 279 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dt (Display Type)
The dt command displays information about a local variable, global variable or data type. This can display information about simple data types, as well as structures and
unions.
Syntax
User-Mode Syntax
dt [-DisplayOpts] [-SearchOpts] [module!]Name [[-SearchOpts] Field] [Address] [-l List]
dt [-DisplayOpts] Address [-l List]
dt -h
Kernel-Mode Syntax
[Processor] dt [-DisplayOpts] [-SearchOpts] [module!]Name [[-SearchOpts] Field] [Address] [-l List]
dt [-DisplayOpts] Address [-l List]
dt -h
Parameters
Processor
Specifies the processor that is running the process containing the information needed. For more information, see Multiprocessor Syntax. Processors can only be specified
in kernel mode.
DisplayOpts
Specifies one or more of the options given in the following table. These options are preceded by a hyphen.
Option
Description
-a
Show each array element on a new line, with its index. A total of quantity elements will be displayed. There must be no space between the a and the quantity.
[quantity] If -a is not followed by a digit, all items in the array are shown. The -a[quantity] switch should appear immediately before each type name or field name that
you want displayed in this manner.
-b
Display blocks recursively. If a displayed structure contains substructures, it is expanded recursively to arbitrary depths and displayed in full. Pointers are
expanded only if they are in the original structure, not in substructures.
-c
Compact output. All fields are displayed on one line, if possible. (When used with the -a switch, each array element takes one line rather than being
formatted as a several-line block.)
-d
When used with a Name that is ended with an asterisk, display verbose output for all types that begin with Name. If Name does not end with an asterisk,
display verbose output.
-e
Forces dt to enumerate types. This option is only needed if dt is mistakenly interpreting the Name value as an instance rather than as a type.
-i
Do not indent the subtypes.
-o
Omit offset values of the structure fields.
-p
Address is a physical address, rather than a virtual address.
-r[depth] Recursively dumps the subtype fields. If depth is given, this recursion will stop after depth levels. The depth must be a digit between 1 and 9, and there must
be no space between the r and the depth. The -r[depth] switch should appear immediately before the address.
-s size
Enumerate only those types whose size in bytes equals the value of size. The -s option is only useful when types are being enumerated. When -s is specified, e is always implied as well.
-t
Enumerate types only.
-v
Verbose output. This gives additional information such as the total size of a structure and the number of its elements. When this is used along with the -y
search option, all symbols are displayed, even those with no associated type information.
SearchOpts
Specifies one or more of the options given in the following table. These options are preceded by a hyphen.
Option
Description
-n
This indicates that the next parameter is a name. This should be used if the next item consists entirely of hexadecimal characters, because it will otherwise be
taken as an address.
-y
This indicates that the next parameter is the beginning of the name, not necessarily the entire name. When -y is included, all matches are listed, followed by
detailed information on the first match in the list. If -y is not included, only exact matches will be displayed.
module
An optional parameter specifying the module that defines this structure. If there is a local variable or type with the same name as a global variable or type, you should
include module to specify that you mean the global variable. Otherwise, the dt command will display the local variable, even if the local variable is a case-insensitive
match and the global variable is a case-sensitive match.
Name
Specifies the name of a type or global variable. If Name ends with an asterisk (*), a list of all matches is displayed. Thus, dt A* will list all data types, globals, and statics
beginning with "A", but will not display the actual instances of these types. (If the -v display option is used at the same time, all symbols will be displayed not just
those with associated type information.) You can also replace Name with a period (.) to signify that you want to repeat the most recently used value of Name. If Name
contains a space, it should be enclosed in parentheses.
Field
Specifies the field(s) to be displayed. If Field is omitted, all fields are displayed. If Field is followed by a period (.), the first-level subfields of this field will be displayed
as well. If Field is followed with a series of periods, the subfields will be displayed to a depth equal to the number of periods. Any field name followed by a period will
be treated as a prefix match, as if the -y search option was used. If Field is followed by an asterisk (*), it is treated as only the beginning of the field, not necessarily the
entire field, and all matching fields are displayed.
Address
Specifies the address of the structure to be displayed. If Name is omitted, Address must be included and must specify the address of a global variable. Address is taken to

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 280 of 1651

be a virtual address unless otherwise specified. Use the -p option to specify a physical address. Use an "at" sign ( @ ) to specify a register (for example, @eax).
List
Specifies the field name that links a linked list. The Address parameter must be included.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The dt command output will always display signed numbers in base 10, and unsigned numbers in hexadecimal.
All parameters of dt that allow symbol values also allow string wildcards. See String Wildcard Syntax for details.
The -y and -n options can precede any Name or Field. The -y option allows you to specify the beginning of the type or structure name. For example, dt -y ALLEN will
display data about the type ALLENTOWN. However, you could not display the type ALLENTOWN with dt -y A. Instead, you would have to use dt -ny A, because A is a
valid hexadecimal value and would be interpreted as an address without the -n option.
If Name indicates a structure, all fields will be displayed (for example, dt myStruct). If you only want one specific field, you can do dt myStruct myField. This displays the
member that C would call myStruct.myField. However, note that the command dt myStruct myField1 myField2 displays myStruct.myField1 and myStruct.myField2. It
does not display myStruct.myField1.myField2.
If a structure name or field is followed by a subscript, this specifies a single instance of an array. For example, dt myStruct myFieldArray[3] will display the fourth element
of the array in question. But if a type name is followed by a subscript, this specifies an entire array. For example, dt CHAR[8] myPtr will display an eight-character string.
The subscript is always taken as decimal regardless of the current radix; an 0x prefix will cause an error.
Because the command uses type information from the .pdb file, it can freely be used to debug any CPU platform.
The type information used by dt includes all type names created with typedef, including all the Windows-defined types. For example, unsigned long and char are not valid
type names, but ULONG and CHAR are. See the Microsoft Windows SDK for a full list of all Windows type names.
All types created by typedefs within your own code will be present, as long as they have actually been used in your program. However, types that are defined in your headers
but never actually used will not be stored in the .pdb symbol files and will not be accessible to the debugger. To make such a type available to the debugger, use it as the input
of a typedef statement. For example, if the following appears in your code, the structure MY_DATA will be stored in the .pdb symbol file and can be displayed by the dt
command:
typedef struct _MY_DATA {
. . .
} MY_DATA;
typedef MY_DATA *PMY_DATA;
On the other hand, the following code would not suffice because both MY_DATA and PMY_DATA are defined by the initial typedef and, therefore, MY_DATA has not
itself been used as the input of any typedef statement:
typedef struct _MY_DATA {
. . .
} MY_DATA, *PMY_DATA;
In any event, type information is included only in a full symbol file, not a symbol file that has been stripped of all private symbol information. For more information, see
Public and Private Symbols.
If you want to display unicode strings, you need to use the .enable_unicode (Enable Unicode Display) command first. You can control the display of long integers with
the .enable_long_status (Enable Long Integer Display) command.
In the following example, dt displays a global variable:
0:000> dt
+0x000
+0x004
+0x006
+0x008
+0x00c
+0x024

mt1
a
b
c
d
gn
ex

:
:
:
:
:
:

10
98 'b'
0xdd
0xabcd
[6] 0x1
0x0

In the following example, dt displays the array field gn:

0:000> dt mt1 -a gn
+0x00c gn :
[00] 0x1
[01] 0x2
[02] 0x3
[03] 0x4
[04] 0x5
[05] 0x6
The following command displays some subfields of a variable:
0:000> dt mcl1 m_t1 dpo
+0x010 dpo : DEEP_ONE

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 281 of 1651

+0x070 m_t1 : MYTYPE1

The following command displays the subfields of the field m_t1. Because the period automatically causes prefix matching, this will also display subfields of any field that
begins with "m_t1":
0:000> dt mcl1 m_t1.
+0x070 m_t1 :
+0x000 a
:
+0x004 b
:
+0x006 c
:
+0x008 d
:
+0x00c gn
:
+0x024 ex
:

0
0 ''
0x0
0x0
[6] 0x0
0x0

You could repeat this to any depth. For example, the command dt mcl1 a..c. would display all fields to depth four, such that the first field name began with a and the third
field name began with c.
Here is a more detailed example of how subfields can be displayed. First, display the Ldr field:
0:000> dt nt!_PEB Ldr 7ffdf000
+0x00c Ldr : 0x00191ea0
Now expand the pointer type field:
0:000> dt nt!_PEB Ldr Ldr. 7ffdf000
+0x00c Ldr : 0x00191ea0
+0x000 Length : 0x28
+0x004 Initialized : 0x1 ''
+0x008 SsHandle : (null)
+0x00c InLoadOrderModuleList : _LIST_ENTRY [ 0x191ee0 - 0x192848 ]
+0x014 InMemoryOrderModuleList : _LIST_ENTRY [ 0x191ee8 - 0x192850 ]
+0x01c InInitializationOrderModuleList : _LIST_ENTRY [ 0x191f58 - 0x192858 ]
+0x024 EntryInProgress : (null)
Now display the CriticalSectionTimeout field:
0:000> dt nt!_PEB CriticalSectionTimeout 7ffdf000
+0x070 CriticalSectionTimeout : _LARGE_INTEGER 0xffffe86d`079b8000
Now expand the CriticalSectionTimeout structure subfields one level deep:
0:000> dt nt!_PEB CriticalSectionTimeout. 7ffdf000
+0x070 CriticalSectionTimeout : 0xffffe86d`079b8000
+0x000 LowPart
: 0x79b8000
+0x004 HighPart
: -6035
+0x000 u
: __unnamed
+0x000 QuadPart
: -25920000000000
Now expand the CriticalSectionTimeout structure subfields two levels deep:
0:000> dt nt!_PEB CriticalSectionTimeout.. 7ffdf000
+0x070 CriticalSectionTimeout
: 0xffffe86d`079b8000
+0x000 LowPart
: 0x79b8000
+0x004 HighPart
: -6035
+0x000 u
:
+0x000 LowPart
: 0x79b8000
+0x004 HighPart
: -6035
+0x000 QuadPart
: -25920000000000
The following command displays an instance of the data type MYTYPE1 that is located at the address 0x0100297C:
0:000> dt
+0x000
+0x004
+0x006
+0x008
+0x00c
+0x024

0x0100297c MYTYPE1
a
: 22
b
: 43 '+'
c
: 0x0
d
: 0x0
gn
: [6] 0x0
ex
: 0x0

The following command displays an array of 10 ULONGs at the address 0x01002BE0:

0:000> dt -ca10 ULONG 01002be0
[0] 0x1001098
[1] 0x1
[2] 0xdead
[3] 0x7d0
[4] 0x1
[5] 0xcd
[6] 0x0
[7] 0x0
[8] 0x0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Unicode string (not NULL-terminated).

Word values (2 bytes).
NULL-terminated ASCII string.
NULL-terminated Unicode string.

Numeric values will be interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the n (Set Number Base) command. The default radix can
be overridden by specifying the 0x prefix (hexadecimal), the 0n prefix (decimal), the 0t prefix (octal), or the 0y prefix (binary).
Note The default radix behaves differently when C++ expressions are being used. See Evaluating Expressions for details.
When entering byte values with the eb command, you can use single straight quotation marks to specify characters. If you want to include multiple characters, each must be
surrounded with its own quotation marks. This allows you to enter a character string that is not terminated by a null character. For example:
eb 'h' 'e' 'l' 'l' 'o'
C-style escape characters (such as '\0' or '\n') may not be used with these commands.
If you omit the Values parameter, you will be prompted for input. The address and its current contents will be displayed, and an Input> prompt will appear. You can then do
any of the following:

Enter a new value, by typing the value and pressing ENTER.

Preserve the current value in memory by pressing SPACE followed by ENTER.
Exit from the command by pressing ENTER.

Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

f, fp (Fill Memory)
The f and fp commands fill the specified memory range with a repeating pattern.
These commands should not be confused with the ~F (Freeze Thread) command.
Syntax
f Range Pattern
fp [MemoryType] PhysicalRange Pattern
Parameters
Range
Specifies the range in virtual memory to fill. For more syntax details, see Address and Address Range Syntax.
PhysicalRange
(Kernel mode only) Specifies the range in physical memory to fill. The syntax of PhysicalRange is the same as that of a virtual memory range, except that no symbol
names are permitted.
MemoryType
(Kernel mode only) Specifies the type of physical memory, which can be one of the following:
[c]
Cached memory.
[uc]
Uncached memory.
[wc]
Write-combined memory.
Pattern
Specifies one or more byte values with which to fill memory.
Environment
Modes

f: user mode, kernel mode

fp: kernel mode only
Targets live, crash dump
Platforms all

Comments
This command fills the memory area specified by range with the specified pattern, repeated as many times as necessary.
The pattern parameter must be input as a series of bytes. These can be entered as numeric or as ASCII characters.
Numeric values will be interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the n (Set Number Base) command. The default radix can

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 286 of 1651

be overridden by specifying the 0x prefix (hexadecimal), the 0n prefix (decimal), the 0t prefix (octal), or the 0y prefix (binary).
Note The default radix behaves differently when C++ expressions are being used. For more information, see the Evaluating Expressions topic.
If ASCII characters are used, each character must be enclosed in single straight quotation marks. C-style escape characters (such as '\0' or '\n') may not be used.
If multiple bytes are specified, they must be separated by spaces.
If pattern has more values than the number of bytes in the range, the debugger ignores the extra values.
Here are some examples. Assuming the current radix is 16, the following command will fill memory locations 0012FF40 through 0012FF5F with the pattern "ABC", repeated
several times:
0:000> f 0012ff40 L20 'A' 'B' 'C'
The following command has the exact same effect:
0:000> f 0012ff40 L20 41 42 43
The following examples show how you can use the physical memory types (c, uc, and wc) with the fp command in kernel mode:
kd> fp [c] 0012ff40 L20 'A' 'B' 'C'
kd> fp [uc] 0012ff40 L20 'A' 'B' 'C'
kd> fp [wc] 0012ff40 L20 'A' 'B' 'C'
Additional Information
For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

g (Go)
The g command starts executing the given process or thread. Execution will halt at the end of the program, when BreakAddress is hit, or when another event causes the
debugger to stop.
Syntax
User-Mode Syntax
[~Thread] g[a] [= StartAddress] [BreakAddress ... [; BreakCommands]]
Kernel-Mode Syntax
g[a] [= StartAddress] [BreakAddress ... [; BreakCommands]]

Parameters
Thread
(User mode only) Specifies the thread to execute. For syntax details, see Thread Syntax.
a
Causes any breakpoint created by this command to be a processor breakpoint (like those created by ba) rather than a software breakpoint (like those created by bp and
bm). If BreakAddress is not specified, no breakpoint is created and the a flag has no effect.
StartAddress
Specifies the address where execution should begin. If this is not specified, the debugger passes execution to the address specified by the current value of the instruction
pointer. For more syntax details, see Address and Address Range Syntax.
BreakAddress
Specifies the address for a breakpoint. If BreakAddress is specified, it must specify an instruction address (that is, the address must contain the first byte of an
instruction). Up to ten break addresses, in any order, can be specified at one time. If BreakAddress cannot be resolved, it is stored as an unresolved breakpoint. For more
syntax details, see Address and Address Range Syntax.
BreakCommands
Specifies one or more commands to be automatically executed when the breakpoint specified by BreakAddress is hit. The BreakCommands parameter must be preceded
by a semicolon. If multiple BreakAddress values are specified, BreakCommands applies to all of them.
Note The BreakCommands parameter is only available when you are embedding this command within a command string used by another command for example,
within another breakpoint command or within an except or event setting. On a command line, the semicolon will terminate the g command, and any additional commands
listed after the semicolon will be executed immediately after the g command is done.
Environment

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 287 of 1651

Page 290 of 1651

For other methods of issuing this command and an overview of related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ib, iw, id (Input from Port)

The ib, iw, and id commands read and display a byte, word, or double word from the selected port.
Syntax
ib Address
iw Address
id Address
Parameters
Address
The address of the port.
Environment
Modes
Kernel mode only
Targets Live debugging only
Platforms x86-based computer only
Comments
The ib command reads a single byte, the iw command reads a word, and the id command reads a double word.
Make sure that reading an I/O port does not affect the behavior of the device that you are reading from. Some devices change state after a read-only port has been read. You
should also not try to read a word or double-word from a port that does not allow values of this length.
See Also
ob, od, ow (Output to Port)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

j (Execute If - Else)
The j command conditionally executes one of the specified commands, depending on the evaluation of a given expression.
Syntax
j Expression Command1 ; Command2
j Expression 'Command1' ; 'Command2'
Parameters
Expression
The expression to evaluate. If this expression evaluates to a nonzero value, Command1 is executed. If this expression evaluates to zero, Command2 is executed. For more
information about the syntax of this expression, see Numerical Expression Syntax.
Command1
The command string to be executed if the expression in Expression evaluates to a nonzero value (TRUE). You can combine multiple commands by surrounding the
command string with single straight quotation marks ( ' ) and separating commands by using semicolons. If the command string is a single command, the single quotation
marks are optional.
Command2
The command string to be executed if the expression in Expression evaluates to zero (FALSE). You can combine multiple commands by surrounding the command string
with single straight quotation marks ( ' ) and separating commands by using semicolons. If the command string is a single command, the single quotation marks are
optional.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 291 of 1651

Comments
You cannot add a semicolon or additional commands after the j command. If a semicolon appears after Command2, everything after the semicolon is ignored.
The following command displays the value of eax if MySymbol is equal to zero and displays the values of ebx and ecx otherwise.
0:000> j (MySymbol=0) 'r eax'; 'r ebx; r ecx'
You could omit the single quotation marks around r eax, but they make the command easier to read. If you want to omit one of the commands, you can include empty
quotation marks or omit the parameter for that command, as in the following commands.
0:000> j (MySymbol=0) ''; 'r ebx; r ecx'
0:000> j (MySymbol=0) ; 'r ebx; r ecx'
You can also use the j command inside other commands. For example, you can use a j command to create conditional breakpoints.
0:000> bp `mysource.cpp:143` "j (poi(MyVar)>0n20) ''; 'gc' "
For more information about the syntax for conditional breakpoints, see Setting a Conditional Breakpoint.
See Also
z (Execute While)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)

The k* commands display the stack frame of the given thread, together with related information..
Syntax
User-Mode
[~Thread]
[~Thread]
[~Thread]
[~Thread]

k[b|p|P|v] [c] [n] [f] [L] [FrameCount]

k[b|p|P|v] [c] [n] [f] [L] = BasePtr [FrameCount]
k[b|p|P|v] [c] [n] [f] [L] = BasePtr StackPtr InstructionPtr
kd [WordCount]

Kernel-Mode
[Processor]
[Processor]
[Processor]
[Processor]

k[b|p|P|v] [c] [n] [f] [L] [FrameCount]

k[b|p|P|v] [c] [n] [f] [L] = BasePtr [FrameCount]
k[b|p|P|v] [c] [n] [f] [L] = BasePtr StackPtr InstructionPtr
kd [WordCount]

Parameters
Thread
Specifies the thread whose stack is to be displayed. If you omit this parameter, the stack of the current thread is displayed. For more information about thread syntax, see
Thread Syntax. You can specify threads only in user mode.
Processor
Specifies the processor whose stack is to be displayed. For more information about processor syntax, see Multiprocessor Syntax. You can specify processors only in
kernel mode.
b
Displays the first three parameters that are passed to each function in the stack trace.
c
Displays a clean stack trace. Each display line includes only the module name and the function name.
p
Displays all of the parameters for each function that is called in the stack trace. The parameter list includes each parameter's data type, name, and value. The p option is
case sensitive. This parameter requires full symbol information.
P
Displays all of the parameters for each function that is called in the stack trace, like the p parameter. However, for P, the function parameters are printed on a second line
of the display, instead of on the same line as the rest of the data.
v
Displays frame pointer omission (FPO) information. On x86-based processors, the display also includes calling convention information.
n
Displays frame numbers.
f
Displays the distance between adjacent frames. This distance is the number of bytes that separate the frames on the actual stack.
L
Hides source lines in the display. L is case sensitive.
FrameCount
Specifies the number of stack frames to display. You should specify this number in hexadecimal format, unless you have changed the radix by using the n (Set Number
Base) command. The default value is 20 (0x14), unless you have changed the default value by using the .kframes (Set Stack Length) command.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 292 of 1651

BasePtr
Specifies the base pointer for the stack trace. The BasePtr parameter is available only if there is an equal sign (=) after the command. On an x86-based processor, you can
add one more parameter after BasePtr (which is interpreted as the FrameCount parameter) or two more parameters after BasePtr (which are interpreted as the StackPtr
and InstructionPtr parameters).
StackPtr
(x86-based processor only) Specifies the stack pointer for the stack trace. If you omit StackPtr and InstructionPtr, the command uses the stack pointer that the esp
register specifies and the instruction pointer that the eip register specifies.
InstructionPtr
(x86-based processor only) Specifies the instruction pointer for the stack trace. If you omit StackPtr and InstructionPtr, the command uses the stack pointer that the esp
register specifies and the instruction pointer that the eip register specifies.
WordCount
Specifies the number of DWORD_PTR values in the stack to dump. The default value is 20 (0x14), unless you changed the default value by using the .kframes (Set
Stack Length) command.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
When you issue the k, kb, kp, kP, or kv command, a stack trace is displayed in a tabular format. If line loading is enabled, source modules and line numbers are also
displayed.
The stack trace includes the base pointer for the stack frame, the return address, and function names.
If you use the kp or kP command, the full parameters for each function that is called in the stack trace are displayed. The parameter list includes each parameter's data type,
name, and value.
This command might be slow. For example, when MyFunction1 calls MyFunction2, the debugger must have full symbol information for MyFunction1 to display the
parameters that are passed in this call. This command does not fully display internal Microsoft Windows routines that are not exposed in public symbols.
If you use the kb or kv command, the first three parameters that are passed to each function are displayed. If you use the kv command, FPO data is also displayed.
On an x86-based processor, the kv command also displays calling convention information.
On an Itanium-based processor, the kv command also causes nonvolatile registers to be displayed. This information enables you to trace the register stack.
When you use the kv command, the FPO information is added at the end of the line in the following format.
FPO text
FPO: [non-Fpo]
FPO: [N1,N2,N3]

Meaning
No FPO data for the frame.
N1 is the total number of parameters.
N2 is the number of DWORD values for the local variables.
N3 is the number of registers that are saved.

FPO: [N1,N2] TrapFrame @ Address N1 is the total number of parameters.

N2 is the number of DWORD values for the locals.
Address is the address of the trap frame.
FPO: TaskGate Segment:0
FPO: [EBP 0xBase]

Segment is the segment selector for the task gate.

Base is the base pointer for the frame.

The kd command displays the raw stack data. Each DWORD value is displayed on a separate line. Symbol information is displayed for those lines together with associated
symbols. This format creates a more detailed list than the other k* commands. The kd command is equivalent to a dds (Display Memory) command that uses the stack
address as its parameter.
If you want a stack trace that begins somewhere other than the current stack location, you can use the BasePtr parameter to specify the base pointer value. If you are
specifying the base pointer value on an x86-based processor, you should specify BasePtr, StackPtr, and InstructionPtr. These parameters should be the values of ebp, esp,
and eip that correspond to the stack trace that you want. If you specify BasePtr and omit StackPtr and InstructionPtr, you might receive incorrect results if there are FPO
frames present.
If you use the k command at the beginning of a function (before the function prolog has been executed), you receive incorrect results. The debugger uses the frame register to
compute the current backtrace, and this register is not set correctly for a function until its prolog has been executed.
In user mode, the stack trace is based on the stack of the current thread. For more information about threads, see Controlling Processes and Threads.
In kernel mode, the stack trace is based on the current register context. You can set the register context to match a specific thread, context record, or trap frame.
Additional Information
For more information about stack traces and other ways to display stack traces, see Viewing the Call Stack. For more information about the register context and other context
settings, see Changing Contexts.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 293 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

l+, l- (Set Source Options)

The l+and l- commands set the source line options that control source display and program stepping options.
Syntax
l+Option
l-Option
l{+|-}
Parameters
+ or
Specifies whether a given option is to be turned on (plus sign [+])or turned off (minus sign []).
Option
One of the following options. The options must be in lowercase letters.
l
Displays source line numbers at the command prompt. You can disable source line display through l-ls or .prompt_allow -src. To make the source line numbers
visible, you must enable source line display through both mechanisms.
o
Hides all messages (other than the source line and line number) when you are stepping through code. (The s option must also be active for the o option to have any
effect.)
s
Displays source lines and source line numbers at the command prompt.
t
Starts source mode. If this mode is not set, the debugger is in assembly mode.
*
Turns on or turns off all options.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you omit Option, the previously set options are displayed. In this case, the l+ and l- commands have identical effects. However, you must include a plus sign (+) or minus
sign () for the l command to work.
You can include only one Option every time that you issue this command. If you list more than one option, only the first option is detected. However, by repeatedly issuing
this command, you can turn on or off as many options as you want. (In other words, l+lst does not work, but l+l; l+s; l+t does achieve the effect that you want.)
When you specify the s option, source lines and line numbers are displayed when you step through code, regardless of whether you specified the l option. The o option has no
effect unless you specify the s option.
Source line options do not take effect unless you enable line number loading by using the .lines (Toggle Source Line Support) command or the -lines command-line option.
By default, if you have not used these commands, WinDbg turns on source line support and CDB turns it off.
Additional Information
For more information about source debugging and related commands, see Debugging in Source Mode. For more information about assembly debugging and related
commands, see Debugging in Assembly Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ld (Load Symbols)
The ld command loads symbols for the specified module and updates all module information.
Syntax
ld ModuleName [/f FileName]
Parameters
ModuleName
Specifies the name of the module whose symbols are to be loaded. ModuleName can contain a variety of wildcard characters and specifiers.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 294 of 1651

/f FileName
Changes the name selected for the match. By default the module name is matched, but when /f is used the file name is matched instead of the module name. FileName
can contain a variety of wildcard characters and specifiers. For more information on the syntax of wildcard characters and specifiers, see String Wildcard Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The debugger's default behavior is to use lazy symbol loading (also known as deferred symbol loading). This means that symbols are not actually loaded until they are needed.
The ld command, on the other hand, forces all symbols for the specified module to be loaded.
Additional Information
For more information about deferred (lazy) symbol loading, see Deferred Symbol Loading. For more information about other symbol options, see Setting Symbol Options.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

lm (List Loaded Modules)

The lm command displays the specified loaded modules. The output includes the status and the path of the module.
Syntax
lm Options [a Address] [m Pattern | M Pattern]
Parameters
Options
Any combination of the following options:
o
Displays only loaded modules.
l
Displays only modules whose symbol information has been loaded.
v
Causes the display to be verbose. The display includes the symbol file name, the image file name, checksum information, version information, date stamps, time
stamps, and information about whether the module is managed code (CLR). This information is not displayed if the relevant headers are missing or paged out.
u
(Kernel mode only) Displays only user-mode symbol information.
k
(Kernel mode only) Displays only kernel-mode symbol information.
e
Displays only modules that have a symbol problem. These symbols include modules that have no symbols and modules whose symbol status is C, T, #, M, or
Export. For more information about these notations, see Symbol Status Abbreviations.
c
Displays checksum data.
1m
Reduces the output so that nothing is included except the names of the modules. This option is useful if you are using the .foreach token to pipe the command output
into another command's input.
sm
Sorts the display by module name instead of by the start address.
In addition, you can include only one of the following options. If you do not include any of these options, the display includes the symbol file name.
i
Displays the image file name.
f
Displays the full image path. (This path always matches the path that is displayed in the initial load notification, unless you issued a .reload -s command.) When you
use f, symbol type information is not displayed.
n
Displays the image name. When you use n, symbol type information is not displayed.
p
Displays the mapped image name. When you use p, symbol type information is not displayed.
t
Displays the file time stamps. When you use t, symbol type information is not displayed.
a Address
Specifies an address that is contained in this module. Only the module that contains this address is displayed. If Address contains an expression, it must be enclosed in
parentheses.
m Pattern
Specifies a pattern that the module name must match. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax of this
information, see String Wildcard Syntax.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 295 of 1651

Note In most cases, the module name is the file name without the file name extension. For example, if you want to display information about the Flpydisk.sys driver, use
the lm mflpydisk command, not lm mflpydisk.sys. In some cases, the module name differs significantly from the file name. For more information, see Executable Image
Path.
M Pattern
Specifies a pattern that the image path must match. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax of this
information, see String Wildcard Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The lm command lists all of the modules and the status of symbols for each module.
Microsoft Windows Server 2003 and later versions of Windows maintain an unloaded module list for user-mode processes. When you are debugging a user-mode process or
dump file, the lm command also shows these unloaded modules.
This command shows several columns or fields, each with a different title. Some of these titles have specific meanings:

module name is typically the file name without the file name extension. In some cases, the module name differs significantly from the file name. For more information,
see Executable Image Path.
The symbol type immediately follows the module name. This column is not labeled. For more information about the various status values, see Symbol Status
Abbreviations. If you have loaded symbols, the symbol file name follows this column.
The first address in the module is shown as start. The first address after the end of the module is shown as end. For example, if start is "faab4000" and end is
"faab8000", the module extends from 0xFAAB4000 to 0xFAAB7FFF, inclusive.
lmv only: The image path column shows the name of the executable file, including the file name extension. Typically, the full path is included in user mode but not in
kernel mode.
lmv only: The loaded symbol image file value is the same as the image name, unless Microsoft CodeView symbols are present.
lmv only: The mapped memory image file value is typically not used. If the debugger is mapping an image file (for example, during minidump debugging), this value
is the name of the mapped image.

The following code example shows the lm command with a Windows Server 2003 target computer. This example includes the m and s* options, so only modules that begin
with "s" are displayed.
kd> lm m
start
f9f73000
fa04b000
faab7000
facac000
fb008000
fb24f000

s*
end
f9f7fd80
fa09b400
faac8500
facbae00
fb00ba80
fb250000

module name
sysaudio
srv
sr
serial
serenum
swenum

Unloaded
f9f53000
fb0ae000
fb040000

modules:
f9f61000
fb0b0000
fb043000

swmidi.sys
splitter.sys
Sfloppy.SYS

(deferred)
(deferred)
(deferred)
(deferred)
e:\mysymbols\SereEnum.pdb\.......
(deferred)

The following two examples show the lm command once without any options and once with the sm option. Compare the sort order in the two examples.
Example 1:
0:000> lm
start
end
01000000 0100d000
77c10000 77c68000
77dd0000 77e6b000
77e70000 77f01000
7c800000 7c8f4000
7c900000 7c9b0000

module name
stst
(deferred)
msvcrt
(deferred)
ADVAPI32
(deferred)
RPCRT4
(deferred)
kernel32
(deferred)
ntdll
(private pdb symbols) c:\db20sym\ntdll.pdb

Example 2:
0:000> lmsm
start
end
77dd0000 77e6b000
7c800000 7c8f4000
77c10000 77c68000
7c900000 7c9b0000
77e70000 77f01000
01000000 0100d000

module name
ADVAPI32
(deferred)
kernel32
(deferred)
msvcrt
(deferred)
ntdll
(private pdb symbols)
RPCRT4
(deferred)
stst
(deferred)

c:\db20sym\ntdll.pdb

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 296 of 1651

Debugging Tools for Windows

ln (List Nearest Symbols)

The ln command displays the symbols at or near the given address.
Syntax
ln Address
Parameters
Address
Specifies the address where the debugger should start to search for symbols. The nearest symbols, either before or after Address, are displayed. For more information
about the syntax, see Address and Address Range Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
You can use the ln command to help determine what a pointer is pointing to. This command can also be useful when you are looking at a corrupted stack to determine which
procedure made a call.
If source line information is available, the ln display also includes the source file name and line number information.
If you are using a source server, the ln command displays information that is related to the source server.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ls, lsa (List Source Lines)

The ls and lsa commands display a series of lines from the current source file and advance the current source line number.
Syntax
ls [.] [first] [, count]
lsa [.] address [, first [, count]]
Parameters
.
Causes the command to look for the source file that the debugger engine or the .srcpath (Set Source Path) command are using. If the period (.) is not included, ls uses
the file that was most recently loaded with the lsf (Load Source File) command.
address
Specifies the address where the source display is to begin. For more information about the syntax, see Address and Address Range Syntax.
first
Specifies the first line to display. The default value is the current line.
count
Specifies the quantity of lines to display. The default value is 20 (0x14), unless you have changed the default value by using the lsp -a command.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
After you run the ls or lsa command, the current line is redefined as the final line that is displayed plus one. The current line is used in future ls, lsa, and lsc commands.
See Also
lsc (List Current Source), lsf, lsf- (Load or Unload Source File)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 297 of 1651

December 09, 2009

Debugging Tools for Windows

lsc (List Current Source)

The lsc command displays the current source file name and line number.
Syntax
lsc
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
See Also
ls, lsa (List Source Lines), lsf, lsf- (Load or Unload Source File)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

lse (Launch Source Editor)

The lse command opens an editor for the current source file.
Syntax
lse
Environment
Modes
User-mode, kernel-mode
Targets Live, crash dump
Platforms All
Comments
The lse command opens an editor for the current source file. This command is equivalent to clicking Edit this file in the shortcut menu of the Source window in WinDbg.
The editor is opened on the computer that the target is running on, so you cannot use the lse command from a remote client.
The WinDiff editor registry information or the value of the WINDBG_INVOKE_EDITOR environment variable determine which editor is opened. For example, consider the
following value of WINDBG_INVOKE_EDITOR.
c:\my\path\myeditor.exe -file %f -line %l
This value indicates that Myeditor.exe opens to the one-based line number of the current source file. The %l option indicates that line numbers should be read as one-based,
and %f indicates that the current source file should be used. You could also include %L to indicate that line numbers are zero-based or %p to indicate that the current source
file should be used.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

lsf, lsf- (Load or Unload Source File)

The lsf and lsf- commands load or unload a source file.
Syntax
lsf Filename
lsf- Filename
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 298 of 1651

Filename
Specifies the file to load or unload. If this file is not located in the directory where the debugger was opened from, you must include an absolute or relative path. The file
name must follow Microsoft Windows file name conventions.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The lsf command loads a source file.
The lsf command unloads a source file. You can use this command to unload files that you previously loaded with lsf or automatically loaded source files. You cannot use
lsf to unload files that were loaded through WinDbg's File | Open Source File command or files that a WinDbg workspace loaded.
In CDB or KD, you can view source files in the Debugger Command window. In WinDbg, source files are loaded as new Source windows.
For more information about source files, source paths, and other ways to load source files, see Source Path.
See Also
ls, lsa (List Source Lines), lsc (List Current Source)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

lsp (Set Number of Source Lines)

9/18/2010

Introduction

Page 302 of 1651

Note If you use this command in kernel mode, execution stops when an instruction is encountered at the specified virtual address in any virtual address space.
During this execution, all steps are displayed explicitly. Called functions are treated as a single unit. Therefore, the display of this command is similar to what you see if you
execute p (Step) repeatedly until the program counter reaches the specified address.
For example, the following command explicitly steps through the target code until the return address of the current function is reached.
0:000> pa @$ra
The following example demonstrates using the pa command along with the kb command to display the stack trace:
0:000> pa 70b5d2f1 "kb"
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

pc (Step to Next Call)

The pc command executes the program until a call instruction is reached.
Syntax
User-Mode
[~Thread] pc [r] [= StartAddress] [Count]
Kernel-Mode
pc [r] [= StartAddress] [Count]
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the pcr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information
about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of call instructions that the debugger must encounter for this command to stop. The default value is one.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The pc command causes the target to begin executing. This execution continues until a call instruction is reached or a breakpoint is encountered.
If the program counter is already on a call instruction, the entire call is executed. After this call is returned, execution continues until another call is reached. This execution,
rather than tracing, of the call is the only difference between pc and tc (Trace to Next Call).
In source mode, you can associate one source line with multiple assembly instructions. The pc command does not stop at a call instruction that is associated with the current
source line.
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 303 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

pct (Step to Next Call or Return)

The pct command executes the program until it reaches a call instruction or a return instruction.
Syntax
User-Mode
[~Thread] pct [r] [= StartAddress] [Count]
Kernel-Mode
pct [r] [= StartAddress] [Count]
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display through the pctr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. Otherwise, the debugger begins at the instruction that the instruction pointer points to. For more information
about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of call or return instructions that must be encountered for this command to stop. The default value is one.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The pct command causes the target to begin executing. This execution continues until a call or return instruction is reached or a breakpoint is encountered.
If the program counter is already on a call or return instruction, the entire call or return is executed. After this call or return is returned, execution continues until another call
or return is reached. This execution, rather than tracing, of the call is the only difference between pct and tct (Trace to Next Call or Return).
In source mode, you can associate one source line with multiple assembly instructions. The pct command does not stop at a call or return instruction that is associated with
the current source line.
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ph (Step to Next Branching Instruction)

The ph command executes the program until any kind of branching instruction is reached, including conditional or unconditional branches, calls, returns, and system calls.
Syntax
User-Mode
[~Thread] ph [r] [= StartAddress] [Count]
Kernel-Mode
ph [r] [= StartAddress] [Count]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

32-bit floating-point
64-bit floating-point

Value
Specifies the value to assign to the register. For more information about the syntax, see Numerical Expression Syntax.
.
Displays the registers used in the current instruction. If no registers are used, no output is displayed.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you do not specify Register, the r command displays all the non-floating-point registers, and the rF command displays all the floating-point registers. You can change this
behavior by using the rm (Register Mask) command.
If you specify Register but you omit the equal sign (=) and the Value parameter, the command displays the current value of the register.
If you specify Register and an equal sign (=) but you omit Value, the command displays the current value of the register and prompts for a new value.
If you specify Register, the equal sign (=), and Value, the command changes the register to contain the value. (If quiet mode is active, you can omit the equal sign. You can
turn on quiet mode by using the sq (Set Quiet Mode) command. In kernel mode, you can also turn on quiet mode by using the KDQUIET environment variable.)
You can specify multiple registers, separated by commas.
In user mode, the r command displays registers that are associated with the current thread. For more information about the threads, see Controlling Processes and Threads.
In kernel mode, the r command displays registers that are associated with the current register context. You can set the register context to match a specific thread, context
record, or trap frame. Only the most important registers for the specified register context are actually displayed, and you cannot change their values. For more information
about register context, see Register Context.
When you specify a floating-point register by name, the F option is not required. When you specify a single floating-point register, the raw hexadecimal value is displayed in
addition to the decimal value.
The following Mask bits are supported for an x86-based processor or an x64-based processor.
Bit Value
Description
0 0x1 Displays the basic integer registers. (Setting one or both of these bits has the same effect.)
1 0x2
2 0x4 Displays the floating-point registers.
3 0x8 Displays the segment registers.
4 0x10 Displays the MMX registers.
5 0x20 Displays the debug registers. In kernel mode, setting this bit also displays the CR4 register.
6 0x40 Displays the SSE XMM registers.
7 0x80 (Kernel mode only) Displays the CR0, CR1, and CR3 registers.
8 0x100 (Kernel mode only) Displays the descriptor and task state registers.
The following Mask bits are supported for an Itanium-based processor.
Bit Value
Description
0 0x1 Displays the basic integer registers. (Setting one or both of these bits has the same effect.)
1 0x2
2 0x4 Displays the floating-point registers.
3 0x8 Displays the high, floating-point registers (f32 to f127).
4 0x10 Displays the user debug registers.
5 0x20 (Kernel mode only) Displays the KSPECIAL_REGISTERS.
The following code examples show r commands for an x86-based processor.
In kernel mode, the following command shows the registers for processor 2.
1: kd> 2r
In user mode, the following command shows the registers for thread 2.
0:000> ~2 r
The following command displays all of the eax registers that are associated with all threads (in thread ordinal order).
0:000> ~* r eax
The following command sets the eax register for the current thread to 0x000000FF.
0:000> r eax=0x000000FF

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 308 of 1651

The following command sets the st0 register to 1.234e+10 (the F is optional).
0:000> rF st0=1.234e+10
The following command displays the zero flag.
0:000> r zf
The following command displays the xmm0 register as 16 unsigned bytes and then displays the full contents of the xmm1 register in double-precision floating-point format.
0:000> r xmm0:16ub, xmm1:d
If the current syntax is C++, you must precede registers by an at sign (@). Therefore, you could use the following command to copy the ebx register to the eax register.
0:000> r eax = @ebx
The following command displays pseudo-registers in the same way that the r command displays registers.
0:000> r $teb
You can also use the r command to create fixed-name aliases. These aliases are not registers or pseudo-registers, even though they are associated with the r command. For
more information about these aliases, see Using Aliases.
Here is an example of the r. command on an x86-based processor. The last entry of the call stack precedes the command itself.
01004af3 8bec
mov
0:000> r.
ebp=0006ffc0 esp=0006ff7c

ebp,esp

Here is an example of the r. command on an Itanium-based processor.

e0000000`83066cf0
1: kd> r.
r25=ffffffff`d0000006

ld8.acq r25 = [r45] e0000000`ffff0b18=????????????????

r45=e0000000`ffff0b18

Additional Information
For more information about registers and their manipulation, see Reading and Writing Registers and Flags. For more information about the register context and other context
settings, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

rdmsr (Read MSR)

The rdmsr command reads a Model-Specific Register (MSR) value from the specified address.
Syntax
rdmsr Address
Parameters
Address
Specifies the address of the MSR.
Environment
Modes
Kernel mode only
Targets Live debugging only
Platforms All
Comments
The rdmsr command can display MSR's on x86-based, Itanium-based, and x64-based platforms. The MSR definitions are platform-specific.
See Also
wrmsr (Write MSR)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 309 of 1651

December 09, 2009

Debugging Tools for Windows

rm (Register Mask)
The rm command modifies or displays the register display mask. This mask controls how registers are displayed by the r (Registers) command.
Syntax
rm
rm ?
rm Mask
Parameters
?
Displays a list of possible Mask bits.
Mask
Specifies the mask to use when the debugger displays the registers. Mask is a sum of bits that indicate something about the register display. The meaning of the bits
depends on the processor and the mode. For more information; see the tables in the following Comments section.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The "m" in the command name must be a lowercase letter.
If you use rm with no parameters, the current value is displayed, along with an explanation about its bits.
To display the basic integer registers, you must set bit 0 (0x1) or bit 1 (0x2). By default, 0x1 is set for 32-bit targets and 0x2 is set for 64-bit targets. You cannot set these two
bits at the same timeif you try to set both bits, 0x2 overrides 0x1.
You can override the default mask by using the r (Registers) command together with the M option.
The following Mask bits are supported for an x86-based processor or an x64-based processor.
Bit Value
Description
0 0x1 Displays the basic integer registers. (Setting one or both of these bits has the same effect.)
1 0x2
2 0x4 Displays the floating-point registers.
3 0x8 Displays the segment registers.
4 0x10 Displays the MMX registers.
5 0x20 Displays the debug registers. In kernel mode, setting this bit also displays the CR4 register.
6 0x40 Displays the SSE XMM registers.
7 0x80 (Kernel mode only) Displays the CR0, CR1, and CR3 registers.
8 0x100 (Kernel mode only) Displays the descriptor and task state registers.
The following Mask bits are supported for an Itanium-based processor.
Bit Value
Description
0 0x1 Displays the basic integer registers. (Setting one or both of these bits has the same effect.)
1 0x2
2 0x4 Displays the floating-point registers.
3 0x8 Displays the high, floating-point registers (f32 to f127).
4 0x10 Displays the user debug registers.
5 0x20 (Kernel mode only) Displays the KSPECIAL_REGISTERS.
Additional Information
For more information about registers and their manipulation, see Reading and Writing Registers and Flags.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

s (Search Memory)
The s command searches through memory to find a specific byte pattern.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 310 of 1651

Do not confuse this command with the ~s (Change Current Processor), ~s (Set Current Thread), |s (Set Current Process), or ||s (Set Current System) commands.
Syntax
s
s
s
s

[-[[Flags]]Type] Range Pattern

-[[Flags]]v Range Object
-[[Flags]]sa Range
-[[Flags]]su Range

Parameters
[Flags]
Specifies one or more search options. Each flag is a single letter. You must enclose the flags in a single set of brackets ([]). You cannot add spaces between the brackets,
except between n or l and its argument. For example, if you want to specify the s and w options, use the command s -[sw]Type Range Pattern.
You can specify one or more of the following flags:
s
Saves all of the results of the current search. You can use these results to repeat the search later.
r
Restricts the current search to the results from the last saved search. You cannot use the s and r flags in the same command. When you use r, the value of Range is
ignored, and the debugger searches only those hits that were saved by the previous s command.
n Hits
Specifies the number of hits to save when you use the s flag. The default value is 1024 hits. If you use n together with other flags, n must be the last flag, followed
by its Hits argument. The space between n and Hits is optional, but you cannot add any other spaces within the brackets. If any later search that uses the s flag
discovers more than the specified number of hits, the Overflow error message is displayed to notify you that not all hits are being saved.
l Length
Causes a search for arbitrary ASCII or Unicode strings to return only strings that are at least Length characters long. The default length is 3. This value affects only
searches that use the -sa or -su flags.
w
Searches only writeable memory regions. You must enclose the "w" in brackets.
1
Displays only the addresses of search matches in the search output. This option is useful if you are using the .foreach token to pipe the command output into another
command's input.
Type
Specifies the memory type to search for. Add a hyphen (-) in front of Type . You can use one of the following Type values.
Type
Description
b
Byte (8 bits)
w
WORD (16 bits)
d
DWORD (32 bits)
q
QWORD (64 bits)
a
ASCII string
(not necessarily a null-terminated string)
u
Unicode string
(not necessarily a null-terminated string)
If you omit Type, byte values are used. However, if you use Flags, you cannot omit Type.
sa
Searches for any memory that contains printable ASCII strings. Use the l Length flag to specify a minimum length of such strings. The default minimum length is 3
characters.
su
Searches for any memory that contains printable Unicode strings. Use the l Length flag to specify a minimum length of such strings. The default minimum length is 3
characters.
Range
Specifies the memory area to search through. This range cannot be more than 256 MB long unless you use the L? syntax. For more information about this syntax, see
Address and Address Range Syntax.
Pattern
Specifies one or more values to search for. By default, these values are byte values. You can specify different types of memory in Type. If you specify a WORD,
DWORD, or QWORD value, enclose it in single quotation marks (for example, 'Tag7'). If you specify a string, enclose it in double quotation marks (for example, "This
string").
-v
Searches for objects of the same type as the specified Object.
Object
Specifies the address of an object or the address of a pointer to an object. The debugger then searches for objects of the same type as the object that Object specifies.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If the debugger finds the byte pattern that you specify, the debugger displays the first memory address in the Range memory area where the pattern was found. The debugger
displays an excerpt of memory that begins at that location in a format that matches the specified Type memory type. If Type is a or u, the memory contents and the
corresponding ASCII or Unicode characters are displayed.
You must specify the Pattern parameter as a series of bytes, unless you specify a different Type value. You can enter byte values as numeric or ASCII characters:

Numeric values are interpreted as numbers in the current radix (16, 10, or 8). To change the default radix, use the n (Set Number Base) command. You can override
the default radix by specifying the 0x prefix (hexadecimal), the 0n prefix (decimal), the 0t prefix (octal), or the 0y prefix (binary).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 311 of 1651

Note The default radix behaves differently when you use C++ expressions. For more information about these expressions and the radix, see Evaluating Expressions.

You must enclose ASCII characters in single straight quotation marks. You cannot use C-style escape characters (such as '\0' or '\n').

If you specify multiple bytes, you must separate them by spaces.

The s-a and s-u commands search for specified ASCII and Unicode strings, respectively. These strings do not have to be null-terminated.
The s-sa and s-su commands search for unspecified ASCII and Unicode strings. These are useful if you are checking a range of memory to see whether it contains any
printable characters.
The s-v command searches for objects of the same data type as the Object object. You can use this command only if the desired object is a C++ class or another object that is
associated with virtual function tables (Vtables). The s-v command searches the Range memory area for the addresses of this class's Vtables. If multiple Vtables exist in this
class, the search algorithm looks for all of these pointer values, separated by the proper number of bytes. If any matches are found, the debugger returns the base address of
the object and full information about this objectsimilar to the output of the dt (Display Type) command.
The following code examples show the s command. If you assume that the current radix is 16, the following command searches memory locations 0012FF40 through
0012FF5F for "Hello".
0:000> s 0012ff40 L20 'H' 'e' 'l' 'l' 'o'
The following command has the same effect.
0:000> s 0012ff40 L20 48 65 6c 6c 6f
The following s-a command also has the same effect.
0:000> s -a 0012ff40 L20 "Hello"
These commands locate each appearance of "Hello" and return the address of each such patternthat is, the address of the letter "H".
The debugger returns only patterns that are completely contained in the search range. Overlapping patterns are found correctly. (In other words, the pattern "QQQ" is found
three times in "QQQQQ".)
The following example shows a search that uses the Type parameter. This command searches memory locations 0012FF40 through 0012FF5F for the double-word 'VUTS':
0:000> s -d 0012ff40 L20 'VUTS'
On little-endian computers, 'VUTS' is the same as the byte pattern 'S' 'T' 'U' 'V'. However, searches for WORDs, DWORDs, and QWORDs return only results that are
correctly byte-aligned.
Additional Information
For more information about memory manipulation and a description of other memory-related commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

so (Set Kernel Debugging Options)

The so command sets or displays the kernel debugging options.
Syntax
so [Options]
Parameters
Options
One or more of the following options:
NOEXTWARNING
Does not issue a warning when the debugger cannot find an extension command.
NOVERSIONCHECK
Does not check the version of debugger extension DLLs.
If you omit Options, the current options are displayed.
Environment
Modes
Kernel mode only
Targets Live, crash dump
Platforms All
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 312 of 1651

You can also set kernel debugging options using the _NT_DEBUG_OPTIONS environment variable.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

sq (Set Quiet Mode)

The sq command turns quiet mode on or off.
Syntax
sq
sq{e|d}
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The sqe command turns quiet mode on, and the sqd command turns it off. The sq command turns on and off quiet mode. Each of these commands also displays the new quiet
mode status.
You can set quiet mode in KD or kernel-mode WinDbg by using the KDQUIET environment variable. (Note that quiet mode exists in both user-mode and kernel-mode
debugging, but the KDQUIET environment variable is only recognized in kernel mode.)
Quiet mode has three distinct effects:

The debugger does not display messages every time that an extension DLL is loaded or unloaded.
The r (Registers) command no longer requires an equal sign (=) in its syntax.
When you break into a target computer while kernel debugging, the long warning message is suppressed.

Do not confuse quiet mode with the effects of the -myob command-line option (in CDB and KD) or the -Q command-line option (in WinDbg).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ss (Set Symbol Suffix)

The ss command sets or displays the current suffix value that is used for symbol matching in numeric expressions.
Syntax
ss [a|w|n]
Parameters
a
Specifies that the symbol suffix should be "A", matching many ASCII symbols.
w
Specifies that the symbol suffix should be "W", matching many Unicode symbols.
n
Specifies that the debugger should not use a symbol suffix. (This parameter is the default behavior.)
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you specify the ss command together with no parameters, the current state of the suffix value is displayed.
Additional Information
For more information about symbol matching, see Symbol Syntax and Symbol Matching.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 313 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

sx, sxd, sxe, sxi, sxn, sxr, sx- (Set Exceptions)

The sx* commands control the action that the debugger takes when an exception occurs in the application that is being debugged, or when certain events occur.
Syntax
sx
sx{e|d|i|n} [-c "Cmd1"] [-c2 "Cmd2"] [-h] {Exception|Event|*}
sx- [-c "Cmd1"] [-c2 "Cmd2"] {Exception|Event|*}
sxr
Parameters
-c "Cmd1"
Specifies a command that is executed if the exception or event occurs. This command is executed when the first chance to handle this exception occurs, regardless of
whether this exception breaks into the debugger. You must enclose the Cmd1 string in quotation marks. This string can include multiple commands, separated by
semicolons. The space between the -c and the quoted command string is optional.
-c2 "Cmd2"
Specifies a command that is executed if the exception or event occurs and is not handled on the first chance. This command is executed when the second chance to
handle this exception occurs, regardless of whether this exception breaks into the debugger. You must enclose the Cmd2 string in quotation marks. This string can include
multiple commands, separated by semicolons. The space between the -c2 and the quoted command string is optional.
-h
Changes the specified event's handling status instead of its break status. If Event is cc, hc, bpec, or ssec, you do not have to use the -h option.
Exception
Specifies the exception number that the command acts on, in the current radix.
Event
Specifies the event that the command acts on. These events are identified by short abbreviations. For a list of the events, see Controlling Exceptions and Events.
*
Affects all exceptions that are not otherwise explicitly named for sx. For a list of explicitly named exceptions, see Controlling Exceptions and Events.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The sx command displays the list of exceptions for the current process and the list of all nonexception events and displays the default behavior of the debugger for each
exception and event.
The sxe, sxd, sxn, and sxi commands control the debugger settings for each exception and event.
The sxr command resets all of the exception and event filter states to the default settings. Commands are cleared, break and continue options are reset to their default settings,
and so on.
The sx- command does not change the handling status or the break status of the specified exception or event. This command can be used if you wish to change the first-chance
command or second-chance command associated with a specific event, but do not wish to change anything else.
If you include the -h option (or if the cc, hc, bpec, or ssec events are specified), the sxe, sxd, sxn, and sxi commands control the handling status of the exception or event. In
all other cases, these commands control the break status of the exception or event.
When you are setting the break status, these commands have the following effects.
Command Status name
sxe
Break

Description
When this exception occurs, the target immediately breaks into the debugger before any other error handlers are activated. This kind of handling
is called first chance handling.

(Enabled)
sxd

Second chance The debugger does not break for a first-chance exception of this type (although a message is displayed). If other error handlers do not address
break
this exception, execution stops and the target breaks into the debugger. This kind of handling is called second chance handling.
(Disabled)

sxn

Output

When this exception occurs, the target application does not break into the debugger at all. However, a message is displayed that notifies the user
of this exception.

(Notify)
sxi

Ignore

When this exception occurs, the target application does not break into the debugger at all, and no message is displayed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 314 of 1651

When you are setting the handling status, these commands have the following effects:
Command Status name
Description
sxe
Handled
The event is considered handled when execution resumes.
Not Handled The event is considered not handled when execution resumes.
sxd,
sxn,
sxi
You can use the -h option together with exceptions, not events. Using this option with ch, bpe, or sse sets the handling status for hc, bpec, or ssec, respectively. If you use the
-h option with any other event, it has no effect.
Using the -c or -c2 options with hc, bpec, or ssec associates the specified commands with ch, bpe, or sse, respectively.
In the following example, the sxe command is used to set the break status of access violation events to break on the first chance, and to set the first-chance command that will
be executed at that point to r eax. Then the sx- command is used to alter the first-chance command to r ebx, without changing the handling status. Finally, a portion of the sx
output is shown, indicating the current settings for access violation events:
0:000> sxe -c "r eax" av
0:000> sx- -c "r ebx" av
0:000> sx
av - Access violation - break - not handled
Command: "r ebx"
. . .
Additional Information
For more information about break status and handling status, descriptions of all event codes, a list of the default status for all events, and other methods of controlling this
status, see Controlling Exceptions and Events.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

t (Trace)
The t command executes a single instruction or source line and optionally displays the resulting values of all registers and flags. When subroutine calls or interrupts occur,
each of their steps is also traced.
Syntax
User-Mode
[~Thread] t [r] [= StartAddress] [Count] ["Command"]
Kernel-Mode
t [r] [= StartAddress] [Count] ["Command"]
Parameters
Thread
Specifies threads to thaw. All other threads are frozen. For more information about this syntax, see Thread Syntax. You can specify threads only in user mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the pr, tr, or
.prompt_allow -reg commands. All three of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other three commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where execution should begin. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For more
information about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of instructions or source lines to trace through before stopping. Each step is displayed as a separate action in the Debugger Command window. The
default value is one.
Command
Specifies a debugger command to execute after the trace is performed. This command is executed before the standard t results are displayed. If you also use Count, this
command is executed after all tracing is complete (but before the results from the final trace are displayed).
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 315 of 1651

Comments
When you specify Count, each instruction is displayed as it is stepped through.
Each trace executes a single assembly instruction or a single source line, depending on whether the debugger is in assembly mode or source mode. Use the l+t and l-t
commands or the buttons on the WinDbg toolbar to switch between these modes.
If you want to trace most function calls but skip certain calls, you can use .step_filter (Set Step Filter) to indicate which calls to step over.
You can use the t command to trace instructions in ROM.
When you are quickly tracing many times in WinDbg, the debugging information windows are updated after each trace. If this update causes slower response time,
use .suspend_ui (Suspend WinDbg Interface) to temporarily suspend the updating of these windows.
Additional Information
For more information about how to issue the t command and an overview of related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ta (Trace to Address)
The ta command executes the program until the specified address is reached, displaying each step (including steps within called functions).
Syntax
User-Mode
[~Thread] ta [r] [= StartAddress] StopAddress
Kernel-Mode
ta [r] [= StartAddress] StopAddress
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the tar, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and use of any of them overrides any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
StopAddress
Specifies the address at which execution stops. This address must match the exact address of an instruction.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The ta command causes the target to begin executing. This execution continues until the specified instruction is reached or a breakpoint is encountered.
Note If you use the ta command in kernel mode, execution stops when an instruction is encountered at the specified virtual address in any virtual address space.
During this execution, all steps are displayed explicitly. If a function is called, the debugger also traces through that function. Therefore, the display of this command
resembles what you see if you executed t (Trace) repeatedly until the program counter reached the specified address.
For example, the following command explicitly traces through the target code until the return address of the current function is reached.
0:000> ta @$ra
Additional Information
For more information about related commands, see Controlling the Target.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 316 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

tb (Trace to Next Branch)

The tb command executes the program until a branch instruction is reached.
Syntax
tb [r] [= StartAddress] [Count]
Parameters
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the tbr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger starts execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of branches to allow. Every time that a branch is encountered, the instruction address and the instruction are displayed. If you omit Count, the
default number is 1.
Environment
Modes

x86-based: Kernel mode only

Itanium-based: User mode, kernel mode
x64-based: User mode, kernel mode
Targets Live debugging only
Platforms x86-based (GenuineIntel processor family 6 and later), Itanium-based, x64-based
Comments
The tb command causes the target to begin executing. This execution continues until a branch command is reached.
Execution stops at any branch command that is to be taken. This stopping of execution is always based on the disassembly code, even when the debugger is in source mode.
Branch instructions include calls, returns, jumps, counted loops, and while loops. If the debugger encounters an unconditional branch, or a conditional branch for which the
condition is true, execution stops. If the debugger encounters a conditional branch whose condition is false, execution continues.
When execution stops, the address of the branch instruction and any associated symbols are displayed. This information is followed by an arrow and then the address and
instructions of the new program counter location.
The tb command works only on the current processor. If you use tb on a multiprocessor system, execution stops when a branch command is reached or when another
processor's event occurs, whichever comes first.
Usually, branch tracing is enabled after the processor control block (PRCB) has been initialized. (The PRCB is initialized early in the boot process.) However, if you have to
use the tb command before this point, you can use .force_tb (Forcibly Allow Branch Tracing) to enable branch tracing earlier. Use the .force_tb command cautiously,
because it can corrupt your processor state.
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

tc (Trace to Next Call)

The tc command executes the program until a call instruction is reached.
Syntax
User-Mode
[~Thread] tc [r] [= StartAddress] [Count]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 317 of 1651

Kernel-Mode
tc [r] [= StartAddress] [Count]
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the tcr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of call instructions that the debugger must encounter for the tc command to end. The default value is one.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The tc command causes the target to begin executing. This execution continues until the debugger reaches a call instruction or encounters a breakpoint.
If the program counter is already on a call instruction, the debugger traces into the call and continues executing until it encounters another call. This tracing, rather than
execution, of the call is the only difference between tc and pc (Step to Next Call).
In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a call instruction that is associated with the current
source line.
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

tct (Trace to Next Call or Return)

The tct command executes the program until it reaches a call instruction or return instruction.
Syntax
User-Mode
[~Thread] tct [r] [= StartAddress] [Count]
Kernel-Mode
tct [r] [= StartAddress] [Count]
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the tctr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of call or return instructions that the debugger must encounter for the tct command to end. The default value is one.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 318 of 1651

Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The tct command causes the target to begin executing. This execution continues until the debugger reaches a call or return instruction or encounters a breakpoint.
If the program counter is already on a call or return instruction, the debugger traces into the call or return and continues executing until it encounters another call or return.
This tracing, rather than execution, of the call is the only difference between tct and pct (Step to Next Call or Return).
In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a call or return instruction that is associated with the
current source line.
Additional Information
For more information about related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

th (Trace to Next Branching Instruction)

The th command executes the program until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls.
Syntax
User-Mode
[~Thread] th [r] [= StartAddress] [Count]
Kernel-Mode
th [r] [= StartAddress] [Count]
Parameters
Thread
Specifies threads to continue executing. All other threads are frozen. For more information about the syntax, see Thread Syntax. You can specify threads only in user
mode.
r
Turns on and off the display of registers and flags. By default, the registers and flags are displayed. You can disable register display by using the thr, pr, tr, or
.prompt_allow -reg commands. All of these commands control the same setting and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other four commands. To control which registers and flags are
displayed, use the rm (Register Mask) command.
StartAddress
Specifies the address where the debugger begins execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
Count
Specifies the number of branching instructions that the debugger must encounter for the th command to end. The default value is one.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The th command causes the target to begin executing. Execution continues until the debugger reaches a branching instruction or encounters a breakpoint.
If the program counter is already on a branching instruction, the debugger traces into the branching instruction and continues executing until another branching instruction is
reached. This tracing, rather than execution, of the call is the only difference between th and ph (Step to Next Branching Instruction).
th is available for all live sessions. This availability is the primary difference between th and tb (Trace to Next Branch).
In source mode, you can associate one source line with multiple assembly instructions. This command does not stop at a branching instruction that is associated with the
current source line.
Additional Information

For more information about assembly debugging and related commands, see Debugging in Assembly Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

up (Unassemble from Physical Memory)

The up command displays an assembly translation of the specified program code in physical memory.
Syntax
up Range
up Address
up
Parameters
Range
Specifies the memory range in physical memory that contains the instructions to disassemble. For more information about the syntax, see Address and Address Range
Syntax.
Address
Specifies the beginning of the memory range in physical memory to disassemble. Eight instructions (on an x86-based processor) or nine instructions (on an Itaniumbased processor) are unassembled. For more information about the syntax, see Address and Address Range Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you do not specify a parameter for the up command, the disassembly begins at the current address and extends eight instructions (on an x86-based processor) or nine
instructions (on an Itanium-based processor).
Do not confuse this command with the u (Unassemble). The up command disassembles only physical memory, while the u command disassembles only virtual memory.
Additional Information
For more information about assembly debugging and related commands, see Debugging in Assembly Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ur (Unassemble Real Mode BIOS)

The ur command displays an assembly translation of the specified 16-bit real-mode code.
Syntax
ur Range
ur Address
ur
Parameters
Range
Specifies the memory range that contains the instructions to disassemble. For more information about the syntax, see Address and Address Range Syntax.
Address
Specifies the beginning of the memory range to disassemble. Eight instructions (on an x86-based processor) or nine instructions (on an Itanium-based processor) are
unassembled. For more information about the syntax, see Address and Address Range Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 322 of 1651

If you do not specify Range or Address, the disassembly begins at the current address and extends eight instructions (on an x86-based processor) or nine instructions (on an
Itanium-based processor).
If you are examining 16-bit real-mode code on an x86-based processor, both the ur command and the u (Unassemble) command give correct results.
However, if real-mode code exists in a location where the debugger is not expecting it (for example, a non-x86 computer that is running or emulating x86-based BIOS code
from a plug-in card), you must use ur to correctly disassemble this code.
If you use ur on 32-bit or 64-bit code, the command tries to disassemble the code as if it were 16-bit code. This situation produces meaningless results.
Additional Information
For more information about how to debug BIOS code, see Debugging BIOS Code.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ux (Unassemble x86 BIOS)

The ux command displays the instruction set of the x86-based BIOS code.
Syntax
ux [Address]
Parameters
Address
Specifies the memory offset within the x86-based BIOS code. If you omit this parameter or specify zero, the default offset is the beginning of the BIOS.
Environment
Modes
Kernel mode only
Targets Live debugging only
Platforms x86-based only
Comments
The debugger displays the instructions that are generated from the first eight lines of code, beginning at the Address offset.
To make the ux command work correctly, HAL symbols must be available to the debugger. If the debugger cannot find these symbols, the debugger displays a "couldn't
resolve" error.
Additional Information
For more information about how to debug BIOS code, see Debugging BIOS Code.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

vercommand (Show Debugger Command Line)

The vercommand command displays the command that opened the debugger.
Syntax
vercommand
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 323 of 1651

Debugging Tools for Windows

version (Show Debugger Version)

The version command displays version information about the debugger and all loaded extension DLLs. This command also displays the current version of the operating
system of the target computer.
Do not confuse this command with the !version (Show DLL Version) extension command.
Syntax
version
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
See Also
CTRL+W (Show Debugger Version), vertarget (Show Target Computer Version)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

vertarget (Show Target Computer Version)

The vertarget command displays the current version of the Microsoft Windows operating system of the target computer.
Syntax
vertarget
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
See Also
CTRL+W (Show Debugger Version), version (Show Debugger Version)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

wrmsr (Write MSR)

The wrmsr command writes a value to a Model-Specific Register (MSR) at the specified address.
Syntax
wrmsr Address Value
Parameters
Address
Specifies the address of the MSR.
Value
Specifies the 64-bit hexadecimal value to write to the MSR.
Environment
Modes
Targets

Kernel mode only

Live debugging only

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 324 of 1651

Platforms All
Comments
The wrmsr command can display MSR's on x86-based, Itanium-based, and x64-based platforms. The MSR definitions are platform-specific.
See Also
rdmsr (Read MSR)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

wt (Trace and Watch Data)

The wt command runs through the whole function and then displays statistics, when you execute this command at the beginning of a function call.
Syntax
wt [WatchOptions] [= StartAddress] [EndAddress]
Parameters
WatchOptions
Specifies how to modify the display. You can use any of the following options.
Option
Effect
-l Depth (User mode only) Specifies the maximum depth of the calls to display. Any calls that are at least Depth levels deeper than the starting point are executed
silently.
-m
(User mode only) Restricts the display to code inside the specified module, plus the first level of calls made from that module. You can include multiple -m
Module options to display code from multiple modules and no other modules.
-i Module (User mode only) Ignores any code within the specified module. You can include multiple -i options to ignore code from multiple modules. If you use a -m
option, the debugger ignores all -i options.
-ni
(User mode only) Does not display any entry into code that is being ignored because of an -m or -i option.
-nc
Does not display individual call information.
-ns
Does not display summary information.
-nw
Does not display warnings during the trace.
-oa
(User mode only) Displays the actual address of call sites.
-or
(User mode only) Displays the return register values of the called function, using the default radix as the base.
-oR
(User mode only) Displays the return register values of the called function, in the appropriate type for each return value.
StartAddress
Specifies the address where the debugger begins execution. If you do not use StartAddress, execution begins at the instruction that the instruction pointer points to. For
more information about the syntax, see Address and Address Range Syntax.
EndAddress
Specifies the address where tracing ends. If you do not use EndAddress, a single instruction or function call is executed.
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms User mode: all
Kernel mode: x86-based only
Comments
The wt command is useful if you want information about the behavior of a specific function, but you do not want to step through the function. Instead, go to the beginning of
that function and then issue the wt command.
If the program counter is at a point that corresponds to a symbol (such as the beginning of a function or entry point into a module), the wt command traces until it reaches the
current return address. If the program counter is on a call instruction, the wt command traces until it returns to the current location. This tracing is profiled in the Debugger
Command window together with output that describes the various calls that the command encounters.
If the wt command is issued somewhere other than the beginning of a function, the command behaves like the p (Step) command. However, if you specify EndAddress,
execution continues until that address is reached, even if this execution involves many program steps and function calls.
When you are debugging in source mode, you should trace into the function only to the point where you see the opening bracket of the function body. Then, you can use the
wt command. (It is typically easier to insert a breakpoint at the first line of the function, or use Debug | Run to Cursor, and then use the wt command.)
Because the output from wt can be long, you might want to use a log file to record your output. For more information about log files, see Keeping a Log File.
The following example shows a typical log file.
0:000> l+
Source options are f:

Source options set to show source lines

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 325 of 1651

1/t - Step/trace by source line

2/l - List source line for LN and prompt
4/s - List source code at prompt
8/o - Only show source code at prompt
0:000> p
Not yet at the function call: use "p"
> 44:
minorVariableOne = 12;
0:000> p
> 45:
variableOne = myFunction(2, minorVariable);
0:000> t
At the function call: now use "t"
MyModule!ILT+10(_myFunction):
0040100f e9cce60000
jmp
MyModule!myFunction (0040f6e0)
0:000> t
> 231:
{
0:000> wt
At the function beginning: now use "wt"
Tracing MyModule!myFunction to return address 00401137
105
1
9
1
11
1
14
50
17
1
59
39
111
39

0
0
0
0
0
0
0
15
66
0
0
0
39
0

[
[
[
[
[
[
[
[
[
[
[
[
[
[

0] MyModule!myFunction
1]
MyModule!ILT+1555(_printf)
1]
MyModule!printf
2]
MyModule!ILT+370(__stbuf)
2]
MyModule!_stbuf
3]
MyModule!ILT+1440(__isatty)
3]
MyModule!_isatty
2]
MyModule!_stbuf
1]
MyModule!printf
2]
MyModule!ILT+980(__output)
2]
MyModule!_output
3]
MyModule!write_char
2]
MyModule!_output
3]
MyModule!write_char

0
11675
11729
11895
11996
83789
0
0
83782

[
[
[
[
[
[
[
[
[

5]
kernel32!__SEH_epilog4
4]
kernel32!ReadFile
3]
MyModule!_read
2]
MyModule!_filbuf
1]
MyModule!fgets
0] MyModule!myFunction
1]
MyModule!ILT+1265(__RTC_CheckEsp)
1]
MyModule!_RTC_CheckEsp
0] MyModule!myFunction

....
11
54
165
100
91
54545
1
2
54547

112379 instructions were executed in 112378 events (0 from other threads)

Function Name
MyModule!ILT+1265(__RTC_CheckEsp)
MyModule!ILT+1440(__isatty)
MyModule!ILT+1540(__ftbuf)
....
ntdll!memcpy
ntdll!memset

Invocations MinInst MaxInst AvgInst

1
1
1
1
21
1
1
1
21
1
1
1
24
2

1
29

40
29

19
29

23 system calls were executed

Calls
23

System Call
ntdll!KiFastSystemCall

In the listing of the trace, the first number specifies the number of instructions that were executed, the second number specifies the number of instructions executed by child
processes of the function, and the third number (in brackets) specifes the depth of the function in the stack (taking the initial function as zero). The indentation of the function
name shows the call depth.
In the preceding example, MyModule!myFunction executes 105 instructions before it calls several subroutines, including printf and fgets, and then executes 54545
additional instructions after calling those functions, but before issuing a few more calls. However, in the final count, the display shows that myFunction executes 112,379
instructions, because this count includes all of the instructions that myFunction and its children execute. (The children of myFunction are functions that are called from
myFunction, either directly or indirectly.)
In the preceding example, note also that ILT+1440 (__isatty) is called 21 times. In the final count, the summary of this function's behavior shows the number of times that it
was called, the smallest number of instructions in any single execution, the largest number of instructions in any single execution, and the average number of instructions per
execution.
If any system calls are made, they appear in the counter and are listed again at the end of the command output.
Additional Information
For more information about issuing the wt command and an overview of related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 326 of 1651

Debugging Tools for Windows

x (Examine Symbols)
The x command displays the symbols in all contexts that match the specified pattern.
Syntax
x [Options] Module!Symbol
x [Options] *
Parameters
Options
Specifies symbol searching options. You can use one or more of the following options:
/t
Displays the data type of each symbol, if the data type is known.
/v
Displays the symbol type (local, global, parameter, function, or unknown) of each symbol. This option also displays the size of each symbol. The size of a function
symbol is the size of the function in memory. The size of other symbols is the size of the data type that the symbol represents. Size is always measured in bytes and
displayed in hexadecimal format.
/s Size
Display only those symbols whose size, in bytes, equals the value of Size. The Size of a function symbol is the size of the function in memory. The Size of other
symbols is the size of the data type that the symbol represents. Symbols whose size cannot be determined are always displayed. Size must be a nonzero integer.
/q
Displays symbol names in quoted format.
/p
Omits the space before the opening parenthesis when the debugger displays a function name and its arguments. This kind of display can make it easier if you are
copying function names and arguments from the x display to another location.
/f
Displays the data size of a function.
/d
Displays the data size of data.
/a
Sorts the display by address, in ascending order.
/A
Sorts the display by address, in descending order.
/n
Sorts the display by name, in ascending order.
/N
Sorts the display by name, in descending order.
/z
Sorts the display by size, in ascending order.
/Z
Sorts the display by size, in descending order.
Module
Specifies the module to search. This module can be an .exe, .dll, or .sys file. Module can contain a variety of wildcard characters and specifiers. For more information
about the syntax, see String Wildcard Syntax.
Symbol
Specifies a pattern that the symbol must contain. Symbol can contain a variety of wildcard characters and specifiers. For more information about the syntax, see String
Wildcard Syntax.
Because this pattern is matched to a symbol, the match is not case sensitive, and a single leading underscore (_) represents any quantity of leading underscores. You can
add spaces within Symbol, so that you can specify symbol names that contain spaces (such as "operator new" or "Template<A, B>") without using wildcard characters.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The x command displays all of the public symbols for the specified module (Module) that match the specified pattern (Symbol). For example, the following command finds all
of the symbols in MyModule that contain the string "spin".
0:000> x mymodule!*spin*
The following command quickly locates the "DownloadMinor" and "DownloadMajor" symbols in MyModule.
0:000> x mymodule!downloadm??or
You can also show all symbols in the MyModule by using the following command.
0:000> x mymodule!*
The preceding commands also force the debugger to reload symbol information from MyModule. If you want to reload the symbols in the module with a minimal display, use
the following command.
0:000> x mymodule!*start*

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 327 of 1651

A few symbols always contain the string "start". Therefore, the preceding command always displays some output to verify that the command works. But the preceding
command avoids the excessive display length of x mymodule!*.
The display shows the starting address of each symbol and the full symbol name. If the symbol is a function name, the display also includes a list of its argument types. If the
symbol is a global variable, its current value is displayed.
There is one other special case of the x command. To display the addresses and names of all local variables for the current context, use the following command.
0:000> x *
Note In most cases, you cannot access local variables unless private symbols have been loaded. For more information about this situation, see dbgerr005: Private Symbols
Required. To display the values of local variables, use the dv (Display Local Variables) command.
The following code examples show the additional x options. When you use the /v option, the first column of the display shows the symbol type (local, global, parameter,
function, or unknown). The second column is the address of the symbol. The third column is the size of the symbol, in bytes. The fourth column shows the module name and
symbol name. In some cases, this display is followed by an equal sign (=) and then the data type of the symbol. The source of the symbol (public or full symbol information)
is also displayed.
kd> x /v nt!CmType*
global 806c9e68
0
global 806c9e68 150
global 806c9e68
0
global 805bd7b0
0
global 805bd7b0
a8

nt!CmTypeName =
nt!CmTypeName =
nt!CmTypeName =
nt!CmTypeString
nt!CmTypeString

struct _UNICODE_STRING []
struct _UNICODE_STRING [42]
struct _UNICODE_STRING []
= unsigned short *[]
= unsigned short *[42]

In the preceding example, the size is given in hexadecimal format, while the data type is given in decimal format. Therefore, in the last line of the preceding example, the data
type is an array of 42 unsigned short integers. The size of this array is 42*4 = 168, and 168 is displayed in hexadecimal format as 0xA8.
You can use the /s Size option to display only those symbols whose size, in bytes, is a certain value. For example, you can restrict the command in the preceding example to
symbols that represent objects whose size is 0xA8.
kd> x /v /s a8 nt!CmType*
global 805bd7b0
a8 nt!CmTypeString = unsigned short *[42]
The /t option causes the debugger to display information about each symbol's data type. Note that for many symbols, this information is displayed even without the /t option.
When you use /t, such symbols have their data type information displayed twice.
0:001> x prymes!__n*
00427d84 myModule!__nullstring = 0x00425de8 "(null)"
0042a3c0 myModule!_nstream = 512
Type information missing error for _nh_malloc
004021c1 myModule!MyStructInstance = struct MyStruct
00427d14 myModule!_NLG_Destination = <no type information>
0:001> x /t prymes!__n*
00427d84 char * myModule!__nullstring = 0x00425de8 "(null)"
0042a3c0 int myModule!_nstream = 512
Type information missing error for _nh_malloc
004021c1 struct MyStruct myModule!MyStructInstance = struct MyStruct
00427d14 <NoType> myModule!_NLG_Destination = <no type information>
The following example demonstrates the switch /f when used to filter functions on the module notepad.exe.
0:000> x /f /v notepad!*main*
prv func
00000001`00003340 249 notepad!WinMain (struct HINSTANCE__ *, struct HINSTANCE__ *, char *, int)
prv func
00000001`0000a7b0
1c notepad!WinMainCRTStartup$filt$0 (void)
prv func
00000001`0000a540 268 notepad!WinMainCRTStartup (void)
See Also
Verifying Symbols, dv (Display Local Variables)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

z (Execute While)
The z command executes a command while a given condition is true.
Syntax
User-Mode
Command ; z( Expression )

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 328 of 1651

Kernel-Mode
Command ; [Processor] z( Expression )
Parameters
Command
Specifies the command to execute while the Expression condition evaluates to a nonzero value. This command is always executed at least once.
Processor
Specifies the processor that applies to the test. For more information about the syntax, see Multiprocessor Syntax. You can specify processors only in kernel mode.
Expression
Specifies the condition to test. If this condition evaluates to a nonzero value, the Command command is executed again and then Expression is tested again. For more
information about the syntax, see Numerical Expression Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
In many debugger commands, the semicolon is used to separate unrelated commands. However, in the z command, a semicolon seperates the "z" from the Command
parameter.
The Command command is always executed at least once, and then Expression is tested. If the condition is a nonzero value, the command is again executed, and then
Expression is tested again. (This behavior is similar to a C-language do - while loop, not a simple while loop.)
If there are several semicolons to the left of the "z", all commands to the left of the "z" repeat as long as the Expression condition is true. Such commands can be any debugger
commands that permit a terminal semicolon.
If you add another semicolon and additional commands after the z command, these additional commands are executed after the loop is complete. We do not typically
recommend a line that begins with "z" because it generates uninteresting output forever unless the condition becomes false because of some other action. Note that you can
nest z commands.
To break a loop that is continuing for too long, use CTRL+C in CDB or KD, or use Debug | Break or CTRL+BREAK in WinDbg.
The following code example shows an unnecessarily complex way to zero the eax register.
0:000> reax = eax - 1 ; z(eax)
The following example increments the eax and ebx registers until one of them is at least 8 and then it increments the ecx register once.
0:000> reax=eax+1; rebx=ebx+1; z((eax<8)|(ebx<8)); recx=ecx+1
The following example uses C++ expression syntax and uses the pseudo-register $t0 as a loop variable.
0:000> .expr /s c++
Current expression evaluator: C++ - C++ source expressions
0:000> db pindexcreate[@$t0].szKey; r$t0=@t0+1; z( @$t0 < cIndexCreate )
See Also
j (Execute If-Else)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Meta-Commands
This section of the reference discusses the various debugger meta-commands that can be used in CDB, KD, and WinDbg. These commands are preceded by a period (.).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.abandon (Abandon Process)

The .abandon command ends the debugging session, but leaves the target application in a debugging state. This returns the debugger to dormant mode.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 329 of 1651

Syntax
.abandon [ /h | /n ]
Parameters
/h
Any outstanding debug event will be continued and marked as handled. This is the default.
/n
Any outstanding debug event will be continued unhandled.
Environment
This command is only supported in Windows XP and later versions of Windows.
Modes
user mode only
Targets live debugging only
Platforms all
Additional Information
If the target is left in a debugging state, a new debugger can be attached to it. See Re-attaching to the Target Application for details. However, after a process has been
abandoned once, it can never be restored to a running state without a debugger attached.
For other methods of exiting the debugger or detaching from the target, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.allow_exec_cmds (Allow Execution Commands)

The .allow_exec_cmds command controls whether execution commands can be used.
Syntax
.allow_exec_cmds 0
.allow_exec_cmds 1
.allow_exec_cmds
Parameters
0
Prevents execution commands from being used.
1
Allows execution commands to be used.
Environment
Modes
user mode and kernel mode
Targets live debugging only
Platforms all
Comments
With no parameters, .allow_exec_cmds will display whether execution commands are currently permitted.
Execution commands include g (Go), t (Trace), p (Step), and any other command or WinDbg graphical interface action that would cause the target to execute.
Additional Information
For a complete list of execution commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.allow_image_mapping (Allow Image Mapping)

The .allow_image_mapping command controls whether image files will be mapped.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 330 of 1651

Syntax
.allow_image_mapping [/r] 0
.allow_image_mapping [/r] 1
.allow_image_mapping
Parameters
/r
Reloads all modules in the debugger's module list. This is equivalent to .reload /d.
0
Prevents image files from being mapped.
1
Allows image files to be mapped.
Environment
Modes
user mode and kernel mode
Targets live, crash dump
Platforms all
Comments
With no parameters, .allow_image_mapping will display whether image file mapping is currently allowed. By default, this mapping is allowed.
Image mapping is most common when a minidump is being debugged. Image mapping can also occur if DbgHelp is unable to access debug records (for example, during
kernel debugging when memory has been paged out).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.apply_dbp (Apply Data Breakpoint to Context)

The .apply_dbp command applies the current process' existing data breakpoints to the specified register context.
Syntax
.apply_dbp [/m Context]
Parameters
/m Context
Specifies the address of a register context (CONTEXT structure) in memory to which to apply the current process' data breakpoints.
Environment
Modes
user mode and kernel mode
Targets live target only
Platforms all
Comments
Breakpoints that are controlled by the processor are called data breakpoints or processor breakpoints. These breakpoints are created by the ba (Break on Access) command.
These breakpoints are associated with a memory location in the address space of a specific process. The .apply_dbp command modifies the specified register context so that
these data breakpoints will be active when this context is used.
If the /m Address parameter is not used, data breakpoints will be applied to the current register context.
This command can only be used if the target is in native machine mode. For example, if the target is running on a 64-bit machine emulating an x86 processor using WOW64,
this command cannot be used.
One example of a time this command is useful is when you are in an exception filter. The .apply_dbp command can update the exception filter's stored context. Data
breakpoints will then be applied when the exception filter exits and the stored context is resumed. Without such a modification it is possible that data breakpoints would be
lost.
Additional Information
For more information about breakpoints controlled by the processor, see Processor Breakpoints (ba Breakpoints). For more information about the register context (thread
context), see Register Context.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 331 of 1651

December 09, 2009

Debugging Tools for Windows

.asm (Change Disassembly Options)

The .asm command controls how disassembly code will be displayed.
Syntax
.asm
.asm[-] Options
Parameters
Causes the specified options to be disabled. If no minus sign is used, the specified options will be enabled.
Options
Can be any number of the following options:
ignore_output_width
Prevents the debugger from checking the width of lines in the disassembly display.
no_code_bytes
(x86 and x64 targets only) Suppresses the display of raw bytes.
source_line
Prefixes each line of disassembly with the line number of the source code.
verbose
(Itanium target only) Causes bundle-type information to be displayed along with the standard disassembly information.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
Using .asm by itself displays the current state of the options.
This command affects the display of any disassembly instructions in the Debugger Command window. In WinDbg it also changes the contents of the Disassembly window.
Additional Information
For a description of assembly debugging and related commands, see Debugging in Assembly Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.attach (Attach to Process)

The .attach command attaches to a new target application.
Syntax
.attach [-premote RemoteOptions] AttachOptions PID
Parameters
RemoteOptions
Specifies a process server to attach to. The options are the same as those for the command line -premote option. See Activating a Smart Client for syntax details.
AttachOptions
Specifies how the attach is to be done. This can include any of the following options:
-b
(Windows XP and later) Prevents the debugger from requesting an initial break-in when attaching to a target process. This can be useful if the application is already
suspended, or if you want to avoid creating a break-in thread in the target.
-e
(Windows XP and later) Allows the debugger to attach to a process that is already being debugged. See Re-attaching to the Target Application for details.
-k
(Windows XP and later) Begins a local kernel debugging session. See Performing Local Kernel Debugging for details.
-f
Freezes all threads in all target applications, except in the new target being attached to. These threads will remain frozen until an exception occurs in the newlyattached process. Note that an initial breakpoint qualifies as an exception. Individual threads can be unfrozen by using the ~u (Unfreeze Thread) command.
-r
(Windows XP and later) Causes the debugger to start the target process running when it attaches to it. This can be useful if the application is already suspended and
you want it to resume execution.
-v

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 332 of 1651

Causes the specified process to be debugged noninvasively.

PID
Specifies the process ID of the new target application.
Environment
Modes
user mode only
Targets live debugging only
Platforms all
Comments
This command can be used when CDB is dormant, or if it is already debugging one or more processes. It cannot be used when WinDbg is dormant.
If this command is successful, the debugger will attach to the specified process the next time the debugger issues an execution command. If this command is used several
times in a row, execution will have to be requested as many times as this command was used.
Because execution is not permitted during noninvasive debugging, the debugger is not able to noninvasively debug more than one process at a time. This also means that
using the .attach -v command may render an already-existing invasive debugging session less useful.
Multiple target processes will always be executed together, unless some of their threads are frozen or suspended.
If you wish to attach to a new process and freeze all your existing targets, use the -f option. For example, you might be debugging a crash in a client application and want to
attach to the server process without letting the client application continue running.
If the -premote option is used, the new process will be part of a new system. For details, see Debugging Multiple Targets.
Additional Information
For more details and for other methods of attaching to a process, see Attaching to a Running Process (User Mode) and Noninvasive Debugging (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.beep (Speaker Beep)

The .beep command makes noise on the computer speaker.
Syntax
.beep
Environment
This command cannot be used in script files.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.bpcmds (Display Breakpoint Commands)

The .bpcmds command displays the commands that were used to set each of the current breakpoints.
Syntax
.bpcmds
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 333 of 1651

If it is unclear whether a particular breakpoint is set at an address, at a symbolic reference, or at a symbol, use the .bpcmds command to shows which breakpoint command
was used to creat it. The command that was used to create a breakpoint determines its nature:

The bp (Set Breakpoint) command sets a breakpoint at an address.

The bu (Set Unresolved Breakpoint) command sets a breakpoint on a symbolic reference.
The bm (Set Symbol Breakpoint) command sets a breakpoint on symbols that match a specified pattern. If the /d switch is included, it creates zero or more
breakpoints on addresses (like bp), otherwise it creates zero or more breakpoints on symbolic references (like bu).
The ba (Break on Access) command sets a data breakpoint at an address.

The output of .bpcmds reflects the current nature of each breakpoint. Each line of the .bpcmds display begins with the command used to create it (bp, bu, or ba) followed by
the breakpoint ID, and then the location of the breakpoint.
If the breakpoint was created by ba, the access type and size are displayed as well.
If the breakpoint was created by bm without the /d switch, the display indicates the breakpoint type as bu, followed by the evaluated symbol enclosed in the @!"" token
(which indicates it is a literal symbol and not a numeric expression or register). If the breakpoint was created by bm with the /d switch, the display indicates the breakpoint
type as bp.
Here is an example:
0:000> bp notepad!winmain
0:000> .bpcmds
bp0 0x00000001`00003340 ;
0:000> bu myprog!winmain
breakpoint 0 redefined
0:000> .bpcmds
bu0 notepad!winmain;
0:000> bu myprog!LoadFile
0:000> bp myprog!LoadFile+10
0:000> bm myprog!openf*
3: 00421200 @!"myprog!openFile"
4: 00427800 @!"myprog!openFilter"
0:000> bm /d myprog!closef*
5: 00421600 @!"myprog!closeFile"
0:000> ba r2 myprog!LoadFile+2E
0:000> .bpcmds
bu0 notepad!winmain;
bu1 notepad!LoadFile;
bp2 0x0042cc10 ;
bu3 @!"myprog!openFile";
bu4 @!"myprog!openFilter";
bp5 0x00421600 ;
ba6 r2 0x0042cc2e ;
In this example, notice that the output of .bpcmds begins with the relevant command ("bu", "bp", or "ba"), followed by the breakpoint number (with no intervening space).
Notice that because breakpoint number 0 was originally set using bp, and then was redefined using bu, the display shows its type as "bu".
Notice also that breakpoints 3, 4, and 5, which were created by the bm commands shown in this example, are displayed as either type "bp" or type "bu", depending on
whether the /d switch was included when bm was used.
Additional Information
For more information about and examples of how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, see Using Breakpoints.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.bpsync (Synchronize Threads at Breakpoint)

When a thread reaches a breakpoint, the .bpsync command freezes all other threads, until the thread to which the breakpoint applies has stepped through the breakpoint.
Syntax
.bpsync 1
.bpsync 0
.bpsync

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 334 of 1651

Parameters
1
Causes all threads to freeze when one thread has reached a breakpoint. After the thread to which the breakpoint applies has stepped through the breakpoint, the other
threads are unfrozen.
0
Allows other threads to continue executing when one thread has reached a breakpoint. This is the default behavior.
Environment
Modes
user mode only
Targets live, crash dump
Platforms all
Comments
With no parameters. the .bpsync command displays the current rule governing breakpoint synchronization behavior.
The .bpsync command applies both to software breakpoints (set with bp, bu, or bm) and to processor breakpoints (set with ba).
If there is a possibility of multiple threads running through the same code, the .bpsync 1 command can be useful for capturing all breakpoint occurrences. Without this
command, a breakpoint occurrence could be missed because the first thread to reach the breakpoint always causes the debugger to temporarily remove the breakpoint. In the
short period when the breakpoint is removed, other threads could reach the same place in the code and not trigger the breakpoint as intended.
The temporary removal of breakpoints is a normal aspect of debugger operation. When the target reaches a breakpoint and is resumed, the debugger has to remove the
breakpoint temporarily so that the target can execute the real code. After the real instruction has been executed, the debugger reinserts the break. To do this, the debugger
restores the code (or turns off data breaks), does a single-step, and then puts the break back.
Note that if you use .bpsync 1, there is a risk of deadlocks among the threads that have been frozen.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.breakin (Break to the Kernel Debugger)

The .breakin command switches from user-mode debugging to kernel-mode debugging. This command is particularly useful when you are controlling the user-mode
debugger from the kernel debugger.
Syntax
.breakin
Environment
Modes
user mode only
Targets live debugging only
Platforms all
Comments
If kernel-mode debugging was enabled during the boot process and you are running a user-mode debugger, you can use the .breakin command to halt the operating system
and transfer control to a kernel debugger.
The .breakin command causes a kernel-mode break in the debugger's process context. If a kernel debugger is attached, it will become active. The kernel debugger's process
context will automatically be set to the process of the user-mode debugger, not the user-mode debugger's target process.
This command is primarily useful when debugging a user-mode problem requires retrieving information about the kernel state of the system. Resuming execution in the
kernel debugger is necessary before the user-mode debugging session can continue.
When you are controlling the user-mode debugger from the kernel debugger and the user-mode debugger prompt is visible in the kernel debugger, this command will pause
the user-mode debugger and make the kernel-mode debugging prompt appear.
If the system is unable to break into the kernel debugger, an error message is displayed.
This command is also useful if you use the kernel debugger to set a breakpoint in user space and that breakpoint is caught by a user-mode debugger instead of the kernel
debugger. Issuing this command in the user-mode debugger will transfer control to the kernel debugger.
If the .breakin command is used on a system that was not booted with debugging enabled, it has no effect.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 335 of 1651

.bugcheck (Display Bug Check Data)

The .bugcheck command displays the data from a bug check on the target computer.
Syntax
.bugcheck
Environment
Modes
kernel mode only
Targets live, crash dump
Platforms all
Comments
This command displays the current bug check data. (This bug check data will be accessible until the crashed machine is rebooted.)
You can also display bug check data on 32-bit systems by using dd NT!KiBugCheckData L5, or on 64-bit systems by using dq NT!KiBugCheckData L5. However,
the .bugcheck command is more reliable, because it works in some scenarios that the d* (Display Memory) command will not (such as user-mode minidumps).
The !analyze extension command is also useful after a bug check occurs.
Additional Information
For more information about bug checks, see Bug Checks (Blue Screens). For a description of individual bug checks, see the Bug Check Code Reference section.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.cache (Set Cache Size)

The .cache command sets the size of the cache used to hold data obtained from the target. Also sets a number of cache and memory options.
Syntax
.cache Size
.cache Option
.cache
Parameters
Size
The size of the kernel debugging cache, in kilobytes. If Size is zero, the cache is disabled. The command output displays the cache size in bytes. (The default size is 1000
KB.)
Option
Can be any one of the following options:
hold
Automatic cache flushing is disabled.
unhold
Turns off the hold option. (This is the default setting.)
decodeptes
All transition page table entries (PTEs) will be implicitly decoded. (This is the default setting.)
nodecodeptes
Turns off the decodeptes option.
forcedecodeptes
All virtual addresses will be translated into physical addresses before access. This option also causes the cache to be disabled. Unless you are concerned with kernelmode memory, it is more efficient to use forcedecodeuser instead.
forcedecodeuser
All user-mode virtual addresses will be translated into physical addresses before access. This option also causes the cache to be disabled.
Note You must activate forcedecodeuser (or forcedecodeptes) before using .thread (Set Register Context), .context (Set User-Mode Address Context),
.process (Set Process Context), or !session during live debugging. If you use the /p option with .thread and .process, the forcedecodeuser option is automatically
set. In any other case, you will need to use the .cache forcedecodeuser command explicitly.
noforcedecodeptes
Turns off the forcedecodeptes and forcedecodeuser options. (This is the default setting.)
flushall
Deletes the entire virtual memory cache.
flushu
Deletes all entries of ranges with errors from the cache, as well as all user-mode entries.
flush Address
Deletes a 4096-byte block of the cache, beginning at Address.
Environment

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 336 of 1651

Modes
kernel mode only
Targets live debugging only
Platforms all
Comments
If .cache is used with no arguments, the current cache size, status, and options are displayed.
The .cache forcedecodeuser or .cache forcedecodeptes option will only last as long as the debugger remains broken into the target computer. If any stepping or execution of
the target takes place, the noforcedecodeptes state will again take effect. This prevents the debugger from interfering with execution or a reboot in an unproductive manner.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.call (Call Function)

The .call command causes the target process to execute a function.
Syntax
.call
.call
.call
.call

[/v] Function( Arguments )

/s Prototype Function( Arguments )
/c
/C

Parameters
/v
Verbose information about the call and its arguments is displayed.
/s Prototype
Allows you to call the function that is specified by Function even though you do not have the correct symbols. In this case, you must have symbols for another function
that has the same calling prototype as the function you are trying to call. The Prototype parameter is the name of this prototype function.
Function
Specifies the function being called. This can be the name of the function (preferably qualified with a module name), or any other expression that evaluates to the function
address. If you need to call a constructor or destructor, you must supply the address or else use a C++ expression to evaluate named syntax for the operators (see
Numerical Expression Syntax for details).
Arguments
Specifies the arguments passed to the function. If you are calling a method, the first argument must be this, and all other arguments follow it. Arguments should be
separated with commas and should match the usual argument syntax. Variable-length argument lists are supported. Expressions within an argument are parsed by the
C++ expression evaluator; see C++ Numbers and Operators for details. You cannot enter a literal string as an argument, but you can use a pointer to a string, or any other
memory accessible to the target process.
/c
Clears any existing call on the current thread.
/C
Clears any existing call on the current thread, and resets the context of the current thread to the context stored by the outstanding call.
Environment
Modes
user mode only
Targets live debugging only
Platforms x86 and x64 only
Comments
The specified function is called by the current thread of the current process.
Only the cdecl, stdcall, fastcall, and thiscall calling conventions are supported. Managed code cannot be called by this command.
After .call is used, the debugger will update the stack, change the instruction pointer to point to the beginning of the called function, and then stop. Use g (Go) to resume
execution, or ~. g to execute just the thread making the call.
When the function returns, a break occurs and the debugger displays the return value of the function. The return value is also stored in the $callret pseudo-register, which
acquires the type of the return value.
If you have broken into the target using CTRL+C or CTRL+BREAK, the current thread is an additional thread created to handle the breakin. If you issue a .call command at
this point, the extra thread will be used for the called function.
If you have reached a predefined breakpoint, there is no extra breakin thread. If you use .call while at a breakpoint in user mode, you could use g to execute the entire process,
or ~. g to execute just the current thread. Using g may distort your program's behavior, since you have taken one thread and diverted it to this new function. On the other hand,
this thread will still have its locks and other attributes, and thus ~. g may risk deadlocks.
The safest way to use .call is to set a breakpoint in your code at a location where a certain function could be safely called. When that breakpoint is hit, you can use .call if you
desire that function to run. If you use .call at a point where this function could not normally be called, a deadlock or target corruption could result.
It may be useful to add extra functions to your source code that are not called by the existing code, but are intended to be called by the debugger. For example, you could add
functions that are used to investigate the current state of your code and its environment and store information about the state in a known memory location. Be sure not to

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 337 of 1651

optimize your code, or these functions may be removed by the compiler. Use this technique only as a last resort, because if your application crashes .call will not be available
when debugging the dump file.
The .call /c and .call /C commands should only be used if an attempt to use .call has failed, or if you changed your mind before entering the g command. These should not be
used casually, since abandoning an uncompleted call can lead to a corrupted target state.
The following code example shows how the .call /s command is used.
.call /s KnownFunction UnknownFunction( 1 )
In this example, you have private symbols for KnownFunction, which takes an integer as its only argument and returns, for example, a pointer to an array. You do not have
symbols, or possibly you only have public symbols for UnknownFunction, but you do know that it takes an integer as its only argument and returns a pointer to an array. By
using the /s option, you can specify that UnknownFunction will work the same way that KnownFunction does. Thus, you can successfully generate a call to
UnknownFunction.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.chain (List Debugger Extensions)

The .chain command lists all loaded debugger extensions in their default search order.
Syntax
.chain
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Additional Information
For details on loading, unloading, and controlling extensions, see Loading Debugger Extension DLLs. For details on executing extension commands and an explanation of the
default search order, see Using Debugger Extension Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.childdbg (Debug Child Processes)

The .childdbg command controls the debugging of child processes.
Syntax
.childdbg 0
.childdbg 1
.childdbg
Parameters
0
Prevents the debugger from debugging child processes.
1
Causes the debugger to debug child processes.
Environment
This command is only supported in Windows XP and later versions of Windows.
Modes
user mode only
Targets live debugging only
Platforms x86, x64, and Itanium only
Comments
Child processes are additional processes launched by the original target application.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

The .cordll command controls managed code debugging and the Microsoft .NET common language runtime (CLR).
Syntax
.cordll [Options]
Parameters
Options

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 341 of 1651

One or more of the following options:

-l (lower-case L)
Loads the CLR debugging modules.
-u
Unloads the CLR debugging modules.
-e
Enables CLR debugging.
-d
Disables CLR debugging.
-D
Disables CLR debugging and unloads the CLR debugging modules.
-N
Reloads the CLR debugging modules.
-lp Path
Specifies the directory path of the CLR debugging modules.
-se
Enables using the short name of the CLR debugging module, mscordacwks.dll.
-sd
Disables using the short name of the CLR debugging module, mscordacwks.dll. Instead, the debugger uses the long name of the CLR debugging module,
mscordacwks_<spec>.dll. Turning off short name usage enables you to avoid having your local CLR used if you are concerned about mismatches.
-ve
Turns on verbose mode for CLR module loading.
-vd
Turns off verbose mode for CLR module loading.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .cordll command is supported in kernel-mode debugging. However, this command might not work unless the necessary memory is paged in.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.crash (Force System Crash)

The .crash command causes the target computer to issue a bug check.
Syntax
.crash
Environment
Modes
kernel mode only
Targets live debugging only
Platforms all
Comments
This command will immediately cause the target computer to crash.
A kernel-mode dump file will be written if crash dumps have been enabled. See Creating a Kernel-Mode Dump File for details.
Additional Information
For an overview of related commands and a description of the options available after a system crash, see Crashing and Rebooting the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.create (Create Process)

The .create command creates a new target application.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 342 of 1651

.create [-premote RemoteOptions] [-f] CommandLine

Parameters
RemoteOptions
Specifies a process server to which to attach. The options are the same as those for the command line -premote option. See Activating a Smart Client for syntax details.
-f
Freezes all threads in all target applications, except in the new target being created. These threads will remain frozen until an exception occurs in the newly-created
process. Note that an initial breakpoint qualifies as an exception. Individual threads can be unfrozen by using the ~u (Unfreeze Thread) command.
CommandLine
Specifies the complete command line for the new process. CommandLine may contain spaces, and must not be surrounded with quotes. All text after the .create
command is taken as part of CommandLine; this command cannot be followed with a semicolon and additional debugger commands.
Environment
Modes
user mode only
Targets live debugging only
Platforms all
Comments
This command can be used when CDB is dormant, or if it is already debugging one or more processes. It cannot be used when WinDbg is dormant.
If this command is successful, the debugger will create the specified process the next time the debugger issues an execution command. If this command is used several times
in a row, execution will have to be requested as many times as this command was used.
Multiple target processes will always be executed together, unless some of their threads are frozen or suspended.
If you wish to create a new process and freeze all your existing targets, use the -f option.
If the -premote option is used, the new process will be part of a new system. For details, see Debugging Multiple Targets.
Additional Information
For more details and for other methods of starting new processes for debugging, see Spawning a New Process (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.createdir (Set Created Process Directory)

The .createdir command controls the starting directory and handle inheritance for any processes created by the debugger.
Syntax
.createdir [-i | -I] [Path]
Parameters
-i
Causes processes created by the debugger to inherit handles from the debugger. This is the default.
-I
Prevents processes created by the debugger from inheriting handles from the debugger.
Path
Specifies the starting directory for all child processes created by any target process. If Path contains spaces, it must be enclosed in quotation marks.
Environment
Modes
user mode only
Targets live debugging only
Platforms all
Comments
If .createdir is used with no parameters, the current starting directory and handle inheritance status are displayed.
If .createdir has never been used, any created process will use its usual default directory as its starting directory. If you have already set a path with .createdir and want to
return to the default status, use .createdir "" with nothing inside the quotation marks.
The .createdir setting affects all processes created by .create (Create Process). It also affects processes created by WinDbg's File | Open Executable menu command,
unless the Start directory text box is used to override this setting.
Additional Information
For other ways of controlling these features, and information about starting new processes for debugging, see Spawning a New Process (User Mode).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 343 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.cxr (Display Context Record)

The .cxr command displays the context record saved at the specified address. It also sets the register context.
Syntax
.cxr [Options] [Address]
Parameters
Options
Can be any combination of the following options:
/f Size
Forces the context size to equal the value of Size, in bytes. This can be useful when the context does not match the actual target for example, when using an x86
context on a 64-bit target during WOW64 debugging. If an invalid or inconsistent size is specified, the error "Unable to convert context to canonical form" will be
displayed.
/w
Writes the current context to memory, and displays the address of the location where it was written.
Address
Address of the system context record. Omitting the address does not display any context record information, but it does reset the register context.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The information from a context record can be used to assist in debugging a system halt where an unhandled exception has occurred and an exact stack trace is not available.
The .cxr command displays the important registers for the specified context record.
This command also instructs the debugger to use the specified context record as the register context. After this command is executed, the debugger will have access to the
most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command
(.thread, .ecxr, .trap , or .cxr again). In user mode, it will also be reset if you change the current process or thread. See Register Context for details.
The .cxr command is often used to debug bug check 0x1E. For more information and an example, see Bug Check 0x1E (KMODE_EXCEPTION_NOT_HANDLED).
The .cxr /w command writes the context to memory and displays the address where it has been stored. This address can be passed to .apply_dbp (Apply Data Breakpoint to
Context) if you need to apply data breakpoints to this context.
Additional Information
For more information about the register context and other context settings, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.dbgdbg (Debug Current Debugger)

The .dbgdbg command launches a new instance of CDB; this new debugger takes the current debugger as its target.
Syntax
.dbgdbg
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The .dbgdbg command is similar to the CTRL+P (Debug Current Debugger) control key. However,.dbgdbg is more versatile, because it can be used from WinDbg as well
as KD and CDB, and it can be used to debug a debugging server on a remote computer.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 344 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.detach (Detach from Process)

The .detach command ends the debugging session, but leaves any user-mode target application running.
Syntax
.detach [ /h | /n ]
Parameters
/h
Any outstanding debug event will be continued and marked as handled. This is the default.
/n
Any outstanding debug event will be continued without being marked as handled.
Environment
For live user-mode debugging, this command is only supported in Windows XP and later versions of Windows.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
This command will end the debugging session in any of the following scenarios:

When you are debugging a user-mode or kernel-mode dump file.

(Windows XP and later) When you are debugging a live user-mode target.
When you are noninvasively debugging a user-mode target.

If you are only debugging a single target, the debugger will return to dormant mode after it detaches.
If you are debugging multiple targets, the debugging session will continue with the remaining targets.
Additional Information
For other methods of exiting the debugger or detaching from the target, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.dump (Create Dump File)

The .dump command creates a user-mode or kernel-mode crash dump file.
Syntax
.dump Options FileName
.dump /?
Parameters
Options
Represents one or more of the following options
/o
Overwrites an existing dump file with the same name. If this option is not used and there is a file with the same file name, the dump file is not written.
/f
(Kernel mode:) Creates a complete memory dump.
(User mode:) Creates a full user-mode dump. Despite their names, the largest minidump file actually contains more information than a full user-mode dump. For
example, .dump /mf or .dump /ma creates a larger and more complete file than .dump /f. In user mode, .dump /m[MiniOptions] is always preferable to .dump /f.
/m[MiniOptions]
Creates a small memory dump (in kernel mode) or a minidump (in user mode). If neither /f nor /m is specified, /m is the default.
In user mode, /m can be followed with additional MiniOptions specifying extra data that is to be included in the dump. If no MiniOptions are included, the dump will

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 345 of 1651

.effmach (Effective Machine)

The .effmach command displays or changes the processor mode that the debugger uses.
Syntax
.effmach [MachineType]
Parameters
MachineType
Specifies the processor type that the debugger uses for this session. If you omit this parameter, the debugger displays the current machine type.
You can enter one of the following machine types.
Machine type Description
.
Use the processor mode of the target computer's native processor mode.
#
Use the processor mode of the code that is executing for the most recent event.
x86
Use an x86-based processor mode.
amd64
Use an x64-based processor mode.
ia64
Use an Itanium-based processor mode.
ebc
Use an EFI byte code processor mode.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The processor mode influences many debugger features:

Which processor is used for stack tracing.

Whether the process uses 32-bit or 64-bit pointers.
Which processor's register set is active.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.enable_long_status (Enable Long Integer Display)

The .enable_long_status command specifies whether the debugger displays long integers in decimal format or in the default radix.
Syntax
.enable_long_status 0
.enable_long_status 1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 351 of 1651

Parameters
0
Displays all long integers in decimal format. This is the default behavior of the debugger.
1
Displays all long integers in the default radix.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .enable_long_status command affects the output of the dt (Display Type) command.
In WinDbg, .enable_long_status also affects the display in the Locals window and the Watch window. These windows are automatically updated after you
issue .enable_long_status.
This command affects only the display of long integers. To control whether standard integers are displayed in decimal format or the default radix, use
the .force_radix_output (Use Radix for Integers) command.
Note The dv (Display Local Variables) command always displays long integers in the current number base.
To change the default radix, use the n (Set Number Base) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.enable_unicode (Enable Unicode Display)

The .enable_unicode command specifies whether the debugger displays USHORT pointers and arrays as Unicode strings.
Syntax
.enable_unicode 0
.enable_unicode 1
Parameters
0
Displays all 16-bit (USHORT) arrays and pointers as short integers. This is the default behavior of the debugger.
1
Displays all 16-bit (USHORT) arrays and pointers as Unicode strings.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .enable_unicode command affects the output of the dt (Display Type) command.
In WinDbg, the .enable_unicode command also affects the display in the Locals window and the Watch window. These windows are automatically updated after you
issue .enable_unicode.
You can also select or clear Display 16-bit values as Unicode on the shortcut menu of the Locals or Watch window to specify the display for USHORT arrays and pointers.
See Also
ds, dS (Display String)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.endpsrv (End Process Server)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 352 of 1651

The .endpsrv command causes the current process server or KD connection server to close.
Syntax
.endpsrv
Environment
You can use this command only when you are performing remote debugging through a process server or KD connection server.
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .endpsrv command terminates the process server or KD connection server currently connected to your smart client.
If you wish to terminate a process server or KD connection server from the computer on which it is running, use Task Manager to end the process (dbgsrv.exe or kdsrv.exe).
The .endpsrv command can terminate a process server or KD connection server, but it cannot terminate a debugging server. For information on how to do that, see
Controlling a Remote Debugging Session.
Additional Information
For more information about these servers, see Process Servers (User Mode) or KD Connection Servers (Kernel Mode)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.endsrv (End Debugging Server)

The .endsrv command causes the debugger to cancel an active debugging server.
Syntax
.endsrv ServerID
Parameters
ServerID
Specifies the ID of the debugging server.
Environment
You can use this command only when you are performing remote debugging through the debugger.
Modes
User mode only
Targets Live, crash dump
Platforms All
Comments
You must issue the .endsrv command from the debugging server or from one of the debugging clients that are connected to the debugging server.
To determine the ID of a debugging server, use the .servers (List Debugging Servers) command.
The .endsrv command can terminate a debugging server, but it cannot terminate a process server or KD connection server. For information on how to end these servers, see
Controlling a Process Server Session and Controlling a KD Connection Server Session. (There is, however, one exceptional case when .endsrv can end a process server that
has been launched programmatically; for details, see IDebugClient::StartProcessServer.)
If you cancel a debugging server, you prevent any future debugging clients from attaching to the server. However, if you cancel a debugging server, you do not detach any
clients that are currently attached through the server.
Consider the following situation. Suppose that you start some debugging servers, as the following example shows.
0:000>
Server
0:000>
Server

.server
started
.server
started

npipe:pipe=rabbit
with 'npipe:pipe=rabbit'
tcp:port=7
with 'tcp:port=7'

Then, you decide to use a password, as the following example shows.

0:000> .server npipe:pipe=tiger,password=hardtoguess

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 353 of 1651

Server started with 'npipe:pipe=tiger,password=hardtoguess'

But the earlier servers are still running, so you should cancel them, as the following example shows.
0:000> .servers
0 - Debugger Server - npipe:Pipe=rabbit
1 - Debugger Server - tcp:Port=7
2 - Debugger Server - npipe:Pipe=tiger,Password=*
0:000> .endsrv 0
Server told to exit. Actual exit may be delayed until
the next connection attempt.
0:000> .endsrv 1
Server told to exit. Actual exit may be delayed until
the next connection attempt.
0:000> .servers
0 - <Disabled, exit pending>
1 - <Disabled, exit pending>
2 - Debugger Server - npipe:Pipe=tiger,Password=*
Finally, to make sure that nothing attached to your computer while the earlier servers were active, use the .clients (List Debugging Clients) command.
0:000> .clients
HotMachine\HostUser, last active Mon Mar 04 16:05:21 2002
Caution Using a password with TCP, NPIPE, or COM protocol offers only a small amount of protection, because the password is not encrypted. When you use a password
together with a SSL or SPIPE protocol, the password is encrypted. If you want to establish a secure remote session, you must use the SSL or SPIPE protocol.
Additional Information
For more information about remote debugging, see Remote Debugging Through the Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.enumtag (Enumerate Secondary Callback Data)

The .enumtag command displays secondary bug check callback data and all data tags.
Syntax
.enumtag
Environment
Modes
Kernel mode only
Targets Live, crash dump
Platforms All
Comments
You can use the .enumtag command only after a bug check has occurred or when you are debugging a kernel-mode crash dump file.
For each block of secondary bug check callback data, the .enumtag command displays the tag (in GUID format) and the data (as bytes and ASCII characters).
Consider the following example.
kd> .enumtag
{87654321-0000-0000-0000000000000000}
4D 5A 90 00 03 00 00 00 04 00 00 00
B8 00 00 00 00 00 00 00 40 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00
....
00 00 00 00 00 00 00 00 00 00 00 00
{12345678-0000-0000-0000000000000000}
F4 BF 7B 80 F4 BF 7B 80 00 00 00 00
4B 44 42 47 98 02 00 00 00 20 4D 80
54 A5 57 80 00 00 00 00 A0 50 5A 80
40 01 08 00 18 00 00 00 BC 7D 50 80
....
00 00 00 00 00 00 00 00

- 0xf9c bytes
FF FF 00 00 MZ..............
00 00 00 00 ........@.......
00 00 00 00 ................
............
- 0x298 bytes
00 00 00 00 ..{...{.........
00 00 00 00 KDBG..... M.....
00 00 00 00 T.W......PZ.....
00 00 00 00 @........}P.....
........

In this example, the first batch of secondary data has a GUID ){87654321-0000-0000-0000000000000000}) as its tag, and the second batch of data has a GUID ({123456780000-0000-0000000000000000}) as its tag. However, the data is not in a useful format.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 354 of 1651

Additional Information
For more information and for other ways of displaying this data, see Reading Bug Check Callback Data.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.event_code (Display Event Code)

The .event_code command displays the current event instructions.
Syntax
.event_code
Environment
Modes
User mode, kernel mode
Targets Live debugging only
Platforms All
Comments
The .event_code command displays the hexadecimal instructions at the current event's instruction pointer. The display includes up to 64 bytes of instructions if they are
available.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.eventlog (Display Recent Events)

The .eventlog command displays the recent Microsoft Win32 debug events, such as module loading, process creation and termination, and thread creation and termination.
Syntax
.eventlog
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .eventlog command shows only 1024 characters.
The following example shows the .eventlog command.
0:000> .eventlog
0904.1014: Load module C:\Windows\system32\ADVAPI32.dll at 000007fe`fed80000
0904.1014: Load module C:\Windows\system32\RPCRT4.dll at 000007fe`fe8c0000
0904.1014: Load module C:\Windows\system32\GDI32.dll at 000007fe`fea00000
0904.1014: Load module C:\Windows\system32\USER32.dll at 00000000`76b10000
0904.1014: Load module C:\Windows\system32\msvcrt.dll at 000007fe`fe450000
0904.1014: Load module C:\Windows\system32\COMDLG32.dll at 000007fe`fecf0000
0904.1014: Load module C:\Windows\system32\SHLWAPI.dll at 000007fe`fe1f0000
0904.1014: Load module C:\Windows\WinSxS\amd64_microsoft.windows.common-controls_6595b6414
4ccf1df_6.0.6000.16386_none_1559f1c6f365a7fa\COMCTL32.dll at 000007fe`fbda0000
0904.1014: Load module C:\Windows\system32\SHELL32.dll at 000007fe`fd4a0000
0904.1014: Load module C:\Windows\system32\WINSPOOL.DRV at 000007fe`f77d0000
0904.1014: Load module C:\Windows\system32\ole32.dll at 000007fe`feb10000
0904.1014: Load module C:\Windows\system32\OLEAUT32.dll at 000007fe`feeb0000
Last event: Break instruction exception - code 80000003 (first chance)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 355 of 1651

December 09, 2009

Debugging Tools for Windows

.exepath (Set Executable Path)

The .exepath command sets or displays the executable file search path.
Syntax
.exepath[+] [Directory [; ...]]
Parameters
+
Specifies that the debugger should append the new directories to the previous executable file search path (instead of replacing the path).
Directory
Specifies one or more directories to put in the search path. If you do not specify Directory, the current path is displayed. You can separate multiple directories with
semicolons.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Additional Information
For more information about how to change this executable file search path, see Executable Image Path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.expr (Choose Expression Evaluator)

The .expr command specifies the default expression evaluator.
Syntax
.expr /s masm
.expr /s c++
.expr /q
.expr
Parameters
/s masm
Changes the default expression type to Microsoft Assembler expression evaluator (MASM). This type is the default value when you start the debugger.
/s c++
Changes the default expression type to the C++ expression evaluator.
/q
Displays the list of possible expression types.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
When you use the .expr command without an argument, the debugger displays the current default expression type.
The ?? (Evaluate C++ Expression) command, the Watch window, and the Locals window always use C++ expression syntax. All other commands and debugging
information windows use the default expression evaluator.
For more information about how to control which syntax is used, see Evaluating Expressions. For more information about the syntax, see Numerical Expression Syntax.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 356 of 1651

Debugging Tools for Windows

.exptr (Display Exception Pointers)

The .exptr command displays an EXCEPTION_POINTERS structure.
Syntax
.exptr Address
Parameters
Address
Specifies the address of the EXCEPTION_POINTERS structure.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.exr (Display Exception Record)

The .exr command displays the contents of an exception record.
Syntax
.exr Address
.exr -1
Parameters
Address
Specifies the address of the exception record. If you specify 1 as the address, the debugger displays the most recent exception.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .exr command displays information that is related to an exception that the debugger encountered on the target computer. The information that is displayed includes the
exception address, the exception code, the exception flags, and a variable list of parameters to the exception.
You can usually obtain the Address by using the !pcr extension.
The .exr command is often used to debug bug check 0x1E. For more information and an example, see Bug Check 0x1E (KMODE_EXCEPTION_NOT_HANDLED).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.extmatch (Display All Matching Extensions)

The .extmatch command displays extension commands exported by the currently loaded extension DLLs that match the specified pattern.
Syntax
.extmatch [Options] Pattern
Parameters
Options
Specifies the searching options. You can use one or more of the following options:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 357 of 1651

/e ExtDLLPattern
Limits the enumeration to extension commands exported by extension DLLs that match the specified pattern string. ExtDLLPattern is matched against the extension
DLL filename.
/n
Excludes the extension name when the extensions are displayed. Thus, if this option is specified, then only the extension name itself will be displayed.
Pattern
Specifies a pattern that the extension must contain. Pattern can contain a variety of wildcard characters and specifiers. For more information about the syntax, see String
Wildcard Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
Here is an example of this command, showing all the loaded extension DLLs that have an export named !help:
0:000> .extmatch help
!ext.help
!exts.help
!uext.help
!ntsdexts.help
The following example lists all extension commands beginning with the string "he" that are exported by extension DLLs whose names begin with the string "ex":
0:000> .extmatch /e ext* he*
!ext.heap
!ext.help
!exts.heap
!exts.help
To display a list of loaded extension DLLs, use the .chain command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.extpath (Set Extension Path)

The .extpath command sets or displays the extension DLL search path.
Syntax
.extpath[+] [Directory [; ...]]
Parameters
+
Signifies that the debugger should append new directories to the previous extension DLL search path (instead of replacing the path).
Directory
Specifies one or more directories to put in the search path. If you do not specify Directory, the current path is displayed. You can separate multiple directories with
semicolons.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Additional Information
For more information about the extension search path and loading extension DLLs, see Loading Debugger Extension DLLs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.f+, .f- (Shift Local Context)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 358 of 1651

The .f+ command shifts the frame index to the next frame in the current stack. The .f- command shifts the frame index to the previous frame in the current stack.
Syntax
.f+
.fEnvironment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The frame specifies the local context (scope) that the debugger uses to interpret local variables
The .f+ and .f- commands are shortcuts for moving to the next and previous frames in the current stack. These commands are equivalent to the following .frame commands,
but the .f commands are shorter for convenience:

.f+ is the same as .frame @$frame + 1.

.f- is the same as .frame @$frame - 1.

The dollar sign ($) identifies the frame value as a pseudo-register. The at sign (@ causes the debugger to access the value more quickly, because it notifies the debugger that a
string is a register or pseudo-register.
When an application is running, the meaning of local variables depends on the location of the program counter, because the scope of such variables extends only to the
function that they are defined in. Unless you use an .f+ or .f- command (or a .frame command), the debugger uses the scope of the current function (the current frame on the
stack) as the local context.
The frame number is the position of the stack frame within the stack trace. You can view this stack trace by using the k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)
command or the Calls window. The first line (the current frame) represents frame number 0. The subsequent lines represent frame numbers 1, 2, 3, and so on.
You can set the local context to a different stack frame to view new local variable information. However, the actual variables that are available depend on the code that is
executed.
The debugger resets the local context to the scope of the program counter if any program execution occurs. The local context is reset to the top stack frame if the register
context is changed.
Additional Information
For more information about the local context and other context settings, see Changing Contexts. For more information about how to display local variables and other memoryrelated commands, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.fiber (Set Fiber Context)

The .fiber command specifies which fiber is used for the fiber context.
Syntax
.fiber [Address]
Parameters
Address
Specifies the address of the fiber. If you omit this parameter or specify zero, the fiber context is reset to the current fiber.
Environment
User mode, kernel mode
Modes
Targets Live, crash dump
Platforms All
Additional Information
For more information about the process context, the register context, and the local context, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 359 of 1651

Debugging Tools for Windows

.fiximports (Fix Target Module Imports)

The .fiximports command validates and corrects all static import links for a target module.
Syntax
.fiximports Module
Parameters
Module
Specifies the target module whose imports the debugger corrects. Module can contain a variety of wildcard characters and specifiers. For more information about the
syntax, see String Wildcard Syntax. If you want to include spaces in Module, you must enclose the parameter in quotation marks.
Environment
Modes
User mode, kernel mode
Targets Crash dump only (minidump only)
Platforms All
Comments
You can use the .fiximports command only when the target is a minidump that does not contain its own executable images.
When the debugger maps images for use as memory, the debugger does not automatically connect image imports to exporters. Therefore, instructions that refer to imports are
disassembled in the same manner as in a live debugging session. You can use .fiximports to request that the debugger perform the appropriate import linking.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.flash_on_break (Flash on Break)

The .flash_on_break command specifies whether the WinDbg taskbar entry flashes when WinDbg is minimized and the target breaks.
Syntax
.flash_on_break on
.flash_on_break off
.flash_on_break
Parameters
on
Causes the WinDbg taskbar entry to flash if WinDbg is minimized and the target breaks into the debugger. This is the default behavior for WinDbg.
off
Prevents the WinDbg taskbar entry from flashing.
Environment
The .flash_on_break command is available only in WinDbg. You cannot use this command in script files.
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you use the .flash_on_break command without parameters, the debugger displays the current flash setting.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.fnent (Display Function Data)

The .fnent command displays information about the function table entry for a specified function.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 360 of 1651

Syntax
.fnent Address
Parameters
Address
Specifies the address of the function.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The symbol search algorithm for the .fnent command is the same as that of the ln (List Nearest Symbols) command. The display first shows the nearest symbols. Then, the
debugger displays the function entry for the first of these symbols.
If the nearest symbol is not in the function table, no information is displayed.
The following example shows a possible display.
0:001> .fnent 77f9f9e7
Debugger function entry 00b61f50 for:
(77f9f9e7)
ntdll!RtlpBreakWithStatusInstruction

(77f9fa98)

ntdll!DbgPrintReturnControlC

Params:
1
Locals:
0
Registers: 0
0:001> .fnent 77f9fa98
Debugger function entry 00b61f70 for:
(77f9fa98)
ntdll!DbgPrintReturnControlC

(77f9fb21)

ntdll!DbgPrompt

Non-FPO
0:001> .fnent 01005a60
No function entry for 01005a60

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.fnret (Display Function Return Value)

The .fnret command displays information about a function's return value.
Syntax
.fnret [/s] Address [Value]
Parameters
/s
Sets the $callret pseudo-register equal to the return value that is being displayed, including type information.
Address
Specifies the address of the function.
Value
Specifies the return value to display. If you include Value, .fnret casts Value to the return type of the specified function and displays it in the format of the return type. If
you omit Value, the debugger obtains the return value of the function from the return value registers.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you include the Value parameter, the .fnret command only casts this value to the proper type and displays the results.
If you omit Value, the debugger uses the return value registers to determine this value. If a function has returned more recently than the function that the Address parameter
specifies, the value that is displayed will probably not be a value that this function returned.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 361 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.force_radix_output (Use Radix for Integers)

The .force_radix_output command specifies whether integers are displayed in decimal format or in the default radix.
Syntax
.force_radix_output 0
.force_radix_output 1
Parameters
0
Displays all integers (except for long integers) in decimal format. This is the default behavior for the Debugger.
1
Displays all integers (except for long integers) in the default radix.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .force_radix_output command affects the output of the dt (Display Type) command.
In WinDbg, .force_radix_output also affects the display in the Locals window and the Watch window. You can select or clear Always display numbers in default radix on
the shortcut menu of the Locals or Watch window to have the same effect as .force_radix_output. These windows are automatically updated after you issue this command.
The .force_radix_output command affects only the display of standard integers. To specify whether long integers are displayed in decimal format or the default radix, use
the .enable_long_status (Enable Long Integer Display) command.
To change the default radix, use the n (Set Number Base) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.force_tb (Forcibly Allow Branch Tracing)

The .force_tb command forces the processor to trace branches early in the boot process.
Syntax
.force_tb
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
Typically, branch tracing is enabled after the debugger initializes the processor control block (PRCB). This initialization occurs early in the boot process.
However, if you have to use the tb (Trace to Next Branch) command before this initialization, you can use the .force_tb command to enable branch tracing earlier. Use this
command carefully because it can corrupt your processor state.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 362 of 1651

.formats (Show Number Formats)

The .formats command evaluates an expression or symbol in the context of the current thread and process and displays it in multiple numeric formats.
Syntax
.formats expression
Parameters
expression
Specifies the expression to evaluate. For more information about the syntax, see Numerical Expression Syntax.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The evaluated expression is displayed in hexadecimal, decimal, octal, and binary formats, as well as single-precision and double-precision floating-point format. ASCII
character formats are also displayed when the bytes correspond to standard ASCII characters. The expression is also interpreted as a time stamp if it is in the allowed range.
The following example shows a .formats command.
0:000> .formats 1c407e62
Evaluate expression:
Hex:
1c407e62
Decimal: 473988706
Octal:
03420077142
Binary: 00011100 01000000 01111110 01100010
Chars:
.@~b
Time:
Mon Jan 07 15:31:46 1985
Float:
low 6.36908e-022 high 0
Double: 2.34182e-315
The Time field displays a 32-bit value in CRT time stamp format and displays a 64-bit value in FILETIME format. You can distinguish these formats because the FILETIME
format includes milliseconds and the CRT format does not.
See Also
? (Evaluate Expression), ?? (Evaluate C++ Expression)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.fpo (Control FPO Overrides)

The .fpo command controls the frame pointer omission (FPO) overrides.
Syntax
.fpo
.fpo
.fpo
.fpo
.fpo

-s [-fFlag] Address
-d Address
-x Address
-o Address
Address

Parameters
-s
Sets an FPO override at the specified address.
-fFlag
Specifies FPO flags for the override. You must not add a space between -f and Flag. If the flag takes an argument, you must add a space between the flag and that
argument. If you want multiple flags, you must repeat the -f switch (for example, -fb -fp 4 -fe). You can use the -f switch only with -s. You can use one of the following
values for Flag.
Flag
Effect
b
Sets fUseBP equal to TRUE.
e
Sets fUseSEH equal to TRUE.
n
Sets cbFrame equal to FRAME_NONFPO. (By default, cbFrame is set to FRAME_FPO.)
l Term Sets cdwLocals equal to Term. Term should specify the local DWORD count that you want.
p Term Sets cdwParams equal to Term. Term should specify the parameter DWORD count that you want.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 363 of 1651

r Term Sets cbRegs equal to Term. Term should specify the register count that you want.
s Term Sets cbProcSize equal to Term. Term should specify the procedure size that you want.
t Term Sets cbFrame equal to Term. Term should specify one of the following frame types:

FRAME_FPO 0
FRAME_TRAP 1
FRAME_TSS 2
FRAME_NONFPO 3

Address
Specifies the address where the debugger sets or removes the override or the address whose overrides the debugger should display. This address must be within a module
in the current module list.
-d
Removes the FPO overrides at the specified address.
-x
Removes all FPO overrides within the module that contains the Address address.
-o
Displays all FPO overrides within the module that contains the Address address.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms all
Comments
Without parameters, the .fpo command displays the FPO overrides for the specified address.
Some compilers (including Microsoft Visual Studio 6.0 and earlier versions) generate FPO information to indicate how the stack frame is set up. During stack walking, the
debugger uses these FPO records to understand the stack. If the compiler generated incorrect FPO information, you can use the .fpo command to fix this problem.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.frame (Set Local Context)

The .frame command specifies which local context (scope) is used to interpret local variables or displays the current local context.
Syntax
.frame [/c] [/r] [FrameNumber]
.frame [/c] [/r] = BasePtr [FrameIncrement]
.frame [/c] [/r] = BasePtr StackPtr InstructionPtr
Parameters
/c
Sets the specified frame as the current local override context. This action allows a user to access the nonvolatile registers for any function in the call stack.
/r
Displays registers and other information about the specified local context.
FrameNumber
Specifies the number of the frame whose local context you want. If this parameter is zero, the command specifies the current frame. If you omit this parameter, this
command displays the current local context.
BasePtr
Specifies the base pointer for the stack trace that is used to determine the frame, if you add an equal sign (=) after the command name (.frame). On an x86-based
processor, you add another argument after BasePtr (which is interpreted as FrameIncrement) or two more arguments after BasePtr (which are interpreted as
InstructionPtr and StackPtr).
FrameIncrement
(x86-based processor only) Specifies an additional quantity of frames past the base pointer. For example, if the base pointer 0x0012FF00 is the address of frame 3, the
command .frame 12ff00 is equivalent to .frame 3, and .frame 12ff00 2 is equivalent to .frame 5.
StackPtr
(x86-based processor only) Specifies the stack pointer for the stack trace that is used to determine the frame. If you omit StackPtr and InstructionPtr, the debugger uses
the stack pointer that the esp register specifies and the instruction pointer that the eip register specifies.
InstructionPtr
(x86-based processor only) Specifies the instruction pointer for the stack trace that is used to determine the frame. If you omit StackPtr and InstructionPtr, the debugger
uses the stack pointer that the esp register specifies and the instruction pointer that the eip register specifies.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

.lines (Toggle Source Line Support)

The .lines command enables or disables support for source-line information.
Syntax
.lines [-e|-d|-t]
Parameters
-e
Enables source line support.
-d
Disables source line support.
-t
Turns source line support on or off. If you do not specify parameters for .lines, the default behavior of the .lines command is this switching of source line support.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
You must enable source line support before you can perform source-level debugging. This support enables the debugger to load source line symbols.
You can enable source line support by using the .lines command or the -lines command-line option. If source line support is already enabled, using the .lines command
disables this support.
By default, if you do not use the .lines command, WinDbg turns on source line support, and console debuggers (KD, CDB, NTSD) turn off the support. For more information
about how to change this setting, see Setting Symbol Options.
Additional Information
For more information about source debugging and related commands, see Debugging in Source Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.load, .loadby (Load Extension DLL)

The .load and .loadby commands load a new extension DLL into the debugger.
Syntax
.load DLLName
!DLLName.load
.loadby DLLName ModuleName
Parameters
DLLName
Specifies the debugger extension DLL to load. If you use the .load command, DLLName should include the full path. If you use the .loadby command, DLLName should
include only the file name.
ModuleName
Specifies the module name of a module that is located in the same directory as the extension DLL that DLLName specifies.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
When you use the .load command, you must specify the full path.
When you use the .loadby command, you do not specify the path. Instead, the debugger finds the module that the ModuleName parameter specifies, determines the path of
that module, and then uses that path when the debugger loads the extension DLL. If the debugger cannot find the module or if it cannot find the extension DLL, you receive
an error message that specifies the problem. There does not have to be any relationship between the specified module and the extension DLL. Using the .loadby command is
therefore simply a way to avoid typing a long path.
After the .load or .loadby command has been completed, you can access the commands that are stored in the loaded extension.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 371 of 1651

To load an extension DLL, you can do one of the following:

Use the .load or .loadby command.

Execute an extension by issuing the full !DLLName.ExtensionCommand syntax. If the debugger has not yet loaded DLLName.dll, it loads the DLL at this point.

Additional Information
For more information about how to load, unload, and control extensions, see Loading Debugger Extension DLLs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.locale (Set Locale)

The .locale command sets the locale or displays the current locale.
Syntax
.locale [Locale]
Parameters
Locale
Specifies the locale that you want. If you omit this parameter, the debugger displays the current locale.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The locale controls how Unicode strings are displayed.
The following examples show the .locale command.
kd> .locale
Locale: C
kd> .locale E
Locale: English_United States.1252
kd> .locale c
Locale: Catalan_Spain.1252
kd> .locale C
Locale: C
Additional Information
For more information about locale, see the setlocale routine in the MSDN Library.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.logappend (Append Log File)

The .logappend command appends a copy of the events and commands from the Debugger Command window to the specified log file.
Syntax
.logappend [/u] [FileName]
Parameters
/u
Writes the log file in Unicode format. If you omit this parameter, the debugger writes the log file in ASCII (ANSI) format.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 372 of 1651

Note When you are appending to an existing log file, you should use the /u parameter only if you created the log file by using the /u option. Otherwise, your log file will
contain ASCII and Unicode characters, which might make it more difficult to read.
FileName
Specifies the name of the log file. You can specify a full path or only the file name. If the file name contains spaces, enclose FileName in quotation marks. If you do not
specify the path, the debugger uses the current directory. If you omit FileName, the debugger names the file Dbgeng.log.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you already have a log file open when you run the .logappend command, the debugger closes the log file. If you specify the name of a file that already exists, the debugger
appends new information to the file. If the file does not exist, the debugger creates it.
Additional Information
For more information and other commands that affect log files, see Keeping a Log File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.logclose (Close Log File)

The .logclose command closes any open log file.
Syntax
.logclose
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Additional Information
For more information and other commands that affect log files, see Keeping a Log File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.logfile (Display Log File Status)

The .logfile command determines whether a log file exists and displays the file's status.
Syntax
.logfile
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Additional Information
For more information and other commands that affect log files, see Keeping a Log File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 373 of 1651

December 09, 2009

Debugging Tools for Windows

.logopen (Open Log File)

The .logopen command sends a copy of the events and commands from the Debugger Command window to a new log file.
Syntax
.logopen [Options] [FileName]
.logopen /d
Parameters
Options
Any of the following options:
/t
Appends the process ID with the current date and time to the log file name. This data is inserted after the file name and before the file name extension.
/u
Writes the log file in Unicode format. If you omit this option, the debugger writes the log file in ASCII (ANSI) format.
FileName
Specifies the name of the log file. You can specify a full path or only the file name. If the file name contains spaces, enclose FileName in quotation marks. If you do not
specify a path, the debugger uses the current directory. If you omit FileName, the debugger names the file Dbgeng.log.
/d
Automatically chooses a file name based on the name of the target process or target computer and the state of the target. The file always has the .log file name extension.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you already have a log file open when you run the .logopen command, the debugger closes it. If you specify a file name that already exists, the file's contents are
overwritten.
The .logopen /t command appends the process ID, date, and time to the log file name. In the following example, the process ID in hexadecimal is 0x02BC, the date is
February 28, 2005, and the time is 9:05:50.935.
0:000> .logopen /t c:\logs\mylogfile.txt
Opened log file 'c:\logs\mylogfile_02BC_2005-02-28_09-05-50-935.txt'
Additional Information
For more information and other commands that affect log files, see Keeping a Log File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.netuse (Control Network Connections)

The .netuse command adds a connection to a network share.
Syntax
.netuse /a "[Local]" "Remote" "[User]" "[Password]"
Parameters
/a
Adds a new connection. You must always use the /a switch.
Local
Specifies the drive letter to use for the connection. You must enclose Local in quotation marks. If you omit this parameter, you must include an empty pair of quotation
marks as the parameter.
Remote
Specifies the UNC path of the share that is being connected. You must enclose Remote in quotation marks.
User
Specifies the user name of an account that is authorized to establish the connection. You must enclose User in quotation marks. If you omit this parameter, you must
include an empty pair of quotation marks as the parameter.
Password
Specifies the password that is associated with the User account. You must enclose Password in quotation marks. If you omit this parameter, you must include an empty
pair of quotation marks as the parameter.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 374 of 1651

Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The .netuse command behaves like the net use Microsoft MS-DOS command.
If you use .netuse during a remote debugging session, this command affects the debugging server, not the debugging client.
The following example shows this command.
0:000> .netuse "m:" "\\myserver\myshare" "" ""

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.noshell (Prohibit Shell Commands)

The .noshell command prevents you from using .shell commands.
Syntax
.noshell
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
If you use the .noshell command, you cannot use .shell (Command Shell) commands as long as the debugger is running, even if you start a new debugging session.
If you are performing remote debugging, this command is useful for security purposes.
Additional Information
For more information about the command shell and for other ways to disable shell commands, see Using Shell Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.noversion (Disable Version Checking)

The .noversion command disables all version checking of extension DLLs.
Syntax
.noversion
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
The build number of extension DLLs should match the build number of the computer that you are debugging, because the DLLs are compiled and linked with dependencies
on specific versions of data structures. If the versions do not match, you typically receive the following message.
*** Extension DLL(1367 Free) does not match target system(1552 Free)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 375 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.ocommand (Expect Commands from Target)

The .ocommand command enables the target application to send commands to the debugger.
Syntax
.ocommand String
.ocommand -d
.ocommand
Parameters
String
Specifies the command prefix string. String can include spaces, but you cannot use C-style control characters such as \" and \n. You can also enclose String in quotation
marks. However, if String includes a semicolon, leading spaces, or trailing spaces, you must enclose String in quotation marks.
-d
Deletes the command prefix string.
Environment
Modes
User mode only
Targets Live debugging only
Platforms All
Comments
If you use the .ocommand command without parameters, the debugger displays the current command prefix string. To clear the existing string, use .ocommand -d.
When you have set a command prefix string, any target output (such as the contents of an OutputDebugString command) is scanned. If this output begins with the command
prefix string, the text of the output that follows the prefix string is treated as a debugger command string and is run. When this text is executed, the command string is not
displayed.
The target can include an .echo (Echo Comment) command in the output string if you want additional messages. Target output that does not begin with the prefix string is
displayed in the typical manner.
After the commands within the command string have been executed, the target remains broken into the debugger, unless the final command is g (Go).
The comparison between the command prefix string and the target output is not case sensitive. (However, subsequent uses of .ocommand display the string that you entered
with the case preserved).
For this example, assume that you enter the following command in the debugger.
0:000> .ocommand magiccommand
Then, the target application executes the following line.
OutputDebugString("MagicCommand kb;g");
The debugger recognizes the command string prefix and executes kb;g immediately.
However, the following line does not cause any commands to be executed.
OutputDebugString("Command on next line.\nmagiccommand kb;g");
There are no commands executed from the preceding example because the command string prefix is not at the beginning of the output, even though it does begin a new line.
Note You should choose a command string prefix that will not likely appear in any target output other than your own commands.
Additional Information
For more information about OutputDebugString and other user-mode functions that communicate with a debugger, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.ofilter (Filter Target Output)

Additional Information
For more information about the Debugger Command window prompt, see Using Debugger Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.pop (Restore Debugger State)

The .pop command restores the state of the debugger to a state that has previously been saved by using the .push (Save Debugger State) command.
Syntax
.pop
.pop /r
.pop /r /q
Parameters
/r
Specifies that the saved values of the pseudo-registers $t0 to $t19 should be restored. If /r is not included, these values are not affected by the .pop command.
/q
Specifies that the command executes quietly. That is, the command executes without displaying any output.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
This command is most useful when used with scripts and debugger command programs so that they can work with one fixed state. If the command is successful, no output is
displayed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.process (Set Process Context)

The .process command specifies which process is used for the process context.
Syntax
.process [/i] [/p [/r] ] [/P] [Process]
Parameters
/i
(Windows XP and later; live debugging only; not during local kernel debugging) Specifies that Process is to be debugged invasively. This kind of debugging means that
the operating system of the target computer actually makes the specified process active. (Without this option, the .process command alters the debugger's output but does
not affect the target computer itself.) If you use /i, you must use the g (Go) command to execute the target. After several seconds, the target breaks back in to the
debugger, and the specified Process is active and used for the process context.
/p
Translates all transition page table entries (PTEs) for this process to physical addresses before access, if you use /p and Process is nonzero. This translation might cause
slowdowns, because the debugger must find the physical addresses for all of the memory that this process uses. Also, the debugger might have to transfer a significant
amount of data across the debug cable. (This behavior is the same as .cache forcedecodeuser.)
If you include the /p option and Process is zero or you omit it, the translation is disabled. (This behavior is the same as .cache noforcedecodeptes.)
/r
Reloads user-mode symbols after the process context has been set, if you use the /r and /p options. (This behavior is the same as .reload /user.)
/P

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 381 of 1651

(Live debugging only) Translates all transition page table entries (PTEs) to physical addresses before access, if you use /P and Process is nonzero. Unlike the /p option,
the /P option translates the PTEs for all user-mode and kernel-mode processes, not only the specified process. This translation might cause slowdowns, because the
debugger must find the physical addresses for all memory in use. Also, the debugger might have to transfer lots of data across the debug cable. (This behavior is the same
as .cache forcedecodeptes.)
Process
Specifies the address of the process that you want. (More precisely, this parameter specifies the address of the EPROCESS block for this process). The process context is
set to this process. If you omit Process or specify zero, the process context is reset to the default process for the current system state. (If you used the /i option to set
process context, you must use the /i option to reset the process context.)
Environment
Modes
Kernel mode only
Targets Live, crash dump
Platforms All
Comments
Typically, when you are doing kernel debugging, the only visible user-mode address space is the one that is associated with the current process.
The .process command instructs the kernel debugger to use a specific user-mode process as the process context. This usage has several effects, but the most important is that
the debugger has access to the virtual address space of this process. The debugger uses the page tables for this process to interpret all user-mode memory addresses, so you
can read and write to this memory.
The .context (Set User-Mode Address Context) command has a similar effect. However, the .context command sets the user-mode address context to a specific page
directory, while the .process command sets the process context to a specific process. On an x86-based processor, .context and .process have almost the same effect. However,
on an Itanium-based processor, a single process might have more than one page directory. In this situation, the .process command is more powerful, because it enables access
to all of the page directories that are associated with a process. For more information about the process context, see Process Context.
Note If you are performing live debugging, you should use the /i or the /p parameter. Without one of these parameters, you cannot correctly display user-mode or session
memory.
The /i parameter activates the target process. When you use this option, you must execute the target once for this command to take effect. If you execute again, the process
context is lost.
The /p parameter enables the forcedecodeuser setting. (You do not have to use /p if the forcedecodeuser option is already active.) The process context and the
forcedecodeuser state remain only until the target executes again.
If you are performing crash dump debugging, the /i and /p options are not available. However, you cannot access any part of the user-mode process' virtual address space that
were paged to disk when the crash occurred.
If you want to use the kernel debugger to set breakpoints in user space, use the /i option to switch the target to the correct process context.
The following example shows how to use the !process extension to find the address of the EPROCESS block for the desired process.
kd> !process 0 0
**** NT ACTIVE PROCESS DUMP ****
PROCESS fe5039e0 SessionId: 0 Cid: 0008
Peb: 00000000 ParentCid: 0000
DirBase: 00030000 ObjectTable: fe529b68 TableSize: 50.
Image: System
.....
PROCESS fe3c0d60 SessionId: 0 Cid: 0208
Peb: 7ffdf000 ParentCid: 00d4
DirBase: 0011f000 ObjectTable: fe3d0f48 TableSize: 30.
Image: regsvc.exe
Now the example uses the .process command with this process address.
kd> .process fe3c0d60
Implicit process is now fe3c0d60
Notice that this command makes the .context command unnecessary. The user-mode address context already has the desired value.
kd> .context
User-mode page directory base is 11f000
This value enables you to examine the address space in various ways. For example, the following example shows the output of the !peb extension.
kd> !peb
PEB at 7FFDF000
InheritedAddressSpace:
No
ReadImageFileExecOptions: No
BeingDebugged:
No
ImageBaseAddress:
01000000
Ldr.Initialized: Yes
Ldr.InInitializationOrderModuleList: 71f40 . 77f68
Ldr.InLoadOrderModuleList: 71ec0 . 77f58
Ldr.InMemoryOrderModuleList: 71ec8 . 77f60
01000000 C:\WINNT\system32\regsvc.exe
77F80000 C:\WINNT\System32\ntdll.dll
77DB0000 C:\WINNT\system32\ADVAPI32.dll
77E80000 C:\WINNT\system32\KERNEL32.DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 382 of 1651

77D40000 C:\WINNT\system32\RPCRT4.DLL
77BE0000 C:\WINNT\system32\secur32.dll
SubSystemData:
0
ProcessHeap:
70000
ProcessParameters: 20000
WindowTitle: 'C:\WINNT\system32\regsvc.exe'
ImageFile:
'C:\WINNT\system32\regsvc.exe'
CommandLine: 'C:\WINNT\system32\regsvc.exe'
DllPath:
'C:\WINNT\system32;.;C:\WINNT\System32;C:\WINNT\system;C:\WINNT;C:\WINNT\system32;C:\WINNT;C:\WI
Environment: 0x10000
Additional Information
For more information about the process context and other context settings, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.prompt_allow (Control Prompt Display)

The .prompt_allow command controls what information is displayed during stepping and tracing and whenever the target's execution stops.
Syntax
.prompt_allow {+|-}Item [...]
.prompt_allow
Parameters
+
Displays the specified item at the stepping, tracing, and execution prompt. You must add a space before the plus sign (+), but you cannot add a space after it.
Prevents the specified item from being displayed at the stepping, tracing, and execution prompt. You must add a space before the minus sign (), but you cannot add a
space after it.
Item
Specifies an item to display or not display. You can specify any number of items. Separate multiple items by spaces. You must add a plus sign (+) or minus sign ()
before each item. You can use the following items:
dis
The disassembled instructions at the current location.
ea
The effective address for the current instruction.
reg
The current state of the most important registers. You can disable register display by using the pr, tr, or .prompt_allow -reg command. All three of these
commands control the same setting, and you can use any of them to override any previous use of these commands.
You can also disable register display by using the l-os command. This setting is separate from the other three commands, as described in the following Comments
section. To control which registers and flags are displayed, use the rm (Register Mask) command.
src
The source line that corresponds to the current instruction. You can disable source line display by using the l-ls or .prompt_allow -src; commands. You must enable
source line display through both mechanisms to be visible.
sym
The symbol for the current instruction. This symbol includes the current module, function name, and offset.
Environment
Modes
User mode, kernel mode
Targets Live, crash dump
Platforms All
Comments
You can use the .prompt_allow command without parameters to show which items are displayed and are not displayed. Every time that you run .prompt_allow, the
debugger changes the status of only the specified items.
By default, all items are displayed.
If you have used the l+os option, this option overrides any of the .prompt_allow options other than src.
You can also use a complex command such as the following example.
0:000> .prompt_allow -reg -dis +ea
Allow the following information to be displayed at the prompt:
(Other settings can affect whether the information is actually displayed)
sym - Symbol for current instruction
ea - Effective address for current instruction

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

src
Do not
dis
reg

Page 383 of 1651

- Source info for current instruction

allow the following information to be displayed at the prompt:
- Disassembly of current instruction
- Register state

Additional Information
For more information about commands that affect execution, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.push (Save Debugger State)

.remote (Create Remote.exe Server)

The .remote command starts a Remote.exe Server, enabling a remote connection to the current debugging session.
Syntax
.remote session
Parameters
session

The .send_file command copies files. If you are performing remote debugging through a process server, it sends a file from the smart client's computer to the process server's
computer.
Syntax
.send_file [-f] Source Destination
.send_file [-f] -s Destination
Parameters
-f
Forces file creation. By default, .send_file will not overwrite any existing files. If the -f switch is used, the destination file will always be created, and any existing file
with the same name will be overwritten.
Source
Specifies the full path and filename of the file to be sent. If you are debugging through a process server, this file must be located on the computer where the smart client is
running.
Destination
Specifies the directory where the file is to be written. If you are debugging through a process server, this directory name is evaluated on the computer where the process

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 390 of 1651

server is running.
-s
Causes the debugger to copy all loaded symbol files.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
This command is particularly useful when you have been performing remote debugging through a process server, but wish to begin debugging locally instead. In this case you
can use the .send_file -s command to copy all the symbol files that the debugger has been using to the process server. These symbol files can then be used by a debugger
running on the local computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.server (Create Debugging Server)

The .server command starts a debugging server, allowing a remote connection to the current debugging session.
Syntax
.server
.server
.server
.server
.server
.server
.server

npipe:pipe=PipeName[,hidden][,password=Password][,IcfEnable]
tcp:port=Socket[,hidden][,password=Password][,ipversion=6][,IcfEnable]
tcp:port=Socket,clicon=Client[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,hidden][,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},pipe=PipeName[,hidden][,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket[,hidden][,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},port=Socket,clicon=Client[,password=Password]

Parameters
PipeName
When NPIPE or SPIPE protocol is used, PipeName is a string that will serve as the name of the pipe. Each pipe name should identify a unique debugging server. If you
attempt to reuse a pipe name, you will receive an error message. PipeName must not contain spaces or quotation marks. PipeName can include a numerical printf-style
format code, such as %x or %d. The debugger will replace this with the process ID of the debugger. A second such code will be replaced with the thread ID of the
debugger.
Socket
When TCP or SSL protocol is used, Socket is the socket port number.
It is also possible to specify a range of ports separated by a colon. The debugger will check each port in this range to see if it is free. If it finds a free port and no error
occurs, the debugging server will be created. The debugging client will have to specify the actual port being used to connect to the server. To determine the actual port,
use any of the methods described in Searching for Debugging Servers; when this debugging server is displayed, the port will be followed by two numbers separated by a
colon. The first number will be the actual port used; the second can be ignored. For example, if the port was specified as port=51:60, and port 53 was actually used, the
search results will show "port=53:60". (If you are using the clicon parameter to establish a reverse connection, the debugging client can specify a range of ports in this
manner, while the server must specify the actual port used.)
clicon=Client
When TCP or SSL protocol is used and the clicon parameter is specified, a reverse connection will be opened. This means that the debugging server will try to connect to
the debugging client, instead of letting the client initiate the contact. This can be useful if you have a firewall that is preventing a connection in the usual direction. Client
specifies the network name of the machine on which the debugging client exists or will be created. The two initial backslashes (\\) are optional.
Note When clicon is used, it is best to start the debugging client before the debugging server is created, although the usual order (server before client) is also permitted.
A reverse-connection server will not appear when another debugger displays all active servers.
COMPort
When COM protocol is used, COMPort specifies the COM port to be used. The prefix COM is optional (for example, both "com2" and "2" are acceptable).
BaudRate
When COM protocol is used, BaudRate specifies the baud rate at which the connection will run. Any baud rate that is supported by the hardware is permitted.
COMChannel
If COM protocol is used, COMChannel specifies the COM channel to be used in communicating with the debugging client. This can be any value between 0 and 254,
inclusive.
Protocol
If SSL or SPIPE protocol is used, Protocol specifies the Secure Channel (S-Channel) protocol. This can be any one of the strings tls1, pct1, ssl2, or ssl3.
Cert
If SSL or SPIPE protocol is used, Cert specifies the certificate. This can either be the certificate name or the certificate's thumbprint (the string of hexadecimal digits
given by the certificate's snapin). If the syntax certuser=Cert is used, the debugger will look up the certificate in the system store (the default store). If the syntax
machuser=Cert is used, the debugger will look up the certificate in the machine store. The specified certificate must support server authentication.
hidden
Prevents the server from appearing when another debugger displays all active servers.
password=Password
Requires a debugging client to supply the specified password in order to connect to the debugging session. Password can be any alphanumeric string.
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

The .sleep command causes the user-mode debugger to pause and the target computer to become active. This command is only used when you are controlling the user-mode
debugger from the kernel debugger.
Syntax
.sleep milliseconds
Parameters
milliseconds
Specifies the length of the pause, in milliseconds.
Environment
Modes
controlling the user-mode debugger from the kernel debugger
Targets live debugging only
Platforms all
Comments
When you are controlling the user-mode debugger from the kernel debugger, and the user-mode debugger prompt is visible in the kernel debugger, this command will activate
sleep mode. The kernel debugger, the user-mode debugger, and the target application will all freeze, but the rest of the target computer will become active.
If you use this command in any other scenario, it will simply freeze the debugger for a period of time.
The sleep time is in milliseconds and interpreted according to the default radix, unless a prefix such as 0n is used. Thus, if the default radix is 16, the following command will
cause about 65 seconds of sleep:
0:000> .sleep 10000
Additional Information
For details and information about how to wake up a debugger in sleep mode, see Controlling the User-Mode Debugger from the Kernel Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.sound_notify (Use Notification Sound)

The .sound_notify command causes a sound to be played when WinDbg enters the wait-for-command state.
Syntax
.sound_notify /ed
.sound_notify /ef File
.sound_notify /d
Parameters
/ed
Causes the default Windows alert sound to be played when WinDbg enters the wait-for-command state.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 394 of 1651

/ef File
Causes the sound contained in the specified file to be played when WinDbg enters the wait-for-command state.
/d
Disables the playing of sounds.
Environment
This command is available only in WinDbg and cannot be used in script files.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.srcfix, .lsrcfix (Use Source Server)

The .srcfix and .lsrcfix commands automatically set the source path to indicate that a source server will be used.
Syntax
.srcfix[+] [Paths]
.lsrcfix[+] [Paths]
Parameters
+
Causes the existing source path to be preserved, and ; srv* to be appended to the end. If the + is not used, the existing source path is replaced.
Paths
Specifies one or more additional paths to append to the end of the new source path.
Environment
The .srcfix command is available on all debuggers. The .lsrcfix command is available only in WinDbg and cannot be used in script files.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
When this command is issued from a debugging client, .srcfix sets the source path to use a source server on the debugging server, while .lsrcfix does the same on the local
machine.
These commands are the same as the .srcpath (Set Source Path) and .lsrcpath (Set Local Source Path) commands followed by the srv* source path element. Thus, the
following two commands are equivalent:
.srcfix[+] [Paths]
.srcpath[+] srv* [;Paths]
Similarly, the following two commands are equivalent:
.lsrcfix[+] [Paths]
.lsrcpath[+] srv* [;Paths]
Additional Information
For more information on setting the local source path for a remote client, see WinDbg Command-Line Options. For details about SrcSrv, see Using a Source Server. For
details on the source path and the local source path, see Source Path. For more information about commands that can be used while performing remote debugging through the
debugger, see Controlling a Remote Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.srcnoisy (Noisy Source Loading)

The .srcnoisy command controls the verbosity level for source file loading.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 395 of 1651

Syntax
.srcnoisy [Options]
Parameters
Options
Can be any one of the following options:
0
Disables the display of extra messages.
1
Displays information about the progress of source file loading and unloading.
2
Displays information about the progress of symbol file loading and unloading.
3
Displays all information displayed by options 1 and 2.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
With no parameters, .srcnoisy will display the current status of noisy source loading.
When parameter 2 (or 3) is selected, symbol loading information is filtered so that only symbol loading messages beginning with

are displayed. However, if the symbol information is already set to be displayed because SYMOPT_DEBUG is on, then this option will display symbol loading information
without filtering.
Note Noisy source loading should not be confused with noisy symbol loading that is controlled by the !sym noisy extension and by other means of controlling the
SYMOPT_DEBUG setting.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.srcpath, .lsrcpath (Set Source Path)

The .srcpath and .lsrcpath commands set or display the source file search path.
Syntax
.srcpath[+] [Directory [; ...]]
.lsrcpath[+] [Directory [; ...]]
Parameters
+
Specifies that the new directories will be appended to (rather than replacing) the previous source file search path.
Directory
Specifies one or more directories to put in the search path. If Directory is not specified, the current path is displayed. Separate multiple directories with semicolons.
Environment
The .srcpath command is available on all debuggers. The .lsrcpath command is available only in WinDbg and cannot be used in script files.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
When this command is issued from a debugging client, .srcpath sets the source path on the debugging server, while .lsrcpath sets the source path on the local machine.
Additional Information
For details and other ways to change this path, see Source Path. For more information about commands that can be used while performing remote debugging through the
debugger, see Controlling a Remote Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic

The .thread command specifies which thread will be used for the register context.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 399 of 1651

Syntax
.thread [/p [/r] ] [/P] [/w] [Thread]
Parameters
/p
(Live debugging only) If this option is included and Thread is nonzero, all transition page table entries (PTEs) for the process owning this thread will be automatically
translated into physical addresses before access. This may cause slowdowns, because the debugger will have to look up the physical addresses for all the memory used by
this process, and a significant amount of data may need to be transferred across the debug cable. (This behavior is the same as that of .cache forcedecodeuser.)
If the /p option is included and Thread is zero or omitted, this translation will be disabled. (This behavior is the same as that of .cache noforcedecodeuser.)
/r
(Live debugging only) If the /r option is included along with the /p option, user-mode symbols for the process owning this thread will be reloaded after the process and
register contexts have been set. (This behavior is the same as that of .reload /user.)
/P
(Live debugging only) If this option is included and Thread is nonzero, all transition page table entries (PTEs) will be automatically translated into physical addresses
before access. Unlike the /p option, this translates the PTEs for all user-mode and kernel-mode processes, not only the process owning this thread. This may cause
slowdowns, because the debugger will have to look up the physical addresses for all memory in use, and a huge amount of data may need to be transferred across the
debug cable. (This behavior is the same as that of .cache forcedecodeptes.)
/w
(64-bit kernel debugging only) Changes the active context for the thread to the WOW64 32-bit context. The thread specified must be running in a process that has a
WOW64 state.
Thread
The address of the thread. If this is omitted or zero, the thread context is reset to the current thread.
Environment
Modes
kernel mode only
Targets live, crash dump
Platforms all
Comments
Generally, when you are doing kernel debugging, the only visible registers are the ones associated with the current thread.
The .thread command instructs the kernel debugger to use the specified thread as the register context. After this command is executed, the debugger will have access to the
most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command
(.thread, .cxr, or .trap). See Register Context for full details.
The /w option can only be used in 64-bit kernel debugging sessions on a thread running in a process that has a WOW64 state. The context retrieved will be the last context
remembered by WOW64; this is usually the last user-mode code executed by Thread. This option can only be used if the target is in native machine mode. For example, if the
target is running on a 64-bit machine that is emulating an x86-based processor using WOW64, this option cannot be used. Using the /w option will cause the machine mode to
switch automatically to an x86-based processor.
This command does not actually change the current thread. In other words, extensions such as !thread and !teb will still default to the current thread if no arguments are used
with them.
Here is an example. Use the !process extension to find the address of the desired thread. (In this case, !process 0 0 is used to list all processes, then !process is used a second
time to list all the threads for the desired process.)
kd> !process 0 0
**** NT ACTIVE PROCESS DUMP ****
PROCESS fe5039e0 SessionId: 0 Cid: 0008
Peb: 00000000 ParentCid: 0000
DirBase: 00030000 ObjectTable: fe529a88 TableSize: 145.
Image: System
.....
PROCESS ffaa5280 SessionId: 0 Cid: 0120
Peb: 7ffdf000 ParentCid: 01e0
DirBase: 03b70000 ObjectTable: ffaa4e48 TableSize: 23.
Image: winmine.exe
kd> !process ffaa5280
PROCESS ffaa5280 SessionId: 0 Cid: 0120
Peb: 7ffdf000 ParentCid: 01e0
DirBase: 03b70000 ObjectTable: ffaa4e48 TableSize: 23.
Image: winmine.exe
VadRoot ffaf6e48 Clone 0 Private 50. Modified 0. Locked 0.
DeviceMap fe502e88
Token
e1b55d70
.....
THREAD ffaa43a0 Cid 120.3a4 Teb: 7ffde000
ffadc6a0 SynchronizationEvent
Not impersonating
Owning Process ffaa5280
WaitTime (seconds)
24323
Context Switch Count
494

Win32Thread: e1b4fea8 WAIT: (WrUserRequest) UserMode Non-Alertable

LargeStack

.....

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 400 of 1651

Now use the .thread command with the address of the desired thread. This sets the register context and enables you to examine the important registers and the call stack for
this thread.
kd> .thread ffaa43a0
Using context of thread ffaa43a0
kd> r
Last set context:
eax=00000000 ebx=00000000 ecx=00000000 edx=00000000 esi=00000000 edi=00000000
eip=80403a0d esp=fd581c2c ebp=fd581c60 iopl=0
nv up di pl nz na pe nc
cs=0000 ss=0000 ds=0000 es=0000 fs=0000 gs=0000
efl=00000000
0000:3a0d ??
???
kd> k
*** Stack trace for last set context - .thread resets it
ChildEBP RetAddr
fd581c38 8042d61c ntoskrnl!KiSwapThread+0xc5
00001c60 00000000 ntoskrnl!KeWaitForSingleObject+0x1a1
Additional Information
For more information about the register context and other context settings, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.time (Display System Time)

The .time command displays information about the system time variables.
Syntax
.time [-h Hours]
Parameters
-h Hours
Specifies the offset from Greenwich Mean Time, in hours. A negative value of Hours must be enclosed in parentheses.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The system time variables control performance counter behavior.
Here is an example in kernel mode:
kd> .time
Debug session time: Wed Jan 31 14:47:08 2001
System Uptime: 0 days 2:53:56
Here is an example in user mode:
0:000> .time
Debug session time: Mon Apr 07 19:10:50 2003
System Uptime: 4 days 4:53:56.461
Process Uptime: 0 days 0:00:08.750
Kernel time: 0 days 0:00:00.015
User time: 0 days 0:00:00.015

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.tlist (List Process IDs)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 401 of 1651

The .tlist command lists all processes running on the system.

Syntax
.tlist [Options] [FileNamePattern]
Parameters
Options
Can be any number of the following options:
-v
Causes the display to be verbose. This includes the session number, the process user name, and the command-line used to start the process.
-c
Limits the display to just the current process.
FileNamePattern
Specifies the file name to be displayed, or a pattern that the file name of the process must match. Only those processes whose file names match this pattern will be
displayed. FileNamePattern may contain a variety of wildcards and specifiers; see String Wildcard Syntax for details. This match is made only against the actual file
name, not the path.
Environment
Modes
user mode only
Targets live debugging only
Platforms all
Comments
Each process ID is displayed with an 0n prefix, to emphasize that the PID is a decimal number.
Additional Information
For other methods of displaying processes, see Finding the Process ID.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.trap (Display Trap Frame)

The .trap command displays the trap frame register state and also sets the register context.
Syntax
.trap [Address]
Parameters
Address
Hexadecimal address of the trap frame on the target system. Omitting the address does not display any trap frame information, but it does reset the register context.
Environment
Modes
kernel mode only
Targets live, crash dump
Platforms all
Comments
The .trap command displays the important registers for the specified trap frame.
This command also instructs the kernel debugger to use the specified context record as the register context. After this command is executed, the debugger will have access to
the most important registers and the stack trace for this thread. This register context persists until you allow the target to execute or use another register context command
(.thread, .cxr, or .trap). See Register Context for full details.
This extension is commonly used when debugging bug check 0xA and 0x7F. For details and an example, see Bug Check 0xA (IRQL_NOT_LESS_OR_EQUAL).
Additional Information
For more information about the register context and other context settings, see Changing Contexts.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 402 of 1651

Debugging Tools for Windows

.tss (Display Task State Segment)

The .tss command displays a formatted view of the saved Task State Segment (TSS) information for the current processor.
Syntax
.tss [Address]
Parameters
address
Address of the TSS.
Environment
Modes
kernel mode only
Targets live, crash dump
Platforms x86 only
Comments
The address of the TSS can be found by examining the output of the !pcr extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.ttime (Display Thread Times)

The .ttime command displays the running times for a thread.
Syntax
.ttime
Environment
Modes
user mode only
Targets live, crash dump
Platforms x86 only
Comments
This command only works in user mode. In kernel mode you should use !thread instead. This command works with user-mode minidumps as long as they were created with
the /mt or /ma options; see Minidumps for details.
The .ttime command shows the creation time of the thread, as well as the amount of time it has been running in kernel mode and in user mode.
Here is an example:
0:000> .ttime
Created: Sat Jun 28 17:58:42 2003
Kernel: 0 days 0:00:00.131
User:
0 days 0:00:02.109

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.typeopt (Set Type Options)

The .typeopt command sets or displays the type options.
Syntax
.typeopt +Flags
.typeopt Flags

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 403 of 1651

.typeopt +FlagName
.typeopt -FlagName
.typeopt
Parameters
+
Causes the type options specified by Flags to be set.
Causes the type options specified by Flags to be cleared.
Flags
Specifies the type options to be changed. Flags can be a sum of any of the following values (there is no default):
0x1
Displays values in all Watch windows and the Locals window as having UNICODE data type.
0x2
Displays values in all Watch windows and the Locals window as having LONG data type.
0x4
Displays integers in all Watch windows and the Locals window in the default radix.
0x8
Causes the debugger to choose the matching symbol with the largest size when the Locals window or Watch window references a symbol by name but there is more
than one symbol that matches this name. The size of a symbol is defined as follows: if the symbol is the name of a function, its size is the size of the function in
memory. Otherwise, the size of the symbol is the size of the data type that it represents.
FlagName
Specifies the type options to be changed. Flag can be any one of the following strings (there is no default):
uni
Displays values in all Watch windows and the Locals window as having UNICODE data type. (This has the same effect as 0x1.)
longst
Displays values in all Watch windows and the Locals window as having LONG data type. (This has the same effect as 0x2.)
radix
Displays integers in all Watch windows and the Locals window in the default radix. (This has the same effect as 0x4.)
size
Causes the debugger to choose the matching symbol with the largest size when the Locals window or Watch window references a symbol by name but there is more
than one symbol that matches this name. The size of a symbol is defined as follows: if the symbol is the name of a function, its size is the size of the function in
memory. Otherwise, the size of the symbol is the size of the data type that it represents. (This has the same effect as 0x8.)
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
Without any arguments, .typeopt displays the current symbol options.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.unload (Unload Extension DLL)

The .unload command unloads an extension DLL from the debugger.
Syntax
.unload DLLName
!DLLName.unload
Parameters
DLLName
Specifies the file name of the debugger extension DLL to be unloaded. If the full path was specified when the DLL was loaded, it needs to be given in full here as well. If
DLLName is omitted, the current extension DLL is unloaded.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
This command is useful when testing an extension you are creating. When the extension is recompiled, you must unload and then load the new DLL.
Additional Information
For more details on loading, unloading, and controlling extensions, see Loading Debugger Extension DLLs.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 404 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.unloadall (Unload All Extension DLLs)

The .unloadall command unloads all extension DLLs from the debugger on the host system.
Syntax
.unloadall
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Additional Information
For more details on loading, unloading, and controlling extensions, see Loading Debugger Extension DLLs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.wake (Wake Debugger)

The .wake command causes sleep mode to end. This command is used only when you are controlling the user-mode debugger from the kernel debugger.
Syntax
.wake PID
Parameters
PID
The process ID of the user-mode debugger.
Environment
Modes
controlling the user-mode debugger from the kernel debugger
Targets live debugging only
Platforms all
Comments
When you are controlling the user-mode debugger from the kernel debugger and the system is in sleep mode, this command can be used to wake up the debugger before the
sleep timer runs out.
This command is not issued in the user-mode debugger on the target machine, nor in the kernel debugger on the host machine. It must be issued from a third debugger (KD,
CDB, or NTSD) running on the target machine.
This debugger can be started expressly for this purpose, or can be another debugger that happens to be running. However, if there is no other debugger already running, it is
easier just to use CDB with the -wake command-line option.
Additional Information
For more details, see Controlling the User-Mode Debugger from the Kernel Debugger. For information about how to find the process ID of the debugger, see Finding the
Process ID.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.write_cmd_hist (Write Command History)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 405 of 1651

The .write_cmd_hist command writes the entire history of the Debugger Command window to a file.
Syntax
.write_cmd_hist Filename
Parameters
Filename
Specifies the path and filename of the file that will be created.
Environment
This command is available only in WinDbg and cannot be used in script files.
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.writemem (Write Memory to File)

The .writemem command writes a section of memory to a file.
Syntax
.writemem FileName Range
Parameters
FileName
Specifies the name of the file to be created. You can specify a full path and file name, or just the file name. If the file name contains spaces, FileName should be enclosed
in quotation marks. If no path is specified, the current directory is used.
Range
Specifies the memory range to be written to the file. For syntax details, see Address and Address Range Syntax.
Environment
Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
The memory is copied literally to the file. It is not parsed in any way.
The .writemem command is the opposite of the .readmem (Read Memory from File) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

.wtitle (Set Window Title)

The .wtitle command sets the title in the main WinDbg window or in the NTSD, CDB, or KD window.
Syntax
.wtitle Title
Parameters
Title
The title to use for the window.
Environment
This command cannot be used in script files.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 406 of 1651

Modes
user mode, kernel mode
Targets live, crash dump
Platforms all
Comments
For CDB, NTSD, or KD, if the .wtitle command has not been used, the window title matches the command line used to launch the debugger.
For WinDbg, if .wtitle has not bee used, the main window title includes the name of the target. If a debugging server is active, its connection string is displayed as well. If
multiple debugging servers are active, only the most recent one is displayed.
When .wtitle is used, Title replaces all this information. Even if a debugging server is started later, Title will not change.
The WinDbg version number is always displayed in the window title bar, regardless of whether this command is used.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Control Keys
This section of the reference discusses the various control keys that can be used in the debuggers.
These control keys work in KD and, in some cases, CDB. Many of these also work in WinDbg (using the CTRL+ALT keys instead of just CTRL).
WinDbg also uses the CTRL key, the ALT key, and the F keys as shortcut keys to toggle the menu options. See Shortcut Keys for a list of their meanings.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+A (Toggle Baud Rate)

The CTRL+A key toggles the baud rate used in the kernel debugging connection.
Syntax
KD Syntax
CTRL+A

ENTER

WinDbg Syntax
CTRL+ALT+A
Environment
Debuggers KD and WinDbg only
Modes
kernel mode only
Targets
live debugging only
Platforms all
Comments
This will cycle through all available baud rates for the kernel debugging connection.
Supported baud rates are 19200, 38400, 57600, and 115200. Each time this control key is used, the next baud rate will be selected. If the baud rate is already at 115200, it will
be reduced to 19200.
In WinDbg, this can also be accomplished by selecting Debug | Kernel Connection | Cycle Baud Rate.
You cannot actually use this control key to change the baud rate at which you are debugging. The baud rate of the host computer and the target computer must match, and the
baud rate of the target computer cannot be changed without rebooting. Therefore, you only need to toggle through the baud rates if the two computers are attempting to
communicate at different rates. In this case, you must change the host computer's baud rate to match that of the target computer.
To change the target computer's baud rate, see Configuring Software on the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 407 of 1651

December 09, 2009

Debugging Tools for Windows

CTRL+B (Quit Local Debugger)

The CTRL+B key causes the debugger to terminate abruptly. This does not end a remote debugging session.
Syntax
CTRL+B

ENTER

Environment
Debuggers CDB and KD only
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
In CDB, the q (Quit) command should be used to exit. CTRL+B should only be used if the debugger is not responding.
In KD, the q command will end the debugging session and leave the target computer locked. If you need to preserve the debugging session (so a new debugger can connect to
it), or if you need to leave the target computer running, you should use CTRL+B.
In WinDbg, the equivalent command is File | Exit or ALT+F4.
Additional Information
For other methods of exiting the debugger or detaching from the target, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+C (Break)
The CTRL+C key breaks into the debugger, stopping the target application or target computer, and cancels debugger commands.
Syntax
CDB Syntax
CTRL+C
KD Syntax
CTRL+C
Target Computer Syntax
SYSRQ
ALT+SYSRQ
F12
Environment
Debuggers CDB and KD only
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
When Using CDB:
In user mode, the CTRL+C key causes the target application to break into the debugger. The target application freezes, the debugger becomes active, and debugger commands
can be entered.
If the debugger is already active, CTRL+C does not affect the target application. It can be, however, used to terminate a debugger command. For instance, if you have
requested a long display and no longer want to see it, CTRL+C will end the display and return you to the debugger command prompt.
When performing remote debugging with CDB, CTRL+C can be pressed on the host computer's keyboard. If you want to issue a break from the target computer's keyboard,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 408 of 1651

use CTRL+C on an x86 machine.

The F12 key can be used to get a command prompt when the application being debugged is busy. Set the focus on one of the target application's windows and press the F12
key on the target computer.
When Using KD:
In kernel mode, the CTRL+C key causes the target computer to break into the debugger. This locks the target computer and wakes up the debugger.
When debugging a system that is still running, CTRL+C must be pressed on the host keyboard to get the initial command prompt.
If the debugger is already active, CTRL+C does not affect the target computer. It can be used, however, to terminate a debugger command. For instance, if you have requested
a long display and no longer want to see it, CTRL+C will end the display and return you to the debugger command prompt.
CTRL+C can also be used to get a command prompt when a debugger command is generating a long display or when the target computer is busy. When debugging an x86
machine, it can be pressed on either the host or target keyboard.
SYSRQ (or ALT+SYSRQ on an enhanced keyboard) is similar. It works from the host or target keyboard on any processor. However, it only works if the prompt has been
acquired by pressing CTRL+C at least once before.
The SYSRQ key can be disabled by editing the registry. In the registry key
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters
create a value named BreakOnSysRq, and set it equal to DWORD 0x0. Then reboot. After this is done, pressing the SYSRQ key on the target computer's keyboard will not
break into the kernel debugger.
When Debugging KD with CDB:
If you are debugging KD with CDB, then CTRL+C will be intercepted by the host debugger (CDB). To break into the target debugger (KD), you should use CTRL+F instead.
Note Note that in WinDbg, CTRL+C is a shortcut key that is used to copy text from a window. To issue a break command in WinDbg, use CTRL+BREAK or select Debug |
Break from the menu.
Additional Information
For other methods of issuing this command and an overview of related commands, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+D (Toggle Debug Info)

The CTRL+D key toggles debugger internal information flow on and off. This is used to restart communication between the target comoputer and the host computer in cases
where the debugger is not communicating properly.
Syntax
KD Syntax
CTRL+D

ENTER

WinDbg Syntax
CTRL+ALT+D
Environment
Debuggers KD and WinDbg only
Modes
kernel mode only
Targets
live debugging only
Platforms all
Comments
When this is toggled on, the debugger outputs information about the communication between the host computer and the target computer.
This key can be used to test whether the debugger has crashed. If you suspect that either the debugger or the target is frozen, use this key. If you see packets being sent, the
target is still working. If you see time-out messages, then the target is not responding. If there are no messages at all, the debugger has crashed.
If the target is not responding, use CTRL+R ENTER CTRL+C. If time-out messages continue to appear, the target has crashed (or the debugger was misconfigured).
This is also useful for debugging the KD debugger itself.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 409 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+F (Break to KD)

The CTRL+F key cancels commands or breaks into the debugger. (This control key is particularly useful when you are using CDB to debug KD itself.)
Syntax
CTRL+F

ENTER

Environment
Debuggers CDB, KD
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
Under typical conditions, CTRL+F is identical to the standard break commands (CTRL+C in KD and CDB, and Debug | Break or CTRL+BREAK in WinDbg.)
However, if you are debugging KD with CDB, these two keys will work differently. CTRL+C will be intercepted by the host debugger (CDB), while CTRL+F will be
intercepted by the target debugger (KD).
See Also
.breakin (Break to the Kernel Debugger)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+K (Change Post-Reboot Break State)

The CTRL+K key changes the conditions on which the debugger will automatically break into the target computer.
Syntax
KD Syntax
CTRL+K

ENTER

WinDbg Syntax
CTRL+ALT+K
Environment
Debuggers KD and WinDbg only
Modes
kernel mode only
Targets
live debugging only
Platforms all
Comments
This control key causes the kernel debugger to cycle through the following three states:
No break
In this state, the debugger will not break into the target computer unless you press CTRL+C.
Break on reboot
In this state, the debugger will break into a rebooted target computer after the kernel initializes. This is equivalent to starting KD or WinDbg with the -b command-line
option.
Break on first module load
In this state, the debugger will break into a rebooted target computer after the first kernel module is loaded. (This will cause the break to occur earlier than in the Break
on reboot option.) This is equivalent to starting KD or WinDbg with the -d command-line option.
When CTRL+K is used, the new break state is displayed.
In WinDbg, this can also be accomplished by selecting Debug | Kernel Connection | Cycle Initial Break.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 410 of 1651

Additional Information
For an overview of related commands and an explanation of how the reboot process affects the debugger, see Crashing and Rebooting the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+P (Debug Current Debugger)

The CTRL+P key launches a new instance of CDB; this new debugger takes the current debugger as its target.
Syntax
CTRL+P

ENTER

Environment
Debuggers CDB and KD only
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
This is equivalent to launching a new CDB through the remote.exe utility, and using it to debug the debugger that you are already running.
CTRL+P is similar to the .dbgdbg (Debug Current Debugger) command. However,.dbgdbg is more versatile, because it can be used from WinDbg as well as KD and CDB,
and it can be used to debug a debugging server on a remote computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+R (Re-synchronize)
The CTRL+R key synchronizes with the target computer.
Syntax
KD Syntax
CTRL+R

ENTER

WinDbg Syntax
CTRL+ALT+R
Environment
Debuggers KD and WinDbg only
Modes
kernel mode only
Targets
live debugging only
Platforms all
Comments
This attempts to synchronize the host computer with the target computer. Use this key if the target is not responding.
If you are using a 1394 kernel connection, resynchronization may not always be successful.
Additional Information
For other methods of re-establishing contact with the target, see Synchronizing with the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 411 of 1651

Debugging Tools for Windows

CTRL+V (Toggle Verbose Mode)

The CTRL+V key toggles verbose mode on and off.
Syntax
CDB / KD Syntax
CTRL+V

ENTER

WinDbg Syntax
CTRL+ALT+V
Environment
Debuggers CDB, KD, WinDbg
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
When verbose mode is turned on, some display commands (such as register dumping) produce more detailed output. Every MODULE LOAD operation that is sent to the
debugger will be displayed. And every time a driver or DLL is loaded by the operating system, the debugger will be notified.
In WinDbg, this can also be accomplished by selecting View | Verbose Output.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CTRL+W (Show Debugger Version)

The CTRL+W key displays version information for the debugger and all loaded extension DLLs.
Syntax
CDB / KD Syntax
CTRL+W

ENTER

WinDbg Syntax
CTRL+ALT+W
Environment
Debuggers CDB, KD, WinDbg
Modes
user mode, kernel mode
Targets
live, crash dump
Platforms all
Comments
This has the same effect as the version (Show Debugger Version) command, except that the latter command displays the Windows operating system version as well.
In WinDbg, this can also be accomplished by selecting View | Show Version.
See Also
version (Show Debugger Version), vertarget (Show Target Computer Version)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 412 of 1651

Debugger Extension Commands

This section describes the various debugger extension commands that you can use in CDB, KD, and WinDbg.
Each extension command (or extension for short) appears on its own reference topic. Characters in bold type represent items that are literally typed, and characters in italic
type indicate parameters that are explained in the Parameters section of the reference topics. Parameters in brackets ([ xxx ]) are optional. Brackets with vertical bars
([ xxx | yyy ]) indicate that you can use one, or none, of the enclosed parameters. Braces with vertical bars ({ xxx | yyy }) indicate that you must use only one of the enclosed
parameters.
Generally, extension commands do not support the full expression syntax that debugger commands and meta-commands do. For more information about each command's
syntax requirements, see the individual reference topics.
This sections describes the following categories of extensions:
General Extensions
Kernel-Mode Extensions
User-Mode Extensions
Specialized Extensions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

General Extensions
This section describes extension commands that are frequently used during both user-mode and kernel-mode debugging.
The debugger automatically loads the proper version of these extension commands. Unless you have manually loaded a different version, you do not have to keep track of the
DLL versions that are being used. For more information about the default module search order, see Using Debugger Extension Commands. For more information about how
to load extension modules, see Loading Debugger Extension DLLs.
Each extension command reference topics lists the DLLs that expose that command. Use the following rules to determine the proper directory to load this extension DLL
from:

If your target computer is running Microsoft Windows XP or a later version of Windows, use winxp\kdexts.dll, winxp\ntsdexts.dll, winxp\exts.dll, winext\ext.dll, or
dbghelp.dll.
If your target computer is running the free build of Windows 2000, use w2kfre\kdextx86.dll, w2kfre\ntsdexts.dll, winext\ext.dll, or dbghelp.dll.
If your target computer is running the checked build of Windows 2000, use w2kchk\kdextx86.dll, w2kchk\ntsdexts.dll, winext\ext.dll, or dbghelp.dll.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!acl
The !acl extension formats and displays the contents of an access control list (ACL).
Syntax
Syntax in Microsoft Windows XP and later versions
!acl Address [Flags]
Syntax in Windows 2000
!acl Address
Parameters
Address
Specifies the hexadecimal address of the ACL.
Flags
(Windows XP and later) Displays the friendly name of the ACL, if the value of Flags is 1. This friendly name includes the security identifier (SID) type and the domain
and user name for the SID.
DLL
Windows 2000

Kdextx86.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 413 of 1651

Windows XP and later Exts.dll

Comments
The following example shows the !acl extenion.
kd>
ACL
ACL
ACL
ACL
ACL
ACL
ACL
ACL
ACL
ACL
ACL

!acl e1bf35d4 1
is:
is: ->AclRevision: 0x2
is: ->Sbz1
: 0x0
is: ->AclSize
: 0x40
is: ->AceCount
: 0x2
is: ->Sbz2
: 0x0
is: ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE
is: ->Ace[0]: ->AceFlags: 0x0
is: ->Ace[0]: ->AceSize: 0x24
is: ->Ace[0]: ->Mask : 0x10000000
is: ->Ace[0]: ->SID: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser)

ACL
ACL
ACL
ACL
ACL

is:
is:
is:
is:
is:

->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:

->AceType: ACCESS_ALLOWED_ACE_TYPE
->AceFlags: 0x0
->AceSize: 0x14
->Mask : 0x10000000
->SID: S-1-5-18 (Well Known Group: NT AUTHORITY\SYSTEM)

Additional Information
For more information about access control lists, see !sid, !sd, and Determining the ACL of an Object. Also, see the Microsoft Windows SDK documentation, the Windows
Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!address
The !address extension displays information about the memory that the target process or target computer uses.
Syntax
User-Mode
!address
!address
!address
!address

Address
-summary
[-f:F1,F2,...] {[-o:{csv | tsv | 1}] | [-c:"Command"]}
-? | -help

Kernel-Mode
!address Address
!address
Parameters
Address
Displays only the region of the address space that contains Address.
-summary
Displays only summary information.
-f:F1, F2,
Displays only the regions specified by the filters F1, F2, and so on.
The following filter values specify memory regions by the way that the target process is using them.
Filter
value
VAR

Memory regions displayed

Busy regions. These regions include all virtual allocation blocks, the SBH heap, memory from custom allocators, and all other regions of the address space
that fall into no other classification.
Free
Free memory. This includes all memory that has not been reserved.
Image
Memory that is mapped to a file that is part of an executable image.
Stack
Memory used for thread stacks.
Teb
Memory used for thread environment blocks (TEBs).
Peb
Memory used for the process environment block (PEB).
Heap
Memory used for heaps.
PageHeap The memory region used for the full-page heap.
CSR
CSR shared memory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Actx
NLS
FileMap

Page 414 of 1651

Memory used for activation context data.

Memory used for National Language Support (NLS) tables.
Memory used for memory-mapped files. This filter is applicable only during live debugging.

The following filter values specify memory regions by the memory type.
Filter value
Memory regions displayed
MEM_IMAGE Memory that is mapped to a file that is part of an executable image.
MEM_MAPPED Memory that is mapped to a file that is not part of an executable image. This includes memory that is mapped to the paging file.
MEM_PRIVATE Private memory. This memory is not shared by any other process, and it is not mapped to any file.
The following filter values specify memory regions by the state of the memory.
Filter value
Memory regions displayed
MEM_COMMIT Committed memory.
MEM_FREE
Free memory. This includes all memory that has not been reserved.
MEM_RESERVE Reserved memory.
The following filter values specify memory regions by the protection applied to the memory.
Filter value
Memory regions displayed
PAGE_NOACCESS
Memory that cannot be accessed.
PAGE_READONLY
Memory that is readable, but not writable and not executable.
PAGE_READWRITE
Memory that is readable and writable, but not executable.
PAGE_WRITECOPY
Memory that has copy-on-write behavior.
PAGE_EXECUTE
Memory that is executable, but not readable and not writeable.
PAGE_EXECUTE_READ
Memory that is executable and readable, but not writable.
PAGE_EXECUTE_READWRITE Memory that is executable, readable, and writable.
PAGE_EXECUTE_WRITECOPY Memory that is executable and has copy-on-write behavior.
PAGE_GUARD
Memroy that acts as a guard page.
PAGE_NOCACHE
Memory that is not cached.
PAGE_WRITECOMBINE
Memory that has write-combine access enabled.
-o:{csv | tsv | 1}
Displays the output according to one of the following options.
Option
Output format
csv
Displays the output as comma-separated values.
tsv
Displays the output as tab-separated values.
1
Displays the output in bare format. This format works well when !address is used as input to .foreach.
-c:"Command"
Executes a custom command for each memory region. You can use the following placeholders in your command to represent output fields of the !address extension.
Placeholder Output field
%1
Base address
%2
End address + 1
%3
Region size
%4
Type
%5
State
%6
Protection
%7
Usage
For example, !address -f:Heap -c:".echo %1 %3 %5" displays the base address, size, and state for each memory region of type Heap.
Quotes in the command must be preceded by a back slash (\"). For example, !address -f:Heap -c:"s -a %1 %2 \"pad\"" searches each memory region of type Heap for the
string "pad".
Multiple commands separated by semicolons are not supported.
-?
Displays minimal Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
Without any parameters, the !address extension displays information about the whole address space. The !address -summary command shows only the summary.
In kernel mode, this extension searches only kernel memory, even if you used .process (Set Process Context) to specify a given process' virtual address space. In user mode,
the !address extension always refers to the memory that the target process owns.
In user mode, !address Address shows the characteristics of the region that the specified address belongs to. Without parameters, !address shows the characteristics of all
memory regions. These characteristics include the memory usage, memory type, memory state, and memory protection. For more information about the meaning of this
information, see the earlier tables in the description of the -f parameter.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 415 of 1651

The following example uses !address to retrieve information about a region of memory that is mapped to kernel32.dll.
0:000> !address 75831234
Usage:
Image
Base Address:
75831000
End Address:
758f6000
Region Size:
000c5000
Type:
01000000MEM_IMAGE
State:
00001000MEM_COMMIT
Protect:
00000020PAGE_EXECUTE_READ
More info:
lmv m kernel32
More info:
!lmi kernel32
More info:
ln 0x75831234
This example uses an Address value of 0x75831234. The display shows that this address is in a memory region that begins with the address 0x75831000 and ends with the
address 0x758f6000. The region has usage Image, type MEM_IMAGE, state MEM_COMMIT, and protection PAGE_EXECUTE_READ. (For more information about
the meaning of these values, see the earlier tables.) The display also lists three other debugger commands that you can use to get more information about this memory address.
If you are starting with an address and trying to determine information about it, the usage information is frequently the most valuable. After you know the usage, you can use
additional extensions to learn more about this memory. For example, if the usage is Heap, you can use the !heap extension to learn more.
The following example uses the s (Search Memory) command to search each memory region of type Image for the wide-character string "Note".
!address /f:Image /c:"s -u %1 %2 \"Note\""
*** Executing:
*** Executing:
00ab2936 004e
00ab2f86 004e
00ab32e4 004e
*** Executing:
. . .

s -u
s -u
006f
006f
006f
s -u

0xab0000 0xab1000 "Note"

0xab1000 0xabc000 "Note"
0074 0065 0070 0061 0064 0000
0074 0065 0070 0061 0064 005c
0074 0065 0070 0061 0064 0000
0xabc000 0xabd000 "Note"

N.o.t.e.p.a.d...
N.o.t.e.p.a.d.\.
N.o.t.e.p.a.d...

In kernel mode, the output of !address is similar to the user mode output but contains less information. The following example example shows the kernel mode output.
kd> !address
804de000 - 00235000
Usage
KernelSpaceUsageImage
ImageName
ntoskrnl.exe
80c00000 - 001e1000
Usage
KernelSpaceUsagePFNDatabase
....
f85b0000 - 00004000
Usage
KernelSpaceUsageKernelStack
KernelStack 817b4da0 : 324.368
f880d000 - 073d3000
Usage
KernelSpaceUsageNonPagedPoolExpansion
The meaning of "usage" is the same as in user mode. "ImageName" indicates the module that is associated with this address. "KernelStack" shows the address of this thread's
ETHREAD block (0x817B4DA0), the process ID (0x324), and the thread ID (0x368).
Additional Information
For more information about how to display and search memory, see Reading and Writing Memory. For additional extensions that display memory properties, see !vm (kernel
mode) and !vprot (user mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!analyze
The !analyze extension displays information about the current exception or bug check.
Syntax
User-Mode
!analyze [-v] [-f | -hang] [-D BucketID]
!analyze -c [ -load KnownIssuesFile | -unload | -help ]
Kernel-Mode

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 416 of 1651

!analyze [-v] [-f | -hang] [-D BucketID]

!analyze -c [ -load KnownIssuesFile | -unload | -help ]
!analyze -show BugCheckCode [BugParameters]
Parameters
-v
Displays verbose output.
-f
Generates the !analyze exception output. Use this parameter to see an exception analysis even when the debugger does not detect an exception.
-hang
Generates !analyze hung-application output. Use this parameter when the target has experienced a bug check or exception, but an analysis of why an application hung is
more relevant to your problem. In kernel mode, !analyze -hang investigates locks that the system holds and then scans the DPC queue chain. In user mode, !analyze hang analyzes the thread stack analysis to determine whether any threads are blocking other threads.
Before you run this extension in user mode, consider changing the current thread to the thread that you think has stopped responding (that is, hung), because the
exception might have changed the current thread to a different one.
-D BucketID
Displays only those items that are relevant to the specified BucketID.
-show
Displays information about the specified bug check code.
-c
Continues execution when the debugger encounters a known issue. If the issue is not a "known" issue, the debugger remains broken into the target.
You can use the -c option with the following subparameters. These subparameters configure the list of known issues. They do not cause execution to occur by
themselves. Until you run !analyze -c -load at least one time, !analyze -c has no effect.
-load KnownIssuesFile
Loads the specified known-issues file. KnownIssuesFile specifies the path and file name of this file. This file must be in XML format. You can find a sample file in
the sdk\samples\analyze_continue subdirectory of the debugger installation directory. (You must have performed a full install of Debugging Tools for Windows to
have this file. For more information about a full installation, see Debugger Installation.)
The list of known issues in the KnownIssuesFile file is used for all later !analyze -c commands until you use !analyze -c -unload, or until you use !analyze -c -load
again (at which point the new data replaces the old data).
-unload
Unloads the current list of known issues.
-help
Displays help for the !analyze -c extension commands extension in the Debugger Command window.
BugCheckCode
Specifies the bug check code to display.
BugParameters
Specifies up to four bug check parameters. Separate these parameters with spaces. This parameter enables you to further refine your search.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
In user mode, the !analyze and !analyze -v extensions display information about the current exception.
In kernel mode, these extensions display information about the most recent bug check. If a bug check occurs, the !analyze display is automatically generated. You can use !
analyze -v to show additional information. If you want to see only the basic bug check parameters, you can use the .bugcheck (Display Bug Check Data) command.
You can use the !analyzebugcheck -show extension command to display information about an individual bug check code. This display is not affected by the current status of
the target computer.
The following example shows the results of !analyze after a breakpoint is hit.
0:000> !analyze
Last event: Hit breakpoint 10000
Additional Information
For sample analysis of a user-mode exception and of a kernel-mode stop error (that is, crash), and for more information about how !analyze uses the triage.ini file, see Using
the !analyze Extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!asd
The !asd extension displays a specified number of failure analysis entries from the data cache, starting at the specified address.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 417 of 1651

Syntax
!asd Address DataUsed
Parameters
Address
Specifies the address of the first failure analysis entry to display.
DataUsed
Determines the number of tokens to display.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
The !asd extension is useful only when you are debugging the !analyze extension.
You can use the !dumpfa extension to debug the !analyze extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!atom
The !atom extension displays the formatted atom table for the specified atom or for all atoms of the current process.
Syntax
!atom [Address]
Parameters
Address
Specifies the hexadecimal virtual address of the atom to display. If you omit this parameter or specify zero, the atom table for the current process is displayed. This table
lists all atoms for the process.
DLL
Windows 2000

Kdextx86.dll

Ntsdexts.dll
Windows XP and later Exts.dll
Additional Information
For more information about atoms and atom tables, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

values that were actually encountered in the image. If the range is longer than 8 bytes, only the first 8 bytes are shown before the colon and after the colon. The following
example shows this situation.
be000015-be000016 2 bytes - win32k!VeryUsefulFunction+15 (0x8)
[ 85 dd:95 23 ]
Occasionally, a driver alters part of the Microsoft Windows kernel by using hooks, redirection, or other methods. Even a driver that is no longer on the stack might have
altered part of the kernel. You can use the !chkimg extension as a file comparison tool to determine which parts of the Windows kernel (or any other image) are being altered
by drivers and exactly how the parts are being changed. This comparison is most effective on full dump files.
You can also use !chkimg together with the !for_each_module extension to check the image of each loaded module. The following example shows this situation.
!for_each_module !chkimg @#ModuleName
Suppose that you encounter a bug check, for example, and begin by using !analyze.
kd> !analyze
....
BugCheck 1000008E, {c0000005, bf920e48, baf75b38, 0}
Probably caused by : memory_corruption
CHKIMG_EXTENSION: !chkimg !win32k
....
In this example, the !analyze output suggests that memory corruption has occurred and includes a CHKIMG_EXTENSION line that suggests that Win32k.sys could be the
corrupted module. (Even if this line is not present, you might consider possible corruption in the module on top of the stack.) Start by using !chkimg without any switches, as
the following example shows.
kd> !chkimg win32k
Number of different bytes for win32k: 31
The following example shows that there are indeed memory corruptions. Use !chkimg -d to display all of the errors for the Win32k module.
kd> !chkimg win32k -d
bf920e40-bf920e46 7 bytes - win32k!HFDBASIS32::vSteadyState+1f
[ 78 08 d3 78 0c c2 04:00 00 00 00 00 01 00 ]
bf920e48-bf920e5f 24 bytes - win32k!HFDBASIS32::vHalveStepSize (+0x08)
[ 8b 51 0c 8b 41 08 56 8b:00 00 00 00 00 00 00 00 ]
Number of different bytes for win32k: 31
When you try to disassemble the corrupted image of the second section that is listed, the following output might occur.
kd> u win32k!HFDBASIS32::vHalveStepSize
win32k!HFDBASIS32::vHalveStepSize:
bf920e48 0000
add
[eax],al
bf920e4a 0000
add
[eax],al
bf920e4c 0000
add
[eax],al
bf920e4e 0000
add
[eax],al
bf920e50 7808
js win32k!HFDBASIS32::vHalveStepSize+0x12 (bf920e5a)
bf920e52 d3780c
sar
dword ptr [eax+0xc],cl
bf920e55 c20400
ret
0x4
bf920e58 8b510c
mov
edx,[ecx+0xc]
Then, use !chkimg -f to fix the memory corruption.
kd> !chkimg win32k -f
Warning: Any detected errors will be fixed to what we expect!
Number of different bytes for win32k: 31 (fixed)
Now you can disassemble the corrected view and see the changes that you have made.
kd> u win32k!HFDBASIS32::vHalveStepSize
win32k!HFDBASIS32::vHalveStepSize:
bf920e48 8b510c
mov
edx,[ecx+0xc]
bf920e4b 8b4108
mov
eax,[ecx+0x8]
bf920e4e 56
push
esi
bf920e4f 8b7104
mov
esi,[ecx+0x4]
bf920e52 03c2
add
eax,edx
bf920e54 c1f803
sar
eax,0x3
bf920e57 2bf0
sub
esi,eax
bf920e59 d1fe
sar
esi,1

2009 Microsoft Corporation

Node

Debug

InitThr EnterThr

WaitThr TryEnThr LeaveThr EnterCnt

WaitCnt

----------------------------------------------------------------------------------------------0
1
2
3
4
5
5
3
4
4
5
2
3

00bb08c0
00dd6fd0
00bb0aa0
00bb09e0
00bb0a40
00bb0a10
00bb0a70
00bb0b00
00bb0ad0
00bb0b30
00dd4fd0
00bb0e90
00bb0d70

77c7e020
0148cfe8
008e8b84
008e8704
008e8944
008e8824
008e8a64
008e8dc4
008e8ca4
008e8ee4
0148afe4
77c2da98
77c2da08

77fbcae0
01683fe0
77fbcc20
77fbcba0
77fbcbe0
77fbcbc0
77fbcc00
77fbcc60
77fbcc40
77fbcc80
0167ffe0
00908fe0
008fcfe0

4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8
4c8

4c8
4c8
0
0
0
0
0
0
0
0
0
4c8
0

0
0
0
0
0
0
0
0
0
0
0
0
0

4c8
4c8
0
0
0
0
0
0
0
0
0
4c8
0

c
2
0
0
0
0
0
0
0
0
0
3a
0

0
0
0
0
0
0
0
0
0
0
0
0
0

The following items appear in this !cs -t display:

InitThr is the thread ID for the thread that initialized the CS.
EnterThr is the ID of the thread that called EnterCriticalSection last time.
WaitThr is the ID of the thread that found the critical section that another thread owned and waited for it last time.
TryEnThr is the ID of the thread that called TryEnterCriticalSection last time.
LeaveThr is the ID of the thread that called LeaveCriticalSection last time
EnterCnt is the count of EnterCriticalSection.
WaitCnt is the contention count.

Additional Information
For other commands and extensions that can display critical section information, see Displaying a Critical Section. For more information about critical sections, see the
Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 424 of 1651

December 09, 2009

Debugging Tools for Windows

!cxr
The !cxr extension command is obsolete. Use the .cxr (Display Context Record) command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dh
The !dh extension displays the headers for the specified image.
Syntax
!dh [Options] Address
!dh -h
Parameters
Options
Any one of the following options:
-f
Displays file headers.
-s
Displays section headers.
-a
Displays all header information.
Address
Specifies the hexadecimal address of the image.
-h
Displays some Help text for this extension in the Debugger Command window.
DLL
Windows 2000

Dbghelp.dll
Kdextx86.dll

Ntsdexts.dll
Windows XP and later Dbghelp.dll
Comments
The !lmi extension extracts the most important information from the image header and displays it in a concise summary format. That extension is frequently more useful
than !dh.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dlls
The !dlls extension displays the table entries of all loaded modules or all modules that a specified thread or process are using.
Syntax
!dlls [Options] [LoaderEntryAddress]
!dlls -h
Parameters
Options
Specifies the level of output. This parameter can be any combination of the following values:
-f
Displays file headers.
-s
Displays section headers.
-a

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 425 of 1651

Displays complete module information. (This option is equivalent to -f -s.)

-c ModuleAddress
Displays the module that contains ModuleAddress.
-i
Sorts the display by initialization order.
-l
Sorts the display by load order. This situation is the default.
-m
Sorts the display by memory order.
-v
(Windows XP and later) Displays version information. This information is taken from the resource section of each module.
LoaderEntryAddress
Specifies the address of the loader entry for a module. If you include this parameter, the debugger displays only this specific module.
-h
Displays some Help text for this extension in the Debugger Command window.
DLL
Windows 2000

Kdextx86.dll

Ntsdexts.dll
Windows XP and later Exts.dll
Comments
The module listing includes all entry points into each module.
The .dlls extension works only in live debugging (not with crash dump analysis).
In kernel mode, this extension displays the modules for the current process context. You cannot use !dlls together with a system process or the idle process.
The following examples shows you how to use the !dlls extension.
kd> !dlls -c 77f60000
Dump dll containing 0x77f60000:
0x00091f38: E:\WINDOWS\System32\ntdll.dll
Base
0x77f60000 EntryPoint 0x00000000
Flags 0x00004004 LoadCount
0x0000ffff
LDRP_IMAGE_DLL
LDRP_ENTRY_PROCESSED

Size
TlsIndex

0x00097000
0x00000000

Size
TlsIndex

0x00020000
0x00000000

kd> !dlls -a 91ec0

0x00091ec0: E:\WINDOWS\system32\winmine.exe
Base
0x01000000 EntryPoint 0x01003e2e
Flags 0x00005000 LoadCount
0x0000ffff
LDRP_LOAD_IN_PROGRESS
LDRP_ENTRY_PROCESSED
File Type: EXECUTABLE IMAGE
FILE HEADER VALUES
14C machine (i386)
3 number of sections
3A98E856 time date stamp Sun Feb 25 03:11:18 2001
0
0
E0
10F

OPTIONAL
10B
7.00
3A00
19E00
0
3E2E
1000
01000000
1000
200
2
5.01
5.01
4.00
20000

file pointer to symbol table

number of symbols
size of optional header
characteristics
Relocations stripped
Executable
Line numbers stripped
Symbols stripped
32 bit word machine
HEADER VALUES
magic #
linker version
size of code
size of initialized data
size of uninitialized data
address of entry point
base of code
----- new ----image base
section alignment
file alignment
subsystem (Windows GUI)
operating system version
image version
subsystem version
size of image

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

400
21970
00040000
00001000
00100000
00001000
01000100
0
40B4
6000
0
0
0
11B0
0
0
0
0
258
1000
0
0
0

Page 426 of 1651

size of headers
checksum
size of stack reserve
size of stack commit
size of heap reserve
size of heap commit
Opt Hdr
[
0] address [size]
[
B4] address [size]
[
19170] address [size]
[
0] address [size]
[
0] address [size]
[
0] address [size]
[
1C] address [size]
[
0] address [size]
[
0] address [size]
[
0] address [size]
[
0] address [size]
[
A8] address [size]
[
1B0] address [size]
[
0] address [size]
[
0] address [size]
[
0] address [size]

of
of
of
of
of
of
of
of
of
of
of
of
of
of
of
of

Export Directory
Import Directory
Resource Directory
Exception Directory
Security Directory
Base Relocation Directory
Debug Directory
Description Directory
Special Directory
Thread Storage Directory
Load Configuration Directory
Bound Import Directory
Import Address Table Directory
Reserved Directory
Reserved Directory
Reserved Directory

SECTION HEADER #1
.text name
3992 virtual size
1000 virtual address
3A00 size of raw data
400 file pointer to raw data
0 file pointer to relocation table
0 file pointer to line numbers
0 number of relocations
0 number of line numbers
60000020 flags
Code
(no align specified)
Execute Read

Debug Directories(1)
Type
Size
cv

Address

Pointer

13d0

7d0

Format: NB10, 3a98e856, 1, winmi

ne.pdb
SECTION HEADER #2
.data name
BB8 virtual size
5000 virtual address
200 size of raw data
3E00 file pointer to raw data
0 file pointer to relocation table
0 file pointer to line numbers
0 number of relocations
0 number of line numbers
C0000040 flags
Initialized Data
(no align specified)
Read Write
SECTION HEADER #3
.rsrc name
19170 virtual size
6000 virtual address
19200 size of raw data
4000 file pointer to raw data
0 file pointer to relocation table
0 file pointer to line numbers
0 number of relocations
0 number of line numbers
40000040 flags
Initialized Data
(no align specified)
Read Only

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 427 of 1651

Debugging Tools for Windows

!dumpfa
The !dumpfa extension displays the contents of a failure analysis entry.
Syntax
!dumpfa Address
Parameters
Address
Specifies the address of the failure analysis entry that is displayed.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
The .dumpfa extension is useful only to debug the !analyze extension, as the following example shows.
0:000> !dumpfa 0x00a34140
DataUsed 3b0
Type =
DEBUG_FLR_MARKER_BUCKET 00010016 - Size = 9
Type =
DEBUG_FLR_MARKER_FILE 0001000d - Size = 16
Type =
DEBUG_FLR_SYSXML_LOCALEID 00004200 - Size = 4
Type =
DEBUG_FLR_SYSXML_CHECKSUM 00004201 - Size = 4
Type =
DEBUG_FLR_READ_ADDRESS 0000000e - Size = 8
Type =
DEBUG_FLR_FAULTING_IP 80000000 - Size = 8
Type =
DEBUG_FLR_MM_INTERNAL_CODE 00001004 - Size = 8
Type = DEBUG_FLR_CPU_MICROCODE_VERSION 0000301f - Size = 28
Type = DEBUG_FLR_CUSTOMER_CRASH_COUNT 0000300b - Size = 8
Type =
DEBUG_FLR_DEFAULT_BUCKET_ID 00010008 - Size = 12
Type =
DEBUG_FLR_BUGCHECK_STR 00000600 - Size = 5
Type = DEBUG_FLR_LAST_CONTROL_TRANSFER 0000000a - Size = 18
Type =
DEBUG_FLR_TRAP_FRAME c0000002 - Size = 8
Type =
DEBUG_FLR_STACK_TEXT 00010005 - Size = 1fb
Type =
DEBUG_FLR_STACK_COMMAND 00010004 - Size = 17
Type =
DEBUG_FLR_OS_BUILD_NAME 0000301e - Size = 9
Type =
DEBUG_FLR_MODULE_NAME 00010006 - Size = 8
Type =
DEBUG_FLR_IMAGE_NAME 00010001 - Size = c
Type =
DEBUG_FLR_IMAGE_TIMESTAMP 80000002 - Size = 8
You can also use the !asd extension to debug the !analyze extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!elog_str
The !elog_str extension adds a string to the event log.
Syntax
!elog_str String
Parameters
String
Specifies the string to add to the event log.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
Because a registered event source does not send String, the string appears in the event log with a warning that no event ID was determined.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 428 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!envvar
The !envvar extension displays the value of the specified environment variable.
Syntax
!envvar Variable
Parameters
Variable
Specifies the environment variable whose value is displayed. Variable is not case sensitive.
DLL
Windows 2000
Unavailable
Windows XP and later Exts.dll
Comments
The !envvar extension works both in user mode and in kernel mode. However, in kernel mode, when you set the idle thread as the current process, the pointer to the Process
Environment Block (PEB) is NULL, so it fails. In kernel mode, the !envvar extension displays the environment variables on the target computer, as the following example
shows.
0:000> !envvar _nt_symbol_path
_nt_symbol_path = srv*C:\mysyms*http://msdl.microsoft.com/download/symbols
Additional Information
For more information about environment variables, see Environment Variables and the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!error
The !error extension decodes and displays information about an error value.
Syntax
!error Value [Flags]
Parameters
Value
Specifies one of the following error codes:
Win32
Winsock
NTSTATUS
NetAPI
Flags
If Flags is set to 1, the error code is read as an NTSTATUS code.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
The following example shows you how to use !error.
0:000> !error 2
Error code: (Win32) 0x2 (2) - The system cannot find the file specified.
0:000> !error 2 1
Error code: (NTSTATUS) 0x2 - STATUS_WAIT_2

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 429 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!exchain
The !exchain extension displays the current exception handler chain.
Syntax
!exchain [Options]
Parameters
Options
One of the following values:
/c
Displays information that is relevant for debugging a C++ try/catch exception, if such an exception is detected.
/C
Displays information that is relevant for debugging a C++ try/catch exception, even when such an exception has not been detected.
/f
Displays information that is obtained by walking the CRT function tables, even if a CRT exception handler was not detected.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
The !exchain extension is available only for an x86-based target computer.
Comments
The !exchain extension displays the list of exception handlers for the current thread.
The list begins with the first handler on the chain (the one that is given the first opportunity to handle an exception) and continues on to the end. The following example shows
this extension.
0:000> !exchain
0012fea8: Prymes!_except_handler3+0 (00407604)
CRT scope 0, filter: Prymes!dzExcepError+e6 (00401576)
func:
Prymes!dzExcepError+ec (0040157c)
0012ffb0: Prymes!_except_handler3+0 (00407604)
CRT scope 0, filter: Prymes!mainCRTStartup+f8 (004021b8)
func:
Prymes!mainCRTStartup+113 (004021d3)
0012ffe0: KERNEL32!GetThreadContext+1c (77ea1856)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!exr
The !exr extension command is obsolete. Use the .exr (Display Exception Record) command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!findxmldata
The !findxmldata extension retrieves XML data from a CAB file that contains a kernel-mode Small Memory Dump file.
Syntax
!findxmldata [ -d DeviceName | -h HwId ]
!findxmldata -r Driver
!findxmldata -chksum [ -z CabFile ]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 430 of 1651

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 436 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!handle
The !handle extension displays information about a handle or handles that one or all processes in the target system own.
Syntax
User-Mode
!handle [Handle [UMFlags [TypeName]]]
!handle -?
Kernel-Mode
!handle [Handle [KMFlags [Process [TypeName]]]]
Parameters
Handle
Specifies the index of the handle to display. If Handle is -1 or if you omit this parameter, the debugger displays data for all handles that are associated with the current
process. If Handle is 0, the debugger displays data for all handles.
UMFlags
(User mode only) Specifies what the display should contain. This parameter can be a sum of any of the following bit values. (The default value is 0x1.)
Bit 0 (0x1)
Displays handle type information.
Bit 1 (0x2)
Displays basic handle information.
Bit 2 (0x4)
Displays handle name information.
Bit 3 (0x8)
Displays object-specific handle information, when available.
KMFlags
(Kernel mode only) Specifies what the display should contain. This parameter can be a sum of any of the following bit values. (The default value is 0x3.)
Bit 0 (0x1)
Displays basic handle information.
Bit 1 (0x2)
Displays information about objects.
Bit 2 (0x4)
Displays free handle entries. If you do not set this bit and you omit Handle or set it to zero, the list of handles that are displayed does not include free handles. If
Handle specifies a single free handle, it is displayed even if you do not set this bit.
Bit 4 (0x10)
(Windows XP and later) Displays the handle from the kernel handle table instead of the current process.
Bit 5 (0x20)
(Windows XP and later) Interprets the handle as a thread ID or process ID and displays information about the corresponding kernel object.
Process
(Kernel mode only) Specifies a process. You can use the process ID or the hexadecimal address of the process object. This parameter must refer to a currently running
process on the target system. If this parameter is -1 or if you omit it, the current process is used.
TypeName
Specifies the type of handle that you want to examine. Only handles that match this type are displayed. TypeName is case sensitive. Valid types include Event, Section,
File, Port, Directory, SymbolicLink, Mutant, WindowStation, Semaphore, Key, Token, Process, Thread, Desktop, IoCompletion, Timer, Job, and WaitablePort.
-?
(User mode only) Displays some Help text for this extension in the Debugger Command window.
DLL
Windows 2000

Kdextx86.dll

Uext.dll
Ntsdexts.dll
Windows XP and later Kdexts.dll
Uext.dll
Ntsdexts.dll
Comments
You can use the !handle extension during user-mode and kernel-mode live debugging. You can also use this extension on kernel-mode dump files. However, you cannot use
this extension on user-mode dump files, unless you specifically created them with handle information. (You can create create such dump files by using the .dump /mh
(Create Dump File) command.)
During live user-mode debugging, you can use the .closehandle (Close Handle) command to close one or more handles.
The following examples are user-mode examples of the !handle extension. The following command displays a list of all handles.
0:000> !handle
Handle 4
Type

Section

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Handle 8
Type
Handle c
Type
Handle 10
Type
Handle 14
Type
Handle 5c
Type
6 Handles
Type
Event
Section
File
Directory

Page 437 of 1651

Event
Event
Event
Directory
File
Count
3
1
1
1

The following command displays detailed information about handle 0x8.

0:000> !handle 8 f
Handle 8
Type
Event
Attributes
0
GrantedAccess 0x100003:
Synch
QueryState,ModifyState
HandleCount
2
PointerCount 3
Name
<none>
Object Specific Information
Event Type Auto Reset
Event is Waiting
The following examples are kernel-mode examples of !handle. The following command lists all handles, including free handles.
kd> !handle 0 4
processor number 0
PROCESS 80559800 SessionId: 0 Cid: 0000
Peb: 00000000 ParentCid: 0000
DirBase: 00039000 ObjectTable: e1000d60 TableSize: 380.
Image: Idle
New version of handle table at e1002000 with 380 Entries in use
0000: free handle, Entry address e1002000, Next Entry fffffffe
0004: Object: 80ed5238 GrantedAccess: 001f0fff
0008: Object: 80ed46b8 GrantedAccess: 00000000
000c: Object: e1281d00 GrantedAccess: 000f003f
0010: Object: e1013658 GrantedAccess: 00000000
......
0168: Object: ffb6c748 GrantedAccess: 00000003 (Protected)
016c: Object: ff811f90 GrantedAccess: 0012008b
0170: free handle, Entry address e10022e0, Next Entry 00000458
0174: Object: 80dfd5c8 GrantedAccess: 001f01ff
......
The following command show detailed information about handle 0x14 in the kernel handle table.
kd> !handle 14 13
processor number 0
PROCESS 80559800 SessionId: 0 Cid: 0000
Peb: 00000000 ParentCid: 0000
DirBase: 00039000 ObjectTable: e1000d60 TableSize: 380.
Image: Idle
Kernel New version of handle table at e1002000 with 380 Entries in use
0014: Object: e12751d0 GrantedAccess: 0002001f
Object: e12751d0 Type: (80ec8db8) Key
ObjectHeader: e12751b8
HandleCount: 1 PointerCount: 1
Directory Object: 00000000 Name: \REGISTRY\MACHINE\SYSTEM\CONTROLSET001\CONTROL\SESSION MANAGER\EXECUTIVE
Additional Information
For more information about handles, see the !htrace extension, the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and
David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 438 of 1651

!heap
The !heap extension displays heap usage information, controls breakpoints in the heap manager, detects leaked heap blocks, searches for heap blocks, or displays page heap
information.
Syntax
Syntax in Windows 2000
!heap
!heap
!heap
!heap
!heap

[HeapOptions] [ValidationOptions] [Heap]

-b [{alloc|realloc|free} [Tag]] [Heap | BreakAddress]
-B {alloc|realloc|free} [Heap | BreakAddress]
-p PageHeapOptions
[-p] -?

Syntax in Windows XP and later

!heap
!heap
!heap
!heap
!heap
!heap
!heap
!heap
!heap
!heap
!heap
!heap

[HeapOptions] [ValidationOptions] [Heap]

-b [{alloc|realloc|free} [Tag]] [Heap | BreakAddress]
-B {alloc|realloc|free} [Heap | BreakAddress]
-l
-s [SummaryOptions] [StatHeapAddress]
-i HeapAddress
-x [-v] Address
-p [PageHeapOptions]
-srch [Size] Pattern
-flt FilterOptions
-stat [-h Handle [-grp GroupBy [MaxDisplay]]]
[-p] -?

Parameters
Heap
Specifies either a heap index number or a heap address. The default is 1; this specifies the process heap. Zero causes the command to display information about all heaps
in the process. Omitting Heap gives a concise list of all heaps in the process.
HeapOptions
Can be any combination of the following options. The HeapOptions values are case-sensitive.
Option
Effect
-v
Causes the debugger to validate the specified heap.
-a
Causes the display to include all information for the specified heap. Size, in this case, is rounded up to the heap granularity. (Running !heap with the a option
is equivalent to running it with the three options -h -f -m, which can take a long time.)
-h
Causes the display to include all entries for the specified heap.
-f
Causes the display to include all the free list entries for the specified heap.
-m
Causes the display to include all the segment entries for the specified heap.
-t
Causes the display to include the tag information for the specified heap.
-T
Causes the display to include the pseudo-tag entries for the specified heap.
-g
Causes the display to include the global tag information. Global tags are associated with each untagged allocation.
-s
Causes the display to include summary information for the specified heap.
-k
(x86-based targets only) Causes the display to include the stack backtrace associated with each entry.
ValidationOptions
Can be any single one of the following options. The ValidationOptions are case-sensitive.
Option
Effect
-D
Disables validate-on-call for the specified heap.
-E
Enables validate-on-call for the specified heap.
-d
Disables heap checking for the specified heap.
-e
Enables heap checking for the specified heap.
BreakAddress
Specifies the address of a block where a breakpoint is to be set or removed.
-b
Causes the debugger to create a conditional breakpoint in the heap manager. The -b option can be followed by alloc, realloc, or free; this specifies whether the
breakpoint will be activated by allocating, reallocating, or freeing memory. If BreakAddress is used to specify the address of the block, the breakpoint type can be
omitted. If Heap is used to specify the heap address or heap index, the type must be included, as well as the Tag parameter.
Tag
Specifies the tag name within the heap.
-B
Causes the debugger to remove a conditional breakpoint from the heap manager. The breakpoint type (alloc, realloc, or free) must be specified, and must be the same as
that used with the -b option.
-l
(Windows XP and later) Causes the debugger to detect leaked heap blocks.
-s
(Windows XP and later) Specifies that summary information is being requested. If SummaryOptions and StatHeapAddress are omitted, then summary information is
displayed for all heaps associated with the current process.
SummaryOptions
(Windows XP and later) Can be any combination of the following options. The SummaryOptions are not case-sensitive.
Option
Effect
-v
Verifies all data blocks.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 439 of 1651

-b BucketSize
Specifies the bucket size. The default is 1024 bits.
-d DumpBlockSize Specifies the bucket size.
-a
Specifies that the contents of each block should be displayed.
-c
StatHeapAddress
(Windows XP and later) Specifies the address of the heap. If this is 0 or omitted, all heaps associated with the current process are displayed.
-i Heap
(Windows XP and later) Displays information about the specified Heap.
-x [-v]
(Windows XP and later) Causes the debugger to search for the heap block containing the specified address. If -v is added, the command will search the entire virtual
memory space of the current process for pointers to this heap block.
Address
(Windows XP and later) Specifies the address to search for.
-p
Specifies that page heap information is being requested. If this is used without any PageHeapOptions, all page heaps will be displayed.
PageHeapOptions
Can be any single one of the following options. The PageHeapOptions are case-sensitive. If no options are specified, then all possible page heap handles will be
displayed.
Option
Effect
-h Handle Causes the debugger to display detailed information about a page heap with handle Handle.
-a
Causes the debugger to find the page heap whose block contains Address. Full details of how this address relates to full-page heap blocks will be included,
Address such as whether this address is part of a page heap, its offset inside the block, and whether the block is allocated or was freed. Stack traces are included
whenever available. When using this option, size is displayed in multiples of the heap allocation granularity.
-t[c|s]
Causes the debugger to display the collected traces of the heavy heap users. Traces specifies the number of traces to display; the default is four. If there are
[Traces] more traces than the specified number, the earliest traces are displayed. If -t or -tc is used, the traces are sorted by count usage. If -ts is used, the traces are
sorted by size. (The -tc and -ts options are supported in Windows XP only; the -t option is supported only in Windows XP and earlier versions of Windows.)
-fi
(Windows XP and later) Causes the debugger to display the most recent fault injection traces. Traces specifies the quantity to be displayed; the default is 4.
[Traces]
-all
(Windows XP and later) Causes the debugger to display detailed information about all page heaps.
-?
Causes the debugger to display page heap help, including a diagram of heap blocks. (These diagrams can also be seen in the following Comments section.)
Before you can use any !heap -p extension command, the page heap must be enabled for your target process. See details in the following Comments section.
-srch
(Windows XP and later) Scans all heaps for the given pattern.
Pattern
(Windows XP and later) Specifies a pattern for which to look.
Size
(Windows XP and later) Can be any single one of the following options. This specifies the size of the pattern. The '-' is required.
Option
Effect
-b
The pattern is one BYTE in size.
-w
The pattern is one WORD in size.
-d
The pattern is one DWORD in size.
-q
The pattern is one QWORD in size.
If none of the above are specified, then the pattern is assumed to be of the same size as the machine pointer.
-flt
(Windows XP and later) Limits the display to include only heaps with the specified size or size range.
FilterOptions
(Windows XP and later) Can be any single one of the following options. The FilterOptions are case-sensitive.
Option
Effect
s Size
Limits the display to include only heaps of the specified size.
r SizeMin SizeMax Limits the display to include only heaps within the specified size range.
-stat
(Windows XP and later) Displays usage statistics for the specified heap.
-h Handle
(Windows XP and later) Causes usage statistics for only the heap at Handle to be displayed. If Handle is 0 or omitted, then usage statistics for all heaps are displayed.
-grp GroupBy
(Windows XP and later) Reorders the display as specified by GroupBy. The options for GroupBy can be found in the following table.
Option
Effect
A
Displays the usage statistics according to allocation size.
B
Displays the usage statistics according to block count.
S
Displays the usage statistics according to the total size of each allocation.
MaxDisplay
(Windows XP and later) Limits the output to only MaxDisplay number of lines.
-?
Displays some brief Help text for this extension in the Debugger Command window. Use !heap -? for generic help, and !heap -p -? for page heap help.
DLL
Windows 2000

Ext.dll
Kdextx86.dll
Ntsdexts.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 440 of 1651

Windows XP and later Ext.dll

Exts.dll
Comments
This extension command can be used to perform a variety of tasks.
The standard !heap command is used to display heap information for the current process. (This should be used only for user-mode processes. The !pool extension command
should be used for system processes.)
The !heap -b and !heap -B commands are used to create and delete conditional breakpoints in the heap manager.
The !heap -l command detects leaked heap blocks. It uses a garbage collector algorithm to detect all busy blocks from the heaps that are not referenced anywhere in the
process address space. For huge applications, it can take a few minutes to complete. This command is only available in Windows XP and later versions of Windows.
The !heap -x command searches for a heap block containing a given address. If the -v option is used, this command will additionally search the entire virtual memory space of
the current process for pointers to this heap block. This command is only available in Windows XP and later versions of Windows.
The !heap -p command displays various forms of page heap information. Before using !heap -p, you must enable the page heap for the target process. This is done through
the Global Flags (gflags.exe) utility. To do this, start the utility, fill in the name of the target application in the Image File Name text box, select Image File Options and
Enable page heap, and click Apply. Alternatively, you can start the Global Flags utility from a Command Prompt window by typing gflags /i xxx.exe +hpa, where xxx.exe is
the name of the target application.
The !heap -p -t[c|s] commands are not supported beyond Windows XP. Use the UMDH tool provided with the debugger package to obtain similar results.
The !heap -srch command displays those heap entries that contain a certain specified pattern. This command is only available in Windows XP and later versions of Windows.
The !heap -flt command limits the display to only heap allocations of a specified size. This command is only available in Windows XP and later versions of Windows.
The !heap -stat command displays heap usage statistics. This command is only available in Windows XP and later versions of Windows.
Here is an example of the standard !heap command:
0:000> !ntsdexts.heap -a
Index
Address Name
Debugging options enabled
1:
00250000
Segment at 00250000 to 00350000 (00056000 bytes committed)
Flags:
50000062
ForceFlags:
40000060
Granularity:
8 bytes
Segment Reserve:
00100000
Segment Commit:
00004000
DeCommit Block Thres:00000400
DeCommit Total Thres:00002000
Total Free Size:
000003be
Max. Allocation Size:7ffddfff
Lock Variable at:
00250b54
Next TagIndex:
0012
Maximum TagIndex:
07ff
Tag Entries:
00350000
PsuedoTag Entries:
00250548
Virtual Alloc List: 00250050
UCR FreeList:
002504d8
128-bit bitmap of free lists
FreeList Usage:
00000014 00000000 00000000 00000000
Free
Free
List
List
#
Head
Blink
Flink
FreeList[ 00 ] at 002500b8: 002a4378 . 002a4378
0x02 - HEAP_ENTRY_EXTRA_PRESENT
0x04 - HEAP_ENTRY_FILL_PATTERN
Entry
Prev
Cur
0x10 - HEAP_ENTRY_LAST_ENTRY
Address
Size
Size flags
002a4370: 00098 . 01c90 [14] - free
FreeList[ 02 ] at 002500c8: 0025cb30 . 002527b8
002527b0: 00058 . 00010 [04] - free
0025cb28: 00088 . 00010 [04] - free
FreeList[ 04 ] at 002500d8: 00269a08 . 0026e530
0026e528: 00038 . 00020 [04] - free
0026a4d0: 00038 . 00020 [06] - free
0026f9b8: 00038 . 00020 [04] - free
0025cda0: 00030 . 00020 [06] - free
00272660: 00038 . 00020 [04] - free
0026ab60: 00038 . 00020 [06] - free
00269f20: 00038 . 00020 [06] - free
00299818: 00038 . 00020 [04] - free
0026c028: 00038 . 00020 [06] - free
00269a00: 00038 . 00020 [46] - free
Segment00 at 00250b90:
Flags:
00000000
Base:
00250000

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 441 of 1651

First Entry:
00250bc8
Last Entry:
00350000
Total Pages:
00000080
Total UnCommit: 00000055
Largest UnCommit:000aa000
UnCommitted Ranges: (1)
002a6000: 000aa000
Heap entries for Segment00
0x01 0x02 0x04 0x08 0x10 0x20 0x40 Entry
Prev
Cur
0x80 Address
00250000:
00250b90:
00250bc8:
00250c08:
00250c68:
00250c90:
00250cf0:
00250d40:
00250d88:
00251998:
...
002525c0:
00252620:
00252670:
002526b0:
002526f0:
00252730:
00252758:
002527b0:
002527c0:
00252818:
00252ae8:
00252e18:
00253148:
002533f0:
00253420:
00253450:
002534e8:
00253548:
00253568:
00253590:
...
0025ccb8:
0025cd18:
0025cd70:
0025cda0:
0025cdc0:
0025d018:
0025e030:
...
002a4190:
002a42a8:
002a42d8:
002a4370:
002a6000:

in Heap 250000
HEAP_ENTRY_BUSY
HEAP_ENTRY_EXTRA_PRESENT
HEAP_ENTRY_FILL_PATTERN
HEAP_ENTRY_VIRTUAL_ALLOC
HEAP_ENTRY_LAST_ENTRY
HEAP_ENTRY_SETTABLE_FLAG1
HEAP_ENTRY_SETTABLE_FLAG2
HEAP_ENTRY_SETTABLE_FLAG3

Size
00000
00b90
00038
00040
00060
00028
00060
00050
00048
00c10

.
.
.
.
.
.
.
.
.
.

Size
00b90
00038
00040
00060
00028
00060
00050
00048
00c10
00030

flags
[01] [01] [07] [07] [07] [07] [07] [07] [07] [07] -

00030
00060
00050
00040
00040
00040
00028
00058
00010
00058
002d0
00330
00330
002a8
00030
00030
00098
00060
00020
00028

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

00060
00050
00040
00040
00040
00028
00058
00010
00058
002d0
00330
00330
002a8
00030
00030
00098
00060
00020
00028
00030

[07]
[07]
[07]
[07]
[07]
[07]
[07]
[04]
[07]
[07]
[07]
[07]
[07]
[07]
[07]
[07]
[07]
[07]
[07]
[07]

- busy (48), tail fill (NTDLL!LDR Database)

- busy (38), tail fill (NTDLL!LDR Database)
- busy (22), tail fill (NTDLL!CSRSS Client)
- busy (24), tail fill (Objects= 64)
- busy (24), tail fill (Objects= 64)
- busy (10), tail fill (Objects= 40)
- busy (3c), tail fill (Objects= 88)
free fill
- busy (3c), tail fill (NTDLL!LDR Database)
- busy (2b8), tail fill (Objects= 720)
- busy (314), tail fill (Objects= 816)
- busy (314), tail fill (Objects= 816)
- busy (28c), tail fill (NTDLL!LocalAtom)
- busy (18), tail fill (NTDLL!LocalAtom)
- busy (18), tail fill (NTDLL!LocalAtom)
- busy (7c), tail fill (BASEDLL!LMEM)
- busy (44), tail fill (BASEDLL!TMP)
- busy (1), tail fill (Objects= 32)
- busy (10), tail fill (Objects= 40)
- busy (16), tail fill (Objects= 48)

00038
00060
00058
00030
00020
00258
01018

.
.
.
.
.
.
.

00060
00058
00030
00020
00258
01018
00060

[07]
[07]
[07]
[06]
[07]
[07]
[07]

- busy (48), tail fill (NTDLL!LDR Database)

- busy (3c), tail fill (NTDLL!LDR Database)
- busy (18), tail fill (NTDLL!LDR Database)
free fill (NTDLL!Temporary)
- busy (23c), tail fill (Objects= 600)
- busy (1000), tail fill (Objects>1024)
- busy (48), tail fill (NTDLL!LDR Database)

. 00118
. 00030
. 00098
. 01c90
000aa000

[07]
[07]
[07]
[14]

- busy (100), tail fill (BASEDLL!GMEM)

- busy (18), tail fill (Objects= 48)
- busy (7c), tail fill (Objects= 152)
free fill
- uncommitted bytes.

00028
00118
00030
00098

busy
busy
busy
busy
busy
busy
busy
busy
busy
busy

(Bytes used)
(Tag name)
(b90)
(38)
(24), tail fill (NTDLL!LDR Database)
(48), tail fill (NTDLL!LDR Database)
(10), tail fill (NTDLL!LDR Database)
(48), tail fill (NTDLL!LDR Database)
(38), tail fill (Objects= 80)
(2e), tail fill (NTDLL!LDR Database)
(bf4), tail fill (Objects>1024)
(12), tail fill (NTDLL!LDR Database)

Here is an example of the !heap -l command:

1:0:011> !heap -l
1:Heap 00170000
Heap 00280000
Heap 00520000
Heap 00b50000
Heap 00c60000
Heap 01420000
Heap 01550000
Heap 016d0000
Heap 019b0000
Heap 01b40000
Scanning VM ...
Entry
User
Heap
Segment
Size PrevSize Flags
---------------------------------------------------------------------001b2958 001b2960 00170000 00000000
40
18 busy extra
001b9cb0 001b9cb8 00170000 00000000
80
300 busy extra

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

001ba208 001ba210
001cbc90 001cbc98
001cbd70 001cbd78
001cbe90 001cbe98
001cbef8 001cbf00
001cc078 001cc080
001cc360 001cc368
001cc3e0 001cc3e8
001fe550 001fe558
001fe6e8 001fe6f0
002057a8 002057b0
00205800 00205808
002058b8 002058c0
00205910 00205918
00205958 00205960
00246970 00246978
00251168 00251170
00527730 00527738
00527920 00527928
21 leaks detected.

Page 442 of 1651

00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00170000
00520000
00520000

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000

80
e0
d8
68
58
f8
80
58
150
48
58
48
58
48
90
60
78
40
40

78
48
e0
48
68
128
50
80
278
48
58
58
70
58
48
88
d0
40
80

busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy
busy

extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra
extra user_flag
extra
extra

The table in this example contains all 21 leaks found.

Here is an example of the !heap -x command:
0:011> !heap 002057b8 -x
Entry
User
Heap
Segment
Size PrevSize Flags
---------------------------------------------------------------------002057a8 002057b0 00170000 00170640
58
58 busy extra
Here is an example of the !heap -x -v command:
1:0:011> !heap 002057b8 -x -v
1:Entry
User
Heap
Segment
Size PrevSize Flags
---------------------------------------------------------------------002057a8 002057b0 00170000 00170640
58
58 busy extra
Search VM for address range 002057a8 - 002057ff : 00205990 (002057d0),
In this example, there is a pointer to this heap block at address 0x00205990.
Here is an example of the !heap -flt s command:
0:001>!heap -flt s 0x50
This will display all of the allocations of size 0x50.
Here is an example of the !heap -flt r command:
0:001>!heap -flt r 0x50 0x80
This will display each allocation whose size is between 0x50 and 0x7F.
Here is an example of the !heap -srch command.
0:001> !heap -srch 77176934
_HEAP @ 00090000
in HEAP_ENTRY: Size : Prev Flags - UserPtr UserSize - state
00099A48: 0018 : 0005 [01] - 00099A50 (000000B8) - (busy)
ole32!CALLFRAME_CACHE<INTERFACE_HELPER_CLSID>::`vftable'
_HEAP @ 00090000
in HEAP_ENTRY: Size : Prev Flags - UserPtr UserSize - state
00099B58: 0018 : 0005 [01] - 00099B60 (000000B8) - (busy)
ole32!CALLFRAME_CACHE<INTERFACE_HELPER_CLSID>::`vftable'
The following diagrams show the arrangement of heap blocks. These are valid in Windows 2000 (Service Pack 1 and later), Windows XP, and later versions of Windows.
Light page heap block allocated:
+-----+---------------+---+
|
|
|
|
+-----+---------------+---+
^
^
^
|
|
8 suffix bytes (filled with 0xA0)
|
User allocation (filled with E0 if zeroing not requested)
Block header (starts with 0xABCDAAAA and ends with 0xDCBAAAAA)
Light page heap block freed:
+-----+---------------+---+
|
|
|
|

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 443 of 1651

+-----+---------------+---+
^
^
^
|
|
8 suffix bytes (filled with 0xA0)
|
User allocation (filled with F0 bytes)
Block header (starts with 0xABCDAAA9 and ends with 0xDCBAAA9)
Full page heap block allocated:
+-----+---------+---+------|
|
|
| ... N/A page
+-----+---------+---+------^
^
^
|
|
0-7 suffix bytes (filled with 0xD0)
|
User allocation (if zeroing not requested, filled
with E0 in Windows 2000 and C0 in Windows XP)
Block header (starts with 0xABCDBBBB and ends with 0xDCBABBBB)
Full page heap block freed:
+-----+---------+---+------|
|
|
| ... N/A page
+-----+---------+---+------^
^
^
|
|
0-7 suffix bytes (filled with 0xD0)
|
User allocation (filled with F0 bytes)
Block header (starts with 0xABCDBBA and ends with 0xDCBABBBA)
To see the stack trace of the allocation or the freeing of a heap block or full page heap block in Windows 2000, use dds (Display Words and Symbols) with the header
address.
To see the stack trace of the allocation or the freeing of a heap block or full page heap block in Windows XP or a later version of Windows, use
dt DPH_BLOCK_INFORMATION with the header address, followed by dds with the block's StackTrace field.
Full page heap blocks in Windows 2000 reside at the beginning of the page containing the user allocation, or at the previous page.
Additional Information
For information about heaps, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark
Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!help
The !help extension displays help text that describes the extension commands exported from the extension DLL.
Do not confuse this extension command with the ? (Command Help) or .help (Meta-Command Help) commands.
Syntax
![ExtensionDLL.]help [-v] [CommandName]
Parameters
ExtensionDLL
Displays help for the specified extension DLL. Type the name of an extension DLL without the .dll file name extension. If the DLL file is not in the extension search
path (as displayed by using .chain (List Debugger Extensions)), include the path to the DLL file . For example, to display help for uext.dll, type !uext.help or !
Path\winext\uext.help.
If you omit the ExtensionDLL, the debugger will display the help text for the first extension DLL in the list of loaded DLLs.
-v
Displays the most detailed help text available. This feature is not supported in all DLLs.
CommandName
Displays only the help text for the specified command. This feature is not supported in all DLLs or for all commands.
DLL
This extension is supported by most extension DLLs.
Comments
Some individual commands will also display a help text if you use the /? or -? parameter with the command name.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 444 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!homedir
The !homedir extension sets the default directory used by the symbol server and the source server.
Syntax
!homedir Directory
!homedir
Parameters
Directory
Specifies the new directory to use as the home directory.
DLL
Windows 2000
Dbghelp.dll
Windows XP and later Dbghelp.dll
Comments
If the !homedir extension is used with no argument, the current home directory is displayed.
The cache for a source server is located in the src subdirectory of the home directory. The downstream store for a symbol server defaults to the sym subdirectory of the home
directory, unless a different location is specified.
When WinDbg is started, the home directory is the directory where Debugging Tools for Windows was installed. The !homedir extension can be used to change this value.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!htrace
The !htrace extension displays stack trace information for one or more handles.
Syntax
User-Mode Syntax
!htrace
!htrace
!htrace
!htrace
!htrace
!htrace

[Handle [Max_Traces]]
-enable [Max_Traces]
-snapshot
-diff
-disable
-?

Kernel-Mode Syntax
!htrace [Handle [Process [Max_Traces]]]
!htrace -?
Parameters
Handle
Specifies the handle whose stack trace will be displayed. If Handle is 0 or omitted, stack traces for all handles in the process will be displayed.
Process
(Kernel mode only) Specifies the process whose handles will be displayed. If Process is 0 or omitted, then the current process is used. In user mode, the current process is
always used.
Max_Traces
Specifies the maximum number of stack traces to display. In user mode, if this parameter is omitted, then all the stack traces for the target process will be displayed.
-enable
(User mode only) Enables handle tracing and takes the first snapshot of the handle information to use as the initial state by the -diff option.
-snapshot
(User mode only) Takes a snapshot of the current handle information to use as the initial state by the -diff option.
-diff
(User mode only) Compares current handle information with the last snapshot of handle information that was taken. Displays all handles that are still open.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 445 of 1651

-disable
(User mode only; Windows Server 2003 and later only) Disables handle tracing. In Windows XP, handle tracing can be disabled only by terminating the target process.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Ntsdexts.dll
Comments
Before !htrace can be used, handle tracing must be enabled. One way to enable handle tracing is to enter the !htrace enable command. When handle tracing is enabled,
stack trace information is saved each time the process opens a handle, closes a handle, or references an invalid handle. It is this stack trace information that !htrace displays.
Note You can also enable handle tracing by activating Application Verifier for the target process and selecting the Handles option.
Some of the traces reported by !htrace may be from a different process context. In this case, the return addresses may not resolve properly in the current process context, or
may resolve to the wrong symbols.
The following example displays information about all handles in process 0x81400300:
kd> !htrace 0 81400300
Process 0x81400300
ObjectTable 0xE10CCF60
-------------------------------------Handle 0x7CC - CLOSE:
0x8018FCB9: ntoskrnl!ExDestroyHandle+0x103
0x801E1D12: ntoskrnl!ObpCloseHandleTableEntry+0xE4
0x801E1DD9: ntoskrnl!ObpCloseHandle+0x85
0x801E1EDD: ntoskrnl!NtClose+0x19
0x010012C1: badhandle!mainCRTStartup+0xE3
0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D
-------------------------------------Handle 0x7CC - OPEN:
0x8018F44A: ntoskrnl!ExCreateHandle+0x94
0x801E3390: ntoskrnl!ObpCreateUnnamedHandle+0x10C
0x801E7317: ntoskrnl!ObInsertObject+0xC3
0x77DE23B2: KERNEL32!CreateSemaphoreA+0x66
0x010011C5: badhandle!main+0x45
0x010012C1: badhandle!mainCRTStartup+0xE3
0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D
-------------------------------------Handle 0x7DC - BAD REFERENCE:
0x8018F709: ntoskrnl!ExMapHandleToPointerEx+0xEA
0x801E10F2: ntoskrnl!ObReferenceObjectByHandle+0x12C
0x801902BE: ntoskrnl!NtSetEvent+0x6C
0x80154965: ntoskrnl!_KiSystemService+0xC4
0x010012C1: badhandle!mainCRTStartup+0xE3
0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D
-------------------------------------Handle 0x7DC - CLOSE:
0x8018FCB9: ntoskrnl!ExDestroyHandle+0x103
0x801E1D12: ntoskrnl!ObpCloseHandleTableEntry+0xE4
0x801E1DD9: ntoskrnl!ObpCloseHandle+0x85
0x801E1EDD: ntoskrnl!NtClose+0x19
0x010012C1: badhandle!mainCRTStartup+0xE3
0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D
-------------------------------------Handle 0x7DC - OPEN:
0x8018F44A: ntoskrnl!ExCreateHandle+0x94
0x801E3390: ntoskrnl!ObpCreateUnnamedHandle+0x10C
0x801E7317: ntoskrnl!ObInsertObject+0xC3
0x77DE265C: KERNEL32!CreateEventA+0x66
0x010011A0: badhandle!main+0x20
0x010012C1: badhandle!mainCRTStartup+0xE3
0x77DE0B2F: KERNEL32!BaseProcessStart+0x3D
-------------------------------------Parsed 0x6 stack traces.
Dumped 0x5 stack traces.
Additional Information
For information about handles, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon. To display
further information about a specific handle, use the !handle extension.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 446 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

!imggp
The !imggp extension displays the global pointer (GP) directory entry value for a 64-bit image.
Syntax
!imggp Address
Parameters
Address
Specifies the base address of the image.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!imgreloc
The !imgreloc extension displays the addresses of each loaded module and indicates their former addresses before they were relocated.
Syntax
!imgreloc Address
Parameters
Address
Specifies the base address of the image.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
Here is an example:
0:000> !imgreloc 00400000
00400000 Prymes - at preferred address
010e0000 appvcore - RELOCATED from 00400000
5b2f0000 verifier - at preferred address
5d160000 ShimEng - at preferred address

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

module name
Prymes
C (pdb symbols)
KERNEL32
(export symbols)
ntdll
(export symbols)

Prymes.pdb
C:\WINNT\system32\KERNEL32.dll
ntdll.dll

0:000> !lmi 00400000

Loaded Module Info: [00400000]
Module: Prymes
Base Address: 00400000
Image Name: Prymes.exe
Machine Type: 332 (I386)
Time Stamp: 3c76c346 Fri Feb 22 14:16:38 2002
Size: 2d000
CheckSum: 0
Characteristics: 230e stripped
Debug Data Dirs: Type Size
VA Pointer
MISC 110,
0,
77a00 [Data not mapped]
Symbol Type: EXPORT
- PDB not found
Load Report: export symbols
For an explanation of the abbreviations shown on the Characteristics line of this example, see Symbol Status Abbreviations.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!mui
The !mui extension displays the Multilingual User Interface (MUI) cache information. The implementation of MUI was vastly improved in Windows Vista. As a result, the
behavior of this extension on earlier implementations is undefined.
Syntax
User-Mode Syntax
!mui
!mui
!mui
!mui
!mui
!mui

c
f
-i
-r ModuleAddress
-t
-?

Kernel-Mode Syntax
!mui
!mui
!mui
!mui
!mui
!mui
!mui

-c
f
-i
-s
-r ModuleAddress
-t
-?

Parameters
-c
Causes the output to include the language identifier (ID), a pointer to the module, a pointer to the resource configuration data, and a pointer to the associated MUI DLL
for each module.
-f
Causes the output to include the loader merged language fallback list.
-i
Causes the output to include the installed and licensed MUI languages and their associated information.
-r ModuleAddress
Causes the resource configuration data for the module at ModuleAddress to be displayed. This includes the file type, the checksum value, and the resource types.
-s
(Kernel Mode Only) Causes the display to include the full file paths for the module and associated MUI DLL for each module.
-t
Causes the output to include the thread preference language.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Vista and later Exts.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 450 of 1651

Additional Information
For information about MUI and resource configuration data format, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!net_send
The !net_send extension sends a message over a local network.
Syntax
!net_send SendingMachine TargetMachine Sender Message
Parameters
SendingMachine
Specifies the computer that will process the command. It is recommended that this be the name of the computer that the debugger is running on, since your network
configuration may refuse to send the message otherwise. SendingMachine should not include leading backslashes (\\).
TargetMachine
Specifies the computer to which the message will be sent. TargetMachine should not include leading backslashes (\\).
Sender
Specifies the sender of the message. It is recommended that Sender be identical to SendingMachine, since your network configuration may refuse to send the message
otherwise. When the message is displayed, this string will be identified as the sender of the message.
Message
Specifies the message itself. All text after the Sender parameter will be treated as part of Message, including spaces and quotation marks, although a semicolon will
terminate Message and begin a new command.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!obja
The !obja extension displays the attributes of an object in the object manager.
Syntax
!obja Address
Parameters
Address
Specifies the hexadecimal address of the object header you want to examine.
DLL
Windows 2000

Ext.dll
Kdextx86.dll
Windows XP and later Ext.dll

Comments
The attributes pertaining to the specified object are listed. Valid attributes are:
#define
#define
#define
#define
#define
#define
#define

OBJ_INHERIT
OBJ_PERMANENT
OBJ_EXCLUSIVE
OBJ_CASE_INSENSITIVE
OBJ_OPENIF
OBJ_OPENLINK
OBJ_VALID_ATTRIBUTES

0x00000002L
0x00000010L
0x00000020L
0x00000040L
0x00000080L
0x00000100L
0x000001F2L

Here is an example:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 451 of 1651

kd> !obja 80967768

Obja +80967768 at 80967768:
OBJ_INHERIT
OBJ_PERMANENT
OBJ_EXCLUSIVE
Additional Information
For information about objects and the object manager, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft
Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!owner
The !owner extension displays the owner of a module or function.
Syntax
!owner [Module[!Symbol]]
Parameters
Module
Specifies the module whose owner is desired. An asterisk (*) at the end of Module represents any number of additional characters.
Symbol
Specifies the symbol within Module whose owner is desired. An asterisk (*) at the end of Symbol represents any number of additional characters. If Symbol is omitted,
the owner of the entire module is displayed.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
If no parameters are used and a fault has occurred, !owner will display the name of the owner of the faulting module or function.
When you pass a module or function name to the !owner extension, the debugger displays the word Followup followed by the name of owner of the specified module or
function.
For this extension to display useful information, you must first create a triage.ini file containing the names of the module and function owners.
For details on the triage.ini file and an example of the !owner extension, see Specifying Module and Function Owners.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!peb
The !peb extension displays a formatted view of the information in the process environment block (PEB).
Syntax
!peb [PEB-Address]
Parameters
PEB-Address
The hexadecimal address of the process whose PEB you want to examine. (This is not the address of the PEB as derived from the kernel process block for the process.) If
PEB-Address is omitted in user mode, the PEB for the current process is used. If it is omitted in kernel mode, the PEB corresponding to the current process context is
displayed.
DLL
Windows 2000

Kdextx86.dll
Ntsdexts.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 452 of 1651

Windows XP and later Exts.dll

Comments
The PEB is the user-mode portion of Microsoft Windows process control structures.
If the !peb extension with no argument gives you an error in kernel mode, you should use the !process extension to determine the PEB address for the desired process. Make
sure your process context is set to the desired process, and then use the PEB address as the argument for !peb.
The exact output displayed depends on the Windows version and on whether you are debugging in kernel mode or user mode. The following example is taken from a kernel
debugger attached to a Windows Server 2003 target:
kd> !peb
PEB at 7ffdf000
InheritedAddressSpace:
No
ReadImageFileExecOptions: No
BeingDebugged:
No
ImageBaseAddress:
4ad00000
Ldr
77fbe900
Ldr.Initialized:
Yes
Ldr.InInitializationOrderModuleList: 00241ef8 . 00242360
Ldr.InLoadOrderModuleList:
00241e90 . 00242350
Ldr.InMemoryOrderModuleList:
00241e98 . 00242358
Base TimeStamp
Module
4ad00000 3d34633c Jul 16 11:17:32 2002 D:\WINDOWS\system32\cmd.exe
77f40000 3d346214 Jul 16 11:12:36 2002 D:\WINDOWS\system32\ntdll.dll
77e50000 3d3484ef Jul 16 13:41:19 2002 D:\WINDOWS\system32\kernel32.dll
....
SubSystemData:
00000000
ProcessHeap:
00140000
ProcessParameters: 00020000
WindowTitle: 'D:\Documents and Settings\Administrator\Desktop\Debuggers.lnk'
ImageFile:
'D:\WINDOWS\system32\cmd.exe'
CommandLine: '"D:\WINDOWS\system32\cmd.exe" '
DllPath:
'D:\WINDOWS\system32;D:\WINDOWS\system32;....
Environment: 00010000
ALLUSERSPROFILE=D:\Documents and Settings\All Users
APPDATA=D:\Documents and Settings\UserTwo\Application Data
CLIENTNAME=Console
....
windir=D:\WINDOWS
The similar !teb extension displays the thread environment block.
Additional Information
For information about process environment blocks, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!psr
The !psr extension displays an Itanium processor status word (PSR).
Syntax
!psr PSR [DisplayLevel]
!psr @ipsr [DisplayLevel]
Parameters
PSR
Specifies the hexadecimal address of the PSR to be displayed.
@ipsr
Causes the ipsr register to be displayed.
DisplayLevel
Can be any one of the following options:
0
This causes only the values of each PSR field to be displayed. This is the default.
1
This causes the display to include more in-depth information on each of the PSR fields that are not reserved or ignored.
2
This causes the display to include more in-depth information on all of the PSR fields, including those that are ignored or reserved.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 453 of 1651

Windows 2000
Unavailable
Windows XP and later Exts.dll
This extension command can only be used with an Itanium target computer.
Comments
Here are a couple of examples:
0:000> !psr @ipsr
psr:ia bn ed ri ss dd da id it mc is cpl rt tb lp db
0 1 0 0 0 0 0 0 1 0 0 3
1 0 0 0
si di pp sp dfh dfl dt pk i ic | mfh mfl ac up be
0 0 1 0 0
0
1 0 1 1 | 0
1
0 0 0
kd> !psr @ipsr 1
be
up
ac
mfl
mfh
ic
i
pk
dt
dfl
dfh
sp
pp
di
si
db
lp
tb
rt
cpl
is
mc
it
id
da
dd
ss
ri
ed
bn
ia

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

0
0
1
1
0
1
0
0
1
0
1
0
1
0
0
0
0
0
1
0
0
0
1
0
0
0
0
0
0
1
0

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

Big-Endian
User Performance monitor enable
Alignment Check
Lower floating-point registers written
Upper floating-point registers written
Interruption Collection
Interrupt enable
Protection Key enable
Data Address Translation enable
Disabled Floating-point Low register set
Disabled Floating-point High register set
Secure Performance monitors
Privileged Performance monitor enable
Disable Instruction set transition
Secure Interval timer
Debug Breakpoint fault enable
Lower Privilege transfer trap enable
Taken Branch trap enable
Register stack translation enable
Current Privilege Level
Instruction Set
Machine Abort Mask delivery disable
Instruction address Translation enable
Instruction Debug fault disable
Disable Data Access and Dirty-bit faults
Data Debug fault disable
Single Step enable
Restart Instruction
Exception Deferral
register Bank
Disable Instruction Access-bit faults

Additional Information
For more information, see Itanium Architecture, or consult an Intel architecture manual.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rebase
The !rebase extension searches in a rebase.log file for a specified address or symbol.
Syntax
!rebase
!rebase
!rebase
!rebase

[-r] Address [Path]

Symbol [Path]
-stack [Path]
-?

Parameters
-r
Attempts to load any module found in rebase.log.
Address
Specifies an address in standard hexadecimal format. The extension will search for DLLs near this address.
Path
Specifies the file path to the rebase.log. If Path is not specified, then the extension tries to guess the path to the rebase.log or, failing that, tries to read a rebase.log file
from the current working directory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 454 of 1651

Symbol
Specifies the symbol or image name. The extension will search for DLLs that contain this substring.
-stack
Displays all modules in the current stack.
-?
Displays a brief help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Ext.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rtlavl
The !rtlavl extension displays the entries of an RTL_AVL_TABLE structure.
Syntax
!rtlavl Address [Module!Type]
!rtlavl -?
Parameters
Address
Specifies the address of the RTL_AVL_TABLE to display.
Module
Specifies the module in which the data structure is defined.
Type
Specifies the name of a data structure.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
Including the Module!Type option causes each entry in the table to be interpreted as having the given type.
The display can be interrupted at any time by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD or CDB).
Additional Information
Use the !gentable extension to display AVL tables.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!sd
The !sd extension displays the security descriptor at the specified address.
Syntax
Syntax in Windows 2000:
!sd Address
Syntax in Windows XP and later
!sd Address [Flags]
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 455 of 1651

Address
Specifies the hexadecimal address of the SECURITY_DESCRIPTOR structure.
Flags
(Windows XP and later) If this is set to 1, the friendly name is displayed. This includes the security identifier (SID) type, as well as the domain and user name for the
SID.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Exts.dll
Comments
Here is an example:
kd> !sd e1a96a80 1
->Revision: 0x1
->Sbz1
: 0x0
->Control : 0x8004
SE_DACL_PRESENT
SE_SELF_RELATIVE
->Owner
: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser)
->Group
: S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users)
->Dacl
:
->Dacl
: ->AclRevision: 0x2
->Dacl
: ->Sbz1
: 0x0
->Dacl
: ->AclSize
: 0x40
->Dacl
: ->AceCount
: 0x2
->Dacl
: ->Sbz2
: 0x0
->Dacl
: ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE
->Dacl
: ->Ace[0]: ->AceFlags: 0x0
->Dacl
: ->Ace[0]: ->AceSize: 0x24
->Dacl
: ->Ace[0]: ->Mask : 0x001f0003
->Dacl
: ->Ace[0]: ->SID: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser)
->Dacl
->Dacl
->Dacl
->Dacl
->Dacl

:
:
:
:
:

->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:

->Sacl

is NULL

->AceType: ACCESS_ALLOWED_ACE_TYPE
->AceFlags: 0x0
->AceSize: 0x14
->Mask : 0x001f0003
->SID: S-1-5-18 (Well Known Group: NT AUTHORITY\SYSTEM)

Additional Information
For an application and an example of this command, see Determining the ACL of an Object. For information about security descriptors, see the Microsoft Windows SDK
documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark Russinovich and David Solomon. Also see !sid and !acl.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!sid
The !sid extension displays the security identifier (SID) at the specified address.
Syntax
Syntax in Windows 2000:
!sid Address
Syntax in Windows XP and later
!sid Address [Flags]
Parameters
Address
Specifies the address of the SID structure.
Flags
(Windows XP and later) If this is set to 1, the SID type, domain, and user name for the SID is displayed.
(Windows XP and later) If this is set to 1, the friendly name is displayed. This includes the SID type, as well as the domain and user name for the SID.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 456 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Exts.dll
Comments
Here are two examples, one without the friendly name shown, and one with:
kd> !sid 0xe1bf35b8
SID is: S-1-5-21-518066528-515770016-299552555-513
kd> !sid 0xe1bf35b8 1
SID is: S-1-5-21-518066528-515770016-299552555-513 (Group: MYGROUP\Domain Users)
Additional Information
For information about SIDs, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, or Microsoft Windows Internals by Mark
Russinovich and David Solomon. Also see !sd and !acl.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!slist
The !slist extension displays a singly-linked list (SList).
Syntax
!slist Address [ Symbol [Offset] ]
!slist -?
Parameters
Address
Specifies the address of the SLIST_HEADER.
Symbol
Specifies the data type to use for display. If Symbol is specified, the debugger will assume that each node of the SList is an instance of this data type when displaying it.
Offset
Specifies the byte offset of the SList pointer within the structure.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Exts.dll
Comments
If you know the nature of the linked structures, the Symbol and Offset parameters are very useful. To see the difference, here are two examples; the first omits the Symbol and
Offset parameters, while the second includes them.
0:000> !slist ListHead
SLIST HEADER:
+0x000 Alignment
+0x000 Next
+0x004 Depth
+0x006 Sequence
SLIST CONTENTS:
002643e8 002642c0
002642c0 00264198
00264198 00264070
00264070 00263f48
00263f48 00261420
00261420 002612f8
002612f8 002611d0
002611d0 002610a8
002610a8 00260f80
00260f80 00000000

0000000a
00000009
00000008
00000007
00000006
00000005
00000004
00000003
00000002
00000001

:
:
:
:

a000a002643e8
2643e8
a
a

6e676953
6e676953
6e676953
6e676953
6e676953
6e676953
6e676953
6e676953
6e676953
6e676953

72757461
72757461
72757461
72757461
72757461
72757461
72757461
72757461
72757461
72757461

0:000> !slist ListHead _PROGRAM_ITEM 0

SLIST HEADER:
+0x000 Alignment
: a000a002643e8
+0x000 Next
: 2643e8
+0x004 Depth
: a

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

+0x006 Sequence
SLIST CONTENTS:
002643e8
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
002642c0
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
00264198
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
00264070
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
00263f48
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
00261420
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
002612f8
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
002611d0
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
002610a8
+0x000 ItemEntry
+0x004 Signature
+0x008 Description
00260f80
+0x000 ItemEntry
+0x004 Signature
+0x008 Description

Page 457 of 1651

: a

: _SINGLE_LIST_ENTRY
: 0xa
: [260] "Signature is: 10"
: _SINGLE_LIST_ENTRY
: 9
: [260] "Signature is: 9"
: _SINGLE_LIST_ENTRY
: 8
: [260] "Signature is: 8"
: _SINGLE_LIST_ENTRY
: 7
: [260] "Signature is: 7"
: _SINGLE_LIST_ENTRY
: 6
: [260] "Signature is: 6"
: _SINGLE_LIST_ENTRY
: 5
: [260] "Signature is: 5"
: _SINGLE_LIST_ENTRY
: 4
: [260] "Signature is: 4"
: _SINGLE_LIST_ENTRY
: 3
: [260] "Signature is: 3"
: _SINGLE_LIST_ENTRY
: 2
: [260] "Signature is: 2"
: _SINGLE_LIST_ENTRY
: 1
: [260] "Signature is: 1"

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!std_map
The !std_map extension displays the entries of a std::map tree.
Syntax
!std_map Address [Module!Type [TypeSize]]
!std_map -?
Parameters
Address
Specifies the address of the std::map tree to display.
Module
Specifies the module in which the data structure is defined.
Type
Specifies the name of a data structure. This must be expressed in Module!std::pair<Type1,Type2> form. If the TypeSize parameter is used, this parameter must be
enclosed in quotation marks.
TypeSize
Specifies the size of the data structure to make the symbols unambiguous.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 458 of 1651

Including the Module!Type option causes each entry in the table to be interpreted as having the given type.
Use dt -ve (Module!std::pair<Type1,Type2>) to display possible sizes.
Additional Information
To display other Standard Template Library (STL) defined templates, see !stl.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!stl
The !stl extension displays some of the known Standard Template Library (STL) templates.
Syntax
!stl [Options] Template
!stl -?
Parameters
Options
May include any of the following possibilities:
-v
Causes detailed output to be displayed.
-V
Causes more detailed output to be displayed, such as information on the progress of the extension, including when certain functions are called and returned.
Template
Specifies the name of the template to be displayed.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Exts.dll
Comments
The verbose options will only take effect if the debugger's verbose mode is enabled.
This extension currently supports STL templates of the following types: string, wstring, vector<string>, vector<wstring>, list<string>, list<wstring>, and pointers to any of
the preceding types.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!str
The !str extension displays an ANSI_STRING or OEM_STRING structure.
Syntax
!str Address
Parameters
Address
Specifies the hexadecimal address of the ANSI_STRING or OEM_STRING structure.
DLL
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 459 of 1651

ANSI strings are counted 8-bit character strings, as defined in the following structure:
typedef struct _STRING {
USHORT Length;
USHORT MaximumLength;
PCHAR Buffer;
} STRING;
typedef STRING ANSI_STRING;
typedef STRING OEM_STRING;
If the string is NULL-terminated, Length does not include the trailing NULL.
Additional Information
For more information about ANSI_STRING structures, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!sym
The !sym extension controls noisy symbol loading and symbol prompts.
Syntax
!sym
!sym
!sym
!sym
!sym

noisy
quiet
prompts
prompts off

Parameters
noisy
Activates noisy symbol loading.
quiet
Deactivates noisy symbol loading.
prompts
Allows authentication dialog boxes to appear when SymSrv receives an authentication request.
prompts off
Suppresses all authentication dialog boxes when SymSrv receives an authentication request. This may result in SymSrv being unable to access symbols over the internet.
DLL
Windows 2000
Dbghelp.dll
Windows XP and later Dbghelp.dll
Comments
If the !sym extension is used with no arguments, the current state of noisy symbol loading and symbol prompting is displayed.
The !sym noisy and !sym quiet extensions control noisy symbol loading. For details and for other methods of displaying and changing this option, see SYMOPT_DEBUG.
The !sym prompts and !sym prompts off extensions control whether authentication dialogs are displayed when SymSrv encounters an authentication request. These
commands must be followed by .reload (Reload Module) for them to take effect. Authentication requests may be sent by proxy servers, internet firewalls, smart card readers,
and secure websites. For details and for other methods of changing this option, see Firewalls and Proxy Servers.
Note Noisy symbol loading should not be confused with noisy source loading that is controlled by the .srcnoisy (Noisy Source Loading) command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!symsrv
The !symsrv extension closes the symbol server client.
Syntax
!symsrv close

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 460 of 1651

DLL
Windows 2000
Dbghelp.dll
Windows XP and later Dbghelp.dll
Comments
The !symsrv close extension will close any active symbol server client.
This can be useful if you need to re-synchronize your connection.
If you have previously refused an internet authentication request, you will need to use !symsrv close to reconnect to the symbol store. See Firewalls and Proxy Servers for
details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!teb
The !teb extension displays a formatted view of the information in the thread environment block (TEB).
Syntax
!teb [TEB-Address]
Parameters
TEB-Address
The hexadecimal address of the thread whose TEB you want to examine. (This is not the address of the TEB as derived from the kernel thread block for the thread.) If
TEB-Address is omitted in user mode, the TEB for the current process is used. If it is omitted in kernel mode, the TEB corresponding to the current register context is
displayed.
DLL
Windows 2000

Kdextx86.dll

Ntsdexts.dll
Windows XP and later Exts.dll
Comments
The TEB is the user-mode portion of Microsoft Windows thread control structures.
If the !teb extension with no argument gives you an error in kernel mode, you should use the !process extension to determine the TEB address for the desired thread. Make
sure your register context is set to the desired thread, and then use the TEB address as the argument for !teb.
Here is an example of this command's output in user mode:
0:001> ~
0 id: 324.458
. 1 id: 324.48c

Suspend: 1 Teb 7ffde000 Unfrozen

Suspend: 1 Teb 7ffdd000 Unfrozen

0:001> !teb
TEB at 7FFDD000
ExceptionList:
76ffdc
Stack Base:
770000
Stack Limit:
76f000
SubSystemTib:
0
FiberData:
1e00
ArbitraryUser:
0
Self:
7ffdd000
EnvironmentPtr:
0
ClientId:
324.48c
Real ClientId:
324.48c
RpcHandle:
0
Tls Storage:
0
PEB Address:
7ffdf000
LastErrorValue:
0
LastStatusValue: 0
Count Owned Locks:0
HardErrorsMode:
0
The similar !peb extension displays the process environment block.
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 461 of 1651

For information about thread environment blocks, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tls
The !tls extension displays a thread local storage (TLS) slot.
Syntax
!tls Slot [TEB]
Parameters
Slot
Specifies the TLS slot. This can be any value between 0 and 1088 (decimal). If Slot is -1, all slots are displayed.
TEB
Specifies the thread environment block (TEB). If this is 0 or omitted, the current thread is used.
DLL
Windows 2000
Unavailable
Windows XP and later Exts.dll
Comments
Here is an example:
0:000> !tls -1
TLS slots on thread: c08.f54
0x0000 : 00000000
0x0001 : 003967b8
0:000> !tls 0
c08.f54: 00000000

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!token
The !token extension displays a formatted view of a security token object.
Syntax
Syntax in Windows 2000 (kernel mode only)
!token [Address]
Kernel-Mode Syntax in Windows XP and later
!token [-n] [Address]
!token -?
User-Mode Syntax in Windows XP and later
!token [-n] [Handle]
!token -?
Parameters
Address
(Kernel mode only) Specifies the address of the token to be displayed. If this is 0 or omitted, the token for the active thread is displayed.
Handle
(User mode only) Specifies the handle of the token to be displayed. If this is 0 or omitted, the token associated with the target thread is displayed.
-n
(Windows XP and later; user mode only) Causes the display to include the friendly name. This includes the security identifier (SID) type, as well as the domain and user
name for the SID. This option cannot be used when you are debugging LSASS.
-?

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 462 of 1651

(Windows XP and later) Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Exts.dll
In Windows 2000, !token is only available in kernel-mode debugging. In Windows XP and later operating systems, !token is available in kernel-mode and live user-mode
debugging. It cannot be used on user-mode dump files.
Comments
The TOKEN structure is a security object type that represents an authenticated user process. Every process has an assigned token, which becomes the default token for each
thread of that process. However, an individual thread can be assigned a token that overrides this default.
You can get the token address from the output of !process. To display a list of the individual fields of the TOKEN structure, use the !tokenfields extension in Windows 2000,
or use the dt nt!_TOKEN command in Windows XP or later.
Here is an example:
kd> !process 81464da8 1
PROCESS 81464da8 SessionId: 0 Cid: 03bc
Peb: 7ffdf000 ParentCid: 0124
DirBase: 0dec2000 ObjectTable: e1a31198 TableSize: 275.
Image: MSMSGS.EXE
VadRoot 81468cc0 Vads 170 Clone 0 Private 455. Modified 413. Locked 0.
DeviceMap e1958438
Token
e1bed030
ElapsedTime
0:44:15.0142
UserTime
0:00:00.0290
KernelTime
0:00:00.0300
QuotaPoolUsage[PagedPool]
49552
QuotaPoolUsage[NonPagedPool]
10872
Working Set Sizes (now,min,max) (781, 50, 345) (3124KB, 200KB, 1380KB)
PeakWorkingSetSize
1550
VirtualSize
57 Mb
PeakVirtualSize
57 Mb
PageFaultCount
2481
MemoryPriority
BACKGROUND
BasePriority
8
CommitCharge
2497
kd> !exts.token -n e1bed030
_TOKEN e1bed030
TS Session ID: 0
User: S-1-5-21-518066528-515770016-299552555-2981724 (User: MYDOMAIN\myuser)
Groups:
00 S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users)
Attributes - Mandatory Default Enabled
01 S-1-1-0 (Well Known Group: localhost\Everyone)
Attributes - Mandatory Default Enabled
02 S-1-5-32-544 (Alias: BUILTIN\Administrators)
Attributes - Mandatory Default Enabled Owner
03 S-1-5-32-545 (Alias: BUILTIN\Users)
Attributes - Mandatory Default Enabled
04 S-1-5-21-518066528-515770016-299552555-2999049 (Group: MYDOMAIN\AllUsers)
Attributes - Mandatory Default Enabled
05 S-1-5-21-518066528-515770016-299552555-2931095 (Group: MYDOMAIN\SomeGroup1)
Attributes - Mandatory Default Enabled
06 S-1-5-21-518066528-515770016-299552555-2931096 (Group: MYDOMAIN\SomeGroup2)
Attributes - Mandatory Default Enabled
07 S-1-5-21-518066528-515770016-299552555-3014318 (Group: MYDOMAIN\SomeGroup3)
Attributes - Mandatory Default Enabled
08 S-1-5-21-518066528-515770016-299552555-3053352 (Group: MYDOMAIN\Another Group)
Attributes - Mandatory Default Enabled
09 S-1-5-21-518066528-515770016-299552555-2966661 (Group: MYDOMAIN\TestGroup)
Attributes - Mandatory Default Enabled
10 S-1-5-21-2117033040-537160606-1609722162-17637 (Group: MYOTHERDOMAIN\someusers)
Attributes - Mandatory Default Enabled
11 S-1-5-21-518066528-515770016-299552555-3018354 (Group: MYDOMAIN\TestGroup2)
Attributes - Mandatory Default Enabled
12 S-1-5-21-518066528-515770016-299552555-3026602 (Group: MYDOMAIN\SomeGroup4)
Attributes - Mandatory Default Enabled
13 S-1-5-21-518066528-515770016-299552555-2926570 (Group: MYDOMAIN\YetAnotherGroup)
Attributes - Mandatory Default Enabled
14 S-1-5-21-661411660-2927047998-133698966-513 (Group: MYDOMAIN\Domain Users)
Attributes - Mandatory Default Enabled
15 S-1-5-21-518066528-515770016-299552555-2986081 (Alias: MYDOMAIN\an_alias)
Attributes - Mandatory Default Enabled GroupResource
16 S-1-5-21-518066528-515770016-299552555-3037986 (Alias: MYDOMAIN\AReallyLongGroupName1)
Attributes - Mandatory Default Enabled GroupResource
17 S-1-5-21-518066528-515770016-299552555-3038991 (Alias: MYDOMAIN\AReallyLongGroupName2)
Attributes - Mandatory Default Enabled GroupResource
18 S-1-5-21-518066528-515770016-299552555-3037999 (Alias: MYDOMAIN\AReallyLongGroupName3)
Attributes - Mandatory Default Enabled GroupResource

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 463 of 1651

19 S-1-5-21-518066528-515770016-299552555-3038983 (Alias: MYDOMAIN\AReallyReallyLongGroupName)

Attributes - Mandatory Default Enabled GroupResource
20 S-1-5-5-0-71188 (no name mapped)
Attributes - Mandatory Default Enabled LogonId
21 S-1-2-0 (Well Known Group: localhost\LOCAL)
Attributes - Mandatory Default Enabled
22 S-1-5-4 (Well Known Group: NT AUTHORITY\INTERACTIVE)
Attributes - Mandatory Default Enabled
23 S-1-5-11 (Well Known Group: NT AUTHORITY\Authenticated Users)
Attributes - Mandatory Default Enabled
Primary Group: S-1-5-21-518066528-515770016-299552555-513 (Group: MYDOMAIN\Domain Users)
Privs:
00 0x000000017 SeChangeNotifyPrivilege
Attributes - Enabled Default
01 0x000000008 SeSecurityPrivilege
Attributes 02 0x000000011 SeBackupPrivilege
Attributes 03 0x000000012 SeRestorePrivilege
Attributes 04 0x00000000c SeSystemtimePrivilege
Attributes 05 0x000000013 SeShutdownPrivilege
Attributes 06 0x000000018 SeRemoteShutdownPrivilege
Attributes 07 0x000000009 SeTakeOwnershipPrivilege
Attributes 08 0x000000014 SeDebugPrivilege
Attributes 09 0x000000016 SeSystemEnvironmentPrivilege
Attributes 10 0x00000000b SeSystemProfilePrivilege
Attributes 11 0x00000000d SeProfileSingleProcessPrivilege
Attributes 12 0x00000000e SeIncreaseBasePriorityPrivilege
Attributes 13 0x00000000a SeLoadDriverPrivilege
Attributes - Enabled
14 0x00000000f SeCreatePagefilePrivilege
Attributes 15 0x000000005 SeIncreaseQuotaPrivilege
Attributes 16 0x000000019 SeUndockPrivilege
Attributes - Enabled
17 0x00000001c SeManageVolumePrivilege
Attributes Authentication ID:
(0,11691)
Impersonation Level:
Anonymous
TokenType:
Primary
Source: User32
TokenFlags: 0x9 ( Token in use )
Token ID: 18296
ParentToken ID: 0
Modified ID:
(0, 18298)
RestrictedSidCount: 0
RestrictedSids: 00000000
Additional Information
For information about the kernel-mode TOKEN structure, see Microsoft Windows Internals by Mark Russinovich and David Solomon. For information about the user-mode
TOKEN structure, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tp
The !tp extension displays thread pool information.
Syntax
!tp
!tp
!tp
!tp
!tp
!tp
!tp
!tp

Page 466 of 1651

DLL:

If your target computer is running the free build of Windows 2000, use w2kfre\Kdextx86.dll.
If your target computer is running the checked build of Windows 2000, use w2kchk\Kdextx86.dll.
If your target computer is running Windows XP or a later version of Windows, use winxp\Kdexts.dll.

In addition, kernel-mode extensions that are not specific to any single operating system can be found in winext\kext.dll.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ahcache
The !ahcache extension displays the application compatibility cache.
Syntax
!ahcache [Flags]
Parameters
Flags
Specifies the information to include in the display. This can be any combination of the following bits (the default is zero):
Bit 0 (0x1)
Displays the RTL_GENERIC_TABLE list instead of the LRU list.
Bit 4 (0x10)
Verbose display: includes all entry details, not just the names.
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll

December 09, 2009

Debugging Tools for Windows

!arbiter
The !arbiter extension displays the current system resource arbiters and arbitrated ranges.
Syntax
!arbiter [Flags]
Parameters
Flags
Specifies which classes of arbiters are displayed. If omitted, all arbiters are displayed. These bits can be combined freely.
Bit 0 (0x1)
I/O arbiters.
Bit 1 (0x2)
Memory arbiters.
Bit 2 (0x4)
IRQ arbiters.
Bit 3 (0x8)
DMA arbiters.
Bit 4 (0x10)
Bus number arbiters.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
For each arbiter, !arbiter displays each allocated range of system resources, some optional flags, the PDO attached to that range (in other words, the range's owner), and the
service name of this owner (if known).
The flags have the following meanings:
Flag
Meaning
S
Range is shared
C Range in conflict
B Range is boot-allocated
D Range is driver-exclusive
A Range alias
P
Range positive decode
Here is an example:
kd> !arbiter 4
DEVNODE 80e203b8 (HTREE\ROOT\0)
Interrupt Arbiter "" at 80167140
Allocated ranges:
0000000000000000 - 0000000000000000
B
80e1d3d8
0000000000000001 - 0000000000000001
B
80e1d3d8
.....
00000000000001a2 - 00000000000001a2
00000000000001a2 - 00000000000001a2 CB
80e1d3d8
00000000000001a2 - 00000000000001a2 CB
80e52538 (Serial)
00000000000001a3 - 00000000000001a3
80e52778 (i8042prt)
00000000000001b3 - 00000000000001b3
80e1b618 (i8042prt)
Possible allocation:
< none >
In this example, the next-to-last line shows the resource range (which consists of 0x1A3 alone), the PDO of 0x80E52778, and the service of i8042prt.sys. No flags are listed
on this line.
You can now use !devobj with this PDO address to find the device extension and device node addresses:
kd> !devobj 80e52778
Device object (80e52778) is for:
00000034 \Driver\PnpManager DriverObject 80e20610
Current Irp 00000000 RefCount 1 Type 00000004 Flags 00001040
DevExt 80e52830 DevObjExt 80e52838 DevNode 80e52628
ExtensionFlags (0000000000)
AttachedDevice (Upper) 80d78b28 \Driver\i8042prt
Device queue is not busy.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 470 of 1651

Additional Information
See Plug and Play Debugging for applications of this extension command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ate
The !ate extension displays the alternate page table entry (ATE) for the specified address.
Syntax
!ate Address
Parameters
Address
Specifies the ATE to display.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
This extension is only available on Itanium-based computers.
The status flags for the ATE are shown in the following table. The !ate display indicates these bits with capital letters or dashes and adds additional information as well.
Display
when
set
V
G
E
W
L
Z
N
C
I
P

Display
when
clear
R
-

Meaning

Commit.
Not accessed.
Execute.
Writeable or read-only.
Locked. The ATE is locked, therefore, any faults on the page that contain the ATE will be retried until the current fault is satisfied. This can happen on
multi-processor systems.
Fill zero.
No access.
Copy on Write.
PTE indirect. This ATE indirectly references another physical page. The page that contains the ATE might have two conflicting ATE attributes.
Reserved.

Additional Information
For information about page tables and page directories, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!bcb
The !bcb extension displays the specified buffer control block.
Syntax
!bcb Address
Parameters
Address
Specifies the address of the buffer control block.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 471 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Unavailable (see Comments section)
Comments
This extension is available for Windows 2000 only. In Windows XP or later, use the dt nt!_BCB Address command to display the buffer control block directly.
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, use the !cchelp extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!blockeddrv
The !blockeddrv extension displays the list of blocked drivers on the target computer.
Syntax
!blockeddrv
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll
Comments
Here is an example:
kd> !blockeddrv
Driver:
Status
afd.sys
0:
agp440.sys
0:
atapi.sys
0:
audstub.sys 0:
Beep.SYS
0:
Cdfs.SYS
0:
.....

GUID
{00000008-0206-0001-0000-000030C964E1}
{0000005C-175A-E12D-5000-010020885580}
{0000005C-B04A-E12E-5600-000020885580}
{0000005C-B04A-E12E-5600-000020885580}
{0000005C-B04A-E12E-5600-000020885580}
{00000008-0206-0001-0000-000008F036E1}

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!bpid
The !bpid extension requests that a process on the target computer break into the debugger or requests that a user-mode debugger be attached to a process on the target
computer.
Syntax
!bpid [Options] PID
Parameters
Option
Controls the additional activities of this command.
The valid values for Option appear in the following table.
-a Attaches a new user-mode debugger to the process specified by PID. The user-mode debugger runs on the target machine.
-s Adds a breakpoint that occurs in the WinLogon process immediately before the break in the user-mode process specified by PID. This allows the user to verify the
request before attempting the action.
-w Stores the request in the memory in the target computer. The target system can then repeat the request, but this is not usually necessary.
PID

Introduction

Page 474 of 1651

Debugging Tools for Windows

!ca
The !ca extension displays the control area for the specified section.
Syntax
!ca Address
Parameters
Address
Specifies the hexadecimal address of the section.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
To get a list of the control areas of all mapped files, use the !memusage extension.
Here is an example:
kd> !memusage
loading PFN database
loading (99% complete)
Zeroed:
16 (
64
Free:
0 (
0
Standby:
2642 ( 10568
Modified:
720 ( 2880
ModifiedNoWrite:
0 (
0
Active/Valid: 13005 ( 52020
Transition:
0 (
0
Unknown:
0 (
0
TOTAL: 16383 ( 65532
Building kernel map
Finished building kernel map

kb)
kb)
kb)
kb)
kb)
kb)
kb)
kb)
kb)

Usage Summary (in Kb):

Control Valid Standby Dirty Shared Locked PageTables name
ff8636e8
56
376
0
0
0
0 mapped_file( browseui.dll
ff8cf388
24
0
0
0
0
0 mapped_file( AVH32DLL.DLL
ff8d62c8
12
0
0
0
0
0 mapped_file( PSAPI.DLL )
ff8dd468
156
28
0
0
0
0 mapped_file( INOJOBSV.EXE
fe424808
136
88
0
52
0
0 mapped_file( oleaut32.dll
fe4228a8
152
44
0
116
0
0 mapped_file( MSVCRT.DLL )
ff8ec848
4
0
0
0
0
0
No Name for File
ff859de8
0
32
0
0
0
0 mapped_file( timedate.cpl
. . . . .

)
)
)
)

kd> !ca ff8636e8

ControlArea @ff8636e8
Segment:
e1b74548
Flink
0
Section Ref
0
Pfn Ref
6c
User Ref
1
Subsections
5
File Object ff86df88
ModWriteCount
0
WaitForDel
0
Paged Usage
380
Flags (10000a0) Image File HadUserReference

Blink:
Mapped Views:
Flush Count:
System Views:
NonPaged Usage

0
1
0
0
e0

File: \WINNT\System32\browseui.dll
Segment @ e1b74548:
Base address
0
Image commit
1
Image Base
0
Based Addr
76e10000
Subsection 1. @ ff863720
ControlArea: ff8636e8
Base Pte
e1b74580
Flags
15
ReadOnly CopyOnWrite
Subsection 2. @ ff863740
ControlArea: ff8636e8
Base Pte
e1b74584
Flags
35

Total Ptes
c8
ControlArea ff8636e8
Committed
0
ProtoPtes
e1b74580

NonExtendPtes:
c8
SizeOfSegment: c8000
PTE Template:
31b8438
Image Info:
e1b748a4

Starting Sector 0 Number Of Sectors 2

Ptes In subsect
1 Unused Ptes
Sector Offset
0 Protection

0
1

Starting Sector 2 Number Of Sectors 3d0

Ptes In subsect
7a Unused Ptes
Sector Offset
0 Protection

0
3

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 475 of 1651

ReadOnly CopyOnWrite
Subsection 3. @ ff863760
ControlArea: ff8636e8
Base Pte
e1b7476c
Flags
55
ReadOnly CopyOnWrite

Starting Sector 3D2 Number Of Sectors 7

Ptes In subsect
1 Unused Ptes
Sector Offset
0 Protection

0
5

Subsection 4. @ ff863780
ControlArea: ff8636e8
Base Pte
e1b74770
Flags
15
ReadOnly CopyOnWrite

Starting Sector 3D9 Number Of Sectors 21f

Ptes In subsect
44 Unused Ptes
Sector Offset
0 Protection

0
1

Subsection 5. @ ff8637a0
ControlArea: ff8636e8
Base Pte
e1b74880
Flags
15
ReadOnly CopyOnWrite

Starting Sector 5F8 Number Of Sectors 3a

Ptes In subsect
8 Unused Ptes
Sector Offset
0 Protection

0
1

Additional Information
For information about control areas, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!callback
The !callback extension displays the callback data related to the trap for the specified thread.
Syntax
!callback Address [Number]
Parameters
Address
Specifies the hexadecimal address of the thread. If this is -1 or omitted, the current thread is used.
Number
Specifies the number of the desired callback frame. This frame is noted in the display.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
Comments
If the system has not experienced a system trap, this extension will not produce useful data.
Additional Information
For information about system traps, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!calldata
The !calldata extension displays performance information in the form of procedure call statistics from the named table.
Syntax
!calldata Table
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 476 of 1651

Table
Name of the table that collects the call data.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!can_write_kdump
The !can_write_kdump extension verifies that there is enough disk space on the target computer to write a kernel dump file of the specified type.
Syntax
!can_write_kdump [-dn] [Options]
Parameters
-dn
Specifies that the file system on the target computer is an NTFS file system. If this parameter is omitted, then the amount of disk free space cannot be determined, and a
warning will be shown. However, the amount of space required will still be displayed.
Options
The following options are valid:
-t
Specifies that the extension should determine if there is enough space for a minidump.
-s
Specifies that the extension should determine if there is enough space for a summary kernel dump. This is the default value.
-f
Specifies that the extension should determine if there is enough space for a full kernel dump.
DLL
Windows 2000
Kext.dll
Windows XP and later Kext.dll
Comments
If no Option is specified, then the extension will determine if there is enough space for a summary kernel dump.
In the following example, the file system is not specified:
kd> !can_write_kdump
Checking kernel summary dump...
WARNING: Can't predict how many pages will be used, assuming worst-case.
Physical memory: 285560 KB
Page file size: 1572864 KB
NO: Page file too small

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!cbreg
The !cbreg extension displays CardBus Socket registers and CardBus Exchangable Card Architecture (ExCA) registers.
Syntax
!cbreg [%%]Address
Parameters
%%
Indicates that Address is a physical address rather than a virtual address.
Address
Specifies the address of the register to be displayed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 477 of 1651

DLL
Windows 2000

Kext.dll
Kdextx86.dll
Windows XP and later Kext.dll
The !cbreg extension is only available for an x86-based target computer.
Additional Information
The !exca extension can be used to display PCIC ExCA registers by socket number.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!cchelp
The !cchelp extension displays some brief Help text in the Debugger command window for some of the cache management extensions.
Syntax
!cchelp
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
The !cchelp extension displays help for the !bcb, !defwrites, !finddata, and !scm cache management extensions. Other cache management extensions include !openmaps
and !pcm.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!chklowmem
The !chklowmem extension determines whether physical memory pages below 4 GB are filled with the required fill pattern on a computer that was booted with the /pae
and /nolowmem options.
Syntax
!chklowmem
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This extension is useful when you are verifying that kernel-mode drivers operate properly with physical memory above the 4 GB boundary. Typically, drivers fail by
truncating a physical address to 32 bits and then in writing below the 4 GB boundary. The !chklowmem extension will detect any writes below the 4 GB boundary.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!cmreslist
The !cmreslist extension displays the CM_RESOURCE_LIST structure for the specified device object.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 478 of 1651

Syntax
!cmreslist Address
Parameters
Address
Specifies the hexadecimal address of the CM_RESOURCE_LIST structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about the CM_RESOURCE_LIST structure, see the Windows Driver Kit (WDK)
documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!cpuinfo
The !cpuinfo extension displays detailed information about the target computer's CPU.
Syntax
Syntax in Windows 2000
!cpuinfo
Syntax in Windows XP and later
!cpuinfo [Processor]
Parameters
Processor
(Windows XP and later) Specifies the processor to be displayed. If this is omitted, all processors are displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !cpuinfo extension command can be used when performing local kernel debugging. When this extension is used on a Windows 2000 target computer, it displays
information about all processors.
Here is an example generated by an x86-based processor:
kd> !cpuinfo
CP F/M/S Manufacturer
0 6,1,9 GenuineIntel

MHz Update Signature Features

198 000000d200000000 000000ff

Here is an example generated by an Itanium-based processor:

kd> !cpuinfo
CP M/R/F/A Manufacturer
0 2,1,31,0 GenuineIntel
1 2,1,31,0 GenuineIntel

SerialNumber
Features
Speed
0000000000000000 0000000000000001 1300 Mhz
0000000000000000 0000000000000001 1300 Mhz

The CP column indicates the processor number. The Manufacturer column specifies the processor manufacturer. The MHz or Speed column specifies the speed, in MHz, of
the processor, if it is available.
For an x86-based processor or an x64-based processor, the F column displays the processor family number, the M column displays the processor model number, and the S
column displays the stepping size.
For an Itanium-based processor, the M column displays the processor model number, the R column displays the processor revision number, the F column displays the
processor family number, and the A column displays the architecture revision number.
Other columns will also appear, depending on your machine's specific architecture.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 479 of 1651

For details on how to interpret specific values for each entry, as well as any additional columns, consult the processor manual.
Additional Information
For more information about debugging multiprocessor computers, see Multiprocessor Syntax.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!db, !dc, !dd, !dp, !dq, !du, !dw

The !db, !dc, !dd, !dp, !dq, !du, and !dw extensions display data at the specified physical address on the target computer.
These extension commands should not be confused with the d* (Display Memory) command, or with the !ntsdexts.dp extension command.
Syntax
!db
!dc
!dd
!dp
!dq
!du
!dw

[Caching]
[Caching]
[Caching]
[Caching]
[Caching]
[Caching]
[Caching]

[-m]
[-m]
[-m]
[-m]
[-m]
[-m]
[-m]

[PhysicalAddress]
[PhysicalAddress]
[PhysicalAddress]
[PhysicalAddress]
[PhysicalAddress]
[PhysicalAddress]
[PhysicalAddress]

[L
[L
[L
[L
[L
[L
[L

Size]
Size]
Size]
Size]
Size]
Size]
Size]

Parameters
Caching
Can be any one of the following values. The Caching value must be surrounded by square brackets:
[c]
Causes this extension to read from cached memory.
[uc]
Causes this extension to read from uncached memory.
[wc]
Causes this extension to read from write-combined memory.
-m
Causes memory to be read one unit at a time. For example, !db -m reads memory in 8-bit chunks and !dw -m reads memory in 16-bit chunks. If your hardware does not
support 32-bit physical memory reads, it may be necessary to use the -m option. This option does not affect the length or appearance of the display it only affects how
the memory is accessed.
PhysicalAddress
Specifies the first physical address to be displayed, in hexadecimal format. If this is omitted the first time this command is used, the address defaults to zero. If this is
omitted on a subsequent use, the display will begin where the last display ended.
L Size
Specifies the number of chunks of memory to display. The size of a chunk is determined by the precise extension used.
DLL
Windows 2000

Kext.dll
Kdextx86.dll
Windows XP and later Kext.dll

Comments
These extensions each display physical memory, but their display formats and default length differ:

The !db extension displays hexadecimal bytes and their ASCII character equivalents. The default length is 128 bytes.
The !dc extension displays DWORD values and their ASCII character equivalents. The default length is 32 DWORDs (128 total bytes).
The !dd extension displays DWORD values. The default length is 32 DWORDs (128 total bytes).
The !dp extension displays ULONG_PTR values. These are either 32-bit or 64-bit words, depending on the instruction size. The default length is 128 total bytes.
The !dq extension displays ULONG64_PTR values. These are 32-bit words. The default length is 128 total bytes.
The !du extension displays UNICODE characters. The default length is 16 characters (32 total bytes), or until a NULL character is encountered.
The !dw extension displays WORD values. The default length is 64 DWORDs (128 total bytes).

Consequently, using two of these extensions that are distinct with the same value of Size will most likely result in a difference in the total amount of memory displayed. For
example, using the command !db L 32 results in 32 bytes being displayed (as hexadecimal bytes), whereas the command !dd L 32 results in 128 bytes being displayed (as
DWORD values).
Here is an example in which the caching attribute flag is needed:
kd> !dc e9000
physical memory read at e9000 failed
If you know the caching attributes used for the memory,
try specifying [c], [uc] or [wc], as in !dd [c] <params>.
WARNING: Incorrect use of these flags will cause unpredictable
processor corruption. This may immediately (or at any time in
the future until reboot) result in a system hang, incorrect data
being displayed or other strange crashes and corruption.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 480 of 1651

kd> !dc [c] e9000

#
e9000 000ea002 000ea002 000ea002 000ea002 ................
#
e9010 000ea002 000ea002 000ea002 000ea002 ................
Additional Information
To write to physical memory, use the !e* extensions. For an overview of memory manipulation and a description of other memory-related commands, see Reading and
Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dbgprint
The !dbgprint extension displays a string that was previously sent to the DbgPrint buffer.
Syntax
!dbgprint
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The kernel-mode routines DbgPrint, KdPrint, DbgPrintEx, and KdPrintEx send a formatted string to a buffer on the target computer. The string is automatically displayed
in the Debugger Command window on the host computer unless such printing has been disabled.
Generally, messages sent to this buffer are displayed automatically in the Debugger Command window. However, this display can be disabled through the Global Flags
(gflags.exe) utility. Moreover, this display does not automatically appear during local kernel debugging. For more information, see The DbgPrint Buffer.
The !dbgprint extension causes the contents of this buffer to be displayed (regardless of whether automatic printing has been disabled). It will not show messages that have
been filtered out based on their component and importance level. (For details on this filtering, see Reading and Filtering Debugging Messages.)
Additional Information
For information about DbgPrint, KdPrint, DbgPrintEx, and KdPrintEx, see Sending Output to the Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dblink
The !dblink extension displays a linked list in the backward direction.
Syntax
!dblink Address [Count] [Bias]
Parameters
Address
Specifies the address of a LIST_ENTRY structure. The display will begin with this node.
Count
Specifies the maximum number of list entries to display. If this is omitted, the default is 32.
Bias
Specifies a mask of bits to ignore in each pointer. Each Blink address is ANDed with (NOT Bias) before following it to the next location. The default is zero (in other
words, do not ignore any bits).
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 481 of 1651

The !dblink extension traverses the Blink fields of the LIST_ENTRY structure and displays up to four ULONGs at each address. To go in the other direction, use !dflink.
The dl (Display Linked List) command is more versatile than !dblink and !dflink.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dcr
The !dcr extension displays the default control register (DCR) at the specified address.
Syntax
!dcr Expression [DisplayLevel]
Parameters
Expression
Specifies the hexadecimal address of the DCR to display. The expression @dcr can also be used for this parameter. In that case, information about the current processor
DCR is displayed.
DisplayLevel
Can be any one of the following options:
0
Causes only the values of each DCR field to be displayed. This is the default value.
1
Causes the display to include more in-depth information about each of the DCR fields that is not reserved or ignored.
2
Causes the display to include more in-depth information about all of the DCR fields, including those that are ignored or reserved.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium-based target computer.
Comments
The DCR specifies default parameters for the processor status register values on interruption. The DCR also specifies some additional global controls, as well as whether or
not speculative load faults can be deferred.
Here are a couple of examples:
kd> !dcr @dcr
dcr:pp be lc dm dp dk dx dr da dd
1 0 1 1 1 1 1 1 1 1
kd> !dcr @dcr 2
pp
be
lc
rv
dm
dp
dk
dx
dr
da
dd
rv

:
:
:
:
:
:
:
:
:
:
:
:

1
0
1
0
1
1
1
1
1
1
0
0

:
:
:
:
:
:
:
:
:
:
:
:

Privileged Performance Monitor Default

Big-Endian Default
IA-32 Lock check Enable
reserved1
Defer TLB Miss faults only
Defer Page Not Present faults only
Defer Key Miss faults only
Defer Key Permission faults only
Defer Access Rights faults only
Defer Access Bit faults only
Defer Debug faults only
reserved2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dcs
The !dcs extension is obsolete. To display the PCI configuration space, use !pci 100 Bus Device Function.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 482 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!deadlock
The !deadlock extension displays information about deadlocks collected by the Deadlock Detection option of Driver Verifier.
Syntax
!deadlock
!deadlock 1
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
This extension will only provide useful information if Driver Verifier's Deadlock Detection option has detected a lock hierarchy violation and issued bug check 0xC4
(DRIVER_VERIFIER_DETECTED_VIOLATION).
Without any arguments, the !deadlock extension causes the basic lock hierarchy topology to be displayed. If the problem is not a simple cyclical deadlock, this command will
describe the situation that has occurred.
The !deadlock 1 extension causes stack traces to be displayed. The stacks displayed will be the ones active at the time the locks were acquired.
Here is an example:
0:kd> !deadlock
Deadlock detected (2 resources in 2 threads):
Thread 0: A B
Thread 1: B A
Where:
Thread
Thread
Lock A
Lock B

0 = 8d3ba030
1 = 8d15c030
=
bba2af30 Type 'Spinlock'
=
dummy!GlobalLock Type 'Spinlock'

This tells you which threads and which locks are involved. However, it is intended to be a summary and may not be enough information to adequately debug the situation.
Use !deadlock 1 to print out the contents of the call stacks at the time that each lock participating in the deadlock was acquired. Because these are run-time stack traces, they
will be more complete if a checked build is being used. On a free build, they may be truncated after as little as one line.
0:kd> !deadlock 1
Deadlock detected (2 resources in 2 threads):
Thread 0 (8D14F750) took locks in the following order:
Lock A -- b7906f30 (Spinlock)
Stack:
dummy!DummyActivateVcComplete+0x63
dummy!dummyOpenVcChannels+0x2E1
dummy!DummyAllocateRecvBufferComplete+0x436
dummy!DummyAllocateComplete+0x55
NDIS!ndisMQueuedAllocateSharedHandler+0xC9
NDIS!ndisWorkerThread+0xEE
Lock B -- dummy!GlobalLock (Spinlock)
Stack:
dummy!dummyQueueRecvBuffers+0x2D
dummy!DummyActivateVcComplete+0x90
dummy!dummyOpenVcChannels+0x2E1
dummy!DummyAllocateRecvBufferComplete+0x436
dummy!DummyAllocateComplete+0x55
Thread 1 (8D903030) took locks in the following order:
Lock B -- dummy!GlobalLock (Spinlock)
Stack:
dummy!dummyRxInterruptOnCompletion+0x25D
dummy!DummyHandleInterrupt+0x32F
NDIS!ndisMDpcX+0x3C
ntkrnlpa!KiRetireDpcList+0x5D
Lock A -- b7906f30 (Spinlock)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Stack:

Page 483 of 1651

<< Current stack >>

With this information, you have almost everything you need, except the current stack:
0: kd> k
ChildEBP
f78aae6c
f78aae74
f78aae9c
f78aaee8
f78aaf08
f78aafa4
f78aafc4
f78aafd8
f78aaff4

RetAddr
80664c58
8066523f
806665df
8065d944
bfd6df46
b1bf2d2d
bfde9d8c
804b393b
804b922b

ntkrnlpa!DbgBreakPoint
ntkrnlpa!ViDeadlockReportIssue+0x2f
ntkrnlpa!ViDeadlockAnalyze+0x253
ntkrnlpa!VfDeadlockAcquireResource+0x20b
ntkrnlpa!VerifierKeAcquireSpinLockAtDpcLevel+0x44
dummy!dummyRxInterruptOnCompletion+0x2b5
dummy!DummyHandleInterrupt+0x32f
NDIS!ndisMDpcX+0x3c
ntkrnlpa!KiRetireDpcList+0x5d

From this you can see which locks were involved and where they were acquired. This should be enough information for you to debug the deadlock. If the source code is
available, you can use the debugger to see exactly where the problem occurred:
0: kd> .lines
Line number information will be loaded
0: kd> u dummy!DummyActivateVcComplete+0x63 l1
dummy!DummyActivateVcComplete+63 [d:\nt\drivers\dummy\vc.c @ 2711]:
b1bfe6c9 837d0c00
cmp
dword ptr [ebp+0xc],0x0
0: kd> u dummy!dummyQueueRecvBuffers+0x2D l1
dummy!dummyQueueRecvBuffers+2d [d:\nt\drivers\dummy\receive.c @ 2894]:
b1bf4e39 807d0c01
cmp
byte ptr [ebp+0xc],0x1
0: kd> u dummy!dummyRxInterruptOnCompletion+0x25D l1
dummy!dummyRxInterruptOnCompletion+25d [d:\nt\drivers\dummy\receive.c @ 1424]:
b1bf5d05 85f6
test
esi,esi
0: kd> u dummy!dummyRxInterruptOnCompletion+0x2b5 l1
dummy!dummyRxInterruptOnCompletion+2b5 [d:\nt\drivers\dummy\receive.c @ 1441]:
b1bf5d5d 8b4648
mov
eax,[esi+0x48]
Now you know the name of the source file and the line number where the acquisition took place. In this case, the source files will show that the threads behaved as follows:

Thread 1: DummyActivateVcComplete took the dummy miniport lock. It then called dummyQueueRecvBuffers, which took the dummy global lock.
Thread 2: dummyRxInterruptOnCompletion took the global lock. Then, a few lines later, it took the miniport lock.

At this point, the deadlock becomes entirely clear.

Additional Information
For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!defwrites
The !defwrites extension displays the values of the kernel variables used by the cache manager.
Syntax
!defwrites
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
When the number of deferred writes ("dirty pages") becomes too large, page writing will be throttled. This extension allows you to see whether your system has reached this
point.
Here is an example:
kd> !defwrites
*** Cache Write Throttle Analysis ***
CcTotalDirtyPages:

0 (

0 Kb)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 484 of 1651

CcDirtyPageThreshold:
MmAvailablePages:
MmThrottleTop:
MmThrottleBottom:
MmModifiedPageListHead.Total:

1538
2598
250
30
699

(
(
(
(
(

6152
10392
1000
120
2796

Kb)
Kb)
Kb)
Kb)
Kb)

Write throttles not engaged

In this case, there are no dirty pages. If CcTotalDirtyPages reaches 1538 (the value of CcDirtyPageThreshold), writing will be delayed until the number of dirty pages is
reduced.
Additional Information
For information about write throttling, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, use the !cchelp extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!devext
The !devext extension displays bus-specific device extension information for devices on a variety of buses.
Syntax
!devext Address TypeCode
Parameters
Address
Specifies the hexadecimal address of the device extension to be displayed.
TypeCode
Specifies the type of object that owns the device extension to be displayed. Type codes are not case-sensitive. Valid type codes are:
TypeCode
Object
PCI
(Windows 2000 only) PCI device extension
ISAPNP ISA PnP device extension
PCMCIA PCMCIA device extension
HID
HID device extension
USBD
(Windows 2000 only) USB bus driver extension
UHCD
(Windows 2000 only) UHCD host controller extension
OpenHCI (Windows 2000 only) Open HCI host controller extension
USBHUB (Windows 2000 only) USB hub extension
MF
(Windows 2000 only) MF device extension
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !usbhub, !hidfdo, and !hidpdo extensions are obsolete; their functionality has been integrated into !devext.
For those object types that are no longer supported by !devext, use the dt (Display Type) debugger command.
Here is an example for an ISA PnP device extension:
kd> !devext e0000165fff32190 ISAPNP
ISA PnP FDO @ 0x00000000, DevExt @ 0xe0000165fff32190, Bus # 196639
Flags (0x854e2530) DF_ACTIVATED, DF_QUERY_STOPPED,
DF_STOPPED, DF_RESTARTED_NOMOVE,
DF_BUS
Unknown flags 0x054e2000
NumberCSNs
ReadDataPort
AddressPort
CommandPort
DeviceList
CardList
PhysicalBusDevice
AttachedDevice
SystemPowerState

-536870912
0x0000000d (mapped)
0x00000000 (not mapped)
0x00000000 (not mapped)
0xe000000085007b50
0x00000000
0x00000000
0x00000000
Unspecified

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

DevicePowerState

Page 485 of 1651

- Unspecified

Here is an example for a PCI device:

kd> !devext e0000000858c31b0 PCI
PDO Extension, Bus 0x0, Device 0, Function 0.
DevObj 0xe0000000858c3060 PCI Parent Bus FDO DevExt 0xe0000000858c4960
Device State = PciNotStarted
Vendor ID 8086 (INTEL) Device ID 123D
Class Base/Sub 08/00 (Base System Device/Interrupt Controller)
Programming Interface: 20, Revision: 01, IntPin: 00, Line Raw/Adj 00/00
Enables ((cmd & 7) = 106): BM
Capabilities Pointer = <none>
CurrentState:
System Working, Device D0
WakeLevel:
System Unspecified, Device Unspecified
Requirements: <none>
Additional Information
See Plug and Play Debugging for applications of this extension command. For more information about device extensions, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!devhandles
The !devhandles extension displays the open handles for the specified device.
Syntax
!devhandles Address
Parameters
Address
Specifies the address of the device for which to display the open handles.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
To display complete handle information, this extension requires private symbols.
The address of a device object can be obtained using the !drvobj or !devnode extensions.
Here is a truncated example:
lkd> !devhandles 0x841153d8
Checking handle table for process 0x840d3940
Handle table at 95fea000 with 578 Entries in use
Checking handle table for process 0x86951d90
Handle table at 8a8ef000 with 28 Entries in use
...
Checking handle table for process 0x87e63650
Handle table at 947bc000 with 308 Entries in use
Checking handle table for process 0x87e6f4f0
00000000: Unable to read handle table

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!devnode

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 486 of 1651

The !devnode extension displays information about a node in the device tree.
Syntax
!devnode Address [Flags] [Service]
!devnode 1
!devnode 2
Parameters
Address
Specifies the hexadecimal address of the device extension whose node is to be displayed. If this is zero, the root of the main device tree is displayed.
Flags
Specifies the level of output to be displayed. This can be any combination of the following bits:
Bit 0 (0x1)
Causes the display to include all children of the device node.
Bit 1 (0x2)
Causes the display to include resources used (CM_RESOURCE_LIST). These include the boot configuration reported by IRP_MN_QUERY_RESOURCES, as well
as the resources allocated to the device in the AllocatedResources parameter of IRP_MN_START_DEVICE.
Bit 2 (0x4)
Causes the display to include resources required (IO_RESOURCE_REQUIREMENTS_LIST) as reported by IRP_MN_FILTER_RESOURCE_REQUIREMENTS.
Bit 3 (0x8)
Causes the display to include a list of translated resources as allocated to the device in the AllocatedResourcesTranslated parameter of
IRP_MN_START_DEVICE.
Bit 4 (0x10)
Specifies that only device nodes that are not started should be displayed.
Bit 5 (0x20)
Specifies that only device nodes with problems should be displayed. (These are nodes that contain the flag bits DNF_HAS_PROBLEM or
DNF_HAS_PRIVATE_PROBLEM.)
Service
Specifies the name of a service. If this is included, only those device nodes driven by this service will be displayed. (If Flags includes bit 0x1, device nodes driven by this
service and all their children will be displayed.)
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !devnode 1 command lists all pending removals of device objects.
The !devnode 2 command lists all pending ejects of device objects.
You can use !devnode 0 1 to see the entire device tree.
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about device trees, see the Windows Driver Kit (WDK) documentation and
Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!devobj
The !devobj extension displays detailed information about a DEVICE_OBJECT structure.
Syntax
!devobj DeviceObject
Parameters
DeviceObject
Specifies the device object. This can be the hexadecimal address of this structure or the name of the device.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
If DeviceObject specifies the name of the device but supplies no prefix, the prefix \Device\ is assumed. Note that this command will check to see if DeviceObject is a valid
address or device name before using the expression evaluator.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 487 of 1651

The information displayed includes the device name of the object, information about the device's current IRP, and a list of addresses of any pending IRPs in the device's
queue. It also includes information about device objects layered on top of this object (listed as "AttachedDevice") and those layered under this object (listed as "AttachedTo").
The address of a device object can be obtained using the !drvobj or !devnode extensions.
Here is one example:
kd> !devnode
Dumping IopRootDeviceNode (= 0x80e203b8)
DevNode 0x80e203b8 for PDO 0x80e204f8
Parent 0000000000
Sibling 0000000000
Child 0x80e56dc8
InstancePath is "HTREE\ROOT\0"
State = DeviceNodeStarted (0x308)
Previous State = DeviceNodeEnumerateCompletion (0x30d)
StateHistory[04] = DeviceNodeEnumerateCompletion (0x30d)
StateHistory[03] = DeviceNodeStarted (0x308)
StateHistory[02] = DeviceNodeEnumerateCompletion (0x30d)
StateHistory[01] = DeviceNodeStarted (0x308)
StateHistory[00] = DeviceNodeUninitialized (0x301)
StateHistory[19] = Unknown State (0x0)
.....
StateHistory[05] = Unknown State (0x0)
Flags (0x00000131) DNF_MADEUP, DNF_ENUMERATED,
DNF_IDS_QUERIED, DNF_NO_RESOURCE_REQUIRED
DisableableDepends = 11 (from children)
kd> !devobj 80e204f8
Device object (80e204f8) is for:
\Driver\PnpManager DriverObject 80e20610
Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001000
DevExt 80e205b0 DevObjExt 80e205b8 DevNode 80e203b8
ExtensionFlags (0000000000)
Device queue is not busy.
Additional Information
See Plug and Play Debugging for examples and applications of this extension command. For information about device objects, see the Windows Driver Kit (WDK)
documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!devstack
The !devstack extension displays a formatted view of the device stack associated with a device object.
Syntax
!devstack DeviceObject
Parameters
DeviceObject
Specifies the device object. This can be the hexadecimal address of the DEVICE_OBJECT structure or the name of the device.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
If DeviceObject specifies the name of the device but supplies no prefix, the prefix \Device\ is assumed. Note that this command will check to see if DeviceObject is a valid
address or device name before using the expression evaluator.
Here is an example:
kd> !devstack e000000085007b50
!DevObj
!DrvObj
!DevExt
ObjectName
e0000165fff32040 \Driver\kmixer
e0000165fff32190
> e000000085007b50 \Driver\swenum
e000000085007ca0 KSENUM#00000005
!DevNode e0000165fff2e010 :
DeviceInst is "SW\{b7eafdc0-a680-11d0-96d8-00aa0051e51d}\{9B365890-165F-11D0-A195-0020AFD156E4}"
ServiceName is "kmixer"
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 488 of 1651

For information about device stacks, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dflink
The !dflink extension displays a linked list in the forward direction.
Syntax
!dflink Address [Count] [Bias]
Parameters
Address
Specifies the address of a LIST_ENTRY structure. The display will begin with this node.
Count
Specifies the maximum number of list entries to display. If this is omitted, the default is 32.
Bias
Specifies a mask of bits to ignore in each pointer. Each Flink address is ANDed with (NOT Bias) before following it to the next location. The default is zero (in other
words, do not ignore any bits).
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !dflink extension traverses the Flink fields of the LIST_ENTRY structure and displays up to four ULONGs at each address. To go in the other direction, use !dblink.
The dl (Display Linked List) command is more versatile than !dblink and !dflink.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!diskspace
The !diskspace extension displays the amount of free space on a hard disk of the target computer.
Syntax
!diskspace Drive[:]
Parameters
Drive
Specifies the drive letter of the disk. The colon (:) after Drive is optional.
DLL
Windows 2000
Kext.dll
Windows XP and later Kext.dll
Comments
Here is an example:
kd> !diskspace c:
Checking Free Space for c: ..........
Cluster Size 0 KB
Total Clusters 4192901 KB
Free Clusters 1350795 KB
Total Space 1 GB (2096450 KB)
Free Space 659.567871 MB (675397 KB)
kd> !diskspace f:
Checking Free Space for f:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 489 of 1651

f: is a CDROM drive. This function is not supported!

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dma
The !dma extension displays information about the Direct Memory Access (DMA) subsystem, and the DMA Verifier option of Driver Verifier.
Syntax
!dma
!dma Adapter [Flags]
Parameters
Adapter
Specifies the hexadecimal address of the DMA adapter to be displayed. If this is zero, all DMA adapters will be displayed.
Flags
Specifies the information to include in the display. This can be any combination of the following bits. The default is 0x1.
Bit 0 (0x1)
Causes the display to include generic adapter information.
Bit 1 (0x2)
Causes the display to include map register information. (Only when DMA Verification is active.)
Bit 2 (0x4)
Causes the display to include common buffer information. (Only when DMA Verification is active.)
Bit 3 (0x8)
Causes the display to include scatter/gather list information. (Only when DMA Verification is active.)
Bit 4 (0x10)
Causes the display to include the device description for the hardware device. (Only when DMA Verification is active.)
Bit 5 (0x20)
Causes the display to include Wait context block information.
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll
Comments
Invalid arguments (for example, !dma 1) generate a brief help text.
When the !dma extension is used with no parameters, it displays a concise list of all DMA adapters and their addresses. This can be used to obtain the address of an adapter
for use in the longer versions of this command.
Here is an example of how this extension can be used when the Driver Verifier's DMA Verification option is active:
0:kd> !dma
Dumping all DMA adapters...
Adapter: 82faebd0
Owner: SCSIPORT!ScsiPortGetUncachedExtension
Adapter: 82f88930
Owner: SCSIPORT!ScsiPortGetUncachedExtension
Adapter: 82f06cd0
Owner: NDIS!NdisMAllocateMapRegisters
Master adapter: 80076800
From this output, you can see that there are three DMA adapters in the system. SCSIPORT owns two and NDIS owns the third. To examine the NDIS adapter in detail, use
the !dma extension with its address:
0:kd> !dma 82f06cd0
Adapter: 82f06cd0
Owner: NDIS!NdisMAllocateMapRegisters (0x9fe24351)
MasterAdapter:
00000000
Adapter base Va
00000000
Map register base:
00000000
WCB:
82f2b604
Map registers: 00000000 mapped, 00000000 allocated, 00000002 max
Dma verifier additional information:
DeviceObject: 82f98690
Map registers:
00000840 allocated,
Scatter-gather lists: 00000000 allocated,
Common buffers:
00000004 allocated,
Adapter channels:
00000420 allocated,
Bytes mapped since last flush: 000000f2

00000000
00000000
00000000
00000420

freed
freed
freed
freed

The first block of data is specific information that a HAL developer can use to debug the problem. For your purposes, the data below "Dma verifier additional information" is

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 490 of 1651

what is interesting. In this example, you see that NDIS has allocated 0x840 map registers. This is a huge number, especially because NDIS had indicated that it planned to use
a maximum of two map registers. This adapter apparently does not use scatter/gather lists and has put away all its adapter channels. Look at the map registers in more detail:
0:kd> !dma 82f06cd0 2
Adapter: 82f06cd0
Owner: NDIS!NdisMAllocateMapRegisters
...
Map register file 82f06c58 (0/2 mapped)
Double buffer mdl: 82f2c188
Map registers:
82f06c80: Not mapped
82f06c8c: Not mapped
Map register file 82f06228 (1/2 mapped)
Double buffer mdl: 82f1b678
Map registers:
82f06250: 00bc bytes mapped to f83c003c
82f0625c: Not mapped
Map register file 82fa5ad8 (1/2 mapped)
Double buffer mdl: 82f1b048
Map registers:
82fa5b00: 0036 bytes mapped to 82d17102
82fa5b0c: Not mapped
...
In this example, you see that certain map registers have been mapped. Each map register file is an allocation of map registers by the driver. In other words, it represents a
single call to AllocateAdapterChannel. NDIS collects a large number of these map register files, while some drivers create them one at a time and dispose of them when
they are finished.
The map register files are also the addresses that are returned to the device under the name "MapRegisterBase". Note that DMA verifier only hooks the first 64 map registers
for each driver. The rest are ignored for reasons of space (each map register represents three physical pages).
In this example, two map register files are in use. This means that the driver has mapped a buffer so it is visible to the hardware. In the first case, 0xBC bytes are mapped to
the system virtual address 0xF83C003C.
An examination of the common buffers reveals:
0:kd> !dma 82f06cd0 4
Adapter: 82f06cd0
Owner: NDIS!NdisMAllocateMapRegisters
...
Common buffer allocated by NDIS!NdisMAllocateSharedMemory:
Length:
1000
Virtual address: 82e77000
Physical address: 2a77000
Common buffer allocated by NDIS!NdisMAllocateSharedMemory:
Length:
12010
Virtual address: 82e817f8
Physical address: 2a817f8
Common buffer allocated by NDIS!NdisMAllocateSharedMemory:
Length:
4300
Virtual address: 82e95680
Physical address: 2a95680
Common buffer allocated by NDIS!NdisMAllocateSharedMemory:
Length:
4800
Virtual address: 82e9d400
Physical address: 2a9d400
This is fairly straightforward; there are four common buffers of varying lengths. The physical and virtual addresses are all given.
Additional Information
For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation. For information about DMA, see the Windows Driver Kit (WDK) documentation
and Microsoft Windows Internals by Mark Russinovich David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dpa
The !dpa extension displays pool allocation information.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 491 of 1651

!dpa Options
!dpa -?
Parameters
Options
Must be exactly one of the following options:
-c
Displays current pool allocation statistics.
-v
Displays all current pool allocations.
-vs
Causes the display to include stack traces.
-f
Displays failed pool allocations.
-r
Displays free pool allocations.
-p Ptr
Displays all pool allocations that contain the pointer Ptr.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
Pool instrumentation must be enabled in Win32k.sys in order for this extension to work.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dpcs
The !dpcs extension displays the deferred procedure call (DPC) queues for a specified processor.
Syntax
!dpcs [Processor]
Parameters
Processor
Specifies a processor. If Processor is omitted, then the DPC queues for all processors are displayed.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Additional Information
For information about DPCs, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!driveinfo
The !driveinfo extension displays volume information for the specified drive.
Syntax
!driveinfo Drive[:]
!driveinfo
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 492 of 1651

Drive
Specifies a drive. The colon at the end of the drive name is optional.
No parameters
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
The drive information displayed by this extension is obtained by querying the underlying file system; for example:
kd> !driveinfo c:
Drive c:, DriveObject e136cd88
Directory Object: e1001408 Name: C:
Target String is '\Device\HarddiskVolume1'
Drive Letter Index is 3 (C:)
Volume DevObj: 82254a68
Vpb: 822549e0 DeviceObject: 82270718
FileSystem: \FileSystem\Ntfs
Volume has 0x229236 (free) / 0x2ee1a7 (total) clusters of size 0x1000
8850.21 of 12001.7 MB free

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!drivers
In operating systems prior to Windows XP, the !drivers extension displays a list of all drivers loaded on the target computer, along with summary information about their
memory use.
In Windows XP and later versions of Windows, the !drivers extension is obsolete. To display information about loaded drivers and other modules, use the lm command. The
command lm t n displays information in a format very similar to the old !drivers extension. However, this command will not display the memory usage of the drivers as the !
drivers extension did. It will only display the drivers' start and end addresses, image names, and timestamps. The !vm and !memusage extensions can be used to display
memory usage statistics.
Syntax
!drivers [Flags]
Parameters
Flags
Can be any combination of the following values. (The default is 0x0.)
Bit 0 (0x1)
Causes the display to include information about resident and standby memory.
Bit 1 (0x2)
If this bit is set and bit 2 (0x4) is not set, the display will include information about resident, standby, and locked memory, as well as the loader entry address. If bit 2
is set, this causes the display to be a much longer and more detailed list of the driver image. Information about the headers is included, as is section information.
Bit 2 (0x4)
Causes the display to be a much longer and more detailed list of the driver image. Information about each section is included. If bit 1 (0x2) is set, this will also
include header information.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable
Comments
An explanation of this command's display is given in the following table:
Column
Meaning
Base
The starting address of the device driver code, in hexadecimal. When the memory address used by the code that causes a stop falls between the base address for a
driver and the base address for the next driver in the list, that driver is frequently the cause of the fault. For instance, the base for Ncrc810.sys is 0x80654000. Any
address between that and 0x8065a000 belongs to this driver.
Code Size The size, in kilobytes, of the driver code, in both hexadecimal and decimal.
Data Size The amount of space, in kilobytes, allocated to the driver for data, in both hexadecimal and decimal.
Locked
(Only when Flag 0x2 is used) The amount of memory locked by the driver.
Resident (Only when Flag 0x1 or 0x2 is used) The amount of the driver's memory that actually resides in physical memory.
Standby (Only when Flag 0x1 or 0x2 is used) The amount of the driver's memory that is on standby.
Loader
(Only when Flag 0x2 is used) The loader entry address.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Entry
Driver
Name
Creation
Time

Page 493 of 1651

The driver file name.

The link date of the driver. Do not confuse this with the file date of the driver, which can be set by external tools. The link date is set by the compiler when a
driver or executable file is compiled. It should be close to the file date, but it is not always the same.

The following is a truncated example of this command:

kd> !drivers
Loaded System Driver Summary
Base
Code Size
Data Size
80080000 f76c0 (989 kb) 1f100 (124
80400000 d980 ( 54 kb) 4040 ( 16
80654000 3f00 ( 15 kb) 1060
( 4
8065a000 a460 ( 41 kb) 1e80
( 7

kb)
kb)
kb)
kb)

Driver Name
ntoskrnl.exe
hal.dll
ncrc810.sys
SCSIPORT.SYS

Creation Time
Fri May 26 15:13:00
Tue May 16 16:50:34
Fri May 05 20:07:04
Fri May 05 20:08:05

Additional Information
See Plug and Play Debugging for applications of this extension command. For information about drivers and their memory use, see the Windows Driver Kit (WDK)
documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!drvobj
The !drvobj extension displays detailed information about a DRIVER_OBJECT.
Syntax
!drvobj DriverObject [Flags]
Parameters
DriverObject
Specifies the driver object. This can be the hexadecimal address of the DRIVER_OBJECT structure or the name of the driver.
Flags
Can be any combination of the following bits. (The default is 0x01.)
Bit 0 (0x1)
Causes the display to include device objects owned by the driver.
Bit 1 (0x2)
Causes the display to include entry points for the driver's dispatch routines.
Bit 2 (0x4)
Lists with detailed information the device objects owned by the driver (requires bit 0 (0x1)).
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
If DriverObject specifies the name of the device but supplies no prefix, the prefix \Driver\ is assumed. Note that this command will check to see if DriverObject is a valid
address or device name before using the expression evaluator.
If DriverObject is an address, it must be the address of the DRIVER_OBJECT structure. This can be obtained by examining the arguments passed to the driver's DriverEntry
routine.
This extension command will display a list of all device objects created by a specified driver. It will also display all fast I/O routines registered with this driver object.
The following is an example for the Symbios Logic 810 SCSI miniport driver:
kd> bp DriverEntry
kd> g
symc810!DriverEntry+0x40:
80006a20: b07e0050 stl
kd> r a0
a0=809d5550

breakpoint at DriverEntry

t2,50(sp)

//address of DevObj (the first parameter)

kd> !drvobj 809d5550

Driver object is for:
\Driver\symc810
Device Object list:

display the driver object

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 494 of 1651

809d50d0
You can also use !devobj 809d50d0 to get information about the device object.
Additional Information
See Plug and Play Debugging for examples and applications of this extension command. For information about driver objects, see the Windows Driver Kit (WDK)
documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dskheap
The !dskheap extension displays desktop heap information for a specified session.
Syntax
!dskheap [-v] [-s SessionID]
Parameters
-v
Causes the display to include more detailed output.
-s SessionID
Specifies a session. If this parameter is omitted, then the desktop heap information for session 0 is displayed.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
The desktop heap information for the session is arranged by window station.
Here are a couple of examples:
kd> !dskheap -s 3
Winstation\Desktop
Heap Size(KB)
Used Rate(%)
-----------------------------------------------------------WinSta0\Screen-saver
3072
0%
WinSta0\Default
3072
0%
WinSta0\Disconnect
64
4%
WinSta0\Winlogon
128
5%
-----------------------------------------------------Total Desktop: (
6336 KB 4 desktops)
Session ID: 3
============================================================
kd> !dskheap
Winstation\Desktop
Heap Size(KB)
Used Rate(%)
-----------------------------------------------------------WinSta0\Default
3072
0%
WinSta0\Disconnect
64
4%
WinSta0\Winlogon
128
9%
Service-0x0-3e7$\Default
512
4%
Service-0x0-3e5$\Default
512
0%
Service-0x0-3e4$\Default
512
1%
SAWinSta\SADesktop
512
0%
-----------------------------------------------------Total Desktop: (
5312 KB 7 desktops)
Session ID: 0
============================================================
Additional Information
For information about desktops or desktop heaps, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David
Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 495 of 1651

!eb, !ed
The !eb and !ed extensions write a sequence of values into a specified physical address.
These extension commands should not be confused with the e* (Enter Values) command.
Syntax
!eb [Flag] PhysicalAddress Data [ ... ]
!ed [Flag] PhysicalAddress Data [ ... ]
Parameters
Flag
Can be any one of the following values. The Flag value must be surrounded by square brackets:
[c]
Writes to cached memory.
[uc]
Writes to uncached memory.
[wc]
Writes to write-combined memory.
PhysicalAddress
Specifies the first physical address on the target computer to which the data will be written, in hexadecimal.
Data
Specifies one or more values to be written sequentially into physical memory. Enter these values in hexadecimal format. For the !eb extension, each value must be 1 byte
(two hexadecimal digits). For the !ed extension, each value must be one DWORD (eight hexadecimal digits). You can include any number of Data values on one line. To
separate multiple values, use commas or spaces.
DLL
Windows 2000

Kext.dll
Kdextx86.dll
Windows XP and later Kext.dll
Additional Information
To read physical memory, use the !d* extensions. For an overview of memory manipulation and a description of other memory-related commands, see Reading and Writing
Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ecb, !ecd, !ecw

The !ecb, !ecd, and !ecw extensions write to the the PCI configuration space.
Syntax
!ec Bus.Device.Function Offset Data
Parameters
Bus
Specifies the bus. Bus can range from 0 to 0xFF.
Device
Specifies the slot device number for the device.
Function
Specifies the slot function number for the device.
Offset
Specifies the address at which to write.
Data
Specifies the value to be written. For the !ecb extension, Data must be 1 byte (two hexadecimal digits). For the !ecw extension, Data must be one WORD (four
hexadecimal digits). For the !ecd extension, Data must be one DWORD (eight hexadecimal digits).
DLL
Windows 2000
Kext.dll
Windows XP and later Kext.dll
These extension commands can only be used with an x86-based target computer.
Comments
You cannot use these extension commands to write a sequence of Data values. This can only be done by repeated use of this extension.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 496 of 1651

To display the PCI configuration space, use !pci 100 Bus Device Function.
Additional Information
See Plug and Play Debugging for applications of this extension command, and some additional examples. For information about PCI buses, see the Windows Driver Kit
(WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ecs
The !ecs extension is obsolete. To edit the PCI configuration space, use !ecb, !ecd, or !ecw.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!errlog
The !errlog extension displays the contents of any pending entries in the I/O system's error log.
Syntax
!errlog
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This command displays information about any pending events in the I/O system's error log. These are events queued by calls to the IoWriteErrorLogEntry function, to be
written to the system's event log for subsequent viewing by the Event Viewer.
Only entries that were queued by IoWriteErrorLogEntry but have not been committed to the error log will be displayed.
This command can be used as a diagnostic aid after a system crash because it reveals pending error information that was unable to be committed to the error log before the
system halted.
Additional Information
For information about IoWriteErrorLogEntry, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!errpkt
The !errpkt extension displays the contents of a Windows Hardware Error Architecture (WHEA) hardware error packet.
Syntax
!errpkt Address
Parameters
Address
Specifies the address of the hardware error packet.
DLL
Windows 2000

Unavailable

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 497 of 1651

Windows XP
Unavailable
Windows Server 2003
Unavailable
Windows Vista and later Kdexts.dll
This extension can be used only in Windows Vista and later versions of Windows.
Comments
The following example shows the output of the !errpkt extension:
3: kd> !errpkt fffffa8007cf44da
WHEA Error Packet Info Section (@ fffffa8007cf44da)
Flags
: 0x00000000
Size
: 0x218
RawDataLength
: 0x392
Context
: 0x0000000000000000
ErrorType
: 0x0 - Processor
ErrorSeverity
: 0x1 - Fatal
ErrorSourceId
: 0x0
ErrorSourceType : 0x0 - MCE
Version
: 00000002
Cpu
: 0000000000000002
RawDataFormat
: 0x2 - Intel64 MCA
Raw Data

: Located @ FFFFFA8007CF45F2

Processor Error: (Internal processor error)

This error means either the processor is damaged or perhaps
voltage and/or temperature thresholds have been exceeded.
If the problem continues to occur, replace the processor.
Processor Number : 2
Bank Number
: 0
Status :
0
Address : 0000000000000000 (I)
Misc
: 0000000000000000 (I)
Additional Information
The !whea and !errrec extensions can be used to display additional WHEA information. For general information about WHEA, see
(WHEA) in the Windows Driver Kit (WDK) documentation.

Windows Hardware Error Architecture

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!errrec
The !errrec extension displays the contents of a Windows Hardware Error Architecture (WHEA) error record.
Syntax
!errrec Address
Parameters
Address
Specifies the address of the error record.
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Server 2003
Unavailable
Windows Vista and later Kdexts.dll
This extension can be used only in Windows Vista and later versions of Windows.
Comments
The following example shows how the !whea extension can be used to obtain the address of an error record, and then the contents of this record can be displayed by the !
errrec extension:
3: kd> !whea
Error Source Table @ fffff800019ca250
13 Error Sources
Error Source 0 @ fffffa80064132c0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Notify Type
Type
Error Count
Record Count
Record Length
Error Records

Page 498 of 1651

:
:
:
:
:
:

Machine Check Exception

0x0 (MCE)
8
10
c3e
wrapper @ fffffa8007cf4000

record @ fffffa8007cf4030

. . . .
3: kd> !errrec fffffa8007cf4030
===============================================================================
Common Platform Error Record @ fffffa8007cf4030
------------------------------------------------------------------------------Revision
: 2.1
Record Id
: 01c9c7ff04e0ff7d
Severity
: Fatal (1)
Length
: 1730
Creator
: Microsoft
Notify Type
: Machine Check Exception
Timestamp
: 4/28/2009 12:54:47
Flags
: 0x00000000
===============================================================================
Section 0
: Processor Generic
------------------------------------------------------------------------------Descriptor
@ fffffa8007cf40b0
Section
@ fffffa8007cf4188
Offset
: 344
Length
: 192
Flags
: 0x00000001 Primary
Severity
: Fatal
No valid data fields are present.
===============================================================================
Section 1
: {390f56d5-ca86-4649-95c4-73a408ae5834}
------------------------------------------------------------------------------Descriptor
@ fffffa8007cf40f8
Section
@ fffffa8007cf4248
Offset
: 536
Length
: 658
Flags
: 0x00000000
Severity
: Fatal
*** Unknown section format ***
===============================================================================
Section 2
: Error Packet
------------------------------------------------------------------------------Descriptor
@ fffffa8007cf4140
Section
@ fffffa8007cf44da
Offset
: 1194
Length
: 536
Flags
: 0x00000000
Severity
: Fatal
WHEA Error Packet Info Section (@ fffffa8007cf44da)
Flags
: 0x00000000
Size
: 0x218
RawDataLength
: 0x392
Context
: 0x0000000000000000
ErrorType
: 0x0 - Processor
ErrorSeverity
: 0x1 - Fatal
ErrorSourceId
: 0x0
ErrorSourceType : 0x0 - MCE
Version
: 00000002
Cpu
: 0000000000000002
RawDataFormat
: 0x2 - Intel64 MCA
Raw Data

: Located @ FFFFFA8007CF45F2

Processor Error: (Internal processor error)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

The !whea and !errpkt extensions can be used to display additional WHEA information. For general information about WHEA, see
(WHEA) in the Windows Driver Kit (WDK) documentation.

Page 499 of 1651

Windows Hardware Error Architecture

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!exca
The !exca extension displays PC-Card Interrupt Controller (PCIC) Exchangable Card Architecture (ExCA) registers.
Syntax
!exca BasePort.SocketNumber
Parameters
BasePort
Specifies the base port of the PCIC.
SocketNumber
Specifies the socket number of the ExCA register on the PCIC.
DLL
Windows 2000

Kext.dll
Kdextx86.dll
Windows XP and later Kext.dll

The !exca extension is only available for an x86-based target computer.

Additional Information
The !cbreg extension can be used to display CardBus Socket registers and CardBus ExCA registers by address.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!exqueue
The !exqueue extension displays a list of items currently queued in the ExWorkerQueue work queues.
Syntax
!exqueue [Flags]
Parameters
Flags
Can be any combination of the following values. The default is 0x0, which will display only a limited amount of information.
Bit 0
Adds time and priority statistics to the display, unless 0x2 is also set.
(0x1)
Bit 1
Adds to the display a list of threads and events associated with the work queue and their wait states.
(0x2)
Bit 2
Adds to the display a list of threads associated with the work queue. If ussed without 0x2, each thread is displayed on a single line. If used with 0x2, each
(0x4)
thread is displayed with a stack trace.
Bit 3
(Windows XP and later) Adds the return address, the stack pointer, and (on Itanium systems) the bsp register value to the display of each thread in the queue.
(0x8)
The display of function arguments is suppressed.
Bit 4
Displays only the critical work queue.
(0x10)
Bit 5
Displays only the delayed work queue.
(0x20)
Bit 6
Displays only the hypercritical work queue.
(0x40)
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 500 of 1651

Comments
If Flags does not include bits 4, 5, or 6, the display includes the critical work queue, the delayed work queue, and the hypercritical work queue.
Here is an sample of the output from this extension:
kd> !exqueue
Dumping ExWorkerQueue: 8046A5C0
**** Critical WorkQueue( current = 0 maximum = 1 )
THREAD fe502940 Cid 8.c Teb: 00000000 Win32Thread: 00000000 WAIT
THREAD fe5026c0 Cid 8.10 Teb: 00000000 Win32Thread: 00000000 WAIT
THREAD fe502440 Cid 8.14 Teb: 00000000 Win32Thread: 00000000 WAIT
THREAD fe5021c0 Cid 8.18 Teb: 00000000 Win32Thread: 00000000 WAIT
THREAD fe501020 Cid 8.1c Teb: 00000000 Win32Thread: 00000000 WAIT
**** Delayed WorkQueue( current
THREAD fe501da0 Cid 8.20 Teb:
THREAD fe501b20 Cid 8.24 Teb:
THREAD fe5018a0 Cid 8.28 Teb:

= 0 maximum = 1 )
00000000 Win32Thread: 00000000 WAIT
00000000 Win32Thread: 00000000 WAIT
00000000 Win32Thread: 00000000 WAIT

**** HyperCritical WorkQueue( current = 0 maximum = 1 )

THREAD fe501620 Cid 8.2c Teb: 00000000 Win32Thread: 00000000 WAIT
The important information in the !exqueue display is:
Parameter
Meaning
current
The number of running threads in the queue; that is, the number of threads in the queue that are not in a wait state.
maximum The number of running threads allowed in the queue at any given point in time. This is usually based on the number of processors in the system.
The system will execute work items in any queue in which the current value is less than its maximum value. The system will not execute any new work items in a queue in
which the current value is greater than or equal to its maximum value until the excess queue threads have either completed execution or entered a wait state. This rule can
delay the system when a CPU-intensive work item is being executed without entering a wait state, because it prevents new work items from being executed, even though the
queue seems to have free threads.
Additional Information
For information about worker threads, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!filecache
The !filecache extension displays information regarding the system file cache memory and PTE use.
Syntax
!filecache
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Each line of this extension's output represents a virtual address control block (VACB). When named files are mapped into the VACB, the names of these files are displayed. If
"no name for file" is specified, this means that this VACB is being used to cache metadata.
Here is an example from a Windows 2000 system:
kd> !filecache
***** Dump file cache******
File Cache Information
Current size 7088 kb
Peak size
11376 kb
loading file cache database...
File cache has 129 valid pages
Usage Summary in KiloBytes (Kb):
Control Valid Standby Dirty Shared Locked PageTables name
80994c08
248
0
0
0
0
0
No Name for File
80995c88
528
0
0
0
0
0
No Name for File
80992a28
120
0
0
0
0
0
No Name for File
80993d28
32
0
0
0
0
0
No Name for File

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

8098c1e8
8091a908
8091d708
80992f08
8098ca48
80949ea8
80992828
8155c688

8
8
16
8
8
8
16
8

Page 501 of 1651

0
0
0
0
0
0
0
0

mapped_file( SysEvent.Evt )
No Name for File
No Name for File
No Name for File
No Name for File
No Name for File
No Name for File
mapped_file( cmd.exe )

Here is an example of the output from this extension from a Windows XP system:
kd> !filecache
***** Dump file cache******
Reading and sorting VACBs ...
Removed 1811 nonactive VACBs, processing 235 active VACBs ...
File Cache Information
Current size 28256 kb
Peak size
30624 kb
235 Control Areas
Skipping view @ c1040000 - no VACB, but PTE is valid!
Loading file cache database (100% of 131072 PTEs)
SkippedPageTableReads = 44
File cache has 4056 valid pages

Usage Summary (in Kb):

Control Valid Standby/Dirty Shared Locked Name
817da668
4
0
0
0 $MftMirr
8177ae68
304
920
0
0 $LogFile
81776160
188
0
0
0 $BitMap
817cf370
4
0
0
0 $Mft
81776a00
8
0
0
0 $Directory
817cfdd0
4
0
0
0 $Directory
81776740
36
0
0
0
No Name for File
817cf7c8
20
0
0
0 $Directory
817cfb98
304
0
0
0 $Directory
8177be40
16
0
0
0 $Directory
817dadc0 2128
68
0
0 $Mft
817cf008
4
0
0
0 $Directory
817d0258
8
4
0
0 $Directory
817763f8
4
0
0
0 $Directory
...
8173f058
4
0
0
0 $Directory
8173e628
32
0
0
0 $Directory
8173e4c8
32
0
0
0 $Directory
8173da38
4
0
0
0 $Directory
817761f8
4
0
0
0 $Directory
81740530
32
0
0
0 $Directory
8173d518
4
0
0
0 $Directory
817d9560
8
0
0
0 $Directory
8173f868
4
0
0
0 $Directory
8173fc00
4
0
0
0 $Directory
81737278
4
0
0
0 $MftMirr
81737c88
44
0
0
0 $LogFile
81735fa0
48
0
0
0 $Mft
81737e88
188
0
0
0 $BitMap
817380b0
4
0
0
0 $Mft
817399e0
4
0
0
0 $Directory
817382b8
4
0
0
0 $Directory
817388d8
12
0
0
0
No Name for File
81735500
8
0
0
0 $Directory
81718e38
232
0
0
0 default
81735d40
48
20
0
0 SECURITY
81723008 8632
0
0
0 software
816da3a0
24
44
0
0 SAM
8173dfa0
4
0
0
0 $Directory
...
8173ba90
4
0
0
0 $Directory
8170ee30
4
36
4
0 AppEvent.Evt
816223f8
4
0
0
0 $Directory
8170ec28
8
28
4
0 SecEvent.Evt
816220a8
4
0
0
0 $Directory
8170ea20
4
32
4
0 SysEvent.Evt
8170d188
232
0
0
0 NTUSER.DAT
81709f10
8
0
0
0 UsrClass.dat
81708918
232
0
0
0 NTUSER.DAT
81708748
8
0
0
0 UsrClass.dat
816c58f8
12
0
0
0 change.log
815c3880
4
0
0
0 $Directory
81706aa8
4
0
0
0 SchedLgU.Txt
815ba2d8
4
0
0
0 $Directory
815aa5f8
8
0
0
0 $Directory
8166d728
44
0
0
0 Netlogon.log

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

81701120
816ff0a8
8159a358
8159da70
8159c158
815cb9b0
81779b20
8159ac20
815683f8
81566978
81568460
815675d8
81567640
...
81515878
81516870
8150df60
...
816e5300
8152afa0
8153bbd8
8172f950
8173e9c0
814f4538
81650790
814f55f8
...
814caef8
8171cd90
815f07f0
814a2298
81541538
81585288
8173f708
...
8158cf10

Page 502 of 1651

8
4
4
4
4
4
4
4
4
580
4
68
4

16
8
0
0
0
0
0
0
0
0
0
0
0

4
4
0
0
0
0
0
0
0
0
0
0
0

0
0
0
0
0
0
0
0
0
0
0
0
0

es.dll
stdole2.tlb
$Directory
$Directory
$Directory
00000001
$Directory
$Directory
$Directory
NTUSER.DAT
$Directory
UsrClass.dat
$Directory

4
8
4

0
0
0

$Directory
$Directory
$Directory

4
16
4
488
4
4
344
4

0
212
32
392
0
0
48
0

0
0
0
0
0
0
0
0

$Directory
msmsgs.exe
stdole32.tlb
OBJECTS.DATA
$Directory
$Directory
INDEX.BTR
$Directory

4
1392
4
4
4
28
4

0
36
0
0
0
0
0

0
0
0
0
0
0
0

$Directory
system
$Directory
$Directory
$Directory
$Directory
$Directory

$Directory

Additional Information
For information about file system drivers, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!filelock
The !filelock extension displays a file lock structure.
Syntax
Syntax in Windows 2000
!filelock FileLockAddress
Syntax in Windows XP and later
!filelock FileLockAddress
!filelock ObjectAddress
Parameters
FileLockAddress
Specifies the hexadecimal address of the file lock structure.
ObjectAddress
(Windows XP and later) Specifies the hexadecimal address of a file object that owns the file lock.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
For information about file objects, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 503 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!fileobj
The !fileobj extension displays detailed information about a FILE_OBJECT structure.
Syntax
!fileobj FileObject
Parameters
FileObject
Specifies the address of a FILE_OBJECT structure.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
If the FILE_OBJECT structure has an associated cache, !fileobj tries to parse and display cache information..
Additional Information
For information about file objects, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by
Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!filetime
The !filetime extension converts a 64-bit FILETIME structure into a human-readable time.
Syntax
!filetime Time
Parameters
Time
Specifies a 64-bit FILETIME structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:
kd> !filetime 1c4730984712348
7/26/2004 04:10:18.712 (Pacific Standard Time)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!finddata
The !finddata extension displays the cached data at a given offset within a specified file object.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 504 of 1651

Syntax
!finddata FileObject Offset
Parameters
FileObject
Specifies the address of the file object.
Offset
Specifies the offset.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, see the !cchelp extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!findfilelockowner
The !findfilelockowner extension attempts to find the owner of a file object lock by examining all threads for a thread that is blocked in an IopSynchronousServiceTail
assert and that has the file object as a parameter.
Syntax
!findfilelockowner [FileObject]
Parameters
FileObject
Specifies the address of a file object. If FileObject is omitted, the extension searches for any thread in the current process that is stuck in IopAcquireFileObjectLock and
retrieves the file object address from the stack trace.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
This extension is most useful after a critical section timeout in which the thread that times out was waiting for the file inside IopAcquireFileObjectLock. After the offending
thread is found, the extension attempts to recover the IRP that was used for the request and to display the driver that was processing the IRP.
The extension takes some time to complete because it walks the stack of all threads in the system until it finds the offending thread.You can stop ` at any point by pressing
CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For information about file objects, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by
Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!for_each_process
The !for_each_process extension executes the specified debugger command once for each process in the target.
Syntax
!for_each_process ["CommandString"]
!for_each_process -?

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 505 of 1651

Parameters
CommandString
Specifies the debugger commands to be executed for each process.
If CommandString includes multiple commands, separate them with semicolons (;) and enclose CommandString in quotation marks ("). If CommandString is enclosed in
quotations marks, the individual commands within CommandString cannot contain quotation marks. Within CommandString, @#Process is replaced by the process
address.
-?
Displays help for this extension in the Debugger Command window.
DLL
This extension works only in kernel mode, even though it resides in Ext.dll.
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
If no arguments are supplied, the debugger displays a list of all processes, along with time and priority statistics. This is equivalent to entering !process @#Process 0 as the
CommandString value.
To terminate execution at any point, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For general information about processes, see Threads and Processes. For information about manipulating or obtaining information about processes, see Controlling Processes
and Threads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!for_each_thread
The !for_each_thread extension executes the specified debugger command once for each thread in the target.
Syntax
!for_each_thread ["CommandString"]
!for_each_thread -?
Parameters
CommandString
Specifies the debugger commands to be executed for each thread. If CommandString includes multiple commands, separate them with semicolons (;) and enclose
CommandString in quotation marks ("). If CommandString is enclosed in quotations marks, the individual commands within CommandString cannot contain quotation
marks. Within CommandString, @#Thread is replaced by the thread address.
-?
Displays help for this extension in the Debugger Command window.
DLL
This extension works only in kernel mode, even though it resides in Ext.dll.
Windows 2000
Ext.dll
Windows XP and later Ext.dll
Comments
If no arguments are supplied, the debugger displays a list of all threads, along with thread wait states. This is equivalent to entering !thread @#Thread 2 as the
CommandString value.
You can terminate execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For more general information about threads, see Threads and Processes. For more information about manipulating or obtaining information about threads, see Controlling
Processes and Threads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 506 of 1651

Debugging Tools for Windows

!fpsearch
The !fpsearch extension searches the freed special pool for a specified address.
Syntax
!fpsearch [Address] [Flag]
Parameters
Address
Specifies a virtual address.
Flag
If set, the debugger displays the raw content of each page on the free list as it searches the freed special pool.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The display for an address includes the virtual address, the page frame number (PFN), the pool tag, size, whether the data at the address is pageable, the thread ID, and the call
stack at the time of deallocation.
If Address is set to -1, the debugger displays the entire freed special pool.
If the debugger cannot find the specified address in the freed special pool, it does not display anything.Here is an example of the output from this extension:
kd> !fpsearch -1 1
Searching the free page list (8 entries) for all freed special pool
1EC4000
1EC4000
1EC4000
1EC4000
1EC4000
1EC4000
1EC4000
1EC4000

04000200
00000800
bad0b0b0
72657355
00028b94
00000000
8153b1b8
0000001b

e56b6f54
00000000
82100000
20203233
00000000
00000000
00028aff
00000000

000001f4
00000000
00000000
0000bac5
0000bac9
ffffffff
00000000
00000012

0000059c
00000000
00000000
00000000
00000000
7fffffff
00000000
00000514

....Tok.........
................
................
User32 ........
................
................
..S.............
................

26A2000
26A2000
26A2000
26A2000
26A2000
26A2000
26A2000
26A2000

000a0008
000a0008
000e000c
00120010
000e000c
000e000c
000a0008
00120010

00adecb0
00adecc8
00adece0
00adecfc
00aded1c
00aded38
00aded54
00aded6c

000e000c
000e000c
000e000c
000e000c
000e000c
000e000c
000e000c
000e000c

00adecba
00adecd2
00adecee
00aded0e
00aded2a
00aded46
00aded5e
00aded7e

................
................
................
................
............*...
....8.......F...
....T.......^...
....l.......~...

2161000
2161000
2161000
2161000
2161000
2161000
2161000
2161000

000a0008
000a0008
000e000c
00120010
000e000c
000e000c
000a0008
00120010

00adeccc
00adece4
00adecfc
00aded18
00aded38
00aded54
00aded70
00aded88

000e000c
000e000c
000e000c
000e000c
000e000c
000e000c
000e000c
000e000c

00adecd6
00adecee
00aded0a
00aded2a
00aded46
00aded62
00aded7a
00aded9a

................
................
................
............*...
....8.......F...
....T.......b...
....p.......z...
................

CEC8000
CEC8000
CEC8000
CEC8000
CEC8000
CEC8000
CEC8000
CEC8000

0311ffa4
00001e00
00000328
7ffdf000
e18ba8c0
00000000
00000000
00000000

03120000
00000000
00000704
00000000
00000000
00000000
00000000
00000000

0311c000
7ff88000
00000000
00000000
00000000
00000000
00000000
00000000

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000

................
................
(...............
................
................
................
................
................

CEAD000
CEAD000
CEAD000
CEAD000
CEAD000
CEAD000
CEAD000
CEAD000

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000

................
................
................
................
................
................
................
................

...

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 507 of 1651

You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!frag
The !frag extension displays fragmentation information about pool memory on the target system.
Syntax
!frag [Flags]
Parameters
Flags
Specifies the level of output. Can be any combination of the following bits. The default is zero.
Bit 0 (0x1)
Causes the display to include the number and size of the fragments for each index.
Bit 1 (0x2)
Causes the display to include allocation information.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Extremely fragmented pools can decrease performance.
Here is an example of the output from this extension:
kd> !frag 1
NonPaged Pool Fragmentation
index: 0 number of fragments:
4 bytes:
128
index: 1 number of fragments:
0 bytes:
0
index: 2 number of fragments:
2 bytes:
192
index: 3 number of fragments:
0 bytes:
0
...
index: 20 number of fragments:
0 bytes:
0
index: 21 number of fragments:
0 bytes:
0
index: 22 number of fragments:
1 bytes:
7232
index: 23 number of fragments:
0 bytes:
0
index: 24 number of fragments:
0 bytes:
0
Number of fragments:
11 consuming
9344 bytes
NonPagedPool Usage: 1105920 bytes
kd> !frag 2
NonPaged Pool Fragmentation
818718a0 size:
20 previous size:
a0
81870720 size:
20 previous size:
60
80d1ae80 size:
20 previous size:
a0
818703c0 size:
20 previous size:
60
80962600 size:
60 previous size:
a0
8098c180 size:
60 previous size: 100
81937680 size: 160 previous size:
40
81870e00 size: 120 previous size:
20
81937d80 size: 260 previous size:
20
81936000 size: 220 previous size:
0
81610260 size: 1c40 previous size: 260
Number of fragments:
11 consuming
NonPagedPool Usage: 1105920 bytes

Cc
Cc
Cc
Cc
ScsD
ScsD
Lric
None
Thre
Proc

9344 bytes

Additional Information
For information about memory management, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 508 of 1651

!frozen
The !frozen extension displays the state of each processor.
Syntax
!frozen
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:
0: kd> !frozen
Processor states:
0 : Current
1 : Frozen

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!fwver
The !fwver extension displays the Itanium firmware version.
Syntax
!fwver
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium target computer.
Comments
Here is an example of the output from this extension:
kd> !fwver
Firmware Version
Sal Revision:
SAL_A_VERSION:
SAL_B_VERSION:
PAL_A_VERSION:
PAL_B_VERSION:
smbiosString:

0
0
0
6623
6625
W460GXBS2.86E.0117A.P08.200107261041

Additional Information
For more information, consult an Intel architecture manual.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!gbl
The !gbl extension displays header information from the ACPI BIOS Root System Description (RSDT) table of the target computer.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 509 of 1651

!gbl [-v]
Parameters
-v
Verbose. Displays detailed information about the table.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Additional Information
For information about the ACPI and ACPI tables, see Other ACPI Debugging Extensions and the ACPI Specification Web site. Also see the Microsoft Windows SDK
documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!gentable
The !gentable extension displays an RTL_GENERIC_TABLE.
Syntax
Syntax in Windows 2000
!gentable Address
Syntax in Windows XP and later
!gentable Address [Flag]
Parameters
Address
Specifies the address of the RTL_GENERIC_TABLE.
Flag
(Windows XP and later) Specifies the table source. If Flag is 1, the AVL table is used. If Flag is 0 or omitted, the non-AVL table is used. In Windows 2000, the nonAVL table is always used.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!hidppd
The !hidppd extension displays the contents of the HIDP_PREPARSED_DATA structure.
Syntax
!hidppd Address
Parameters
Address
Specifies the hexadecimal address of the HIDP_PREPARSED_DATA structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 510 of 1651

Additional Information
For information about human input devices (HID), see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ib, !id, !iw

The !ib, !id, and !iw extension commands are obsolete. Use the ib, id, iw (Input from Port) commands instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!icpleak
The !icpleak extension examines all I/O completion objects in the system for the object with the largest number of queued entries.
Syntax
!icpleak [HandleFlag]
Parameters
HandleFlag
If this flag is set, the display also includes all processes that have a handle to the object with the largest number of queued entries.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
This extension is useful when there is a leak in the I/O completion pool. I/O completion pool leaks can occur when a process is allocating I/O completion packets by calling
PostQueuedCompletionStatus, but is not calling GetQueuedCompletionStatus to free them, or when a process is queuing completion entries to a port, but there is no
thread retrieving the entries. To detect a leak run the !poolused extension and check the value of ICP pool tag. If pool use with the ICP tag is significant, a leak might have
occurred.
This extension works only if the system maintains type lists. If the HandleFlag is set and the system has many processes, this extension will take a long time to run.
You can stop at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For information about I/O completion ports, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!idt
The !idt extension displays the interrupt service routines (ISRs) for a specified interrupt dispatch table (IDT).
Syntax
!idt IDT
!idt [-a]
!idt -?
Parameters
IDT
Specifies the IDT to display.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 511 of 1651

-a
When IDT is not specified, the debugger displays the IDTs of all processors on the target computer in an abbreviated format. If -a is specified, the ISRs for each IDT are
also displayed.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an x64-based or x86-based target computer.
Comments
Here is an example of the output from this extension:
0: kd> !idt
Dumping IDT:
37:806ba78c hal!PicSpuriousService37
3d:806bbc90 hal!HalpApcInterrupt
41:806bbb04 hal!HalpDispatchInterrupt
50:806ba864 hal!HalpApicRebootService
63:8641376c VIDEOPRT!pVideoPortInterrupt (KINTERRUPT 86413730)
73:862aa044 portcls!CInterruptSyncServiceRoutine (KINTERRUPT 862aa008)
82:86594314 atapi!IdePortInterrupt (KINTERRUPT 865942d8)
83:86591bec SCSIPORT!ScsiPortInterrupt (KINTERRUPT 86591bb0)
92:862b53dc serial!SerialCIsrSw (KINTERRUPT 862b53a0)
93:86435844 i8042prt!I8042KeyboardInterruptService (KINTERRUPT 86435808)
a3:863b366c i8042prt!I8042MouseInterruptService (KINTERRUPT 863b3630)
a4:8636bbec USBPORT!USBPORT_InterruptService (KINTERRUPT 8636bbb0)
b1:86585bec ACPI!ACPIInterruptServiceRoutine (KINTERRUPT 86585bb0)
b2:863c0524 serial!SerialCIsrSw (KINTERRUPT 863c04e8)
b4:86391a54 NDIS!ndisMIsr (KINTERRUPT 86391a18)
USBPORT!USBPORT_InterruptService (KINTERRUPT 863ae890)
c1:806ba9d0 hal!HalpBroadcastCallService
d1:806b9dd4 hal!HalpClockInterrupt
e1:806baf30 hal!HalpIpiHandler
e3:806baca8 hal!HalpLocalApicErrorService
fd:806bb460 hal!HalpProfileInterrupt
Additional Information
For information about ISRs and IDTs, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For more information about how to display the interrupt vector tables on an Itanium target computer, see !ivt.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ih
The !ih extension displays the interrupt history record for the specified processor.
Syntax
!ih Processor
Parameters
Processor
Specifies a processor. If Processor is omitted, the current processor is used.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium-based target computer.
Comments
This extension displays the interrupt history record without referencing the program counter symbols. To display the interrupt history record using the program counter
symbols, use the !ihs extension. To enable the interrupt history record, add /configflag=32 to the boot entry options.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 512 of 1651

Here is an example of the output from this extension:

kd> !ih
Total # of interruptions = 2093185
Vector
IIP
VHPT FAULT e0000000830d3190
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d3190
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d3880
VHPT FAULT e0000000830d3fb0
VHPT FAULT e000000083063390
THREAD SWITCH e000000085896040
VHPT FAULT e00000008329b130
VHPT FAULT e0000165f7eda640
PROCESS SWITCH e0000000818bbe10
VHPT FAULT e00000008307cfc0
EXTERNAL INTERRUPT e0000000830623b0
VHPT FAULT e00000008314e310
VHPT FAULT e000000083580760
PROCESS SWITCH e00000008558c990
VHPT FAULT e00000008307cfc0
VHPT FAULT
77cfbda0
VHPT FAULT
77cfbdb0
DATA ACCESS BIT
77b8e150
VHPT FAULT
77ed5d60
DATA ACCESS BIT
77ed5d60
DATA ACCESS BIT
77b8e1b0
USER SYSCALL
77cafa40
VHPT FAULT e00000008344dc20
...

IPSR
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
e00000008588c040
1210092a6018
1210092a6018
e000000085896040
1010092a2018
1010092a6018
1010092a2018
1010092a2018
e0000000818bbe10
1010092a2018
1013082a6018
1213082a6018
1213082a6018
1013082a6018
1213082a6018
1013082a6018
10082a6018
1010092a6018

ExtraField
IFA=
6fc00a0200c
IFA= 1ffffe00001de2d0
IFA= 1ffffe01befff338
IFA=
6fc00a0200c
IFA= 1ffffe00001d9188
IFA= 1ffffe01befff250
IFA= e0000165f82dc1c0
IFA= e0000000fffe0018
OSP= e0000165f82dbd40
IFA= e0000165f7edaf30
IFA= e0000165fff968a9
OSP= e0000165f8281de0
IFA= e00000008189fe50
IVR=
d0
IFA= e0000165f88203f0
IFA= e0000000f00ff3fd
OSP= e00000008189fe20
IFA= e0000165f02433f0
IFA=
77cfbda0
IFA=
6fbfee0ff98
IFA=
77c16ab8
IFA=
6fbfffa6048
IFA=
77c229c0
IFA=
77c1c320
Num=
42
IFA= e000010600703784

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ihs
The !ihs extension displays the interrupt history record for the specified processor, using program counter symbols.
Syntax
!ihs Processor
Parameters
Processor
Specifies a processor. If Processor is omitted, the current processor is used.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium target computer.
Comments
To display the interrupt history record without using program counter symbols, use the !ih extension. To enable the interrupt history record, add /configflag=32 to the boot
entry options.
Here is an example of the output from this extension:
kd> !ihs
Total # of interruptions = 2093185
Vector
IIP
VHPT FAULT e0000000830d3190
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d3190
VHPT FAULT e0000000830d33d0
VHPT FAULT e0000000830d3880
VHPT FAULT e0000000830d3fb0
VHPT FAULT e000000083063390
THREAD SWITCH e000000085896040
VHPT FAULT e00000008329b130

IPSR
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
1010092a6018
e00000008588c040
1210092a6018

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

IIP Symbol
nt!MiAgeAndEstimateAvailableInWorkingSet+0x70
nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0
nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0
nt!MiAgeAndEstimateAvailableInWorkingSet+0x70
nt!MiAgeAndEstimateAvailableInWorkingSet+0x2b0
nt!MiAgeAndEstimateAvailableInWorkingSet+0x760
nt!MiCheckAndSetSystemTrimCriteria+0x190
nt!KeQuerySystemTime+0x30
nt!IopProcessWorkItem+0x30

9/18/2010

Introduction

VHPT FAULT
PROCESS SWITCH
VHPT FAULT
EXTERNAL INTERRUPT
VHPT FAULT
VHPT FAULT
PROCESS SWITCH
VHPT FAULT
VHPT FAULT
VHPT FAULT
DATA ACCESS BIT
VHPT FAULT
DATA ACCESS BIT
DATA ACCESS BIT
USER SYSCALL
VHPT FAULT
...

Page 513 of 1651

e0000165f7eda640
e0000000818bbe10
e00000008307cfc0
e0000000830623b0
e00000008314e310
e000000083580760
e00000008558c990
e00000008307cfc0
77cfbda0
77cfbdb0
77b8e150
77ed5d60
77ed5d60
77b8e1b0
77cafa40
e00000008344dc20

1210092a6018
e000000085896040
1010092a2018
1010092a6018
1010092a2018
1010092a2018
e0000000818bbe10
1010092a2018
1013082a6018
1213082a6018
1213082a6018
1013082a6018
1213082a6018
1013082a6018
10082a6018
1010092a6018

IFA=
OSP=
IFA=
IVR=
IFA=
IFA=
OSP=
IFA=
IFA=
IFA=
IFA=
IFA=
IFA=
IFA=
Num=
IFA=

e0000165fff968a9
e0000165f8281de0
e00000008189fe50
d0
e0000165f88203f0
e0000000f00ff3fd
e00000008189fe20
e0000165f02433f0
77cfbda0
6fbfee0ff98
77c16ab8
6fbfffa6048
77c229c0
77c1c320
42
e000010600703784

netbios!RunTimerForLana+0x60
nt!SwapFromIdle+0x1e0
nt!Kil_TopOfIdleLoop
nt!KdReceivePacket+0x10
hal!READ_PORT_UCHAR+0x80
nt!SwapFromIdle+0x1e0
0x0000000077cfbda0
0x0000000077cfbdb0
0x0000000077b8e150
0x0000000077ed5d60
0x0000000077ed5d60
0x0000000077b8e1b0
0x0000000077cafa40
nt!ExpLookupHandleTableEntry+0x20

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ioresdes
The !ioresdes extension displays the IO_RESOURCE_DESCRIPTOR structure at the specified address.
Syntax
!ioresdes Address
Parameters
Address
Specifies the hexadecimal address of the IO_RESOURCE_DESCRIPTOR structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about the IO_RESOURCE_DESCRIPTOR structure, see the Windows Driver Kit
(WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ioreslist
The !ioreslist extension displays an IO_RESOURCE_REQUIREMENTS_LIST structure.
Syntax
!ioreslist Address
Parameters
Address
Specifies the hexadecimal address of the IO_RESOURCE_REQUIREMENTS_LIST structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 514 of 1651

kd> !ioreslist 0xe122b768

IoResList at 0xe122b768 : Interface 0x5 Bus 0 Slot 0xe
Alternative 0 (Version 1.1)
Preferred Descriptor 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000100 byte range with alignment 0x000100
1000 - 0x10ff
Alternative Descriptor 1 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000100 byte range with alignment 0x000100
0 - 0xffffffff
Descriptor 2 - DevicePrivate (0x81) Device Exclusive (0x1)
Flags (0000) Data:
: 0x1 0x0 0x0
Preferred Descriptor 3 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
0x001000 byte range with alignment 0x001000
40080000 - 0x40080fff
Alternative Descriptor 4 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
0x001000 byte range with alignment 0x001000
0 - 0xffffffff
Descriptor 5 - DevicePrivate (0x81) Device Exclusive (0x1)
Flags (0000) Data:
: 0x1 0x1 0x0
Descriptor 6 - Interrupt (0x2) Shared (0x3)
Flags (0000) - LEVEL_SENSITIVE
0xb - 0xb
The IO_RESOURCE_REQUIREMENTS_LIST contains information about:

Resource types
There are four types of resources: I/O, Memory, IRQ, DMA.

Descriptors
Each preferred setting has a "Preferred" descriptor and a number of "Alternative" descriptors.

This resource list contains the following requests:

I/O Ranges
Prefers a range of 0x1000 to 0x10FF inclusive, but can use any 0x100 range between 0 and 0xFFFFFFFF, provided it is 0x100-aligned. (For example, 0x1100 to
0x11FF is acceptable.)

Memory
Prefers a range of 0x40080000 to 0x40080FFF, but can use any range that is of size 0x1000, is 0x1000-aligned, and is located between 0 and 0xFFFFFFFF.

IRQ
Must use IRQ 0xB.

Interrupts and DMA channels are represented as ranges with the same beginning and end.
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about the IO_RESOURCE_REQUIREMENTS_LIST structure, see the Windows
Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!iovirp
The !iovirp extension displays detailed information for a specified I/O Verifier IRP.
Syntax
!iovirp [IRP]
Parameters
IRP
Specifies the address of an IRP tracked by the Driver Verifier. If IRP is 0 or is omitted, the summary information for each outstanding IRP is displayed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 515 of 1651

DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:
kd> !iovirp 947cef68
IovPacket
84509af0
TrackedIrp
947cef68
HeaderLock
84509d61
LockIrql
0
ReferenceCount 1
PointerCount
1
HeaderFlags
00000000
ChainHead
84509af0
Flags
00200009
DepartureIrql
0
ArrivalIrql
0
StackCount
1
QuotaCharge
00000000
QuotaProcess
0
RealIrpCompletionRoutine
0
RealIrpControl
0
RealIrpContext
0
TopStackLocation
2
PriorityBoost
0
LastLocation
0
RefTrackingCount
0
SystemDestVA
0
VerifierSettings
84509d08
pIovSessionData
84509380
Allocation Stack:
nt!IovAllocateIrp+1a (817df356)
nt!IopXxxControlFile+40c (8162de20)
nt!NtDeviceIoControlFile+2a (81633090)
nt!KiFastCallEntry+164 (81513c64)
nt!EtwpFlushBuffer+10f (817606d7)
nt!EtwpFlushBuffersWithMarker+bd (817608cb)
nt!EtwpFlushActiveBuffers+2b4 (81760bc2)
nt!EtwpLogger+213 (8176036f)
You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ipi
The !ipi extension displays the interprocessor interrupt (IPI) state for a specified processor.
Syntax
!ipi [Processor]
Parameters
Processor
Specifies a processor. If Processor is omitted, the IPI state for every processor is displayed.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
Comments
Here is an example of the output from this extension:
0: kd> !ipi
IPI State for Processor 0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Worker Routine:
Parameter[0]:
Parameter[1]:
Parameter[2]:
Ipi Trap Frame:
Signal Done:
IPI Frozen:
Request Summary:
Target Set:
Packet Barrier:

Page 516 of 1651

nt!KiFlushTargetMultipleTb [Stale]
0
3
F7C98770
F7CCCCDC [.trap F7CCCCDC]
0
24 [FreezeActive] [Owner]
0
0
0

IPI State for Processor 1

Worker Routine: nt!KiFlushTargetMultipleTb [Stale]
Parameter[0]:
1
Parameter[1]:
3
Parameter[2]:
F7CDCD28
Ipi Trap Frame: F7C8CCC4 [.trap F7C8CCC4]
Signal Done:
0
IPI Frozen:
2 [Frozen]
Request Summary: 0
Target Set:
0
Packet Barrier: 0
Additional Information
For information about IPIs, see Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!irp
The !irp extension displays information about an I/O request packet (IRP).
Syntax
!irp Address [Detail]
Parameters
Address
Specifies the hexadecimal address of the IRP.
Detail
If this parameter is included with any value, such as 1, the output includes the status of the IRP, the address of its memory descriptor list (MDL), its owning thread, and
stack information for all of its I/O stacks, and information about each stack location for the IRP, including hexadecimal versions of the major function code and the minor
function code. If this parameter omitted, the output includes only a summary of the information.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The following information is included to help you interpret the output from this extension command.
The IRP major function codes are as follows:
Major Function Code
Hexadecimal Code
IRP_MJ_CREATE
0x00
IRP_MJ_CREATE_NAMED_PIPE
0x01
IRP_MJ_CLOSE
0x02
IRP_MJ_READ
0x03
IRP_MJ_WRITE
0x04
IRP_MJ_QUERY_INFORMATION
0x05
IRP_MJ_SET_INFORMATION
0x06
IRP_MJ_QUERY_EA
0x07
IRP_MJ_SET_EA
0x08
IRP_MJ_FLUSH_BUFFERS
0x09
IRP_MJ_QUERY_VOLUME_INFORMATION 0x0A
IRP_MJ_SET_VOLUME_INFORMATION
0x0B
IRP_MJ_DIRECTORY_CONTROL
0x0C

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_DEVICE_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_SCSI
IRP_MJ_SHUTDOWN
IRP_MJ_LOCK_CONTROL
IRP_MJ_CLEANUP
IRP_MJ_CREATE_MAILSLOT
IRP_MJ_QUERY_SECURITY
IRP_MJ_SET_SECURITY
IRP_MJ_POWER
IRP_MJ_SYSTEM_CONTROL
IRP_MJ_DEVICE_CHANGE
IRP_MJ_QUERY_QUOTA
IRP_MJ_SET_QUOTA
IRP_MJ_PNP
IRP_MJ_MAXIMUM_FUNCTION

Page 517 of 1651

0x0D
0x0E
0x0F
0x10
0x11
0x12
0x13
0x14
0x15
0x16
0x17
0x18
0x19
0x1A
0x1B

The Plug and Play minor function codes are as follows:

Minor Function Code
Hexadecimal Code
IRP_MN_START_DEVICE
0x00
IRP_MN_QUERY_REMOVE_DEVICE
0x01
IRP_MN_REMOVE_DEVICE
0x02
IRP_MN_CANCEL_REMOVE_DEVICE
0x03
IRP_MN_STOP_DEVICE
0x04
IRP_MN_QUERY_STOP_DEVICE
0x05
IRP_MN_CANCEL_STOP_DEVICE
0x06
IRP_MN_QUERY_DEVICE_RELATIONS
0x07
IRP_MN_QUERY_INTERFACE
0x08
IRP_MN_QUERY_CAPABILITIES
0x09
IRP_MN_QUERY_RESOURCES
0x0A
IRP_MN_QUERY_RESOURCE_REQUIREMENTS 0x0B
IRP_MN_QUERY_DEVICE_TEXT
0x0C
IRP_MN_FILTER_RESOURCE_REQUIREMENTS 0x0D
IRP_MN_READ_CONFIG
0x0F
IRP_MN_WRITE_CONFIG
0x10
IRP_MN_EJECT
0x11
IRP_MN_SET_LOCK
0x12
IRP_MN_QUERY_ID
0x13
IRP_MN_QUERY_PNP_DEVICE_STATE
0x14
IRP_MN_QUERY_BUS_INFORMATION
0x15
IRP_MN_DEVICE_USAGE_NOTIFICATION
0x16
IRP_MN_SURPRISE_REMOVAL
0x17
IRP_MN_QUERY_LEGACY_BUS_INFORMATION 0x18
The WMI minor function codes are as follows:
Minor Function Code
Hexadecimal Code
IRP_MN_QUERY_ALL_DATA
0x00
IRP_MN_QUERY_SINGLE_INSTANCE 0x01
IRP_MN_CHANGE_SINGLE_INSTANCE 0x02
IRP_MN_CHANGE_SINGLE_ITEM
0x03
IRP_MN_ENABLE_EVENTS
0x04
IRP_MN_DISABLE_EVENTS
0x05
IRP_MN_ENABLE_COLLECTION
0x06
IRP_MN_DISABLE_COLLECTION
0x07
IRP_MN_REGINFO
0x08
IRP_MN_EXECUTE_METHOD
0x09
The power management minor function codes are as follows:
Minor Function Code
Hexadecimal Code
IRP_MN_WAIT_WAKE
0x00
IRP_MN_POWER_SEQUENCE 0x01
IRP_MN_SET_POWER
0x02
IRP_MN_QUERY_POWER
0x03
The SCSI minor function codes are as follows:
Minor Function Code Hexadecimal Code

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 518 of 1651

IRP_MN_SCSI_CLASS 0x01
The output also indicates under what conditions the completion routine for each stack location will be called once the IRP has completed and the stack location is processed.
There are three possibilities:
Success
Indicates that the completion routine will be called when the IRP is completed with a success code.
Error
Indicates that the completion routine will be called when the IRP is completed with an error code.
Cancel
Indicates that the completion routine will be called if an attempt was made to cancel the IRP.
Any combination of these three may appear, and if any of the conditions shown are satisfied, the completion routine will be called. The appropriate values are listed at the end
of the first row of information about each stack location, immediately after the Completion-Context entry.
Here is an example of the output from this extension from Windows XP:
!irp 81183468
Irp is active with 2 stacks 2 is current (= 0x811834fc)
No Mdl Thread 00000000: Irp stack trace.
Cmd flg cl Device
File
Completion-Context
[ 0, 0]
0 0 8145f470 00000000 00000000-00000000
\Driver\E100B
Args: 00000000 00000000 00000000 00000000
[ 16, 2]
0 e1 8145f470 00000000 8047f744-814187a8 Success Error Cancel pending
\Driver\E100B
ntoskrnl!PopCompleteSystemPowerIrp
Args: 00000000 00000000 00000002 00000002
In the second stack location entry of the Windows XP example, the major function code is 16, indicating that this IRP has been sent to the power stack. The minor function
code is 2, so the power stack recognizes it as a set request. The IRP is pending, and when it completes, ntoskrnl!PopCompleteSystemPowerIrp will be called regardless of
the return code as both Success and Error are specified.
Here is an example of the output from this extension from Windows Vista.
0: kd> !irp 0x831f4a00
Irp is active with 8 stacks 5 is current (= 0x831f4b00)
Mdl = 82b020d8 Thread 8c622118: Irp stack trace.
cmd flg cl Device
File
Completion-Context
[ 0, 0]
0 0 00000000 00000000 00000000-00000000

0, 0]

Args: 00000000 00000000 00000000 00000000

0 00000000 00000000 00000000-00000000

0, 0]

Args: 00000000 00000000 00000000 00000000

0 00000000 00000000 00000000-00000000

0, 0]

Args: 00000000 00000000 00000000 00000000

0 00000000 00000000 00000000-00000000

3,34]

3, 0]

Args: 00000000 00000000 00000000 00000000

40 e1 828517a8 00000000 842511e0-00000000 Success Error Cancel pending
\Driver\disk
partmgr!PmReadWriteCompletion
Args: 00007000 00000000 fe084e00 00000004
40 e0 82851450 00000000 842414d4-82956350 Success Error Cancel
\Driver\PartMgr volmgr!VmpReadWriteCompletionRoutine
Args: 129131bb 000000de fe084e00 00000004
0 e0 82956298 00000000 847eeed0-829e2ba8 Success Error Cancel
\Driver\volmgr
Ntfs!NtfsMasterIrpSyncCompletionRoutine
Args: 00007000 00000000 1bdae400 00000000
0 0 82ac2020 8e879410 00000000-00000000
\FileSystem\Ntfs
Args: 00007000 00000000 00018400 00000000

Note that the completion routine next to the driver name is set on that stack location, and it was set by the driver in the line below. In the preceding example, Ntfs!
NtfsMasterIrpSyncCompletionRoutine was set by \FileSystem\Ntfs. The Completion-Context entry above Ntfs!NtfsMasterIrpSyncCompletionRoutine, 847eeed0829e2ba8, indicates the address of the completion routine, as well as the context that will be passed to Ntfs!NtfsMasterIrpSyncCompletionRoutine. From this we can see
that the address of Ntfs!NtfsMasterIrpSyncCompletionRoutine is 847eeed0, and the context that will be passed to this routine when it is called is 829e2ba8.
Additional Information
See Plug and Play Debugging and Debugging Interrupt Storms for applications of this extension command. For information about IRPs, see the Windows Driver Kit (WDK)
documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon. For further information on the major and minor function codes, see the Windows
Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 519 of 1651

!irpfind
The !irpfind extension displays information about all I/O request packets (IRP) currently allocated in the target system, or about those IRPs matching the specified search
criteria.
Syntax
Syntax in Windows 2000
!irpfind [PoolType [RestartAddress [Criteria Data]]]
Syntax in Windows XP and later
!irpfind [-v] [PoolType [RestartAddress [Criteria Data]]]
Parameters
-v
(Windows XP and later) Displays verbose information.
PoolType
Specifies the type of pool to be searched. The following values are permitted:
0
Specifies nonpaged memory pool. This is the default.
1
Specifies paged memory pool.
2
Specifies the special pool.
4
(Windows XP and later) Specifies the session pool.
RestartAddress
Specifies the hexadecimal address at which to begin the search. This is useful if the previous search was terminated prematurely. The default is zero.
Criteria
Specifies the criteria for the search. Only those IRPs that satisfy the given match will be displayed.
Criteria
Match
arg
Finds all IRPs with a stack location where one of the arguments equals Data.
device
Finds all IRPs with a stack location where DeviceObject equals Data.
fileobject Finds all IRPs whose Irp.Tail.Overlay.OriginalFileObject equals Data.
mdlprocess Finds all IRPs whose Irp.MdlAddress.Process equals Data.
thread
Finds all IRPs whose Irp.Tail.Overlay.Thread equals Data.
userevent Finds all IRPs whose Irp.UserEvent equals Data.
Data
Specifies the data to be matched in the search.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This example finds the IRP in the nonpaged pool that is going to set user event FF9E4F48 upon completion:
kd> !irpfind 0 0 userevent ff9e4f48
The following example produces a full listing of all IRPs in the nonpaged pool:
kd> !irpfind
Searching NonPaged pool (8090c000 : 8131e000) for Tag: Irp
8097c008 Thread 8094d900 current stack belongs to \Driver\symc810
8097dec8 Thread 8094dda0 current stack belongs to \FileSystem\Ntfs
809861a8 Thread 8094dda0 current stack belongs to \Driver\symc810
809864e8 Thread 80951ba0 current stack belongs to \Driver\Mouclass
80986608 Thread 80951ba0 current stack belongs to \Driver\Kbdclass
80986728 Thread 8094dda0 current stack belongs to \Driver\symc810
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about IRPs, see the Windows Driver Kit (WDK) documentation and Microsoft
Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 520 of 1651

!irpzone
The !irpzone extension command is obsolete. Use !irpfind instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!irql
The !irql extension displays the interrupt request level (IRQL) of a processor on the target computer before the debugger break.
Syntax
!irql [Processor]
Parameters
Processor
Specifies the a processor. Enter the processor number. If this parameter is omitted, the debugger displays the IRQL of the current processor.
DLL
The !irql extension is only available in Windows Server 2003 and later versions of Windows.
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Server 2003 and later Kdexts.dll
Comments
When the target computer breaks into the debugger, the IRQL changes, but the IRQL that was effective just before the debugger break is saved. The !irql extension displays
the saved IRQL.
Similarly, when a bug check occurs and a crash dump file is created, the IRQL saved in the crash dump file is the one immediately prior to the bug check, not the IRQL at
which the KeBugCheckEx routine was executed.
In both cases, the current IRQL is raised to DISPATCH_LEVEL, except on x86 architectures. Thus, if more than one such event occurs, the IRQL displayed will also be
DISPATCH_LEVEL, making it useless for debugging purposes.
The !pcr extension displays the current IRQL on all versions of Windows, but the current IRQL is usually not useful. The IRQL that existed just before the bug check or
debugger connection is more interesting, and this is displayed only with !irql.
If you supply an invalid processor number, or there has been kernel corruption, the debugger displays a message "Cannot get PRCB address".
Here is an example of the output from this extension from a dual-processor x86 computer:
kd> !irql 0
Debugger saved IRQL for processor 0x0 -- 28 (CLOCK2_LEVEL)
kd> !irql 1
Debugger saved IRQL for processor 0x1 -- 0 (LOW_LEVEL)
If the debugger is in verbose mode, a description of the IRQL itself is included. Here is an example from an Itanium processor:
kd> !irql
Debugger saved IRQL for processor 0x0 -- 12 (PC_LEVEL) [Performance counter level]
The meaning of the IRQL number often depends on the processor. Here is an example from an x64 processor. Note that the IRQL number is the same as in the previous
example, but the IRQL meaning is different:
kd> !irql
Debugger saved IRQL for processor 0x0 -- 12 (SYNCH_LEVEL) [Synchronization level]
Additional Information
For information about IRQLs, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 521 of 1651

!isainfo
The !isainfo extension displays information about PNPISA cards or devices present in the system..
Syntax
!isainfo [Card]
Parameters
Card
Specifies a PNPISA Card. If Card is 0 or omitted, all the devices and cards on the PNPISA (that is, the PC I/O) Bus are displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:
0: kd> !isainfo
ISA PnP FDO @ 0x867b9938, DevExt @ 0x867b99f0, Bus # 0
Flags (0x80000000) DF_BUS
ISA PnP PDO @ 0x867B9818, DevExt @ 0x86595388
Flags (0x40000818) DF_ENUMERATED, DF_ACTIVATED,
DF_REQ_TRIMMED, DF_READ_DATA_PORT

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!isr
The !isr extension displays the Itanium Interruption Status Register (ISR) at the specified address.
Syntax
!isr Expression [DisplayLevel]
Parameters
Expression
Specifies the hexadecimal address of the ISR register to display. The expression @isr can also be used for this parameter. In that case, information about the current
processor ISR register is displayed.
DisplayLevel
Can be any one of the following options:
0
Displays only the values of each ISR field. This is the default.
1
Displays detailed information about ISR fields that are not reserved or ignored.
2
Displays details about all ISR fields, including those that are ignored or reserved.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium target computer.
Comments
Here are a couple of examples of output from this extension:
kd> !isr @isr
isr:ed ei so ni ir rs sp na r w x vector code
0 0 0 0 0 0 0 0 0 0 0
0
0
kd> !isr @isr 2
cod : 0 : interruption Code
vec : 0 : IA32 exception vector number

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

rv
x
w
r
na
sp
rs
ir
ni
so
ei
ed
rv

:
:
:
:
:
:
:
:
:
:
:
:
:

0
0
0
0
0
0
0
0
0
0
0
0
0

:
:
:
:
:
:
:
:
:
:
:
:
:

Page 522 of 1651

reserved0
eXecute exception
Write exception
Read exception
Non-Access exception
Speculative load exception
Register Stack
Invalid Register frame
Nested Interruption
IA32 Supervisor Override
Exception IA64 Instruction
Exception Deferral
reserved1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ivt
The !ivt extension displays the Itanium interrupt vector table.
Syntax
!ivt [-v] [-a] [Vector]
!ivt -?
Parameters
Vector
Specifies an interrupt vector table entry for the current processor. If Vector is omitted, the entire interrupt vector table for the current processor on the target computer is
displayed. Interrupt vectors that have not been assigned are not displayed unless the a option is specified.
-a
Displays all interrupt vectors, including those that are unassigned.
-v
Displays detailed output.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium target computer.
Comments
Here is an example of the output from this extension:
kd> !ivt
Dumping IA64 IVT:
00:e000000083005f60
0f:e000000083576830
10:e0000000830067f0
20:e000000083006790
30:e000000083576b30
31:e000000083576b20
41:e000000085039680
51:e000000085039910
61:e0000000854484f0
71:e0000000856c9450
81:e0000000857fd000
91:e0000000857ff510
a1:e0000000857d84b0
a2:e0000165fff2cab0
b1:e0000000858c7460
b2:e0000000850382e0
d0:e0000000835768d0
e0:e000000083576850
f0:e0000000835769c0
f1:e000000083576830
fd:e000000083576b10
fe:e000000083576830

nt!KiPassiveRelease
hal!HalpPCIISALine2Pin
nt!KiApcInterrupt
nt!KiDispatchInterrupt
hal!HalpCMCIHandler
hal!HalpCPEIHandler
i8042prt!I8042KeyboardInterruptService (KINTERRUPT e000000085039620)
i8042prt!I8042MouseInterruptService (KINTERRUPT e0000000850398b0)
VIDEOPRT!pVideoPortInterrupt (KINTERRUPT e000000085448490)
NDIS!ndisMIsr (KINTERRUPT e0000000856c93f0)
SCSIPORT!ScsiPortInterrupt (KINTERRUPT e0000000857fcfa0)
atapi!IdePortInterrupt (KINTERRUPT e0000000857ff4b0)
atapi!IdePortInterrupt (KINTERRUPT e0000000857d8450)
portcls!CInterruptSyncServiceRoutine (KINTERRUPT e0000165fff2ca50)
ACPI!ACPIInterruptServiceRoutine (KINTERRUPT e0000000858c7400)
USBPORT!USBPORT_InterruptService (KINTERRUPT e000000085038280)
hal!HalpClockInterrupt
hal!HalpIpiInterruptHandler
hal!HalpProfileInterrupt
hal!HalpPCIISALine2Pin
hal!HalpMcRzHandler
hal!HalpPCIISALine2Pin

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 523 of 1651

Additional Information
For more information about how to display the interrupt dispatch tables on an x64 or x86 target computer, see !idt.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!job
The !job extension displays a job object.
Syntax
!job [Process [Flags]]
Parameters
Process
Specifies the hexadecimal address of a process or a thread whose associated job object is to be examined. If this is omitted, or equal to -1 (in Windows 2000), or equal to
zero (in Windows XP and later), the job associated with the current process is displayed.
Flags
Specifies what the display should contain. This can be a sum of any of the following bit values. The default is 0x1:
Bit 0 (0x1)
Causes the display to include job settings and statistics.
Bit 1 (0x2)
Causes the display to include a list of all processes in the job.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension:
kd> !process 52c
Searching for Process with Cid == 52c
PROCESS 8276c550 SessionId: 0 Cid: 052c
Peb: 7ffdf000 ParentCid: 0060
DirBase: 01289000 ObjectTable: 825f0368 TableSize: 24.
Image: cmd.exe
VadRoot 825609e8 Vads 30 Clone 0 Private 77. Modified 0. Locked 0.
DeviceMap e1733f38
Token
e1681610
ElapsedTime
0:00:12.0949
UserTime
0:00:00.0359
.....
CommitCharge
109
Job
8256e1f0
kd> !job 8256e1f0
Job at ffffffff8256e1f0
TotalPageFaultCount
TotalProcesses
ActiveProcesses
TotalTerminatedProcesses
LimitFlags
MinimumWorkingSetSize
MaximumWorkingSetSize
ActiveProcessLimit
PriorityClass
UIRestrictionsClass
SecurityLimitFlags
Token

0
1
1
0
0
0
0
0
0
0
0
00000000

Additional Information
For information about job objects, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 524 of 1651

!kb, !kv
The !kb and !kv extension commands are obsolete. Use the kb (Display Stack Backtrace) and kv (Display Stack Backtrace) commands instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!loadermemorylist
The !loadermemorylist extension displays the memory allocation list that the Windows boot loader passes to Windows.
Syntax
!loadermemorylist ListHeadAddress
Parameters
ListHeadAddress
Specifies the address of a list header.
DLL
Windows 2000
Kdexts.dll
Windows XP
Kdexts.dll
Windows Server 2003
Windows Vista and later Kdexts.dll
Comments
This extension is designed to be used at the beginning of the system boot process while Ntldr is running. It displays a memory allocation list that includes the start, end, and
type of each page range.
You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!lockedpages
The !lockedpages extension displays driver-locked pages for the current process in Windows 2000 and for a specified process in Windows XP and later.
Syntax
Syntax in Windows 2000
!lockedpages
Syntax in Windows XP and later
!lockedpages [Process]
Parameters
Process
(Windows XP and later only) Specifies a process. If Process is omitted, the current process is used.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 525 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

!locks (!kdext*.locks)
The !locks extension in Kdextx86.dll and Kdexts.dll displays information about kernel ERESOURCE locks.
This extension command should not be confused with the !ntsdexts.locks extension command.
Syntax
!locks [Options] [Address]
Parameters
Options
Specifies the amount of information to be displayed. Any combination of the following options can be used:
-v
Displays detailed information about each lock.
-p
Display all available information about the locks, including performance statistics.
-d
Display information about all locks. Otherwise, only locks with contention are displayed.)
Address
Specifies the hexadecimal address of the ERESOURCE lock to be displayed. If Address is 0 or omitted, information about all ERESOURCE locks in the system will be
displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !locks extension displays all locks held on resources by threads. A lock can be shared or exclusive, which means no other threads can gain access to that resource. This
information is useful when a deadlock occurs on a system. A deadlock is caused by one non-executing thread holding an exclusive lock on a resource that the executing thread
needs.
You can usually pinpoint a deadlock in Microsoft Windows 2000 by finding one non-executing thread that holds an exclusive lock on a resource that is required by an
executing thread. Most of the locks are shared.
Here is an example of the basic !locks output:
kd> !locks
**** DUMP OF ALL RESOURCE OBJECTS ****
KD: Scanning for held locks......
Resource @ 0x80e97620
Shared 4 owning threads
Threads: ff688da0-01<*> ff687da0-01<*> ff686da0-01<*> ff685da0-01<*>
KD: Scanning for held locks.......................................................
Resource @ 0x80e23f38
Shared 1 owning threads
Threads: 80ed0023-01<*> *** Actual Thread 80ed0020
KD: Scanning for held locks.
Resource @ 0x80d8b0b0
Shared 1 owning threads
Threads: 80ed0023-01<*> *** Actual Thread 80ed0020
2263 total locks, 3 locks currently held
Note that the address for each thread displayed is followed by its thread count (for example, "-01"). If a thread is followed by "<*>", that thread is one of the owners of the
lock. In some instances, the initial thread address contains an offset. In that case, the actual thread address is displayed as well.
If you want to find more information about one of these resource objects, use the address that follows "Resource @" as an argument for future commands. To investigate the
second resource shown in the preceding example, you could use dt ERESOURCE 80d8b0b0 or !thread 80ed0020. Or you could use the !locks extension again with the -v
option:
kd> !locks -v 80d8b0b0
Resource @ 0x80d8b0b0
Shared 1 owning threads
Threads: 80ed0023-01<*> *** Actual Thread 80ed0020
THREAD 80ed0020 Cid 4.2c
8055e100 Unknown
Not impersonating
GetUlongFromAddress: unable to
Owning Process 80ed5238
WaitTime (ticks)
Context Switch Count
UserTime

Teb: 00000000 Win32Thread: 00000000 WAIT: (WrQueue) KernelMode Non-Alertable

read from 00000000

44294977
147830
0:00:00.0000

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 526 of 1651

KernelTime
0:00:02.0143
Start Address nt!ExpWorkerThread (0x80506aa2)
Stack Init fafa4000 Current fafa3d18 Base fafa4000 Limit fafa1000 Call 0
Priority 13 BasePriority 13 PriorityDecrement 0
ChildEBP RetAddr
fafa3d30 804fe997 nt!KiSwapContext+0x25 (FPO: [EBP 0xfafa3d48] [0,0,4]) [D:\NT\base\ntos\ke\i386\ctxswap.asm @ 139]
fafa3d48 80506a17 nt!KiSwapThread+0x85 (FPO: [Non-Fpo]) (CONV: fastcall) [d:\nt\base\ntos\ke\thredsup.c @ 1960]
fafa3d78 80506b36 nt!KeRemoveQueue+0x24c (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ke\queueobj.c @ 542]
fafa3dac 805ad8bb nt!ExpWorkerThread+0xc6 (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ex\worker.c @ 1130]
fafa3ddc 8050ec72 nt!PspSystemThreadStartup+0x2e (FPO: [Non-Fpo]) (CONV: stdcall) [d:\nt\base\ntos\ps\create.c @ 2164]
00000000 00000000 nt!KiThreadStartup+0x16 [D:\NT\base\ntos\ke\i386\threadbg.asm @ 81]
1 total locks, 1 locks currently held

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!logonsession
The !logonsession extension displays information about a specified logon session.
Syntax
Free Build Syntax
!logonsession LUID
Checked Build Syntax
!logonsession LUID [InfoLevel]
Parameters
LUID
Specifies the locally unique identifier (LUID) of a logon session to display. If LUID is 0, information about all logon sessions is displayed.
To display information about the system session and all system tokens in a checked build, enter !logonsession 3e7 1.
InfoLevel
(Checked Build Only) Specifies how much token information is displayed. The InfoLevel parameter can take values from 0 to 4, with 0 representing the least information
and 4 representing the most information.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
Here is an example of the output from this extension on a free build:
kd> !logonsession 0
Dumping all logon sessions.
** Session
0
LogonId
References
** Session
1
LogonId
References
** Session
2
LogonId
References
** Session
3
LogonId
References
** Session
4
LogonId
References
** Session
5
LogonId
References
** Session
6
LogonId
References

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

0x0
{0x0 0x0}
0
0x8ebb50
{0xe9f1 0x0}
21
0x6e31e0
{0x94d1 0x0}
1
0x8ecd60
{0x6b31 0x0}
0
0xe0000106
{0x0 0x0}
0
0x0
{0x0 0x0}
0
0x8e9720
{0x3e4 0x0}
6

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

** Session
7
LogonId
References
** Session
8
LogonId
References
** Session
9
LogonId
References
** Session 10
LogonId
References
** Session 11
LogonId
References
** Session 12
LogonId
References
** Session 13
LogonId
References
14 sessions in

Page 527 of 1651

= 0xe0000106
= {0x0 0x0}
= 0
= 0xa2e160
= {0x3e5 0x0}
= 3
= 0xe0000106
= {0x0 0x0}
= 0
= 0x3ca0
= {0x3e6 0x0}
= 2
= 0xe0000106
= {0x0 0x0}
= 0
= 0x1cd0
= {0x3e7 0x0}
= 33
= 0xe0000106
= {0x0 0x0}
= 0
the system.

You can stop execution at any point by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For information about logon sessions, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!lookaside
The !lookaside extension displays information about look-aside lists, resets the counters of look-aside lists, or modifies the depth of a look-aside list.
Syntax
!lookaside [Address [Options [Depth]]]
Parameters
Address
Specifies the hexadecimal address of a look-aside list to be displayed or modified. If Address is 0 or omitted, a set of well-known, standard system look-aside lists is
displayed or modified. The set of lists is not exhaustive; that is, it does not include all system look-aside lists. Also, the set does not include custom look-aside lists that
were created by calls to ExInitializePagedLookasideList or ExInitializeNPagedLookasideList.
Options
Controls what operation will be taken. The following possible Options are supported. The default is zero:
0
Displays information about the specified look-aside list or lists.
1
Resets the counters of the specified look-aside list.
2
Modifies the depth of the specified look-aside list. This option can only be used if Address is nonzero.
Depth
Specifies the new maximum depth of the specified look-aside list. This parameter is permitted only if Address is nonzero and Options is equal to 2.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Look-aside lists are multiprocessor-safe mechanisms for managing pools of fixed-size entries from either paged or nonpaged memory.
Look-aside lists are efficient, because the routines do not use spin locks on most platforms.
Note that if the current depth of a look-aside list exceeds the maximum depth of that list, then freeing a structure associated with that list will result in freeing it into pool
memory, rather than list memory.
Here is an example of the output from this extension:
kd> !lookaside e0000165f7621800
Lookaside "" @ e0000165f7621800 "Ntfs"

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Type
=
Current Depth
Size
AllocateMisses
TotalAllocates
Hit Rate

Page 528 of 1651

0011 PagedPool RaiseIfAllocationFailure

=
0
Max Depth =
4
=
488
Max Alloc =
1952
=
3
FreeMisses =
0
=
4
TotalFrees =
4
=
25% Hit Rate
=
100%

Additional Information
For information about look-aside lists, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!lpc
The !lpc extension displays information about all local procedure call (LPC) ports and messages in the target system.
Syntax
Syntax in Windows 2000
!lpc
!lpc
!lpc
!lpc
!lpc

message MessageID
port Port
scan Port
thread Thread

Syntax in Windows Server 2003 and Windows XP

!lpc
!lpc
!lpc
!lpc
!lpc
!lpc

message MessageID
port Port
scan Port
thread Thread
PoolSearch

Parameters
message
(Windows Server 2003, Windows XP, and Windows 2000 only) Displays information about a message, such as the server port that contains the message in the queue, and
the thread waiting for this message, if any.
MessageID
(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the message ID of the message to be displayed. If the value of this parameter is 0 or this
parameter is omitted, the !lpc message command displays a summary list of messages. (In Windows 2000 with Service Pack 1 (SP1), the summary includes all messages
in the LPC zone. In Windows 2000 with Service Pack 2 (SP2), Windows XP, and later versions of Windows, the summary includes all messages in the kernel pool.
Paged-out messages are not included.)
port
(Windows Server 2003, Windows XP, and Windows 2000 only) Displays port information, such as the name of the port, its semaphore state, messages in its queues,
threads in its rundown queue, its handle count, its references, and related ports.
scan
(Windows Server 2003, Windows XP, and Windows 2000 only) Displays summary information about the specified port and about all ports that are connected to it.
Port
(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the hexadecimal address of the port to be displayed. If the !lpc port command is used, and Port
is 0 or is omitted, a summary list of all LPC ports is displayed. If the !lpc scan command is used, Port must specify the address of an actual port.
thread
(Windows Server 2003, Windows XP, and Windows 2000 only) Displays port information for all ports that contain the specified thread in their rundown port queues.
Thread
(Windows Server 2003, Windows XP, and Windows 2000 only) Specifies the hexadecimal address of the thread. If this is 0 or omitted, the !lpc thread command displays
a summary list of all threads that are performing any LPC operations.
PoolSearch
(Windows Server 2003 and Windows XP only) Determines whether the !lpc message command searches for messages in the kernel pool. Each time !lpc PoolSearch is
used, this setting toggles on or off (the initial setting is to not search the kernel pool). This only affects !lpc message commands that specify a nonzero value for
MessageID.
DLL
Windows 2000
Kdextx86.dll
Windows XP
Kdexts.dll
Windows Server 2003
Comments
This extension is not supported in Windows Vista and later versions of Windows.
In Windows Server 2003, Windows XP, and Windows 2000, using !lpc with no arguments displays help for this extension in the Debugger Command window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 529 of 1651

If you have a thread that is marked as waiting for a reply to a message, use the !lpc message command with the ID of the delayed message. This command displays the
specified message, the port that contains it, and all related threads.
If the message is not found and there were no read errors (such as "Unable to access zone segment"), the server received the message.
In this case, the server port can usually be found by using the !lpc thread command. Threads that are waiting for replies are linked into a server communication queue. This
command will display all ports that contain the specified thread. After you know the port address, use the !lpc port command. More specific information about each thread
can then be obtained by using the !lpc thread command with the address of each thread.
Here are several examples of the output from this extension from a Windows XP system:
In this example, all port LPC ports are displayed.
kd> !lpc port
Scanning 225 objects
1 Port: 0xe1405650
1 Port: 0xe141ef50
1 Port: 0xe13c5740
1 Port: 0xe13d9550
3 Port: 0xe13d8830
80000004 Port: 0xe13d8910
3 Port: 0xe13d8750
.....

Connection:
Connection:
Connection:
Connection:
Connection:
Connection:
Connection:

0xe1405650
0xe141ef50
0xe13c5740
0xe13d9550
0xe141ef50
0xe141ef50
0xe13d9550

Communication:
Communication:
Communication:
Communication:
Communication:
Communication:
Communication:

0x00000000
0x00000000
0x00000000
0x00000000
0xe13d8910
0xe13d8830
0xe13a4030

'SeRmCommandPort'
'SmApiPort'
'ApiPort'
'SbApiPort'
''
''
''

In the previous example, the port at address e14ae238 has no messages; that is, all messages have been picked up and no new messages have arrived.
kd> !lpc port e14ae238
Server connection port e14ae238 Name: ApiPort
Handles: 1
References: 107
Server process : 84aa0140 (csrss.exe)
Queue semaphore : 84a96da8
Semaphore state 0 (0x0)
The message queue is empty
The LpcDataInfoChainHead queue is empty
In the previous example, the port at 0xe14ae238 has messages which have been queued, but not yet picked up by the server.
kd> !lpc port 0xe14ae238
Server connection port e14ae238 Name: ApiPort
Handles: 1
References: 108
Server process : 84aa0140 (csrss.exe)
Queue semaphore : 84a96da8
Semaphore state 0 (0x0)
Messages in queue:
0000 e20d9b80 - Busy Id=0002249c From: 0584.0680 Context=00000021 [e14ae248 . e14ae248]
Length=0098007c Type=00000001 (LPC_REQUEST)
Data: 00000000 0002021e 00000584 00000680 002f0001 00000007
The message queue contains 1 messages
The LpcDataInfoChainHead queue is empty
The remaining Windows XP examples concern the other options that can be used with this extension.
kd> !lpc message 222be
Searching message 222be in threads ...
Client thread 842a4db0 waiting a reply from 222be
Searching thread 842a4db0 in port rundown queues ...
Server communication port 0xe114a3c0
Handles: 1
References: 1
The LpcDataInfoChainHead queue is empty
Connected port: 0xe1e7b948
Server connection port: 0xe14ae238
Client communication port 0xe1e7b948
Handles: 1
References: 3
The LpcDataInfoChainHead queue is empty
Server connection port e14ae238 Name: ApiPort
Handles: 1
References: 107
Server process : 84aa0140 (csrss.exe)
Queue semaphore : 84a96da8
Semaphore state 0 (0x0)
The message queue is empty
The LpcDataInfoChainHead queue is empty
Done.
kd> !lpc thread 842a4db0
Searching thread 842a4db0 in port rundown queues ...
Server communication port 0xe114a3c0
Handles: 1
References: 1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 530 of 1651

The LpcDataInfoChainHead queue is empty

Connected port: 0xe1e7b948
Server connection port: 0xe14ae238
Client communication port 0xe1e7b948
Handles: 1
References: 3
The LpcDataInfoChainHead queue is empty
Server connection port e14ae238 Name: ApiPort
Handles: 1
References: 107
Server process : 84aa0140 (csrss.exe)
Queue semaphore : 84a96da8
Semaphore state 0 (0x0)
The message queue is empty
The LpcDataInfoChainHead queue is empty
kd> !lpc scan e13d8830
Scanning 225 objects
3 Port: 0xe13d8830 Connection: 0xe141ef50
80000004 Port: 0xe13d8910 Connection: 0xe141ef50
Scanning 3 objects

Communication: 0xe13d8910
Communication: 0xe13d8830

''
''

Additional Information
For information about LPCs, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!mca
On an x86 target computer, the !mca extension displays the machine check architecture (MCA) registers. On an Itanium target computer, the !mca extension displays the
MCA error record.
Syntax
Syntax for x86 target computer
!mca
Syntax for Itanium target computer
!mca Address [Flags]
Parameters
Address
(Itanium target only) Specifies the address of the MCA error record.
Flags
(Itanium target only) Specifies the level of output. Flags can be any combination of the following bits. The default value is 0xFF, which displays all sections present in
the log.
Bit 0 (0x1)
Displays the processor section.
Bit 1 (0x2)
Displays the platform-specific section.
Bit 2 (0x4)
Displays the memory section.
Bit 3 (0x8)
Displays the PCI component section.
Bit 4 (0x10)
Displays the PCI bus section.
Bit 5 (0x20)
Displays the SystemEvent Log section.
Bit 6 (0x40)
Displays the platform host controller section.
Bit 7 (0x80)
Displays to include the platform bus section.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based or Itanium target computer.
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 531 of 1651

On an Itanium target, !mca displays the MCA error record from the system abstraction layer (SAL). Here is an example of the output from this extension:
kd> !mca e0000165f3f58000
hal!HalpFeatureBits: 0xf [HAL_PERF_EVENTS|HAL_MCA_PRESENT|HAL_CMC_PRESENT|HAL_CPE_PRESENT]
MCA Error Record Header @ 0xe0000165f3f58000 0xe0000165f3f597a8
Id
: 8
Revision
:
Revision
: 2
Minor
: 0x2 ''
Major
: 0 ''
ErrorSeverity
: 0 ''
Valid
:
Valid
: 0 ''
OemPlatformID
: 0y0
Reserved
: 0y0000000 (0)
Length
: 0x17a8
TimeStamp
:
TimeStamp
: 0x20031106`00134944
Seconds
: 0x44 'D'
Minutes
: 0x49 'I'
Hours
: 0x13 ''
Reserved
: 0 ''
Day
: 0x6 ''
Month
: 0x11 ''
Year
: 0x3 ''
Century
: 0x20 ' '
OemPlatformId
: [16] ""

Severity

: ErrorRecoverable

MCA Error Section Header

Header
:
Guid
:
Data1
Data2
Data3
Data4
Revision
:
Revision
Minor
Major
RecoveryInfo
:
RecoveryInfo
Corrected
NotContained
Reset
Reserved
Valid
Reserved
:
Length
:
Valid
:
Valid
:
ErrorMap
:
StateParameter
:
CRLid
:
StaticStruct
:
CacheCheckNum
:
TlbCheckNum
:
BusCheckNum
:
RegFileCheckNum :
MsCheckNum
:
CpuIdInfo
:
Reserved
:
ErrorMap
:
ErrorMap
:
Cid
:
Tid
:
Eic
:
Edc
:
Eit
:
Edt
:
Ebh
:
Erf
:
Ems
:
Reserved
:
StateParameter
:
StateParameter
:
reserved0
:
rz
:
ra
:
me
:

@ 0xe0000165f3f58028 0xe0000165f3f59578

:
:
:
:

[Processor]

0xe429faf1
0x3cb7
0x11d4
[8] "???"

: 2
: 0x2 ''
: 0 ''
:
:
:
:
:
:

0 ''
0y0
0y0
0y0
0y0000
0y0
0 ''
0x1550
0x100101f
0y1
0y1
0y1
0y1
0y0001
0y0000
0y0001
0y0000
0y0000
0y1
0y000000000000000000000000000000000000000 (0)
0x1002000
0y0000
0y0000
0y0000
0y0010
0y0000
0y0000
0y0001
0y0000
0y0000000000000000 (0)
0y0000000000000000 (0)
0x28000000`fff21130
0y00
0y0
0y0
0y1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

mn
sy
co
ci
us
hd
tl
mi
pi
pm
dy
in
rs
cm
ex
cr
pc
dr
tr
rr
ar
br
pr
fp
b1
b0
gr
dsize
reserved1
cc
tc
bc
rc
uc
CRLid
LocalId
reserved
eid
id
ignored

Page 532 of 1651

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

0y1
0y0
0y0
0y1
0y0
0y0
0y0
0y1
0y0
0y0
0y0
0y0
0y1
0y0
0y0
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y1
0y0000000000000000 (0)
0y00000000000 (0)
0y1
0y0
0y1
0y0
0y0

:
:
:
:
:

0
0y0000000000000000 (0)
0y00000000 (0)
0y00000000 (0)
0y00000000000000000000000000000000 (0)

CacheErrorInfo[0]:
Valid
: 1
CheckInfo
: 0y1
RequestorIdentifier : 0y0
ResponderIdentifier : 0y0
TargetIdentifier : 0y0
PreciseIP
: 0y0
Reserved
: 0y00000000000000000000000000000000000000000000000000000000000 (0)
CheckInfo
: 0x0
RequestorId
: 0x0
ResponderId
: 0x0
TargetIp
: 0x0
TargetId
: 0x0
PreciseIp
: 0x0
CheckInfo:
CacheCheck
: 0
Operation
: 0y0000
Level
: 0y00
Reserved1
: 0y00
DataLine
: 0y0
TagLine
: 0y0
DataCache
: 0y0
InstructionCache : 0y0
MESI
: 0y000
MESIValid
: 0y0
Way
: 0y00000 (0)
WayIndexValid
: 0y0
Reserved2
: 0y0000000000 (0)
Index
: 0y00000000000000000000 (0)
Reserved3
: 0y00
InstructionSet
: 0y0
InstructionSetValid : 0y0
PrivilegeLevel
: 0y00
PrivilegeLevelValid : 0y0
MachineCheckCorrected : 0y0
TargetAddressValid : 0y0
RequestIdValid
: 0y0
ResponderIdValid : 0y0
PreciseIPValid
: 0y0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 533 of 1651

BusErrorInfo[0]:
Valid
: 9
CheckInfo
: 0y1
RequestorIdentifier : 0y0
ResponderIdentifier : 0y0
TargetIdentifier : 0y1
PreciseIP
: 0y0
Reserved
: 0y00000000000000000000000000000000000000000000000000000000000 (0)
CheckInfo
: 0x1080000003000144
RequestorId
: 0x0
ResponderId
: 0x0
TargetIp
: 0x0
TargetId
: 0xd0022004
PreciseIp
: 0x0
CheckInfo:
BusCheck
: 0x10800000`03000144
Size
: 0y00100 (0x4)
Internal
: 0y0
External
: 0y1
CacheTransfer
: 0y0
Type
: 0y00000001 (0x1)
Severity
: 0y00000 (0)
Hierarchy
: 0y00
Reserved1
: 0y0
Status
: 0y00000011 (0x3)
Reserved2
: 0y0000000000000000000000 (0)
InstructionSet
: 0y0
InstructionSetValid : 0y1
PrivilegeLevel
: 0y00
PrivilegeLevelValid : 0y0
MachineCheckCorrected : 0y0
TargetAddressValid : 0y1
RequestIdValid
: 0y0
ResponderIdValid : 0y0
PreciseIPValid
: 0y0
StaticInfo @ 0xe0000165f3f580f0 0xe0000165f3f59578
Valid @ 0xe0000165f3f580f0
Valid
MinState
BR
CR
AR
RR
FR
Reserved

:
:
:
:
:
:
:
:

0x3f
0y1
0y1
0y1
0y1
0y1
0y1
0y0000000000000000000000000000000000000000000000000000000000 (0)

MinState @ 0xe0000165f3f580f8 0xe0000165f3f584f0

IntNats
IntGp
IntT0
IntT1
IntS0
IntS1
IntS2
IntS3
IntV0
IntT2
IntT3
IntT4
IntSp
IntTeb
IntT5
IntT6
B0R16
B0R17
B0R18
B0R19
B0R20
B0R21
B0R22
B0R23
B0R24
B0R25
B0R26

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

0
0xe0000165`f1a99b00
0
0xe0f0e0f0`e0f0e000
0
1
0xe0000000`83068300
0xe0000000`832f8780
0x4600
0x230
0x3ff
0xe0000165`f38c6000
0xe0000165`f0f97da0
0
0
0xfffff630
0x1010`082a6018
0
0xe0000000`830067c0
0x101
0x80000000`00000308
0
0xe0000000`84bedd20
0xe0000000`84bedd20
0xe0000165`f213df5a
0xfff80000`597c84f0
0x6081

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

B0R27
B0R28
B0R29
B0R30
B0R31
IntT7
IntT8
IntT9
IntT10
IntT11
IntT12
IntT13
IntT14
IntT15
IntT16
IntT17
IntT18
IntT19
IntT20
IntT21
IntT22
Preds
BrRp
RsRSC
StIIP
StIPSR
StIFS
XIP
XPSR
XFS

Page 534 of 1651

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

0xfffffe00`00165f20
0x8000465
0x8000465
0x60
0xa04`00000000
0x44
0x200
0xe0000165`f38c6000
0xe0000165`f3cb81bc
0xe0000165`f3cb81b8
0xe0000000`8363f7b0
0xe0000165`f1899d08
0x9804c`8a70433f
0xe0000000`832821f8
0xe0000000`836536e0
0xe0000000`8363f7b8
0xffffffff`fffffbc3
0xe0000165`f1ff6000
0x2400580
0xe0000165`f1ff6004
0xe0000165`f3cb8dc0
0x2277
0xe0000165`ea212df0
3
0xe0000165`f1895370
0x1010`082a6018
0x80000000`00000285
0xe0000165`ea212c50
0x1010`082a6018
0x80000000`00000b1c

BR @ 0xe0000165f3f584f8 0xe0000165f3f58530
e0000165`f3f584f8
e0000165`f3f58500
e0000165`f3f58508
e0000165`f3f58510
e0000165`f3f58518
e0000165`f3f58520
e0000165`f3f58528
e0000165`f3f58530

e0000165`ea212df0 USBPORT!USBPORT_StopDevice+0x850
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
e0000000`832cb061 nt!NtClose+0x1
e0000165`f1895320 usbohci!OHCI_StopController

CR @ 0xe0000165f3f58538 0xe0000165f3f58930
e0000165`f3f58538
e0000165`f3f58540
e0000165`f3f58548
e0000165`f3f58550
...
e0000165`f3f585c8
e0000165`f3f585d0
e0000165`f3f585d8
e0000165`f3f585e0
e0000165`f3f585e8
e0000165`f3f585f0
...
e0000165`f3f58930

00000000`00007e05
00000154`a7047201
e0000000`83230000 nt!KiVhptTransVector
00000000`00000000
00000000`00000000
e0000165`f1895370 usbohci!OHCI_StopController+0x50
e0000165`f213df5a
00000000`00000060
e0000165`f1895360 usbohci!OHCI_StopController+0x40
80000000`00000285
00000000`00000000

AR @ 0xe0000165f3f58938 0xe0000165f3f58d30
e0000165`f3f58938
e0000165`f3f58940
e0000165`f3f58948
e0000165`f3f58950
e0000165`f3f58958
e0000165`f3f58960
e0000165`f3f58968
e0000165`f3f58970
e0000165`f3f58978
e0000165`f3f58980
e0000165`f3f58988
e0000165`f3f58990
e0000165`f3f58998
e0000165`f3f589a0
e0000165`f3f589a8
e0000165`f3f589b0
e0000165`f3f589b8
e0000165`f3f589c0
...
e0000165`f3f58d30

00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000006
e0000000`8301add0 nt!KiMemoryFault
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
e0000165`f1895370 usbohci!OHCI_StopController+0x50
e0000165`f0f988e0
00000000`00000000

RR @ 0xe0000165f3f58d38 0xe0000165f3f58d70

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

e0000165`f3f58d38
e0000165`f3f58d40
e0000165`f3f58d48
e0000165`f3f58d50
e0000165`f3f58d58
e0000165`f3f58d60
e0000165`f3f58d68
e0000165`f3f58d70

Page 535 of 1651

00000000`00000535
00000000`00000535
00000000`00000535
00000000`00000535
00000000`00000535
00000000`00000535
00000000`00000535
00000000`00000535

FR @ 0xe0000165f3f58d78 0xe0000165f3f59570
e0000165`f3f58d78
e0000165`f3f58d80
e0000165`f3f58d88
e0000165`f3f58d90
e0000165`f3f58d98
e0000165`f3f58da0
e0000165`f3f58da8
e0000165`f3f58db0
...
e0000165`f3f59570

00000000`00000000
00000000`00000000
80000000`00000000
00000000`0000ffff
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000
00000000`00000000

MCA Error Section Header @ 0xe0000165f3f59578 0xe0000165f3f596a0

[PciComponent]
Header
:
Guid
:
Data1
: 0xe429faf6
Data2
: 0x3cb7
Data3
: 0x11d4
Data4
: [8] "???"
Revision
:
Revision
: 2
Minor
: 0x2 ''
Major
: 0 ''
RecoveryInfo
:
RecoveryInfo
: 0x80 ''
Corrected
: 0y0
NotContained
: 0y0
Reset
: 0y0
Reserved
: 0y0000
Valid
: 0y1
Reserved
: 0 ''
Length
: 0x128
Valid
:
Valid
: 0x23
ErrorStatus
: 0y1
Info
: 0y1
MemoryMappedRegistersPairs : 0y0
ProgrammedIORegistersPairs : 0y0
RegistersDataPairs : 0y0
OemData
: 0y1
Reserved
: 0y0000000000000000000000000000000000000000000000000000000000 (0)
ErrorStatus
:
Status
: 0x121900
Reserved0
: 0y00000000 (0)
Type
: 0y00011001 (0x19)
Address
: 0y0
Control
: 0y1
Data
: 0y0
Responder
: 0y0
Requestor
: 0y1
FirstError
: 0y0
Overflow
: 0y0
Reserved1
: 0y00000000000000000000000000000000000000000 (0)
Info
:
VendorId
: 0x8086
DeviceId
: 0x100e
ClassCodeInterface : 0 ''
ClassCodeSubClass : 0 ''
ClassCodeBaseClass : 0x2 ''
FunctionNumber
: 0 ''
DeviceNumber
: 0x3 ''
BusNumber
: 0xa0 ''
SegmentNumber
: 0 ''
Reserved0
: 0 ''
Reserved1
: 0
MemoryMappedRegistersPairs : 0
ProgrammedIORegistersPairs : 0
OemData @ 0xe0000165f3f595b8

0xe0000165f3f596a0

Data Length = 0xe6

Data:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

e0000165`f3f595ba
e0000165`f3f595ca
e0000165`f3f595da
e0000165`f3f595ea
e0000165`f3f595fa
e0000165`f3f5960a
e0000165`f3f5961a
e0000165`f3f5962a
e0000165`f3f5963a
e0000165`f3f5964a
e0000165`f3f5965a
e0000165`f3f5966a
e0000165`f3f5967a
e0000165`f3f5968a
e0000165`f3f5969a

Page 536 of 1651

00
2b
00
0e
00
00
00
00
00
00
00
1e
00
00
00

00
f6
00
10
02
d0
00
00
00
00
00
00
00
00
00

00
f7
00
47
20
00
00
00
3c
dc
2a
00
00
00
00

00
a6
00
01
80
00
00
00
10
00
01
00
00
00
00

00
cc
00
30
00
00
00
00
74
00
ff
40
00
00
00

00
ca
00
22
00
00
00
00
12
00
00
04
00
00
00

91
00
00
08
10
18
20
28
30
38
e4
00
00
00

d3-86
ff-ff
00-00
00-00
00-00
00-00
00-00
00-00
00-00
00-00
00-00
00-00
00-00
00-00

d3
ff
00
00
00
00
00
00
00
00
00
00
00
00

7a
ff
08
08
08
08
08
08
08
08
08
00
00
00

5e
ff
00
00
00
00
00
00
00
00
00
00
00
00

7e
ff
00
00
00
00
00
00
00
00
00
00
00
00

48
ff
00
00
00
00
00
00
00
00
00
00
00
00

a4
09
86
02
00
81
00
00
00
00
07
00
00
00

0a
00
80
00
00
a0
00
00
00
00
f0
00
00
00

..........z^~H..
+...............
................
..G.0"..........
.. .............
................
...... .........
......(.........
..<.t.0.........
......8.........
..*.............
....@...........
................
................
......

MCA Error Section Header @ 0xe0000165f3f596a0 0xe0000165f3f597a8

[PciBus]
Header
:
Guid
:
Data1
: 0xe429faf4
Data2
: 0x3cb7
Data3
: 0x11d4
Data4
: [8] "???"
Revision
:
Revision
: 2
Minor
: 0x2 ''
Major
: 0 ''
RecoveryInfo
:
RecoveryInfo
: 0x84 ''
Corrected
: 0y0
NotContained
: 0y0
Reset
: 0y1
Reserved
: 0y0000
Valid
: 0y1
Reserved
: 0 ''
Length
: 0x108
Valid
:
Valid
: 0x74f
ErrorStatus
: 0y1
ErrorType
: 0y1
Id
: 0y1
Address
: 0y1
Data
: 0y0
CmdType
: 0y0
RequestorId
: 0y1
ResponderId
: 0y0
TargetId
: 0y1
OemId
: 0y1
OemData
: 0y1
Reserved
: 0y00000000000000000000000000000000000000000000000000000 (0)
ErrorStatus
:
Status
: 0x121900
Reserved0
: 0y00000000 (0)
Type
: 0y00011001 (0x19)
Address
: 0y0
Control
: 0y1
Data
: 0y0
Responder
: 0y0
Requestor
: 0y1
FirstError
: 0y0
Overflow
: 0y0
Reserved1
: 0y00000000000000000000000000000000000000000 (0)
Type
:
Type
: 0x4 ''
Reserved
: 0 ''
Id
:
BusNumber
: 0xa0 ''
SegmentNumber
: 0 ''
Reserved
: [4] ""
Address
: 0xd0022054
Data
: 0
CmdType
: 0
RequestorId
: 0xfed2a000
ResponderId
: 0
TargetId
: 0xd0022054
OemId
: [16] ".???"
OemData
:
Length
: 0x98

CP M/R/F/A Manufacturer

SerialNumber

Features

Speed

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0 1,5,31,0 GenuineIntel

Page 537 of 1651

0000000000000000 0000000000000001 1000 Mhz

On an x86 target, !mca displays the machine check registers supported by the active processor. It also displays basic CPU information (identical to that displayed by !
cpuinfo). Here is an example of the output from this extension:
0: kd> !mca
MCE: Enabled, Cycle Address: 0x00000001699f7a00, Type: 0x0000000000000000
MCA: Enabled, Banks 5, Control Reg: Supported, Machine Check: None.
Bank Error Control Register
Status Register
0. None
0x000000000000007f
0x0000000000000000
1. None

0x00000000ffffffff

0x0000000000000000

2. None

0x00000000000fffff

0x0000000000000000

3. None

0x0000000000000007

0x0000000000000000

4. None

0x0000000000003fff

0x0000000000000000

No register state available.

CP F/M/S Manufacturer
MHz Update Signature Features
0 15,5,0 SomeBrandName 1394 0000000000000000 a0017fff
Note that this extension requires private HAL symbols. Without these symbols, the extension will display the message "HalpFeatureBits not found" along with basic CPU
information. For example:
kd> !mca
HalpFeatureBits not found
CP F/M/S Manufacturer MHz Update Signature Features
0 6,5,1 GenuineIntel 334 0000004000000000 00001fff

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!memlist
The !memlist extension scans physical memory lists from the page frame number (PFN) database in order to check them for consistency.
Syntax
!memlist Flags
Parameters
Flags
Specifies which memory lists to verify. At present, only one value has been implemented:
Bit 0 (0x1)
Causes the zeroed pages list to be verified.
DLL
Windows 2000
Kdexts.dll
Windows XP and later Kdexts.dll
Comments
At present, this extension will only check the zeroed pages list to make sure that all pages in that list are zeroed. The appropriate syntax is:
kd> !memlist 1

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!memusage
The !memusage extension displays summary statistics about physical memory use.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 538 of 1651

Syntax
Syntax in Windows 2000
!memusage
Syntax in Windows XP and later
!memusage [Flags]
Flags
(Windows XP and later only) Can be any one of the following values. The default is 0x0.
0x0
Displays general summary information, along with a more detailed description of the pages in the PFN database. See the Comments section for an example of this
type of output.
0x1
Displays only summary information about the modified no-write pages in the PFN database..
0x2
Displays only detailed information about the modified no-write pages in the PFN database.
0x8
Displays only general summary information about memory use.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Physical memory statistics are collected from the Memory Manager's page frame number (PFN) database table.
This command takes a long time to run, especially if the target computer is running in 64-bit mode, due to the greater amount of data to obtain. While it is loading the PFN
database, a counter shows its progress. To speed up this loading, increase the COM port speed with the CTRL+A (Toggle Baud Rate) key, or use the .cache (Set Cache Size)
command to increase the cache size (perhaps to around 10 MB).
The !memusage command can also be used while performing local kernel debugging.
Here is an example of the output from this extension:
kd> !memusage
loading PFN database
loading (98% complete)
Compiling memory usage data
Zeroed:
49
Free:
5
Standby:
5489
Modified:
714
ModifiedNoWrite:
1
Active/Valid: 10119
Transition:
6
Unknown:
0
TOTAL: 16383

(100% Complete).
(
196 kb)
(
20 kb)
( 21956 kb)
( 2856 kb)
(
4 kb)
( 40476 kb)
(
24 kb)
(
0 kb)
( 65532 kb)

Building kernel map

Finished building kernel map
Scanning PFN database - (99% complete)
Usage Summary (in Kb):

Control Valid Standby Dirty Shared Locked PageTables

name

8251a258
827ab1b8
8263c408
8252dda8
8272f638
......
82755958
8250b518
8254d8d8
82537be8

12
8
908
0
128

108
1708
48
324
112

0
0
0
0
0

0
0
0
0
116

0
0
0
0
0

mapped_file(
mapped_file(
mapped_file(
mapped_file(
mapped_file(

0
0
0
0

4
4
4
4

0
0
0
0

mapped_file( $Directory )
No Name for File
mapped_file( $Directory )
mapped_file( Windows Explorer.lnk )

---------------------------------------------------------

1348
492
3364
972
496
1144
944
412

0
0
1384
0
1456
0
0
0

0
0
1396
0
384
0
0
0

---------------------------------

904
72
188
88
164
120
156
64

process
process
process
process
process
process
process
process

(
(
(
(
(
(
(
(

cscui.dll )
$Mft )
win32k.sys )
ShellIconCache )
advapi32.dll )

System )
winmine.exe )
explorer.exe )
services.exe )
winmgmt.exe )
svchost.exe )
winlogon.exe )
csrss.exe )

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 539 of 1651

......
--------

0 ----- -----

process ( wmiadap.exe )

---------------

316
4096

0
0

0 ----- ----0 ----- -----

0
0

pagefile section (346e)

pagefile section (9ad)

----------------------------......
-------------------------------------------

884
88
8
12

280
8
0
0

36
0
0
0

-----------------

0
0
0
0

-----------------

driver
driver
driver
driver

(
(
(
(

ntoskrnl.exe )
hal.dll )
kdcom.dll )
BOOTVID.dll )

8
16
56
2756
1936
0

0
0
0
1060
128
0

0
0
0
876
148
0

-------------------------

0
0
0
0
0
0

-------------------------

driver
driver
driver
driver
driver
driver

(
(
(
(
(
(

ndisuio.sys )
dump_scsiport.sys )
dump_aic78xx.sys )
Paged Pool )
Kernel Stacks )
NonPaged Pool )

The first column displays the address of the control area structure that describes each mapped structure. Use the !ca extension command to display these control areas.
Comments
You can use the !vm extension command to analyze virtual memory use. This extension is typically more useful than !memusage. For more information about memory
management, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
The !pfn extension command can be used to display a particular page frame entry in the PFN database.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!mps
The !mps extension displays BIOS information for the Intel Multiprocessor Specification (MPS) of the target computer.
Syntax
!mps [Address]
Parameters
Address
Specifies the hexadecimal address of the MPS table in the BIOS. If this is omitted, the information is obtained from the HAL. This will require HAL symbols.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
Additional Information
For more information about BIOS debugging, see Debugging BIOS Code. For more information about the MPS, refer to the appropriate version of the Intel MultiProcessor
Specification.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!mtrr
The !mtrr extension displays the contents of the MTRR register.
Syntax
!mtrr
DLL
Windows 2000

Kdextx86.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 540 of 1651

Windows XP and later Kdexts.dll

This extension command can only be used with an x86-based target computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!npx
The !npx extension displays the contents of the floating-point register save area.
Syntax
!npx Address
Parameters
Address
Specifies the hexadecimal address of the FLOATING_SAVE_AREA structure.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ob, !od, !ow

The !ob, !od, and !ow extension commands are obsolete. Use the ob, od, ow (Output to Port) commands instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!object
The !object extension displays information about a system object.
Syntax
!object
!object
!object
!object

Address
0 Name
Path
-r

Parameters
Address
If the first argument is a nonzero hexadecimal number, it specifies the hexadecimal address of the system object for which to display information.
Name
If the first argument is zero, the second argument is interpreted as the name of a class of system objects for which to display all instances.
Path
If the first argument begins with a backslash (\), !object interprets it as an object path name. When this option is used, the display will be arranged according to the
directory structure used by the Object Manager.
-r
Causes cached values of global variables to be refreshed.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 541 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !object extension caches certain global variables whose values can change. If the set of kernel symbols you are using has become stale, use !object -r to refresh the
cached values.
The following example obtains an object pointer by executing the !handle extension:
kd> !handle
processor number 0
PROCESS 80a02920 Cid: 0002
Peb: 00000000 ParentCid: 0000
DirBase: 0006c805 ObjectTable: 80a03788 TableSize: 54.
Image: System
006c: Object: 80967768 GrantedAccess: 00100003
Object: 80967768 Type: (809d5c20) File
ObjectHeader: 80967750
HandleCount: 1 PointerCount: 1
Directory Object: 00000000 Name: \WINNT\system32\config\software {Partition1}
kd> !object 80967768
Object: 80967768 Type: (809d5c20) File
ObjectHeader: 80967750
HandleCount: 1 PointerCount: 1
Directory Object: 00000000 Name: \WINNT\system32\config\software {Partition1}
Additional Information
For information about objects and the object manager, see the Microsoft Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft
Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!obtrace
The !obtrace extension displays object reference tracing data for the specified object.
Syntax
!obtrace Object
Parameters
Object
A pointer to the object or a path.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
The object reference tracing feature of Windows records sequential stack traces whenever an object reference counter is incremented or decremented.
Before using this extension to display object reference tracing data, you must use GFlags to enable object reference tracing for the specified object. You can enable object
reference tracing as a kernel flag (run-time) setting, in which the change is effective immediately, but disappears if you shut down or restart; or as a registry setting, which
requires a restart, but remains effective until you change it.
Here is an example of the output from the !obtrace extension:
kd> !obtrace 0xfa96f700
Object: fa96f700
Image: cmd.exe
Sequence (+/-) Stack
-------- ----- --------------------------------------------------2421d
+1 nt!ObCreateObject+180
nt!NtCreateEvent+92
nt!KiFastCallEntry+104
nt!ZwCreateEvent+11
win32k!UserThreadCallout+6f
win32k!W32pThreadCallout+38
nt!PsConvertToGuiThread+174
nt!KiBBTUnexpectedRange+c

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 542 of 1651

2421e

-1

nt!ObfDereferenceObject+19
nt!NtCreateEvent+d4
nt!KiFastCallEntry+104
nt!ZwCreateEvent+11
win32k!UserThreadCallout+6f
win32k!W32pThreadCallout+38
nt!PsConvertToGuiThread+174
nt!KiBBTUnexpectedRange+c

2421f

nt!ObReferenceObjectByHandle+1c3
win32k!xxxCreateThreadInfo+37d
win32k!UserThreadCallout+6f
win32k!W32pThreadCallout+38
nt!PsConvertToGuiThread+174
nt!KiBBTUnexpectedRange+c

24220

nt!ObReferenceObjectByHandle+1c3
win32k!ProtectHandle+22
win32k!xxxCreateThreadInfo+3a0
win32k!UserThreadCallout+6f
win32k!W32pThreadCallout+38
nt!PsConvertToGuiThread+174
nt!KiBBTUnexpectedRange+c

24221

-1

nt!ObfDereferenceObject+19
win32k!xxxCreateThreadInfo+3a0
win32k!UserThreadCallout+6f
win32k!W32pThreadCallout+38
nt!PsConvertToGuiThread+174
nt!KiBBTUnexpectedRange+c

---- ---------------------------------------------------------References: 3, Dereferences 2

The primary indicators in the !obtrace 0xfa96f700 display are listed in the following table.
Parameter
Meaning
Sequence Represents the order of operations.
+/Indicates a reference or a dereference operation.
+1 indicates a reference operation.
-1 indicates a dereference operation.
+/-n indicates multiple reference/dereference operations.

The object reference traces on x64-based target computers might be incomplete because it is not always possible to acquire stack traces at IRQL levels higher than
PASSIVE_LEVEL.
You can stop execution at any time by pressing CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For more information about the Global Flags utility (GFlags), see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and
David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!openmaps
The !openmaps extension displays the referenced buffer control blocks (BCBs) and virtual address control blocks (VACBs) for the specified shared cache map.
Syntax
!openmaps Address [Flag]
Parameters
Address
Specifies the address of the shared cache map.
Flag
Determines which control blocks are displayed. If Flag is 1, the debugger displays all control blocks. If Flag is 0, the debugger displays only referenced control blocks.
The default is 0.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 543 of 1651

DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, see the !cchelp extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pars
The !pars extension displays a specified processor application registers file.
Syntax
!pars Address
Parameters
Address
Specifies the address of a processor application registers file.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium-based target computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pat
The !pat extension displays the Page Attribute Table (PAT) registers for the target processor.
Syntax
!pat Flag
!pat
Parameters
Flag
If Flag is set, the debugger verifies that the PAT feature is present before the PAT is displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pci

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 544 of 1651

The !pci extension displays the current status of the peripheral component interconnect (PCI) buses, as well as any devices attached to those buses.
Syntax
!pci [Flags [Segment] [Bus [Device [Function [MinAddress MaxAddress]]]]]
Parameters
Flags
Specifies the level of output. Can be any combination of the following bits:
Bit 0 (0x1)
Causes a verbose display.
Bit 1 (0x2)
Causes the display to include all buses in the range from bus 0 (zero) to the specified Bus.
Bit 2 (0x4)
Causes the display to include information in raw byte format. If MinAddress, MaxAddress, or flag bit 0x8 is set, this bit is automatically set as well.
Bit 3 (0x8)
Causes the display to include information in raw DWORD format.
Bit 4 (0x10)
Causes the display to include invalid device numbers. If Device is specified, this flag is ignored.
Bit 5 (0x20)
Causes the display to include invalid function numbers.
Bit 6 (0x40)
Causes the display to include capabilities.
Bit 7 (0x80)
Causes the display to include Intel 8086 device-specific information.
Bit 8 (0x100)
Causes the display to include the PCI configuration space.
Bit 9 (0x200)
Causes the display to include segment information. When this bit is included, the Segment parameter must be included.
Bit 10 (0x400)
Causes the display to include all valid segments in the range from segment 0 to the specified segment. When this bit is included, the Segment parameter must be
included.
Segment
Specifies the number of the segment to be displayed. Segment numbers range from 0 to 0xFFFF. If Segment is omitted, information about the primary segment (segment
0) is displayed. If Flags includes bit 10 (0x400), Segment specifies the highest valid segment to be displayed.
Bus
Specifies the bus to be displayed. Bus can range from 0 to 0xFF. If it is omitted, information about the primary bus (bus 0) is displayed. If Flags includes bit 1 (0x2), Bus
specifies the highest bus number to be displayed.
Device
Specifies the slot device number for the device. If this is omitted, information about all devices is printed.
Function
Specifies the slot function number for the device. If this is omitted, all information about all device functions is printed.
MinAddress
Specifies the first address from which raw bytes or DWORDs are to be displayed. This must be between 0 and 0xFF.
MaxAddress
Specifies the last address from which raw bytes or DWORDs are to be displayed. This must be between 0 and 0xFF, and not less than MinAddress.
DLL
Windows 2000

Kext.dll
Kdextx86.dll
Windows XP and later Kext.dll
This extension command can only be used with an x86-based target computer.
Comments
To edit the PCI configuration space, use !ecb, !ecd, or !ecw.
The following example displays a list of all buses and their devices. This command will take a long time to execute. You will see a moving counter at the bottom of the
display while the debugger scans the target system for PCI buses:
kd> !pci 2 ff
PCI Bus 0
00:0 8086:1237.02
0d:0 8086:7000.01
0d:1 8086:7010.00
0e:0 1011:0021.02
10:0 102b:0519.01
PCI Bus 1
08:0 10b7:9050.00
09:0 9004:8178.00

Cmd[0106:.mb..s]
Cmd[0007:imb...]
Cmd[0005:i.b...]
Cmd[0107:imb..s]
Cmd[0083:im....]

Sts[2280:.....]
Sts[0280:.....]
Sts[0280:.....]
Sts[0280:.....]
Sts[0280:.....]

Device Host bridge

Device ISA bridge
Device IDE controller
PciBridge 0->1-1 PCI-PCI bridge
Device VGA compatible controller

Cmd[0107:imb..s]
Cmd[0117:imb..s]

Sts[0200:.....]
Sts[0280:.....]

Device
Device

Ethernet
SCSI controller

This example displays verbose information about the devices on the primary bus. The two-digit number at the beginning of each line is the device number; the one-digit
number following it is the function number:
kd> !pci 1 0
PCI Bus 0
00:0 8086:1237.02
cf8:80000000

Cmd[0106:.mb..s] Sts[2280:.....]
IntPin:0 IntLine:0 Rom:0 cis:0

Device
cap:0

Host bridge

0d:0

Cmd[0007:imb...]

Device

ISA bridge

8086:7000.01

Sts[0280:.....]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 545 of 1651

cf8:80006800

IntPin:0

IntLine:0

Rom:0

cis:0

cap:0

0d:1

8086:7010.00
cf8:80006900
IO[4]:fff1

Cmd[0005:i.b...] Sts[0280:.....]
IntPin:0 IntLine:0 Rom:0 cis:0

0e:0

1011:0021.02
cf8:80007000
IO:f000-ffff

Cmd[0107:imb..s] Sts[0280:.....] PciBridge 0->1-1 PCI-PCI bridge

IntPin:0 IntLine:0 Rom:0 cap:0 2sts:2280 BCtrl:6 ISA
Mem:fc000000-fdffffff PMem:fff00000-fffff

10:0

102b:0519.01 Cmd[0083:im....] Sts[0280:.....]

cf8:80008000 IntPin:1 IntLine:9 Rom:80000000
MEM[0]:fe800000 MPF[1]:fe000008

Device
cap:0

IDE controller

Device VGA compatible controller

cis:0 cap:0

This example shows even more detailed information about bus 0 (zero), device 0x0D, and function 0x1, including the raw DWORDS from addresses between 0x00 and 0x3F:
kd> !pci f 0 d 1 0 3f
PCI Bus 0
0d:1 8086:7010.00 Cmd[0005:i.b...] Sts[0280:.....]
cf8:80006900 IntPin:0 IntLine:0 Rom:0 cis:0
IO[4]:fff1
00000000: 70108086 02800005 01018000 00002000
00000010: 00000000 00000000 00000000 00000000
00000020: 0000fff1 00000000 00000000 00000000
00000030: 00000000 00000000 00000000 00000000

Device
cap:0

IDE controller

This example displays the configuration space for segment 1, bus 0, device 1:
0: kd> !pci 301 1 0 1
PCI Configuration Space (Segment:0001 Bus:00 Device:01 Function:00)
Common Header:
00: VendorID
14e4 Broadcom Corporation
02: DeviceID
16c7
04: Command
0146 MemSpaceEn BusInitiate PERREn SERREn
06: Status
02b0 CapList 66MHzCapable FB2BCapable DEVSELTiming:1
.
.
.
5a: MsgCtrl
64BitCapable MultipleMsgEnable:0 (0x1) MultipleMsgCapable:3 (0x8)
5c: MsgAddr
2d4bff00
60: MsgAddrHi
1ae09097
64: MsData
9891

To display all devices and buses on valid segments, issue the command !pci 602 ffff ff:
0: kd> !pci 602 ffff ff
Scanning the following PCI segments: 0 0x1
PCI Segment 0 Bus 0
01:0 14e4:16c7.10 Cmd[0146:.mb.ps] Sts[02b0:c6...]
02:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
02:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
03:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
03:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
PCI Segment 0 Bus 0x38
01:0 14e4:1644.12 Cmd[0146:.mb.ps] Sts[02b0:c6...]
PCI Segment 0 Bus 0x54
00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....]
PCI Segment 0 Bus 0x70
00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....]
PCI Segment 0 Bus 0xa9
01:0 8086:b154.00 Cmd[0147:imb.ps] Sts[0ab0:c6.A.]
PCI Segment 0 Bus 0xaa
04:0 1033:0035.41 Cmd[0146:.mb.ps] Sts[0210:c....]
04:1 1033:0035.41 Cmd[0146:.mb.ps] Sts[0210:c....]
04:2 1033:00e0.02 Cmd[0146:.mb.ps] Sts[0210:c....]
05:0 1002:5159.00 Cmd[0187:imb..s] Sts[0290:c....]
PCI Segment 0 Bus 0xc6
00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....]
PCI Segment 0 Bus 0xe3
00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....]
PCI Segment 0x1 Bus 0
01:0 14e4:16c7.10 Cmd[0146:.mb.ps] Sts[02b0:c6...]
02:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
02:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
03:0 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
03:1 1000:0030.08 Cmd[0147:imb.ps] Sts[0230:c6...]
PCI Segment 0x1 Bus 0x54
00:0 103c:403b.00 Cmd[0547:imb.ps] Sts[0010:c....]
PCI Segment 0x1 Bus 0x55
00:0 8086:10b9.06 Cmd[0147:imb.ps] Sts[0010:c....]

Ethernet
LSI SCSI
LSI SCSI
LSI SCSI
LSI SCSI

Controller
Controller
Controller
Controller
Controller

SubID:103c:1321
SubID:103c:1323
SubID:103c:1323
SubID:103c:1323
SubID:103c:1323

Ethernet Controller

SubID:10b7:1000

HP PCI-PCI Bridge 0x54->0x55-0x55

HP PCI-PCI Bridge 0x70->0x71-0x71
Intel PCI-PCI Bridge 0xa9->0xaa-0xaa
NEC
NEC
NEC
ATI

USB Controller SubID:103c:1293

USB Controller SubID:103c:aa55
USB2 Controller SubID:103c:aa55
VGA Compatible Controller SubID:103c:1292

HP PCI-PCI Bridge 0xc6->0xc7-0xc7

HP PCI-PCI Bridge 0xe3->0xe4-0xe4
Ethernet
LSI SCSI
LSI SCSI
LSI SCSI
LSI SCSI

Controller
Controller
Controller
Controller
Controller

SubID:103c:1321
SubID:103c:1323
SubID:103c:1323
SubID:103c:1323
SubID:103c:1323

HP PCI-PCI Bridge 0x54->0x55-0x55

Intel Ethernet Controller

0200 905010b7 (d=8, f=0) devext fe515ee8 Network Controller/Ethernet
0100 81789004 (d=9, f=0) devext fe515ce8 Mass Storage Controller/SCSI

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 547 of 1651

0300 0519102b (d=10, f=0) devext fe4f4428 Display Controller/VGA

Total PCI Root busses processed = 1
To understand this display, consider the final device shown. Its base class is 03, its subclass is 00, its Device ID is 0x0519, and its Vendor ID is 0x102B. These values are all
intrinsic to the device itself.
The number after "d=" is the device number; the number after "f=" is the function number. After "devext" is the device extension address, 0xFE4F4428. Finally, the base class
name and the subclass name appear.
To obtain more information about a device, use the !devext extension command with the device extension address as the argument. For this particular device, the command to
use would be:
kd> !devext fe4f4428 pci
If the !pcitree extension generates an error, this often means that your PCI symbols were not loaded properly. Use .reload pci.sys to fix this problem.
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about PCI buses and PCI device objects, see the Windows Driver Kit (WDK)
documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pcm
The !pcm extension displays the specified private cache map. This extension is only available in Windows 2000.
Syntax
!pcm Address
Parameters
Address
Specifies the address of the private cache map.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable (see Comments section)
Comments
This extension is supported only in Windows 2000. In Windows XP and later versions of Windows, use the dt nt!_PRIVATE_CACHE_MAP Address command.
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, see the !cchelp extension reference.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pcr
The !pcr extension displays the current status of the Processor Control Region (PCR) on a specific processor.
Syntax
!pcr [Processor]
Parameters
Processor
Specifies the processor to retrieve the PCR information from. If Processor is omitted, the current processor is used.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 548 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The processor control block (PRCB) is an extension of the PCR. It can be displayed with the !prcb extension.
Here is an example of the !pcr extension on an x86 target computer:
kd> !pcr 0
KPCR for Processor 0 at ffdff000:
Major 1 Minor 1
NtTib.ExceptionList: 801626e0
NtTib.StackBase: 801628f0
NtTib.StackLimit: 8015fb00
NtTib.SubSystemTib: 00000000
NtTib.Version: 00000000
NtTib.UserPointer: 00000000
NtTib.SelfTib: 00000000
SelfPcr:
Prcb:
Irql:
IRR:
IDR:
InterruptMode:
IDT:
GDT:
TSS:

ffdff000
ffdff120
00000000
00000000
ffffffff
00000000
80043400
80043000
803cc000

CurrentThread: 8015e8a0
NextThread: 00000000
IdleThread: 8015e8a0
DpcQueue:

0x80168ee0 0x80100d04 ntoskrnl!KiTimerExpiration

One of the entries in this display shows the interrupt request level (IRQL). The !pcr extension shows the current IRQL, but the current IRQL is usually not of much interest.
The IRQL that existed just before the bug check or debugger connection is more interesting. This is displayed by !irql, which is only available on computers running
Windows Server 2003 or later versions of Windows.
Additional Information
For information about the PCR and the PRCB, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pcrs
The !pcrs extension displays the Intel Itanium-specific processor control registers.
Syntax
!pcrs Address
Parameters
Address
Specifies the address of a processor control registers file.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an Itanium-based target computer.
Comments
Do not confuse the !pcrs extension with the !pcr extension, which displays the current status of the processor control region.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 549 of 1651

December 09, 2009

Debugging Tools for Windows

!pfn
The !pfn extension displays information about a specific page frame or the entire page frame database.
Syntax
!pfn PageFrame
Parameters
PageFrame
Specifies the hexadecimal number of the page frame to be displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The page frame number for a virtual address can be obtained by using the !pte extension.
Here is an example of the output from this extension:
kd> !pte 801544f4
801544F4 - PDE at C0300800
PTE at C0200550
contains 0003B163
contains 00154121
pfn 3b G-DA--KWV
pfn 154 G--A--KRV
kd> !pfn 3b
PFN 0000003B at address 82350588
flink
00000000 blink / share count 00000221 pteaddress C0300800
reference count 0001
color 0
restore pte 00000000 containing page
000039 Active

kd> !pfn 154

PFN 00000154 at address 82351FE0
flink
00000000 blink / share count 00000001 pteaddress C0200550
reference count 0001
color 0
restore pte 00000060 containing page
00003B Active
M
Modified
Additional Information
For information about page tables, page directories, and page frames, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pmc
The !pmc extension displays the Performance Monitor Counter (PMC) register at the specified address.
This extension is supported only on an Itanium-based target computer.
Syntax
!pmc [- Option] Expression [DisplayLevel]
Parameters
Option
Can be any one of the following values:
gen
Displays the register as a generic PMC register.
btb
Displays the register as a branch trace buffer (BTB) PMC register.
Expression
Specifies the hexadecimal address of a PMC. The expressions @kpfcgen and @kpfcbtb can be used as values for this parameter.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 550 of 1651

If Expression is @kpfcgen, the debugger displays the current processor PMC register as a generic PMC register. You can also display the current processor PMC register
as a generic PMC register by setting Option to gen and using @kpfc4, @kpfc5, @kpfc6, or @kpfc7 for the Expression value.
If Expression is @kpfcbtb, the debugger displays the current processor PMC register as a BTB PMC register. You can also display the current processor PMC register as
a BTB PMC register by setting Option to btb and using @kpfc12 for the Expression value.
DisplayLevel
Can be any one of the following values:
0
Displays only the values of each PMC register field. This is the default.
1
Displays detailed information about the PMC register fields that are not reserved or ignored.
2
Displays detailed information about all PMC register fields, including those that are ignored or reserved.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pmssa
The !pmssa extension displays a specified processor Minimal State Save Area (also known as Min-StateSave Area).
This extension can only be used with an Itanium-based target computer.
Syntax
!pmssa Address
Parameters
Address
Specifies the address of a processor Min-StateSave Area.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pnpevent
The !pnpevent extension displays the Plug and Play device event queue.
Syntax
!pnpevent [DeviceEvent]
Parameters
DeviceEvent
Specifies the address of a device event to display. If this is zero or omitted, the tree of all device events in the queue is displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about Plug and Play drivers, see the Windows Driver Kit (WDK) documentation.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 551 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pocaps
The !pocaps extension displays the power capabilities of the target computer.
Syntax
!pocaps
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of this command's output:
kd> !pocaps
PopCapabilities @ 0x8016b100
Misc Supported Features: S4 FullWake
Processor Features:
Disk Features:
SpinDown
Battery Features:
Wake Caps
Ac OnLine Wake:
Sx
Soft Lid Wake:
Sx
RTC Wake:
Sx
Min Device Wake:
Sx
Default Wake:
Sx
Additional Information
To view the system's power policy, use the !popolicy extension command. For information about power capabilities and power policy, see the Windows Driver Kit (WDK)
documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pool
The !pool extension displays information about a specific pool allocation or about the entire system-wide pool.
Syntax
!pool [Address [Flags]]
Parameters
Address
Specifies the pool entry to be displayed. If Address is -1, this command displays information about all heaps in the process. If Address is 0 or omitted, this command
displays information about the process heap.
Flags
Specifies the level of detail to be used. This can be any combination of the following bit values; the default is zero:
Bit 0 (0x1)
Causes the display to include the pool contents, not just the pool headers.
Bit 1 (0x2)
Causes the display to suppress pool header information for all pools, except the one that actually contains the specified Address.
Bit 31 (0x80000000)
(Windows XP and later) Suppresses the description of the pool type and pool tag in the display.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 552 of 1651

In Windows XP and later versions of Windows, the !pool extension displays the pool tag associated with each allocation. The owner of that pool tag is also displayed. This
display is based on the contents of the pooltag.txt file. This file is located in the triage subdirectory of your Debugging Tools for Windows installation. If you want , you can
edit this file to add additional pool tags relevant to your project.
Warning If you install an updated version of Debugging Tools for Windows in the same directory as the current version, it overwrites all of the files in that directory,
including pooltag.txt. If you modify or replace the sample pooltag.txt file, be sure to save a copy of it to a different directory. After reinstalling the debuggers, you can copy
the saved pooltag.txt over the default version.
If the !pool extension reports pool corruption, you should use !poolval to investigate.
Here is an example. If Address specifies 0xE1001050, the headers of all pools in this block are displayed, and 0xE1001050 itself is marked with an asterisk (*).
kd> !pool
e1001000
e1001040
*e1001050
e1001060
e1001070
e1001080
e10010c0
.....

e1001050
size:
40
size:
10
size:
10
size:
10
size:
10
size:
40
size:
10

previous
previous
previous
previous
previous
previous
previous

size:
size:
size:
size:
size:
size:
size:

0
40
10
10
10
10
40

(Allocated) MmDT
(Free)
Mm
(Allocated) *ObDi
(Allocated) ObDi
(Allocated) Symt
(Allocated) ObDm
(Allocated) ObDi

In this example, the right-most column shows the pool tag. The column to the left of this shows whether the pool is free or allocated.
The following command shows the pool headers and pool contents:
kd> !pool e1001050 1
e1001000 size:
40 previous size:
0 (Allocated)
e1001008 ffffffff 0057005c 004e0049 004f0044
e1001018 ffffffff 0053005c 00730079 00650074
e1001040 size:
10 previous size:
40 (Free)
e1001048 ffffffff e1007ba8 e1501a58 01028101
e1001058 ffffffff 00000000 e1000240 01028101

MmDT

*e1001050 size:
10 previous size:
10 (Allocated) *ObDi
e1001058 ffffffff 00000000 e1000240 01028101
e1001068 ffffffff 00000000 e10009c0 01028101
e1001060 size:
10 previous size:
10 (Allocated)
e1001068 ffffffff 00000000 e10009c0 01028101
e1001078 ffffffff 00000000 00000000 04028101

ObDi

......
Additional Information
For information about memory pools, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!poolfind
The !poolfind extension finds all instances of a specific pool tag in either nonpaged or paged memory pools.
Syntax
!poolfind TagString [PoolType]
!poolfind TagValue [PoolType]
Parameters
TagString
Specifies the pool tag. TagString is a case-sensitive ASCII string. The asterisk (*) can be used to represent any number of characters; the question mark (?) can be used to
represent exactly one character. Unless an asterisk is used, TagString must be exactly four characters in length.
TagValue
Specifies the pool tag. TagValue must begin with "0x", even if the default radix is 16. If this parameter begins with any other value (including "0X") it will be interpreted
as an ASCII tag string.
PoolType
Specifies the type of pool to be searched. The following values are permitted:
0
Specifies nonpaged memory pool. This is the default.
1
Specifies paged memory pool.
2
Specifies the special pool.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 553 of 1651

4
(Windows XP and later) Specifies the session pool.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This command can take a significant amount of time to execute, depending on the size of pool memory that must be searched. To speed up this execution, increase the COM
port speed with the CTRL+A (Toggle Baud Rate) key, or use the .cache (Set Cache Size) command to increase the cache size (to approximately 10 MB).
The pool tag is the same tag passed to the ExAllocateXxx family of routines.
Here is an example. The entire nonpaged pool is searched and then the paged pool is searched, but the command is terminated before completion (after an hour of operation):
kd> !poolfind SeSd 0
Scanning large pool allocation table for Tag: SeSd (827d1000 : 827e9000)
Searching NonPaged pool (823b1000 : 82800000) for Tag: SeSd
826fa130
82712000
82715940
8271da30
82721c00
8272b3f0
8272d770
8272d7d0
8272d960
82736f30
82763840
8278b730
8278b830
82790130
82799180
827c00e0
827c8320
827ca180
827ec140

size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:

c0
c0
a0
c0
10
60
60
a0
a0
a0
a0
100
10
a0
a0
a0
a0
a0
a0

previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous
previous

size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:
size:

40
0
60
10
30
30
40
60
70
10
10
290
100
20
10
30
60
50
10

(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Free)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Free)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Allocated)
(Allocated)

SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd
SeSd

Searching NonPaged pool (fe7c3000 : ffbe0000) for Tag: SeSd

kd> !poolfind SeSd 1
Scanning large pool allocation table for Tag: SeSd (827d1000 : 827e9000)
Searching Paged pool (e1000000 : e4400000) for Tag: SeSd
e10000b0
e1000260
......
e1221dc0
e1224250

size:
size:

d0 previous size:
d0 previous size:

20
60

(Allocated) SeSd
(Allocated) SeSd

size:
size:

a0 previous size:
a0 previous size:

60
30

(Allocated) SeSd
(Allocated) SeSd

...terminating - searched pool to e1224000

kd>
Additional Information
For information about memory pools and pool tags, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David
Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!poolused
The !poolused extension displays memory use summaries, based on the tag used for each pool allocation.
Syntax
!poolused [Flags [TagString]]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 554 of 1651

Parameters
Flags
Specifies the amount of output to be displayed and the method of sorting the output. This can be any combination of the following bit values, except that bits 1 (0x2) and
2 (0x4) cannot be used together. The default is 0x0, which produces summary information, sorted by pool tag.
Bit 0 (0x1)
Displays more detailed (verbose) information.
Bit 1 (0x2)
Sorts the display by the amount of nonpaged memory use.
Bit 2 (0x4)
Sorts the display by the amount of paged memory use.
Bit 3 (0x8)
(Windows Server 2003 and later) Displays the session pool instead of the standard pool.
TagString
Specifies the pool tag. TagString is a case-sensitive ASCII string. The asterisk (*) can be used to represent any number of characters; the question mark (?) can be used to
represent exactly one character. Unless an asterisk is used, TagString must be exactly four characters in length.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !poolused extension gathers data from the pool tagging feature of Windows. Pool tagging is permanently enabled on Windows Server 2003 and later versions of
Windows. On Windows XP and earlier versions of Windows, you must enable pool tagging by using Gflags.
If you stop executing the extension before it completes, the debugger displays partial results.
The display for this command shows the memory use for each tag in paged pool and nonpaged pool. In both cases, the display includes the number of currently outstanding
allocations for the given tag and the number of bytes being consumed by those allocations.
Here is a partial example of the output from this extension:
0: kd> !poolused
Sorting by Tag
Pool Used:
Tag
1394
1MEM
2MEM
3MEM
8042
AGP
AcdN
AcpA
AcpB
AcpD
AcpF
AcpM
AcpO

NonPaged
Allocs
Used
1
520
1
3368
1
3944
3
248
4
3944
1
344
2
1072
3
192
0
0
40
13280
6
240
0
0
4
208

Paged
Allocs
Used
0
0UNKNOWN pooltag '1394', please update pooltag.txt
0
0UNKNOWN pooltag '1MEM', please update pooltag.txt
0
0UNKNOWN pooltag '2MEM', please update pooltag.txt
0
0UNKNOWN pooltag '3MEM', please update pooltag.txt
0
0PS/2 kb and mouse , Binary: i8042prt.sys
2
384UNKNOWN pooltag 'AGP ', please update pooltag.txt
0
0TDI AcdObjectInfoG
1
504ACPI Pooltags , Binary: acpi.sys
4
576ACPI Pooltags , Binary: acpi.sys
0
0ACPI Pooltags , Binary: acpi.sys
0
0ACPI Pooltags , Binary: acpi.sys
1
128ACPI Pooltags , Binary: acpi.sys
0
0ACPI Pooltags , Binary: acpi.sys

...
WmiG
WmiR
Wmip
Wmit
Wrpa
Wrpc
Wrpi
Wrps
aEoP
fEoP
hSVD
hibr
iEoP
idle
jEoP
mEoP
ohci
rx..
sidg
thdd
usbp
vPrt
TOTAL

30
6960
63
4032
146
3504
1
4096
2
720
1
72
1
120
2
128
1
672
1
16
0
0
0
0
1
24
2
208
1
24
1
88
1
136
3
1248
2
48
0
0
18
77056
0
0
3570214 209120008

0
0
182
7
0
0
0
0
0
0
1
1
0
0
0
0
0
0
0
1
2
18

0Allocation of WMIGUID
0Wmi Registration info blocks
18600Wmi General purpose allocation
49480Wmi Trace
0WAN_ADAPTER_TAG
0WAN_CONN_TAG
0WAN_INTERFACE_TAG
0WAN_STRING_TAG
0UNKNOWN pooltag 'aEoP', please update pooltag.txt
0UNKNOWN pooltag 'fEoP', please update pooltag.txt
40Shared Heap Tag , Binary: mrxdav.sys
24576UNKNOWN pooltag 'hibr', please update pooltag.txt
0UNKNOWN pooltag 'iEoP', please update pooltag.txt
0Power Manager idle handler
0UNKNOWN pooltag 'jEoP', please update pooltag.txt
0UNKNOWN pooltag 'mEoP', please update pooltag.txt
01394 OHCI host controller driver
0UNKNOWN pooltag ' rx', please update pooltag.txt
0GDI spooler events
20480DirectDraw/3D handle manager table
96UNKNOWN pooltag 'usbp', please update pooltag.txt
68160UNKNOWN pooltag 'vPrt', please update pooltag.txt
38769 13066104

Additional Information
For information about memory pools and pool tags, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 555 of 1651

Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!poolval
The !poolval extension analyzes the headers for a pool page and diagnoses any possible corruption. This extension is only available in Windows XP and later versions.
Syntax
!poolval Address [DisplayLevel]
Parameters
Address
Specifies the address of the pool whose header is to be analyzed.
DisplayLevel
Specifies the information to include in the display. This can be any of the following values (the default is zero):
0
Causes basic information to be displayed.
1
Causes basic information and linked header lists to be displayed.
2
Causes basic information, linked header lists, and basic header information to be displayed.
3
Causes basic information, linked header lists, and full header information to be displayed.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Additional Information
For information about memory pools, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!popolicy
The !popolicy extension displays the power policy of the target computer.
Syntax
!popolicy [Address]
Parameters
Address
Specifies the address of the power policy structure to display. If this is omitted, then nt!PopPolicy is displayed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of this command's output:
kd> !popolicy
SYSTEM_POWER_POLICY (R.1) @ 0x80164d58
PowerButton:
Shutdown Flags: 00000003
SleepButton:
None Flags: 00000003
LidClose:
None Flags: 00000001
Idle:
None Flags: 00000001
OverThrottled:
None Flags: c0000004
IdleTimeout:
0 IdleSensitivity:

Event:
Event:
Event:
Event:
Event:

00000000
00000000
00000000
00000000
00000000
50%

Query UI
Query UI
Query
Query
Override NoWakes Critical

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

MinSleep:
LidOpenWake:
WinLogonFlags:
VideoTimeout:
SpinTimeout:
FanTolerance:
MinThrottle:

Page 556 of 1651

S0
S0
1
0
0
0%
0%

MaxSleep:
FastSleep:
S4Timeout:
VideoDim:
OptForPower:
ForcedThrottle:

S0
S0
0
209
1
0%

Additional Information
To view the system's power capabilities, use the !pocaps extension command. For information about power capabilities and power policy, see the Windows Driver Kit
(WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!prcb
The !prcb extension displays the processor control block (PRCB).
Syntax
!prcb [Processor]
Parameters
Processor
Specifies the processor to retrieve the PRCB information from. If Processor is omitted, processor zero will be used.
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll
Comments
The PRCB is an extension of the processor control region (PCR). To display the PCR, use the !pcr extension.
Here is an example:
kd> !prcb
PRCB for Processor 0 at e0000000818ba000:
Threads-- Current e0000000818bbe10 Next 0000000000000000 Idle e0000000818bbe10
Number 0 SetMember 00000001
Interrupt Count -- 0000b81f
Times -- Dpc
00000028 Interrupt 000003ff
Kernel 00005ef4 User
00000385
Additional Information
For information about the PCR and the PRCB, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!process
The !process extension displays information about the specified process, or about all processes, including the EPROCESS block.
This extension can be used only during kernel-mode debugging.
Syntax
Syntax in Windows 2000:
!process [/s Session] [Process [Flags]]
!process [/s Session] 0 Flags ImageName
Syntax in Windows XP and later:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 557 of 1651

!process [/s Session] [/m Module] [Process [Flags]]

!process [/s Session] [/m Module] 0 Flags ImageName
Parameters
/s Session
Specifies the session that owns the desired process.
/m Module
(Windows XP and later only) Specifies the module that owns the desired process.
Process
Specifies the hexadecimal address or the process ID of the process on the target computer.
The value of Process determines whether the !process extension displays a process address or a process ID . If Process is omitted in any version of Windows, the
debugger displays data only about the current system process. If Process is 0 and ImageName is omitted, the debugger displays information about all active processes.
Flags
Specifies the level of detail to display. Flags can be any combination of the following bits. If Flags is 0, only a minimal amount of information is displayed. The default
varies according to the version of Windows and the value of Process. In Windows 2000, the default is 0x3 if Process is omitted or if Process is 0 and ImageFile is
omitted; otherwise, the default is 0xF. In Windows XP and later, the default is 0x3 if Process is omitted or if Process is either 0 or -1; otherwise, the default is 0xF.
Bit 0 (0x1)
Displays time and priority statistics.
Bit 1 (0x2)
Displays a list of threads and events associated with the process, and their wait states.
Bit 2 (0x4)
Displays a list of threads associated with the process. If this is included without Bit 1 (0x2), each thread is displayed on a single line. If this is included along with
Bit 1, each thread is displayed with a stack trace.
Bit 3 (0x8)
(Windows XP and later) Displays the return address, the stack pointer, and (on Itanium-based systems) the bsp register value for each function. The display of
function arguments is suppressed.
Bit 4 (0x10)
(Windows XP and later) Sets the process context equal to the specified process for the duration of this command. This results in a more accurate display of thread
stacks. Because this flag is equivalent to using .process /p /r for the specified process, any existing user-mode module list will be discarded. If Process is zero, the
debugger displays all processes, and the process context is changed for each one. If you are only displaying a single process and its user-mode state has already been
refreshed (for example, with .process /p /r), it is not necessary to use this flag. This flag is only effective when used with Bit 0 (0x1).
ImageName
Specifies the name of the process to be displayed. The debugger displays all processes whose executable image names match ImageName. The image name must match
that in the EPROCESS block. In general, this is the executable name that was invoked to start the process, including the file extension (usually .exe), and truncated after
the fifteenth character. There is no way to specify an image name that contains a space. When ImageName is specified, Process must be zero.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The following is an example of a !process 0 0 display:
kd> !process 0 0
**** NT ACTIVE PROCESS DUMP ****
PROCESS 80a02a60 Cid: 0002
Peb:
DirBase: 00006e05 ObjectTable:
Image: System
PROCESS 80986f40 Cid: 0012
Peb:
DirBase: 000bd605 ObjectTable:
Image: smss.exe
PROCESS 80958020 Cid: 001a
Peb:
DirBase: 0008b205 ObjectTable:
Image: csrss.exe
PROCESS 80955040 Cid: 0020
Peb:
DirBase: 00112005 ObjectTable:
Image: winlogon.exe
PROCESS 8094fce0 Cid: 0026
Peb:
DirBase: 00055005 ObjectTable:
Image: services.exe
PROCESS 8094c020 Cid: 0029
Peb:
DirBase: 000c4605 ObjectTable:
Image: lsass.exe
PROCESS 809258e0 Cid: 0044
Peb:
DirBase: 001e5405 ObjectTable:
Image: SPOOLSS.EXE

00000000
80a03788

ParentCid: 0000
TableSize: 150.

7ffde000
8098fce8

ParentCid: 0002
TableSize: 38.

7ffde000
809782a8

ParentCid: 0012
TableSize: 150.

7ffde000
80955ce8

ParentCid: 0012
TableSize: 54.

7ffde000
80950cc8

ParentCid: 0020
TableSize: 222.

7ffde000
80990fe8

ParentCid: 0020
TableSize: 110.

7ffde000
80925c68

ParentCid: 0026
TableSize: 70.

The following table describes some of the elements of the !process 0 0 output.
Element
Process address

Meaning
The eight-character hexadecimal number after the word PROCESS is the address of the EPROCESS block. In the final entry in the preceding
example, the process address is 0x809258E0.
Process ID (PID)
The hexadecimal number after the word Cid. In the final entry in the preceding example, the PID is 0x44, or decimal 68.
Process Environment Block The hexadecimal number after the word Peb is the address of the process environment block. In the final entry in the preceding example, the
(PEB)
PEB is located at address 0x7FFDE000.
Parent process PID
The hexadecimal number after the word ParentCid is the PID of the parent process. In the final entry in the preceding example, the parent
process PID is 0x26, or decimal 38.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 558 of 1651

Image
Process object address

The name of the module that owns the process. In the final entry in the preceding example, the owner is spoolss.exe. In the first entry, the
owner is the operating system itself.
The hexadecimal number after the word ObjectTable. In the final entry in the preceding example, the address of the process object is
0x80925c68.

To display full details on one process, set Flags to 7. The process itself can be specified by setting Process equal to the process address, setting Process equal to the process
ID, or setting ImageName equal to the executable image name. Here is an example:
kd> !process fb667a00 7
PROCESS fb667a00 Cid: 0002 Peb: 00000000 ParentCid: 0000
DirBase: 00030000 ObjectTable: e1000f88 TableSize: 112.
Image: System
VadRoot fb666388 Clone 0 Private 4. Modified 9850. Locked 0.
FB667BBC MutantState Signalled OwningThread 0
Token
e10008f0
ElapsedTime
15:06:36.0338
UserTime
0:00:00.0000
KernelTime
0:00:54.0818
QuotaPoolUsage[PagedPool]
1480
Working Set Sizes (now,min,max) (3, 50, 345)
PeakWorkingSetSize
118
VirtualSize
1 Mb
PeakVirtualSize
1 Mb
PageFaultCount
992
MemoryPriority
BACKGROUND
BasePriority
8
CommitCharge
8
THREAD fb667780 Cid 2.1 Teb: 00000000 Win32Thread: 80144900 WAIT: (WrFreePage) KernelMode Non-Alertable
80144fc0 SynchronizationEvent
Not impersonating
Owning Process fb667a00
WaitTime (seconds)
32278
Context Switch Count 787
UserTime
0:00:00.0000
KernelTime
0:00:21.0821
Start Address Phase1Initialization (0x801aab44)
Initial Sp fb26f000 Current Sp fb26ed00
Priority 0 BasePriority 0 PriorityDecrement 0 DecrementCount 0
ChildEBP RetAddr Args to Child
fb26ed18 80118efc c0502000 804044b0 00000000 KiSwapThread+0xb5
fb26ed3c 801289d9 80144fc0 00000008 00000000 KeWaitForSingleObject+0x1c2
Note that the address of the process object can be used as input to other extensions, such as !handle, to obtain further information.
The following table describes some of the elements in the previous example.
Element
WAIT
ElapsedTime
UserTime
KernelTime
Working Set sizes
QuotaPoolUsage
entries
Clone
Private

Meaning
The parenthetical comment after this heading gives the reason for the wait. The command dt nt!_KWAIT_REASON will display a list of all
wait reasons.
Lists the amount of time that has elapsed since the process was created. This is displayed in units of Hours : Minutes : Seconds . Milliseconds.
Lists the amount of time the process has been running in user mode. If the value for UserTime is exceptionally high, it might identify a process that is
depleting system resources. Units are the same as those of ElapsedTime.
Lists the amount of time the process has been running in kernel mode. If the value for KernelTime is exceptionally high, it might identify a process
that is depleting system resources. Units are the same as those of ElapsedTime.
Lists the current, minimum and maximum working set size for the process, in pages. An exceptionally large working set size can be a sign of a
process that is leaking memory or depleting system resources.
Lists the paged and nonpaged pool used by the process. On a system with a memory leak, looking for excessive nonpaged pool usage on all the
processes can tell you which process has the memory leak.
Indicates whether or not the process was created by the POSIX or Interix subsystems.
Indicates the number of private (non-sharable) pages currently being used by the process. This includes both paged in and paged out memory.

In addition to the process list information, the thread information contains a list of the resources on which the thread has locks. This information is listed in the third line of
output after the thread header. In this example, the thread has a lock on one resource, a SynchronizationEvent with an address of 80144fc0. By comparing this address to the
list of locks shown by the !kdext*.locks extension, you can determine which threads have exclusive locks on resources.
The !stacks extension gives a brief summary of the state of every thread. This can be used instead of the !process extension to get a quick overview of the system, especially
when debugging multithread issues, such as resource conflicts or deadlocks.
Additional Information
For information about processes in kernel mode, see Changing Contexts. For more information about analyzing processes and threads, see Microsoft Windows Internals, by
Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 559 of 1651

Debugging Tools for Windows

!processfields
The !processfields extension displays the names and offsets of the fields within the executive process (EPROCESS) block.
Syntax
!processfields
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable (see the Comments section)
Comments
This extension command is not available in Windows XP or later versions of Windows. Instead, use the dt (Display Type) command to show the EPROCESS structure
directly:
kd> dt nt!_EPROCESS
Here is an example of !processfields from a Windows 2000 system:
kd> !processfields
EPROCESS structure offsets:
Pcb:
ExitStatus:
LockEvent:
LockCount:
CreateTime:
ExitTime:
LockOwner:
UniqueProcessId:
ActiveProcessLinks:
QuotaPeakPoolUsage[0]:
QuotaPoolUsage[0]:
PagefileUsage:
CommitCharge:
PeakPagefileUsage:
PeakVirtualSize:
VirtualSize:
Vm:
DebugPort:
ExceptionPort:
ObjectTable:
Token:
WorkingSetLock:
WorkingSetPage:
ProcessOutswapEnabled:
ProcessOutswapped:
AddressSpaceInitialized:
AddressSpaceDeleted:
AddressCreationLock:
ForkInProgress:
VmOperation:
VmOperationEvent:
PageDirectoryPte:
LastFaultCount:
VadRoot:
VadHint:
CloneRoot:
NumberOfPrivatePages:
NumberOfLockedPages:
ForkWasSuccessful:
ExitProcessCalled:
CreateProcessReported:
SectionHandle:
Peb:
SectionBaseAddress:
QuotaBlock:
LastThreadExitStatus:
WorkingSetWatch:
InheritedFromUniqueProcessId:
GrantedAccess:
DefaultHardErrorProcessing
LdtInformation:
VadFreeHint:
VdmObjects:
DeviceMap:

0x0
0x6c
0x70
0x80
0x88
0x90
0x98
0x9c
0xa0
0xa8
0xb0
0xb8
0xbc
0xc0
0xc4
0xc8
0xd0
0x120
0x124
0x128
0x12c
0x130
0x150
0x154
0x155
0x156
0x157
0x158
0x17c
0x180
0x184
0x1f0
0x18c
0x194
0x198
0x19c
0x1a0
0x1a4
0x182
0x1aa
0x1ab
0x1ac
0x1b0
0x1b4
0x1b8
0x1bc
0x1c0
0x1c8
0x1cc
0x1d0
0x1d4
0x1d8
0x1dc
0x1e0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

ImageFileName[0]:
VmTrimFaultValue:
Win32Process:
Win32WindowStation:

Page 560 of 1651

0x1fc
0x20c
0x214
0x1c4

Additional Information
For information about the EPROCESS block, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!psp
The !psp extension displays the processor state parameter (PSP) register at the specified address.
This extension is supported only on Itanium-based target computers.
Syntax
!psp Address [DisplayLevel]
Parameters
Address
Specifies the hexadecimal address of the PSP register to display.
DisplayLevel
Can be any one of the following options:
0
Displays only the values of each PSP field. This is the default.
1
Displays more in-depth information on each of the PSP fields that is not reserved or ignored.
2
Displays more in-depth information on all of the PSP fields, including those that are ignored or reserved.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!pte
The !pte extension displays the page table entry (PTE) and page directory entry (PDE) for the specified address.
Syntax
Syntax in Windows 2000
!pte
!pte
!pte
!pte

VirtualAddress
PTE
LiteralAddress 1
StartAddress EndAddress

Introduction

Page 563 of 1651

9de9000 12f000
2b0c000 130000
87cd000 131000
aaf6000 140000
...
...
The numbers in the left column are the physical addresses of each memory page that has a mapping for this process. The numbers in the right column are the virtual addresses
to which they are mapped.
The total display is very long.
Additional Information
For related topics, see !vtop and Converting Virtual Addresses to Physical Addresses. For information about page tables and page directories, see Microsoft Windows
Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!qlocks
The !qlocks extension displays the state of all queued spin locks.
Syntax
!qlocks
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This command is useful only on a multiprocessor system.
Here is an example:
0: kd> !qlocks
Key: O = Owner, 1-n = Wait order, blank = not owned/waiting, C = Corrupt

Lock Name
KE
KE
MM
MM
CC
CC
EX
IO
EX
IO
IO
IO
NTFS
AFD
CC
MM

Processor Number
1 2 3

Dispatcher
Unused Spare
PFN
System Space
Vacb
Master
NonPagedPool
Cancel
WorkQueue
Vpb
Database
Completion
Struct
WorkQueue
Bcb
MM NonPagedPool

Additional Information
For information about spin locks, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ready

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 564 of 1651

The !ready extension displays summary information about each thread in the system in a READY state.
Syntax
!ready [Flags]
Parameters
Flags
Specifies the level of detail to display. Flags can be any combination of the following bits. If Flags is 0, only a minimal amount of information is displayed. The default
is 0x6.
Bit 1 (0x2)
Causes the display to include the thread's wait states.
Bit 2 (0x4)
If this is included without Bit 1 (0x2), this has no effect. If this is included along with Bit 1, the thread is displayed with a stack trace.
Bit 3 (0x8)
(Windows XP and later) Causes the display of each function to include the return address, the stack pointer, and (on Itanium systems) the bsp register value. The
display of function arguments is suppressed.
Bit 4 (0x10)
(Windows XP and later) Causes the display of each function to include only the return address; arguments and stack pointers are suppressed.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The output from this extension is similar to that of !thread, except that only ready threads are displayed, and they are sorted in order of decreasing priority.
Additional Information
For information about thread scheduling and the READY state, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!reg
The !reg extension displays and searches through registry data.
Syntax
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg
!reg

kcb Address
knode Address
kbody Address
kvalue Address
valuelist HiveAddress KeyNodeAddress
subkeylist HiveAddress KeyNodeAddress
cellindex HiveAddress Index
baseblock HiveAddress
seccache HiveAddress
hashindex HashKey
openkeys {HiveAddress|0}
findkcb Path
hivelist
viewlist HiveAddress
freebins HiveAddress
freecells BinAddress
dirtyvector HiveAddress
freehints HiveAddress
dumppool [s|r]

Parameters
kcb Address
Displays a registry key control block. Address specifies the address of the key control block.
knode Address
Displays a registry key node structure. Address specifies the address of the key node.
kbody Address
Displays a registry key body (KBODY) structure. Address specifies the address of the key body. (Registry key bodies are the actual objects associated with handles.)
kvalue Address
Displays a registry key value structure. Address specifies the address of the value.
valuelist HiveAddress KeyNodeAddress
Displays a list of the values in the specified key node. HiveAddress specifies the address of the hive. KeyNodeAddress specifies the address of the key node.
subkeylist HiveAddress KeyNodeAddress
Displays a list of the subkeys of the specified key node. HiveAddress specifies the address of the hive. KeyNodeAddress specifies the address of the key node.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 565 of 1651

cellindex HiveAddress Index

Displays the virtual address for a cell in a hive. HiveAddress specifies the address of the hive. Index specifies the cell index.
baseblock HiveAddress
Displays the base block for a hive (also known as the hive header). HiveAddress specifies the address of the hive.
seccache HiveAddress
Displays the security cache for a hive. HiveAddress specifies the address of the hive.
hashindex HashKey
Computes the hash index entry for a hash key. HashKey specifies the key.
openkeys { HiveAddress | 0 }
Displays all open keys in a hive. HiveAddress specifies the address of the hive. If zero is used instead, the entire registry hash table is displayed; this table contains all
open keys in the registry.
findkcb Path
Displays the registry key control block corresponding to a registry path. Path specifies the full key path; this path must be present in the hash table.
hivelist
Displays a list of all hives in the system, along with detailed information about each hive.
viewlist HiveAddress
Displays all pinned and mapped views for a hive, with detailed information for each view. HiveAddress specifies the address of the hive.
freebins HiveAddress
Displays all free bins for a hive, with detailed information for each bin. HiveAddress specifies the address of the hive.
freecells BinAddress
Iterates through a bin and displays all free cells inside it. BinAddress specifies the address of the bin.
dirtyvector HiveAddress
Displays the dirty vector for a hive. HiveAddress specifies the address of the hive.
freehints HiveAddress
Displays free hints. HiveAddress specifies the address of the hive.
dumppool [ s | r ]
Displays registry-allocated paged pool. If s is specified, the list of registry pages is saved to a temporary file. If r is specified, the registry page list is restored from the
previously saved temporary file.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
To display formatted registry key information, use the !dreg extension instead.
Here are are some examples:
kd> !reg hivelist
------------------------------------------------------------------------------------------------------------| HiveAddr |Stable Length|Stable Map|Volatile Length|Volatile Map|MappedViews|PinnedViews|U(Cnt)| BaseBlock |
------------------------------------------------------------------------------------------------------------| e16e7428 |
2000 | e16e7484 |
0
| 00000000 |
1 |
0 |
0| e101f000 |
| e1705a78 |
77000 | e1705ad4 |
1000
| e1705bb0 |
30 |
0 |
0| e101c000 |
| e13d4b88 |
814000 | e146a000 |
1000
| e13d4cc0 |
255 |
0 |
0| e1460000 |
| e13ad008 |
23000 | e13ad064 |
1000
| e13ad140 |
9 |
0 |
0| e145e000 |
| e13b3b88 |
a000 | e13b3be4 |
1000
| e13b3cc0 |
3 |
0 |
0| e145d000 |
| e142d008 |
5000 | e142d064 |
0
| 00000000 |
2 |
0 |
0| e145f000 |
| e11e3628 |
4000 | e11e3684 |
3000
| e11e3760 |
0 |
0 |
0| e11e4000 |
| e10168a8 |
1c1000 | e1016904 |
15000
| e10169e0 |
66 |
0 |
0| e1017000 |
| e10072c8 |
1000 | e1007324 |
0
| 00000000 |
0 |
0 |
0| e1010000 |
-------------------------------------------------------------------------------------------------------------

FileName

\Microsoft\Windows\
ttings\Administrato
emRoot\System32\Con
temRoot\System32\Co
emRoot\System32\Con
<UNKNOWN>
<NONAME>
SYSTEM
<NONAME>

kd> !reg hashindex e16e7428

CmpCacheTable = e100a000
Hash Index[e16e7428] : 5ac
Hash Entry[e16e7428] : e100b6b0
kd> !reg openkeys e16e7428

Index 68: 7bab7683 kcb=e13314f8 cell=00000740 f=00200004 \REGISTRY\USER\S-1-5-21-1715567821-413027322-527237240-500_Classes\CLSI

Index 7a1: 48a30288 kcb=e13a3738 cell=00000020 f=002c0004 \REGISTRY\USER\S-1-5-21-1715567821-413027322-527237240-500_Classes
Additional Information
For information about the registry and its components, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!regkcb

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 566 of 1651

The !regkcb extension displays a registry key control block.

Syntax
!regkcb Address
Parameters
Address
Specifies the address of the key control block.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable
Comments
In Windows 2000, !regkcb displays a specific registry key control block.
In Windows XP and later versions of Windows, the !reg extension command should be used instead.
Every registry key has a control block that contains properties, such as its permissions.
Additional Information
For information about the registry and its components, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rellist
The !rellist extension displays a Plug and Play relation list.
Syntax
!rellist Address [Flags]
Parameters
Address
Specifies the address of the relation list.
Flags
Specifies additional information to include in the display. This can be any combination of the following bits (the default is zero):
Bit 1 (0x2)
Causes the display to include the CM_RESOURCE_LIST. The display also includes the boot resources list, if it is available.
Bit 2 (0x4)
Causes the display to include the resource requirements list (IO_RESOURCE_LIST).
Bit 3 (0x8)
Causes the display to include the translated CM_RESOURCE_LIST.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
See Plug and Play Debugging for applications of this extension command. For information about these list structures, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!running
The !running extension displays a list of running threads on all processors of the target computer.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 567 of 1651

!running [-i] [-t]

Parameters
-i
Causes the display to include idle processors as well.
-t
Causes a stack trace to be displayed for each processor.
DLL
Unavailable
Windows 2000
Windows XP and later Kdexts.dll
Comments
With no options, !running will display the affinity of all active processors and all idle processors. For all active processors, it will also display the current and next thread
fields from the process control block (PRCB) and the state of the 16 built-in queued spin locks.
Here is an example from a multiprocessor Itanium system:
0: kd> !running
System Processors 3 (affinity mask)
Idle Processors 0

0
1

Prcb
Current
Next
e0000000818f8000 e0000000818f9e50 e0000000866f12f0 ................
e000000086f16010 e00000008620ebe0 e000000086eddbc0 .O..............

The 16 characters at the end of each line indicate the built-in queued spin locks (the LockQueue entries in the PRCB). A period ( . ) indicates that the lock is not in use, O
means the lock is owned by this processor, and W means the processor is queued for the lock. To see more information about the spin lock queue, use !qlocks.
Here is an example that shows active and idle processors, along with their stack traces:
0: kd> !running -it
System Processors f (affinity mask)
Idle Processors f
All processors idle.

Prcb
ffdff120

ChildEBP
8053e3f0
8053e3f0
ffdff980
1

Current
805495a0

Next
................

RetAddr
805329c2 nt!RtlpBreakWithStatusInstruction
80533464 nt!_KeUpdateSystemTime+0x126
ffdff980 nt!KiIdleLoop+0x14

f87e0120

f87e2e60

................

ChildEBP RetAddr
f87e0980 f87e0980 nt!KiIdleLoop+0x14
2

f87f0120

f87f2e60

................

ChildEBP RetAddr
f87f0980 f87f0980 nt!KiIdleLoop+0x14
3

f8800120

f8802e60

................

ChildEBP RetAddr
f8800980 f8800980 nt!KiIdleLoop+0x14
Additional Information
For more information about debugging multiprocessor computers, see Multiprocessor Syntax.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!scm
The !scm extension displays the specified shared cache map.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 568 of 1651

!scm Address
Parameters
Address
Specifies the address of the shared cache map.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable
Comments
In Windows XP and later versions of Windows, use the dt nt!_SHARED_CACHE_MAP Address command instead of !scm.
Additional Information
For information about cache management, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
For information about other cache management extensions, see the !cchelp extension.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!search
The !search extension searches pages in physical memory for pointer-sized data that matches the specified criteria.
Syntax
Syntax in Windows 2000
!search Data [ Delta [ StartPFN [ EndPFN ]]]
!search -?
Syntax in Windows XP and later
!search [-s] [-p] Data [ Delta [ StartPFN [ EndPFN ]]]
!search -?
Parameters
-s
(Windows XP and later) Causes symbol check errors to be ignored during the search. This is useful if you are getting too many "incorrect symbols for kernel" errors.
-p
(Windows XP and later) Causes the value of Data to be interpreted as a 32-bit value, preventing any sign extension.
Data
Specifies the data to search for. Data must be the size of a pointer on the target system (32 bits or 64 bits). An exact match for the value of Data is always displayed.
Other matches are displayed as well, depending on the value of Delta; see the Comments section below for details.
Delta
Specifies the allowable difference between a value in memory and the value of Data. See the Comments section below for details.
StartPFN
Specifies the page frame number (PFN) of the beginning of the range to be searched. If this is omitted, the search begins at the lowest physical page.
EndPFN
Specifies the page frame number (PFN) of the end of the range to be searched. If this is omitted, the search ends at the highest physical page.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
If StartPFN and EndPFN are specified, these are taken as the page frame numbers of the beginning and end of the range in physical memory to be searched. For an
explanation of page frame numbers, see Converting Virtual Addresses to Physical Addresses. If StartPFN and EndPFN are omitted, all physical memory is searched.
In Windows 2000, only the first hit on each page is displayed, unless StartPFN and EndPFN are equal to each other. In Windows XP and later, all hits are displayed.
The !search extension will search through all memory for in the specified page range and examine each ULONG_PTR-aligned value. Values that satisfy at least one of the
following criteria are displayed:

The value matches Data exactly.

If Delta is 0 or omitted: The value differs from Data by a single bit.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 569 of 1651

If Delta is nonzero: The value differs from Data by at most Delta. In other words, the value lies in the range [Data - Delta, Data + Delta].
If Delta is nonzero: The value differs from the lowest number in the range (Data - Delta) by a single bit.

In most cases, Data will specify an address you are interested in, but any ULONG_PTR sized data can be specified.
Because the debugger's search engine structures reside in memory on the target computer, if you search all of memory (or any range containing these structures) you will see
matches in the area where the structures themselves are located. If you need to eliminate these matches, do a search for a random value; this will indicate where the debugger's
search structures are located.
Here are some examples. The following will search the memory page with PFN 0x237D for values between 0x80001230 and 0x80001238, inclusive:
kd> !search 80001234 4 237d 237d
The following will search the memory pages ranging from PFN 0x2370 to 0x237F for values that are within one bit of 0x0F100F0F. The exact matches are indicated in bold;
the others are off by one bit:
kd> !search 0f100f0f 0 2370 237f
Searching PFNs in range 00002370 - 0000237F for [0F100F0F - 0F100F0F]
Pfn
Offset
- - - - - - - - 0000237B 00000368
0000237C 00000100
0000237D 000003A8
0000237D 000003C8
0000237D 000003E8
0000237D 00000408
0000237D 00000428
Search done.

Hit
Va
- - - - - - - - 0F000F0F 01003368
0F100F0F 01004100
0F100F0F 010053A8
0F100F8F 010053C8
0F100F0F 010053E8
0F100F0F 01005408
0F100F8F 01005428

Pte
- - - - - - - - C0004014
C0004014
C0004014
C0004014
C0004014
C0004014
C0004014

The columns in the display are as follows: Pfn is the page frame number (PFN) of the page; Offset is the offset on that page; Hit is the value at that address; Va is the virtual
address mapped to this physical address (if this exists and can be determined); Pte is the page table entry (PTE).
To calculate the physical address, shift the PFN left three hexadecimal digits (12 bits) and add the offset. For example, the last line in the table is virtual address 0x0237D000
+ 0x428 = 0x02347D428.
Additional Information
For more ways to display and search physical memory, see Reading and Writing Memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!searchpte
The !searchpte extension searches physical memory for the specified page frame number (PFN).
Syntax
!searchpte PFN
!searchpte -?
Parameters
PFN
Specifies the PFN in hexadecimal format.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
To stop execution at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
For information about page tables and page directories, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 570 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

!sel
The !sel extension command is obsolete. Use the dg (Display Selector) command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!session
In Windows 2000, the !session extension displays one or more user sessions, or displays a specified process running in multiple user sessions.
In Windows XP and later versions of Windows, the !session extension controls the session context. It can also display a list of all user sessions.
Syntax
Syntax in Windows 2000
!session [SessionID [2 Image]]
Syntax in Windows XP and later
!session
!session -s DefaultSession
!session -?
Parameters
SessionID
(Windows 2000 only) Specifies the session ID for the session to be displayed. If this is -1 or omitted, all sessions are displayed.
2 Image
(Windows 2000 only) Specifies the image name of a process. All processes with this name that belong to the session specified by SessionID are displayed. If Image is
omitted, the csrss.exe process is displayed. Omitting this parameter is an easy way of listing all current user sessions, because every user session contains exactly one
csrss.exe process.
-s DefaultSession
(Windows XP and later) Sets the session context to the specified value. If DefaultSession is -1, the session context is set to the current session.
-?
(Windows XP and later) Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This is really two different extensions. The !session extension in Windows 2000 is used to display information about a user session.
The !session extension in Windows XP and later versions of Windows is used to control the session context. Using !session with no parameters will display a list of active
sessions on the target computer. Using !session /s DefaultSession will change the session context to the new default value.
When you set the session context, the process context is automatically changed to the active process for that session. You should always use .cache forcedecodeptes when
this occurs.
For more details and a list of all the session-related extensions that are affected by the session context, see Changing Contexts.
Additional Information
For information about user sessions and the Session Manager (smss.exe), see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!smt

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 571 of 1651

The !smt extension displays a summary of the simultaneous multithreaded processor information.
Syntax
!smt
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
Here is an example:
lkd> !smt
SMT Summary:
-----------KeActiveProcessors: **------------------------------ (00000003)
KiIdleSummary: -------------------------------- (00000000)
No PRCB
Set Master SMT Set
IAID
0 820f4820 Master
**------------------------------ (00000003) 00
1 87a4d120 820f4820
**------------------------------ (00000003) 01
Maximum cores per physical processor:
Maximum logical processors per core:

!stacks [Detail]
Syntax in Windows XP and later:
!stacks [Detail [FilterString]]
Parameters
Detail
Specifies the level of detail to use in the display. The following table lists the valid values for Detail.
0 Displays a summary of the current kernel stacks. This is the default value.
1 Displays stacks that are currently paged out, as well as the current kernel stacks.
2 Displays the full parameters for all stacks, as well as stacks that are currently paged out and the current kernel stacks.
FilterString
(Windows XP and later only) Displays only threads that contain the specified substring in a symbol.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !stacks extension gives a brief summary of the state of every thread. You can use this extension instead of the !process extension to get a quick overview of the system,
especially when debugging multithread issues such as resource conflicts or deadlocks.
The !findstack user-mode extension also displays information about particular stacks.
Here is an example of the simplest !stacks display:
kd> !stacks 0
Proc.Thread .Thread
4.000050

827eea10

ThreadState
Blocked

Blocker
[System]
+0xfe0343a5
[smss.exe]

b0.0000a8
b0.0000c8
b0.0000d0
.....

82723b70
82719620
827d5d50

Blocked
Blocked
Blocked

[csrss.exe]
ntoskrnl!_KiSystemService+0xc4
ntoskrnl!_KiSystemService+0xc4
ntoskrnl!_KiSystemService+0xc4

The first column shows the process ID and the thread ID (separated by a period).
The second column is the current address of the thread's ETHREAD block.
The third column shows the state of the thread (initialized, ready, running, standby, terminated, transition, or blocked).
The fourth column shows the top address on the thread's stack.
Here are examples of more detailed !stacks output:
kd> !stacks 1
Proc.Thread .Thread
4.000008
4.000010
4.000014
4.000018
4.00001c
.....

827d0030
827d0430
827cf030
827cfda0
827cfb10

Blocked
Blocked
Blocked
Blocked
Blocked

Blocker
[System]
ntoskrnl!MmZeroPageThread+0x66
ntoskrnl!ExpWorkerThread+0x189
Stack paged out
Stack paged out
ntoskrnl!ExpWorkerThread+0x189

9c.000098
9c.0000a0
9c.0000a4

82738310
826a5190
82739d30

Blocked
Blocked
Blocked

[smss.exe]
Stack paged out
Stack paged out
Stack paged out

b0.0000bc
b0.0000b4
b0.0000a8
.....

826d0030
826c9030
82723b70

Blocked
Blocked
Blocked

[csrss.exe]
Stack paged out
Stack paged out
ntoskrnl!_KiSystemService+0xc4

kd> !stacks 2
Proc.Thread .Thread
4.000008

827d0030

ThreadState

ThreadState
Blocked

Blocker
[System]
ntoskrnl!KiSwapThread+0xc5
ntoskrnl!KeWaitForMultipleObjects+0x2b4
ntoskrnl!MmZeroPageThread+0x66
ntoskrnl!Phase1Initialization+0xd82

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

4.000010

827d0430

Page 575 of 1651

Blocked

ntoskrnl!PspSystemThreadStartup+0x4d
ntoskrnl!CreateSystemRootLink+0x3d8
+0x3f3f3f3f
ntoskrnl!KiSwapThread+0xc5
ntoskrnl!KeRemoveQueue+0x191

.....
Additional Information
For information about kernel stacks, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!swd
The !swd extension displays the software watchdog timer states for the specified processor, including the deferred procedure call (DPC) and the watchdog timer states for
threads.
Syntax
!swd [Processor]
Parameters
Processor
Specifies the processor. If Processor is omitted, information is displayed for all processors on the target computer.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
The watchdog timer shuts down or restarts Windows if Windows stops responding. The times are displayed in seconds.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!sysinfo
The !sysinfo extension reads and displays specified SMBIOS, Advanced Configuration and Power Interface (ACPI), and CPU information from a dump file or live system.
Syntax
!sysinfo
!sysinfo
!sysinfo
!sysinfo
!sysinfo
!sysinfo
!sysinfo
!sysinfo

cpuinfo [-csv [-noheaders]]

cpumicrocode [-csv [-noheaders]]
cpuspeed [-csv [-noheaders]]
gbl [-csv [-noheaders]]
machineid [-csv [-noheaders]]
registers
smbios [-csv [-noheaders]] {-debug | -devices | -memory | -power | -processor | -system | -v}
-?

Parameters
cpuinfo
Displays information about the processor.
cpumicrocode
(GenuineIntel processors only) Displays the initial and cached microcode processor versions.
cpuspeed
Displays the maximum and current processor speeds.
gbl
Displays the BIOS list of ACPI tables.
machineid
Displays machine ID information for the SMBIOS, BIOS, firmware, system, and baseboard.
registers
Displays machine-specific registers (MSRs).
smbios

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 576 of 1651

Displays the SMBIOS table.

-csv
Displays all data in comma-separated, variable-length (CSV) format.
-noheaders
Suppresses the header for the CSV format.
-debug
Displays output in standard format and CSV format.
-devices
Displays the device entries in the SMBIOS table.
-memory
Displays the memory entries in the SMBIOS table.
-power
Displays the power entries in the SMBIOS table.
-processor
Displays the processor entries in the SMBIOS table.
-system
Displays the system entries in the SMBIOS table.
-v
Verbose. Displays the details of entries in the SMBIOS table.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP base system
Unavailable
Windows 2003 base system
Windows XP, Service Pack 2 and later Kdexts.dll
Windows 2003, Service Pack 1 and later
Comments
This extension is useful only when the dump file is a System Crash File (.dmp) that has not been converted to a minidump file from a kernel or full dump file, or the live
system has finished starting and is online (for example, at the log-in prompt).
You can use any combination of the -debug, -devices, memory, -power, -processor, -system, and -v parameters in a single extension command.
The following parameters are supported only on particular systems:

The gbl parameter works only when the target computer supports ACPI.
The smbios parameter works only when the target computer supports SMBIOS.
The registers parameter does not work on Itanium-based target computers, because they do not collect MSRs.

Microsoft makes every effort to remove personally identifiable information (PII) from these records. All PII is removed from dump files. However, on a live system, some PII
may not yet be removed. As a result, PII fields will be reported as 0 or blank, even if they actually contain information.
To stop execution of commands that include the cpuinfo, gbl, registers, or smbios parameters at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!sysptes
The !sysptes extension displays a formatted view of the system page table entries (PTEs).
Syntax
!sysptes [Flags]
Parameters
Flags
Specifies the level of detail to display. Flags can be any combination of the following bits. The default is zero:
Bit 0 (0x1)
Displays information about free PTEs.
Bit 1 (0x2)
(Windows 2000 only) Displays unused pages in the page usage statistics.
(Windows XP and later) Displays information about free PTEs in the the global special pool.
Bit 2 (0x4)
Displays detailed information about any system PTEs that are allocated to mapping locked pages.)
Bit 3 (0x8)
(Windows 2000 and Windows XP only) Displays nonpaged pool expansion free PTE information. If this bit is set, the other lists are not displayed. If both 0x1 and
0x8 are set, all nonpaged pool expansion free PTEs are displayed. If only 0x8 is set, only the total is displayed.
Bit 4 (0x10)
(Windows Vista and later) Displays special pool free PTE information for the session.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 577 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
To examine a specific PTE, use the !pte extension.
Here is an example from a Windows 2000 system:
kd> !sysptes 1
System PTE Information
Total System Ptes 50962
SysPtes list of size
SysPtes list of size
SysPtes list of size
SysPtes list of size
SysPtes list of size

1
2
4
8
16

has 389 free

has 95 free
has 55 free
has 35 free
has 27 free

starting PTE: c03c7000

ending PTE:
c03f8c44
loading (99% complete)
free ptes: c03c8d60
free blocks: 1
Page
a0
a1
a2
a3
......

number free: 45134.

total free: 45134

largest free block: 45134

Count
2.
2.
2.
2.

In Windows XP and later versions of Windows, the display is similar, except that the page count statistics at the end are not included. Here is an example from a Windows XP
system:
kd> !sysptes 1
System PTE Information
Total System Ptes 571224
SysPtes list of size 1 has 361 free
SysPtes list of size 2 has 91 free
SysPtes list of size 4 has 48 free
SysPtes list of size 8 has 36 free
SysPtes list of size 9 has 29 free
SysPtes list of size 23 has 29 free
starting PTE: fffffe0059388000
ending PTE:
fffffe00597e3ab8
free ptes: fffffe0059388000
free ptes: fffffe00597be558
free ptes: fffffe00597d2828
free blocks: 3

number free: 551557.

number free: 104.
number free: 676.

total free: 552337

largest free block: 551557

Additional Information
For information about page tables and PTEs, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!thread
The !thread extension displays summary information about a thread on the target system, including the ETHREAD block. This command can be used only during kernelmode debugging.
This extension command is not the same as the .thread (Set Register Context) command.
Syntax
Syntax in Windows 2000:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 578 of 1651

!thread [Address [Flags]]

Syntax in Windows XP:
!thread [-p] [-t] [Address [Flags]]
Parameters
-p
Displays summary information about the process that owns the thread.
-t
When this option is included, Address is the thread ID, not the thread address.
Address
Specifies the hexadecimal address of the thread on the target computer. If Address is -1 or omitted, it indicates the current thread.
Flags
Specifies the level of detail to display. Flags can be any combination of the following bits. If Flags is 0, only a minimal amount of information is displayed. The default
is 0x6:
Bit 1 (0x2)
Displays the thread's wait states.
Bit 2 (0x4)
If this bit is used without Bit 1 (0x2), it has no effect. If this bit is used with Bit 1, the thread is displayed with a stack trace.
Bit 3 (0x8)
(Windows XP and later)
Adds the return address, the stack pointer, and (on Itanium systems) the bsp register value to the information displayed for each function and suppresses the display
of function arguments.
Bit 4 (0x10)
(Windows XP and later) Sets the process context equal to the process that owns the specified thread for the duration of this command. This results in more accurate
display of thread stacks.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example from a Windows 2000 system:
kd> !thread ff8632c0
THREAD ff8632c0 Cid 38c.380 Teb: 7ffde000 Win32Thread: e1bc1a08 WAIT: (WrUserRequest) UserMode Non-Alertable
ff8543e0 SynchronizationEvent
Not impersonating
Owning Process ff89c7a0
WaitTime (seconds)
16923
Context Switch Count
67
LargeStack
UserTime
0:00:00.0000
KernelTime
0:00:00.0093
Start Address 0x77e878c1
Win32 Start Address 0x01003dd0
Stack Init fd536000 Current fd535c20 Base fd536000 Limit fd531000 Call 0
Priority 12 BasePriority 8 PriorityDecrement 0 DecrementCount 0
ChildEBP
fd535c38
fd535cbc
fd535d4c
fd535d4c
ffffffff

RetAddr
8012d61c
801672a2
80161691
a01772a8
00000000

Args to Child
00000000 e1bc1a08
00000001 00000001
0006ff08 00000000
0006ff08 00000000
00000000 00000000

00000001
000021bf
00000000
00000000
00000000

ntoskrnl!KiSwapThread+0xc5
ntoskrnl!KeWaitForSingleObject+0x1a1
ntoskrnl!ExFreePool+0xb
ntoskrnl!KiSystemService+0xc4
+0xa01772a8

The important information in the !thread display is explained in the following table.
Parameter
Thread address
Thread ID
Thread Environment
Block (TEB)
System Service Dispatch
Table
Thread State
Owning Process
Start Address
User Thread Function
Priority
Stack trace

Meaning
The hexadecimal number after the word THREAD is the address of the ETHREAD block. In the preceding example, the thread address is
0xFF8632C0.
The two hexadecimal numbers after the word Cid are the process ID and the thread ID: process ID.thread ID. In the preceding example, the
process ID is 0x38C, or decimal 908, and the thread ID is 0x380, or decimal 896.
The hexadecimal number after the word Teb is the address of the thread environment block (TEB). In the preceding example, the TEB is located
at address 0x7FFDE000.
The hexadecimal number after the word Win32Thread is the address of the system service dispatch table. In the preceding example, the system
dispatch table is located at address 0xE1BC1A08.
The thread state is displayed at the end of the line that begins with the word WAIT. In the preceding example, the thread is in a non-alertable
state.
The hexadecimal number after the words Owning Process is the address of the EPROCESS for the process that owns this thread.
The hexadecimal number after the words Start Address is the thread start address. This might appear in symbolic form.
The hexadecimal number after the words Win32 Start Address is the address of the user thread function.
The priority information for the thread follows the word Priority.
A stack trace for the thread appears at the end of this display.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 579 of 1651

Additional Information
For information about threads in kernel mode, see Changing Contexts. For more information about analyzing processes and threads, see Microsoft Windows Internals, by
Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!threadfields
The !threadfields extension displays the names and offsets of the fields within the executive thread (ETHREAD) block.
Syntax
!threadfields
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable (see the Comments section)
Comments
This extension command is not available in Windows XP or later versions of Windows. Instead, use the dt (Display Type) command to show the ETHREAD structure
directly:
kd> dt nt!_ETHREAD
Here is an example of !threadfields from a Windows 2000 system:
kd> !threadfields
ETHREAD structure offsets:
Tcb:
CreateTime:
ExitTime:
ExitStatus:
PostBlockList:
TerminationPortList:
ActiveTimerListLock:
ActiveTimerListHead:
Cid:
LpcReplySemaphore:
LpcReplyMessage:
LpcReplyMessageId:
ImpersonationInfo:
IrpList:
TopLevelIrp:
ReadClusterSize:
ForwardClusterOnly:
DisablePageFaultClustering:
DeadThread:
HasTerminated:
GrantedAccess:
ThreadsProcess:
StartAddress:
Win32StartAddress:
LpcExitThreadCalled:
HardErrorsAreDisabled:

0x0
0x1b0
0x1b8
0x1c0
0x1c4
0x1cc
0x1d4
0x1d8
0x1e0
0x1e8
0x1fc
0x200
0x208
0x20c
0x214
0x21c
0x220
0x221
0x222
0x224
0x228
0x22c
0x230
0x234
0x238
0x239

Additional Information
For information about the ETHREAD block, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!time
The !time extension command is obsolete. Use the .time (Display System Time) command instead.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 580 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!timer
The !timer extension displays a detailed listing of all system timer use.
Syntax
!timer
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !timer extension displays the timer tree, which stores all timer objects in the system.
Here is an example:
kd> !timer
Dump system timers
Interrupt time: 9f760774 00000000 [12/ 8/2000 10:59:22.685 (Pacific Standard Time)]
List Timer
Interrupt Low/High
Fire Time
0 8016aea0 P 9fbd8e00 00000000 [12/ 8/2000 10:59:23.154]
1 8257f118
e4e4225a 00000000 [12/ 8/2000 11:01:19.170]
3 80165fc0
286be1c9 0000594a [ 4/ 1/2001 01:59:59.215]
80165f40
2a7bf8d9 006f105e [12/31/2099 23:59:59.216]
5 825a0bf8
a952e1c2 00000000 [12/ 8/2000 10:59:39.232]
10 8251c7a8
41f54d84 00000001 [12/ 8/2000 11:03:55.310]
8249fe88
41f54d84 00000001 [12/ 8/2000 11:03:55.310]
11 8250e7e8
bc73ffde 00000000 [12/ 8/2000 11:00:11.326]

DPC/thread
ntoskrnl!PopScanIdleList
thread 8257f030
ntoskrnl!ExpTimeZoneDpcRoutine
ntoskrnl!ExpCenturyDpcRoutine
thread 825a0b10
thread 8251c6c0
thread 8249fda0
thread 8250e700

.....
237 82757070
82676348
82728b78
238 fe4b5d78
801658f0
239 8259ad40
250 826d42f0

9f904152
9f904152
9f904152
9f92a3ac
9f92a3ac
765a6f19
1486bed8

00000000
00000000
00000000
00000000
00000000
00000bba
80000000

[12/ 8/2000 10:59:22.857]

[12/ 8/2000 10:59:22.857]
[12/ 8/2000 10:59:22.857]
[12/ 8/2000 10:59:22.873]
[12/ 8/2000 10:59:22.873]
[12/23/2000 09:07:22.900]
[
NEVER
]

+f7a56f2e
+fe516352
+fe516352
thread 827ceb10
ntoskrnl!CcScanDpc
thread 825d3670
thread 825fa030

Total Timers: 193, Maximum List: 7

Current Hand: 226, Maximum Search: 0
Wakeable timers:
Additional Information
For information about timer objects, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tokenfields
The !tokenfields extension displays the names and offsets of the fields within the access token object (the TOKEN structure).
Syntax
!tokenfields
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 581 of 1651

Windows 2000
Kdextx86.dll
Windows XP and later Unavailable (see the Comments section)
Comments
This extension command is not available in Windows XP or later versions of Windows. Instead, use the dt (Display Type) command to show the TOKEN structure directly:
kd> dt nt!_TOKEN
To see a specific instance of the TOKEN structure, use the !token extension.
Here is an example of !tokenfields from a Windows 2000 system:
kd> !tokenfields
TOKEN structure offsets:
TokenSource:
AuthenticationId:
ExpirationTime:
ModifiedId:
UserAndGroupCount:
PrivilegeCount:
VariableLength:
DynamicCharged:
DynamicAvailable:
DefaultOwnerIndex:
DefaultDacl:
TokenType:
ImpersonationLevel:
TokenFlags:
TokenInUse:
ProxyData:
AuditData:
VariablePart:

0x0
0x18
0x28
0x30
0x3c
0x44
0x48
0x4c
0x50
0x54
0x6c
0x70
0x74
0x78
0x79
0x7c
0x80
0x84

Additional Information
For information about the TOKEN structure, see Microsoft Windows Internals, by Mark Russinovich and David Solomon. (The user-mode token structures described in the
Microsoft Windows SDK documentation are slightly different.)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!trap
The !trap extension command is obsolete. Use the .trap (Display Trap Frame) command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tss
The !tss extension command is obsolete. Use the .tss (Display Task State Segment) command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tz
The !tz extension displays the specified power thermal zone structure.
Syntax
!tz [Address]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 582 of 1651

Parameters
Address
The address of a power thermal zone that you want to display. If this parameter is omitted, the display includes all thermal zones on the target computer.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
To stop execution at any time, press CTRL+BREAK (in WinDbg) or CTRL+C (in KD).
Additional Information
To view the system's power capabilities, use the !pocaps extension command. To view the system's power policy, use the !popolicy extension command. For information
about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!tzinfo
The !tzinfo extension displays the contents of the specified thermal zone information structure.
Syntax
!tzinfo Address
Parameters
Address
The address of a thermal zone information structure that you want to display.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Additional Information
To view the system's power capabilities, use the !pocaps extension command. To view the system's power policy, use the !popolicy extension command. For information
about power capabilities and power policy, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ubc
The !ubc extension clears a user-space breakpoint.
Syntax
!ubc BreakpointNumber
Parameters
BreakpointNumber
Specifies the number of the breakpoint to be cleared. An asterisk (*) indicates all breakpoints.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This will permanently delete a breakpoint set with !ubp.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 583 of 1651

See Also
!ubd, !ube, !ubl, !ubp, User Space and System Space
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ubd
The !ubd extension temporarily disables a user-space breakpoint.
Syntax
!ubd BreakpointNumber
Parameters
BreakpointNumber
Specifies the number of the breakpoint to be disabled. An asterisk (*) indicates all breakpoints.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Disabled breakpoints will be ignored. Use !ube to re-enable the breakpoint.
See Also
!ubc, !ube, !ubl, !ubp, User Space and System Space
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ube
The !ube extension re-enables a user-space breakpoint.
Syntax
!ube BreakpointNumber
Parameters
BreakpointNumber
Specifies the number of the breakpoint to be enabled. An asterisk (*) indicates all breakpoints.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This is used to re-enable a breakpoint that was disabled by !ubd.
See Also
!ubc, !ubd, !ubl, !ubp, User Space and System Space
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 584 of 1651

!ubl
The !ubl extension lists all user-space breakpoints and their current status.
Syntax
!ubl
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the use and display of user-space breakpoints:
kd> !ubp 8014a131
This command is VERY DANGEROUS, and may crash your system!
If you don't know what you are doing, enter "!ubc *" now!
kd> !ubp 801544f4
kd> !ubd 1
kd> !ubl
0: e ffffffff`8014a131 (ffffffff`82deb000) 1 ffffffff
1: d ffffffff`801544f4 (ffffffff`82dff000) 0 ffffffff
Each line in this listing contains the breakpoint number, the status (e for enabled or d for disabled), the virtual address used to set the breakpoint, the physical address of the
actual breakpoint, the byte position, and the contents of this memory location at the time the breakpoint was set.
See Also
!ubc, !ubd, !ube, !ubp, User Space and System Space
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ubp
The !ubp extension sets a breakpoint in user space.
Syntax
!ubp Address
Parameters
Address
Specifies the hexadecimal virtual address of the location in user space where the breakpoint is to be set.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The !ubp extension sets a breakpoint in user space. The breakpoint is set on the actual physical page, not just the virtual page.
Setting a physical breakpoint will simultaneously modify every virtual copy of a page, with unpredictable results. One possible consequence is corruption of the system state,
possibly followed by a bug check or other system crash. Therefore, these breakpoints should be used cautiously, if at all.
This extension cannot be used to set breakpoints on pages that have been swapped out of memory. If a page is swapped out of memory after a breakpoint is set, the breakpoint
ceases to exist.
It is not possible to set a breakpoint inside a page table or a page directory.
Each breakpoint is assigned a breakpoint number. To find out the breakpoint number assigned, use !ubl. Breakpoints are enabled upon creation. To step over a breakpoint,
you must first disable it by using !ubd. To clear a breakpoint, use !ubc.
See Also

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 585 of 1651

!ubc, !ubd, !ube, !ubl, User Space and System Space

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!urb
The !urb extension command is obsolete. Use the dt URB command instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!vad
The !vad extension displays details of the virtual address descriptor (VAD) for one or more virtual addresses.
Syntax
!vad VAD-Root [Flags]
Parameters
VAD-Root
Specifies the hexadecimal address of the root of the VAD tree to be displayed.
Flags
Specifies the form the display will take. Possible values include:
0
The entire VAD tree based at VAD-Root is displayed. (This is the default.)
1
Only the VAD specified by VAD-Root is displayed. The display will include a more detailed analysis.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
The address of the root of the VAD for any process can be found by using the !process command.
The !vad command can be very useful when determining what needs to be reloaded when symbols cannot be determined due to paged out memory. For details, see Mapping
Symbols When the PEB is Paged Out.
Here is an example of the !vad extension:
kd> !vad 824bc2f8
VAD
level
82741bf8 ( 1)
824ef368 ( 2)
824bc2f8 ( 0)
8273e508 ( 2)
82643fc8 ( 1)

start
78000
7f6f0
7ffb0
7ffde
7ffdf

Total VADs:

average level:

end
78045
7f7ef
7ffd3
7ffde
7ffdf

commit
8
0
0
1
1
2

Mapped Exe
Mapped
Mapped
Private
Private

EXECUTE_WRITECOPY
EXECUTE_READ
READONLY
EXECUTE_READWRITE
EXECUTE_READWRITE

maximum depth: 2

kd> !vad 824bc2f8 1

VAD @ 824bc2f8
Start VPN:
7ffb0 End VPN:
7ffd3
First ProtoPte: e1008500 Last PTE e100858c
Secured.Flink
0 Blink
0
ViewShare NoChange READONLY

Control Area: 827f1208

Commit Charge
0 (0.)
Banked/Extend:
0 Offset 0

SecNoChange
Additional Information
For information about virtual address descriptors, see Microsoft Windows Internals, by Mark Russinovich and David Solomon.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 586 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!validatelist
The !validatelist extension verifies that the backward and forward links in a doubly-linked list are valid.
Syntax
!validatelist Address
Parameters
Address
The address of the doubly-linked list.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
To stop execution, press Ctrl+Break (in WinDbg) or Ctrl+C (in KD).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!verifier
The !verifier extension displays the status of Driver Verifier and its actions.
Driver Verifier is included in Windows. It works on both checked and free builds. For information about Driver Verifier, see the
Driver Kit (WDK) documentation.

Driver Verifier topic in the Windows

Syntax
Syntax in Windows 2000
!verifier [Flags [Image]]
Syntax in Windows XP and later
!verifier
!verifier
!verifier
!verifier
!verifier
!verifier
!verifier
!verifier
!verifier
!verifier

[Flags [Image]]
4 [Quantity]
8 [Quantity]
0x20 [CompletionTime CancelTime ForceCancellation]
0x40 [Quantity]
0x80 [Quantity]
0x80 Address
0x100 [Quantity]
0x100 Address
?

Parameters
Flags
Specifies what information is displayed in the output from this command. If Flags is equal to the value 4, 8, 0x20, 0x40, 0x80, or 0x100, then the remaining arguments
to !verifier are interpreted based on the the specific arguments associated with those values. If Flags is equal to any other value, even if one or more of these bits are set,
only the Flags and Image arguments are permitted. Flags can be any sum of the following bits; the default is 0:
Bit 0 (0x1)
Displays the names of all drivers being verified. The number of bytes currently allocated to each driver from the nonpaged pool and the paged pool is also displayed.
Bit 1 (0x2)
Displays information about pools (pool size, headers, and pool tags) and outstanding memory allocations left by unloaded drivers. This flag has no effect unless bit 0
(0x1) is also set.
Bit 2 (0x4)
(Windows XP and later) Displays fault injection information. The return address, symbol name, and displacement of the code requesting each allocation are
displayed. If Flags is exactly 0x4 and the Quantity parameter is included, the number of these records displayed can be chosen. Otherwise, four records are
displayed.
Bit 3 (0x8)
(Windows XP and later) Displays the most recent IRQL changes made by the drivers being verified. The old IRQL, new IRQL, processor, and time stamp are

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 587 of 1651

displayed. If Flags is exactly 0x8 and the Quantity parameter is included, the number of these records displayed can be chosen. Otherwise, four records are
displayed.
Bit 5 (0x20)
(Windows Vista and later) Displays information related to the Driver Hang Verification option of Driver Verifier. If the CompletionTime, CancelTime, and
ForceCancellation arguments are specified, these replace the previous the Driver Hang Verification settings.
Bit 6 (0x40)
(Windows Vista and later) Displays information from the Force Pending I/O Requests option of Driver Verifier, including traces from the log of forced pending
IRPs.
The Quantity parameter specifies the number of traces to be displayed. By default, the entire log is displayed.
Bit 7 (0x80)
(Windows Vista and later) Displays information from the kernel pool Allocate/Free log.
The Quantity parameter specifies the number of traces to be displayed. By default, the entire log is displayed.
If Address is specified, only traces associated with the specified address within the kernel pool Allocate/Free log are displayed.
Bit 8 (0x100)
(Windows Vista and later) Displays information from the log of IoAllocateIrp, IoCompleteRequest and IoCancelIrp calls.
The Quantity parameter specifies the number of traces to be displayed. By default, the entire log is displayed.
If Address is specified, only traces associated with the specified IRP address are displayed.
Image
If Flags is used and is not equal to 4, 8, or 0x10, Image specifies the name of a driver. Image is used to filter the information displayed by Flags values of 0x1 and 0x2:
only the specified driver is considered. This driver must be currently verified.
Quantity
(Windows XP and later) If Flags is exactly equal to 0x4, Quantity specifies the number of fault injection records to display. If Flags is exactly equal to 0x8, Quantity
specifies the number of IRQL log entries to display. If Flags is exactly equal to 0x40, Quantity specifies the number of traces displayed from the log of forced pending
IRPs. If Flags is exactly equal to 0x80, Quantity specifies the number of traces displayed from the kernel pool Allocate/Free log. If Flags is exactly equal to 0x100,
Quantity specifies the number of traces displayed from the log of IoAllocateIrp, IoCompleteRequest and IoCancelIrp calls.
CompletionTime
(Windows Vista and later) Specifies the time limit for completing an IRP, in milliseconds. The default value is 0x2710 (10 seconds). If the driver exceeds this limit, the
completion routine is reported in the Driver Hang Verification log. When CompletionTime is 0, Driver Verifier does not monitor IRP completion. This Driver Hang
Verification parameter is supported only when Flags is exactly equal to 0x20.
CancelTime
(Windows Vista and later) Specifies the time limit for canceling an IRP, in milliseconds. The default value is 0x1388 (5 seconds). If the driver exceeds this limit, the
cancellation routine is reported in the Driver Hang Verification log. When CancelTime is 0, Driver Verifier does not monitor IRP cancellation. This Driver Hang
Verification parameter is available only when Flags is exactly equal to 0x20.
ForceCancellation
(Windows Vista and later) Enables or disables the cancellation of IRPs that do not complete within the time specified by CompletionTime. To enable forced cancellation,
set ForceCancellation to 1. To disable forced cancellation, set ForceCancellation to 0. The default is 0. This Driver Hang Verification parameter is available only when
Flags is exactly equal to 0x20.
?
(Windows XP and later) Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
When using Driver Verifier to test graphics drivers, use the !gdikdx.verifier extension instead of !verifier.
The values of 4, 8, and 0x20, 0x40, 0x80, and 0x100 are special values for Flags. If these values are used, the special arguments listed in the Parameters section can be used,
and the display will include only the information associated with that flag value.
If any other value for Flags is used, even if one or more of these bits are set, only the Flags and Image arguments are permitted. In this situation, in addition to all the other
information displayed, !verifier will display the Driver Verifier options that are active, along with statistics on pool allocations, IRQL raises, spin locks, and trims.
If Flags equals 0x20, the values specified for CompletionTime, CancelTime, and ForceCancellation are used by the Driver Hang Verification option of Driver Verifier. These
new values take effect immediately and last until the next boot. When you reboot, they revert to their default values.
Also, if Flags equals 0x20 (with or without additional parameters), the Driver Hang Verification log is printed. For information on interpreting the log, see the Driver Hang
Verification section of the Driver Verifier documentation in the Windows Driver Kit (WDK) documentation.
Here is an example of the !verifier extension on a Windows XP computer. Notice that the display is sorted by driver name:
kd> !verifier 0xf
Verify Level 1f ... enabled options are:
special pool
special irql
inject random pool failures
all pool allocations checked on unload
Io subsystem checking enabled
Summary of All Verifier Statistics
RaiseIrqls

0x0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 588 of 1651

AcquireSpinLocks
Synch Executions
Trims
Pool
Pool
Pool
Pool
Pool
Pool

Allocations
Allocations
Allocations
Allocations
Allocations
Allocations

0x22a
0xbcd7
0x20e
Attempted
Succeeded
Succeeded SpecialPool
With NO TAG
Failed
Failed Deliberately

Current paged pool allocations

Peak paged pool allocations
Current nonpaged pool allocations
Peak nonpaged pool allocations

0x48
0x48
0x48
0x0
0x0
0x0
0x8
0xa
0xb
0xb

for
for
for
for

000002D8
00000494
00003038
00003038

bytes
bytes
bytes
bytes

Driver Verification List

Entry

State

NonPagedPool

PagedPool

Module

fe527df8 Loaded

00002094

000002b8

ftdisk.sys

Current Pool Allocations

Current Pool Bytes
Peak Pool Allocations
Peak Pool Bytes

00000007
000002b8
00000009
00000338

PoolAddress
f7b1bff0
f7b1df88
f7bfbfd0
fe4e4000
f7c19ff8
f7c2bfb0
f7c2df60
f7c47fe0
f7c73f60
f7c8dfe0
f7cb9f60
f7cd3fe0

Tag
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt
ScFt

CallersAddress
fdbac7af
fdbb6e9f
fdbac7af
fdba01e6
fdba2677
fdbac2c1
fdba672e
fdba6968
fdba672e
fdba6968
fdba672e
fdba6968

fe527d68 Loaded

00000f84

00000000

Current Pool Allocations

Current Pool Bytes
Peak Pool Allocations
Peak Pool Bytes

00000000
00000000
00000002
000001bc

PoolAddress
f8a6ff40
f8a71f88
f8cf1b50
f93bb6a0
f93b9fc0

SizeInBytes
0x00000010
0x00000078
0x00000030
0x00002000
0x00000004
0x00000050
0x000000a0
0x00000020
0x000000a0
0x00000020
0x000000a0
0x00000020

00000005
00002094
00000005
00002094

00000005
00000f84
00000005
00000f84

Tag
8042
8042
8042
8042
8042

CallersAddress
fdde2eec
fdde2f3e
fdddf64c
fdde0990
fdddfd0e

fe527cd8 Loaded

00000020

Current Pool Allocations

Current Pool Bytes
Peak Pool Allocations
Peak Pool Bytes

00000001
00000020
00000001
00000020

PoolAddress
f93abfe0
f93affe0

SizeInBytes
0x000000c0
0x00000074
0x000004b0
0x00000960
0x00000040

SizeInBytes
0x00000020
0x00000020

Tag
Flop
Flop

i8042prt.sys

flpydisk.sys

00000001
00000020
00000001
00000020
CallersAddress
fdf5dcb5
fdf5b75d

----------------------------------------------Fault injection trace log

----------------------------------------------No fault injection traces found.
----------------------------------------------Track irql trace log
----------------------------------------------Size of track irql queue is 0x80
Thread:
Old irql:
New irql:
Processor:
Time stamp:

FFFFFFFFFE4FA880
0
2
0
5B97C

FFFFFFFF80535D9E ntoskrnl!VerifierKfAcquireSpinLock+0x28

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 589 of 1651

FFFFFFFFFDB9ED56
FFFFFFFFFDB9F2CA
FFFFFFFF804175BD
FFFFFFFFFDBEA69B
Thread:
Old irql:
New irql:
Processor:
Time stamp:

+0xfffffffffdb9ed56
+0xfffffffffdb9f2ca
ntoskrnl!IopfCallDriver+0x31
+0xfffffffffdbea69b
FFFFFFFFFE4FA880
2
0
0
5B979

FFFFFFFF80535E57
FFFFFFFFFDB9EEED
FFFFFFFFFDB9F2CA
FFFFFFFF804175BD
FFFFFFFFFDBEA69B
Thread:
Old irql:
New irql:
Processor:
Time stamp:

ntoskrnl!VerifierKfReleaseSpinLock+0x67
+0xfffffffffdb9eeed
+0xfffffffffdb9f2ca
ntoskrnl!IopfCallDriver+0x31
+0xfffffffffdbea69b
FFFFFFFFFE4FA880
0
2
0
5B979

FFFFFFFF80535D9E
FFFFFFFFFDB9ED56
FFFFFFFFFDB9F2CA
FFFFFFFF804175BD
FFFFFFFFFDBEA69B
Thread:
Old irql:
New irql:
Processor:
Time stamp:

ntoskrnl!VerifierKfAcquireSpinLock+0x28
+0xfffffffffdb9ed56
+0xfffffffffdb9f2ca
ntoskrnl!IopfCallDriver+0x31
+0xfffffffffdbea69b
FFFFFFFFFE4FA880
2
0
0
5B974

FFFFFFFF80535E57
FFFFFFFFFDB9EEED
FFFFFFFFFDB9F2CA
FFFFFFFF804175BD
FFFFFFFFFDBEA69B

ntoskrnl!VerifierKfReleaseSpinLock+0x67
+0xfffffffffdb9eeed
+0xfffffffffdb9f2ca
ntoskrnl!IopfCallDriver+0x31
+0xfffffffffdbea69b

Here is an example of the !verifier extension on a Windows Vista computer with bit 7 turned on and Address specified.
0: kd> !verifier 80 a2b1cf20
Parsing 00004000 array entries, searching for address a2b1cf20.
=======================================
Pool block a2b1ce98, Size 00000168, Thread a2b1ce98
808f1be6 ndis!ndisFreeToNPagedPool+0x39
808f11c1 ndis!ndisPplFree+0x47
808f100f ndis!NdisFreeNetBufferList+0x3b
8088db41 NETIO!NetioFreeNetBufferAndNetBufferList+0xe
8c588d68 tcpip!UdpEndSendMessages+0xdf
8c588cb5 tcpip!UdpSendMessagesDatagramsComplete+0x22
8088d622 NETIO!NetioDereferenceNetBufferListChain+0xcf
8c5954ea tcpip!FlSendNetBufferListChainComplete+0x1c
809b2370 ndis!ndisMSendCompleteNetBufferListsInternal+0x67
808f1781 ndis!NdisFSendNetBufferListsComplete+0x1a
8c04c68e pacer!PcFilterSendNetBufferListsComplete+0xb2
809b230c ndis!NdisMSendNetBufferListsComplete+0x70
8ac4a8ba test1!HandleCompletedTxPacket+0xea
=======================================
Pool block a2b1ce98, Size 00000164, Thread a2b1ce98
822af87f nt!VerifierExAllocatePoolWithTagPriority+0x5d
808f1c88 ndis!ndisAllocateFromNPagedPool+0x1d
808f11f3 ndis!ndisPplAllocate+0x60
808f1257 ndis!NdisAllocateNetBufferList+0x26
80890933 NETIO!NetioAllocateAndReferenceNetBufferListNetBufferMdlAndData+0x14
8c5889c2 tcpip!UdpSendMessages+0x503
8c05c565 afd!AfdTLSendMessages+0x27
8c07a087 afd!AfdTLFastDgramSend+0x7d
8c079f82 afd!AfdFastDatagramSend+0x5ae
8c06f3ea afd!AfdFastIoDeviceControl+0x3c1
8217474f nt!IopXxxControlFile+0x268
821797a1 nt!NtDeviceIoControlFile+0x2a
8204d16a nt!KiFastCallEntry+0x127
Additional Information
For information about

Driver Verifier , see the Windows Driver Kit (WDK) documentation.

For more information and downloads, see the

Driver Verifier page on the Windows Hardware Developer Central (WHDC) Web site.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 590 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!vm
The !vm extension displays summary information about virtual memory use statistics on the target system.
Syntax
!vm [Flags]
Parameters
Flags
Specifies what information will be displayed in the output from this command. This can be any sum of the following bits. The default is 0, which causes the display to
include system-wide virtual memory statistics as well as memory statistics for each process.
Bit 0 (0x1)
Causes the display to omit process-specific statistics.
Bit 1 (0x2)
Causes the display to include memory management thread stacks.
Bit 2 (0x4)
(Windows XP and later) Causes the display to include terminal server memory usage.
Bit 3 (0x8)
(Windows XP and later) Causes the display to include the page file write log.
Bit 4 (0x10)
(Windows XP and later) Causes the display to include working set owner thread stacks.
Bit 5 (0x20)
(Windows XP and later) Causes the display to include kernel virtual address usage.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
Here is an example of the short output produced when Flags is 1:
kd> !vm 1
*** Virtual Memory Usage ***
Physical Memory:
16270
(
65080
Page File: \??\E:\pagefile.sys
Current:
98304Kb Free Space:
Minimum:
98304Kb Maximum:
Available Pages:
5543
(
22172
ResAvail Pages:
6759
(
27036
Locked IO Pages:
112
(
448
Free System PTEs:
45089
( 180356
Free NP PTEs:
5145
(
20580
Free Special NP:
336
(
1344
Modified Pages:
714
(
2856
NonPagedPool Usage:
877
(
3508
NonPagedPool Max:
6252
(
25008
PagedPool 0 Usage:
729
(
2916
PagedPool 1 Usage:
432
(
1728
PagedPool 2 Usage:
436
(
1744
PagedPool Usage:
1597
(
6388
PagedPool Maximum:
13312
(
53248
Shared Commit:
1097
(
4388
Special Pool:
229
(
916
Shared Process:
1956
(
7824
PagedPool Commit:
1597
(
6388
Driver Commit:
828
(
3312
Committed pages:
21949
(
87796
Commit limit:
36256
( 145024

Kb)
61044Kb
196608Kb
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)

All memory use is listed in pages and in kilobytes. The most useful information in this display is the following:
Parameter
physical
memory
available pages
nonpaged pool
usage

Meaning
Total physical memory in the system.
Number of pages of memory available on the system, both virtual and physical.
The amount of pages allocated to the nonpaged pool. The nonpaged pool is memory that cannot be swapped out to the paging file, so it must always occupy
physical memory. If this number is too large, this is usually an indication that there is a memory leak somewhere in the system.

Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 591 of 1651

15:02:16.040s

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!whatperftime
The !whatperftime extension converts a high-resolution performance counter value into a standard time value.
Syntax
!whatperftime Count
Parameters
Count
The performance counter clock value.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 595 of 1651

DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
Comments
You can use !whatperftime to convert values retrieved by calling QueryPerformanceCounter. Performance counter time values are also found in software traces.
The output is displayed as HH:MM:SS.mmm. Here is an example:
kd> !whatperftime 304589
3163529 Performance Counter in Standard Time: .004.313s

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!whea
The !whea extension displays top-level Windows Hardware Error Architecture (WHEA) information.
Syntax
!whea
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Server 2003
Unavailable
Windows Vista and later Kdexts.dll
This extension can be used only in Windows Vista and later versions of Windows.
Comments
The following example shows the (truncated) output of the !whea extension:
3: kd> !whea
Error Source Table @ fffff800019ca250
13 Error Sources
Error Source 0 @ fffffa80064132c0
Notify Type
: Machine Check Exception
Type
: 0x0 (MCE)
Error Count
: 8
Record Count
: 10
Record Length
: c3e
Error Records
: wrapper @ fffffa8007cf4000
: wrapper @ fffffa8007cf4c3e
: wrapper @ fffffa8007cf587c
: wrapper @ fffffa8007cf64ba
: wrapper @ fffffa8007cf70f8
: wrapper @ fffffa8007cf7d36
: wrapper @ fffffa8007cf8974
: wrapper @ fffffa8007cf95b2
: wrapper @ fffffa8007cfa1f0
: wrapper @ fffffa8007cfae2e
: wrapper @ fffffa8007cfba6c
: wrapper @ fffffa8007cfc6aa
: wrapper @ fffffa8007cfd2e8
: wrapper @ fffffa8007cfdf26
: wrapper @ fffffa8007cfeb64
: wrapper @ fffffa8007cff7a2
Descriptor
: @ fffffa8006413328
Length
: 3cc
Max Raw Data Length
: 392
Num Records To Preallocate : 10
Max Sections Per Record
: 3
Error Source ID
: 0
Flags
: 00000000
Error Source 1 @ fffffa8007d00bc0
Notify Type
: Corrected Machine Check
Type
: 0x1 (CMC)
Error Count
: 0
Record Count
: 10

record
record
record
record
record
record
record
record
record
record
record
record
record
record
record
record

@
@
@
@
@
@
@
@
@
@
@
@
@
@
@
@

fffffa8007cf4030
fffffa8007cf4c6e
fffffa8007cf58ac
fffffa8007cf64ea
fffffa8007cf7128
fffffa8007cf7d66
fffffa8007cf89a4
fffffa8007cf95e2
fffffa8007cfa220
fffffa8007cfae5e
fffffa8007cfba9c
fffffa8007cfc6da
fffffa8007cfd318
fffffa8007cfdf56
fffffa8007cfeb94
fffffa8007cff7d2

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Record Length
Error Records

Page 596 of 1651

:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:
:

c3e
wrapper @ fffffa8007d01000
wrapper @ fffffa8007d01c3e
wrapper @ fffffa8007d0287c
wrapper @ fffffa8007d034ba
wrapper @ fffffa8007d040f8
wrapper @ fffffa8007d04d36
wrapper @ fffffa8007d05974
wrapper @ fffffa8007d065b2
wrapper @ fffffa8007d071f0
wrapper @ fffffa8007d07e2e
wrapper @ fffffa8007d08a6c
wrapper @ fffffa8007d096aa
wrapper @ fffffa8007d0a2e8
wrapper @ fffffa8007d0af26
wrapper @ fffffa8007d0bb64
wrapper @ fffffa8007d0c7a2
Descriptor
@ fffffa8007d00c28
Length
: 3cc
Max Raw Data Length
: 392
Num Records To Preallocate : 10
Max Sections Per Record
: 3
Error Source ID
: 1
Flags
: 00000000
Error Source 2 @ fffffa8007d00770
Notify Type
: Non-Maskable Interrupt
Type
: 0x3 (NMI)
Error Count
: 1
Record Count
: 1
Record Length
: 1f8
Error Records
: wrapper @ fffffa800631b2c0
Descriptor
: @ fffffa8007d007d8
Length
: 3cc
Max Raw Data Length
: 100
Num Records To Preallocate : 1
Max Sections Per Record
: 1
Error Source ID
: 2
Flags
: 00000000
Error Source 3 @ fffffa8007d0dbc0
Notify Type
: BOOT Error Record
Type
: 0x7 (BOOT)
Error Count
: 0
Record Count
: 1
Record Length
: 4f8
Error Records
: wrapper @ 0000000000000000
Descriptor
: @ fffffa8007d0dc28
Length
: 3cc
Max Raw Data Length
: 400
Num Records To Preallocate : 1
Max Sections Per Record
: 1
Error Source ID
: 3
Flags
: 00000000

record
record
record
record
record
record
record
record
record
record
record
record
record
record
record
record

@
@
@
@
@
@
@
@
@
@
@
@
@
@
@
@

fffffa8007d01030
fffffa8007d01c6e
fffffa8007d028ac
fffffa8007d034ea
fffffa8007d04128
fffffa8007d04d66
fffffa8007d059a4
fffffa8007d065e2
fffffa8007d07220
fffffa8007d07e5e
fffffa8007d08a9c
fffffa8007d096da
fffffa8007d0a318
fffffa8007d0af56
fffffa8007d0bb94
fffffa8007d0c7d2

record @ fffffa800631b2f0

record @ 0000000000000030

. . . .
Additional Information
The !errrec and !errpkt extensions can be used to display additional WHEA information. For general information about WHEA, see
Architecture (WHEA) in the Windows Driver Kit (WDK) documentation.

Windows Hardware Error

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wsle
The !wsle extension displays all working set list entries (WSLEs).
Syntax
Syntax in Windows 2000
!wsle [DisplayMode [Address]]
Syntax in Windows XP and later
!wsle [Flags [Address]]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 597 of 1651

Parameters
DisplayMode
(Windows 2000 only) Specifies the information to include in the display. This can be one of the following values (the default is zero):
0
Displays only basic information about the working set list.
7
Displays basic information about the working set list, plus information about each WSLE's address, age, lock status, and reference count. If a WSLE has an invalid
page table entry (PTE) or page directory entry (PDE) associated with it, this is displayed as well.
8
Displays basic information about the working set list, plus the index and value of each WSLE.
Flags
(Windows XP and later) Specifies the information to include in the display. This can be any combination of the following bits. The default is zero. If this is used, only
basic information about the working set is displayed.
Bit 0 (0x1)
Causes the display to include information about each WSLE's address, age, lock status, and reference count. If a WSLE has an invalid page table entry (PTE) or page
directory entry (PDE) associated with it, this is also displayed.
Bit 1 (0x2)
Causes the display to include the total number of valid WSLEs, the index of the last WSLE, and the index of the first free WSLE.
Bit 2 (0x4)
Causes the display to include the total number of free WSLEs, as well as the index of each free WSLE. If bit 1 is also set, then a check is done to make sure that the
number of free WSLEs plus the number of valid WSLEs is actually equal to the total number of WSLEs.
Address
Specifies the address of the working set list. If this is omitted, the default working set list is used. (In Windows 2000, specifying -1 for Address is the same as omitting it.
In Windows XP and later versions of Windows, specifying zero for Address is the same as omitting it.)
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Kdexts.dll
Comments
This extension can take a significant amount of time to execute.
Here is an example from an x86 target computer running Windows Server 2003:
kd> !wsle 3
Working Set @ c0503000
FirstFree:
a7 FirstDynamic:
LastEntry
23d NextSlot:
NonDirect
65 HashTable:

4
0

4
LastInitialized
HashTableSize:

259
0

Reading the WSLE data...

Virtual Address
c0300203
c0301203
c0502203
c0503203
c01ff201
77f74d19
7ffdfa01
c0001201

Age
0
0
0
0
0
3
2
0

Locked
1
1
1
1
0
0
0
0

ReferenceCount
1
1
1
1
1
1
1
1

.....
Reading the WSLE data...
Valid WSLE entries = 0xa7
found end @ wsle index 0x259
.....
Additional Information
For information about working sets, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!xpoolmap
(Windows XP only.) The !xpoolmap extension displays a map of pool use.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 598 of 1651

!xpoolmap [Pool]
!xpoolmap -?
Parameters
Pool
Specifies the paged or nonpaged pool. Use 0 or 1. 0 represents the non-paged pool. 1 represents the paged pool. 0 is the default.
-?
Displays help for this extension in the Debugger Command window.
DLL
Windows 2000
Unavailable
Windows XP and later Kdexts.dll
This extension command can only be used with an x86-based target computer.
Comments
The !xpoolmap extension is supported only on Windows XP. On Windows 2000, use !kdex2x86.xpool -map. This extension is part of the OEM Support Extensions package.
For information about installing this package, see OEM Support Extensions (kdex2x86.dll).
Here is a partial example:
0: kd> !xpoolmap
unable to get nt!MmSubsectionTopPage
unable to get nt!MmNonPagedMustSucceed
.....................................................
Status Map of Pool Area Pages
==============================
'O': one page in use
('P':
'<': start page of contiguous pages in use
('{':
'>': last page of contiguous pages in use
('}':
'=': intermediate page of contiguous pages in use ('-':
'.': one page not used

paged
paged
paged
paged

out)
out)
out)
out)

Non-Paged Pool Area Summary

---------------------------Maximum Number of Pages = 52691 pages
Number of Pages In Use
= 52689 pages (100.0%)
+00000 +08000
+10000 +18000
+20000 +28000
81653000: OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO
81693000: OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO
816d3000: OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOO

+30000 +38000
OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO

...
86753000:
86793000:
867d3000:
f7fba000:
f7ffa000:
f803a000:
f807a000:

OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
.>OOOOOOOOO<====
OOOO<=><><=><===
>O<===><==>OOOOO
><>OOOOO<=>O<=>O

OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
>O<=><>OOOO<><>O
>OOOO<>OO<=><>OO
OOOOOOOOOOOOO<=>
<>OOOOOOOO<==>OO

OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO
OOOOOOOOOOOO<
O<=======>OOOO<=
OOO<><=>O<=====>
OOOOO<=>O<==><>O
<>OOOOOOO<====>O

OOOOOOOOOOOOOOOO
OOOOOOOOOOOOOOOO

>OOO<>OOOOOOOOOO
O<>OO<>OOOOOOOOO
<==>OO<>OOOOO<=>
=>OOO<=====>O<==

OOO<==>OOO<>O<>O
O<==>OOOOO<>OO<>
OOOO<=>O<==><===
>OOO<=><=>OOOO<=

OO<=======>OOOOO O<===>OOOOOOOOOO
OO<=>O<=><>OOOO< >OOOOOOOOOOO<><>
====>OOOO<>OOOOO OOO<>O<>OOO<==><
>OO<=.

>OO<>OOOOOOOOOOO
<=>OOOOO<>O<==><
OOO<>OO<=====><=
<>OO<><>OOOOO<>O

...
ffafa000:
ffb3a000:
ffb7a000:
ffbba000:

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!zombies
The !zombies extension displays all dead ("zombie") processes or threads.
Syntax
!zombies [Flags [RestartAddress]]
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 599 of 1651

Flags
Specifies what will be displayed. Possible values include:
1
Displays all zombie processes. (This is the default.)
2
Displays all zombie threads.
RestartAddress
Specifies the hexadecimal address at which to begin the search. This is useful if the previous search was terminated prematurely. The default is zero.
DLL
Windows 2000
Kdextx86.dll
Windows XP and later Unavailable
Comments
Zombie processes are dead processes that have not yet been removed from the process list. Zombie threads are analogous.
This extension is available only for Windows 2000.
Additional Information
To see a list of all processes and threads, use the !process extension.
For general information about processes and threads in kernel mode, see Changing Contexts. For more information about analyzing processes and threads, see Microsoft
Windows Internals, by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User-Mode Extensions
This section of the reference describes extension commands that are primarily used during user-mode debugging.
The debugger will automatically load the proper version of these extension commands. Unless you have manually loaded a different version, you do not have to keep track of
the DLL versions being used. See Using Debugger Extension Commands for a description of the default module search order. See Loading Debugger Extension DLLs for an
explanation of how to load extension modules.
Each extension command reference page lists the DLLs that expose that command. Use the following rules to determine the proper directory from which to load this extension
DLL:

If your target application is running on the free build of Windows 2000, use w2kfre\Ntsdexts.dll.
If your target application is running on the checked build of Windows 2000, use w2kchk\Ntsdexts.dll.
If your target application is running on Windows XP or a later version of Windows, use winxp\Ntsdexts.dll.

In addition, user-mode extensions that are not specific to any single operating system can be found in winext\Uext.dll.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!avrf
The !avrf extension controls the settings of Application Verifier and displays a variety of output produced by Application Verifier.
Syntax
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf
!avrf

!dreg System\CurrentControlSet\Services\Tcpip!Start
Typing !dreg without any arguments will display some brief Help text for this extension in the Debugger Command window..
Additional Information
For information about the registry, see the Windows Driver Kit (WDK) documentation and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!dt
The !dt extension displays information about a CSR thread.
This extension command should not be confused with the dt (Display Type) command.
Syntax
!dt [v] CSR-Thread
Parameters
v
Verbose mode.
CSR-Thread
Specifies the hexadecimal address of the CSR thread.
DLL
Windows 2000
Ntsdexts.dll
Windows XP and later Ntsdexts.dll
Comments
This extension displays the thread, process, client ID, flags, and reference count associated with the CSR thread. If verbose mode is selected, the display will also include list
pointers, thread handle, and the wait block.
See Also
!dp (!ntsdexts.dp)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!evlog
The !evlog extension displays, changes, or backs up the event log.
Syntax
!evlog
!evlog
!evlog
!evlog
!evlog
!evlog
!evlog
!evlog

addsource [-d] [-s Source] [-t Type] [-f MsgFile]

backup [-d] [-l EventLog] [-f BackupFile]
clear [-!] [-d] [-l EventLog] [-f BackupFile]
info
option [-d] [-!] [-n Count] [ -l EventLog [ -+ | -r RecordBound ]] [-o Order] [-w Width]
read [-d] [-l EventLog] [-s Source] [-e ID] [-c Category] [-t Type] [-n Count] [-r Record]
report [-s Source] [-e ID] [-c Category] [-t Type] Message
[Option] -?

Parameters
addsource
Adds an event source to the registry. By default, this only adds events from the DebuggerExtensions source (to support !evlog report).
backup
Makes a backup of the specified event log and writes it to a file.
clear
Erases the specified event log, and optionally creates a file recording its old contents.
info
Displays summary information about the event log.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 604 of 1651

option
Sets the default search options. These options will be used in future !evlog read commands.
read
Displays a list of events logged to the specified event log. Details of this display such as the number of records displayed and the chronological order of the display
can be controlled by the !evlog read parameters or by a previous use of !evlog option.
report
Writes an event record to the application event log.
-d
Specifies that all default values should be used. The -d option is only required if you are omitting all other parameters. However, with the !evlog option command this
option displays the existing default settings.
-!
With !evlog option, this resets all defaults. With !evlog clear, this prevents a backup file from being written.
Source
Specifies the event source. The default value is DebuggerExtensions.
Type
Specifies the success type. Possible Type values are 1 (Error), 2 (Warning), 4 (Information), 8 (Audit_Success), or 16 (Audit_Failure). A value of 0 represents Success.
For !evlog read and !evlog report, the default is Success (0). For !evlog addsource, these bits can be combined, and the default is all bits (31).
MsgFile
Specifies the path and file name of the message file. If the path is omitted, the directory of the current Uext.dll is used.
EventLog
For !evlog read, !evlog backup, and !evlog clear, EventLog specifies the event log from which to read. The possible values are Application, System, and Security. The
default is Application.
For !evlog option, EventLog specifies the event log whose maximum count is to be set. The possible values are All, Application, System, and Security. The default is
All.
BackupFile
Specifies the path and file name of the backup file. The default location is the current directory. The default file name is EventLog_backup.evt, where EventLog is the
event log used in this command. If this file already exists, the command will be terminated.
Count
Specifies the maximum number of records to retrieve. The default is 20.
-+
Specifies that the current maximum record number should be the highest record number retrieved in future !evlog read commands. (In other words, no records will be
shown as long as the search is performed forward.)
RecordBound
Specifies the highest record number to retrieve in future !evlog read commands. If zero is specified, no bound is set this is the default.
Record
If -n Count is not included, -r Record specifies the record number to retrieve. If -n Count is included, Record specifies the record number at which the display should
begin.
Order
Specifies the search order, either Forwards or Backwards. The default is Forwards. A backward search order causes searches to start from the most recent record
logged to the event log, and continue in reverse-chronological order as matching records are found.
Width
Specifies the data display width, in characters. This is the width displayed in the Data section. The default is 8 characters.
ID
Specifies the prefix to display before the event. Possible values are 0 (no prefix), 1000 (Information), 2000 (Success), 3000 (Warning), and 4000 (Error). The default is 0.
Category
Specifies the event category. Possible values are 0 (no category), 1 (Devices), 2 (Disk), 3 (Printers), 4 (Services), 5 (Shell), 6 (System_Event), and 7 (Network). The
default is 0.
Message
Specifies a text message to add to the event description.
Option
Specifies the !evlog option whose help text is to be displayed.
-?
Displays some brief Help text for this extension or one of its options in the Debugger Command window.
DLL
Windows 2000
Uext.dll
Windows XP and later Uext.dll
The !evlog extension can only be used during live debugging.
Comments
After you have added an event source to the registry with !evlog addsource, you can view the values with !dreg. For example:
0:000> !dreg hklm\system\currentcontrolset\services\eventlog\Application\<source>!*
The !evlog option command is used to set new defaults for the !evlog read command. This lets you avoid retyping all the parameters every time you use !evlog read. Setting
a maximum record bound with the -+ parameter or the -r Records parameter allows you to terminate all searches after a known record number is encountered. This can be
useful if you are only interested in all records logged after a certain event.
Before using !evlog report, you should use !evlog addsource to configure an event source in the registry. After this has been configured, the event viewer will recognize the
various event IDs.
Here is an example of the !evlog info extension:
0:000> !evlog info -?
-------------------------------Application Event Log:
# Records
: 4362
Oldest Record # : 1
Newest Record # : 4362

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 605 of 1651

Event Log Full : false

-------------------------------System Event Log:
# Records
: 2296
Oldest Record # : 1
Newest Record # : 2296
Event Log Full : false
-------------------------------Security Event Log:
# Records
: 54544
Oldest Record # : 1
Newest Record # : 54544
Event Log Full : false
-------------------------------0:000> !evlog option -n 4
Default EvLog Option Settings:
-------------------------------Max Records Returned: 4
Search Order:
Backwards
Data Display Width:
8
-------------------------------Bounding Record Numbers:
Application Event Log: 0
System Event Log:
0
Security Event Log:
0
-------------------------------0:000> !evlog read -l application
-------------- 01 -------------Record #: 4364
Event Type:
Event Source:
Event Category:
Event ID:
Date:
Time:
Description:
The Group Policy

Error (1)
Userenv
None (0)
1000 (0xC00003E8)
06/06/2002
18:03:17
(1 strings)
client-side extension Security was passed flags (17) and returned a failure status code of (87).

-------------- 02 -------------Record #: 4363

Event Type:
Warning (2)
Event Source:
SceCli
Event Category: None (0)
Event ID:
1202 (0x800004B2)
Date:
06/06/2002
Time:
18:03:17
Description:
(1 strings)
0x57 : The parameter is incorrect.
Please look for more details in TroubleShooting section in Security Help.
-------------- 03 -------------Record #: 4362
Event Type:
Event Source:
Event Category:
Event ID:
Date:
Time:
Description:
The Group Policy

Error (1)
Userenv
None (0)
1000 (0xC00003E8)
06/06/2002
16:04:08
(1 strings)
client-side extension Security was passed flags (17) and returned a failure status code of (87).

-------------- 04 -------------Record #: 4361

Event Type:
Warning (2)
Event Source:
SceCli
Event Category: None (0)
Event ID:
1202 (0x800004B2)
Date:
06/06/2002
Time:
16:04:08
Description:
(1 strings)
0x57 : The parameter is incorrect.
Please look for more details in TroubleShooting section in Security Help.
WARNING: Max record count (4) exceeded, increase record count to view more

2009 Microsoft Corporation

Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 606 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

!findstack
The !findstack extension locates all of the stacks that contain a specified symbol or module.
Syntax
!findstack Symbol [DisplayLevel]
!findstack -?
Parameters
Symbol
Specifies a symbol or module.
DisplayLevel
Specifies what the display should contain. This can be any one of the following values. The default value is 1.
0
Displays only the thread ID for each thread that contains Symbol.
1
Displays both the thread ID and the frame for each thread that contains Symbol.
2
Displays the entire thread stack for each thread that contains Symbol.
-?
Displays some brief Help text for this extension in the Debugger Command window.
DLL
Windows 2000
Uext.dll
Windows XP and later Uext.dll
Comments
The !stacks kernel-mode extension also display information about stacks, including a brief summary of the state of every thread.
The following are some examples of the output from this extension:
0:023> !uext.findstack wininet
Thread 009, 2 frame(s) match
* 06 03eaffac 771d9263 wininet!ICAsyncThread::SelectThread+0x22a
* 07 03eaffb4 7c80b50b wininet!ICAsyncThread::SelectThreadWrapper+0xd
Thread 011, 2 frame(s) match
* 04 03f6ffb0 771cda1d wininet!AUTO_PROXY_DLLS::DoThreadProcessing+0xa1
* 05 03f6ffb4 7c80b50b wininet!AutoProxyThreadFunc+0xb
Thread 020, 6 frame(s) match
* 18 090dfde8 771db73a
* 19 090dfe18 771c5e4d
* 20 090dfe8c 771c5d6a
* 21 090dfe98 771bcb2c
* 22 090dfeb0 771d734a
* 23 090dfee0 77f6ad84

wininet!CheckForNoNetOverride+0x9c
wininet!InternetAutodialIfNotLocalHost+0x220
wininet!ParseUrlForHttp_Fsm+0x135
wininet!CFsm_ParseUrlForHttp::RunSM+0x2b
wininet!CFsm::Run+0x39
wininet!CFsm::RunWorkItem+0x79

Thread 023, 9 frame(s) match

* 16 0bd4fe00 771bd256
* 17 0bd4fe0c 771bcb2c
* 18 0bd4fe24 771bcada
* 19 0bd4fe3c 771bd22b
* 20 0bd4fe4c 771bd706
* 21 0bd4fe8c 771bd4cb
* 22 0bd4fe98 771bcb2c
* 23 0bd4feb0 771d734a
* 24 0bd4fee0 77f6ad84

wininet!ICSocket::Connect_Start+0x17e
wininet!CFsm_SocketConnect::RunSM+0x42
wininet!CFsm::Run+0x39
wininet!DoFsm+0x25
wininet!ICSocket::Connect+0x32
wininet!HTTP_REQUEST_HANDLE_OBJECT::OpenConnection_Fsm+0x391
wininet!CFsm_OpenConnection::RunSM+0x33
wininet!CFsm::Run+0x39
wininet!CFsm::RunWorkItem+0x79

0:023> !uext.findstack wininet!CFsm::Run 0

Thread 020, 2 frame(s) match
Thread 023, 3 frame(s) match
0:023> !uext.findstack wininet!CFsm 0
Thread 020, 3 frame(s) match
Thread 023, 5 frame(s) match
Additional Information
For more information about stack traces and other ways to display stack traces, see Viewing the Call Stack and k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)
commands.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 607 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!gatom
The !gatom extension displays the global atom table.
Syntax
!gatom
DLL
Windows 2000
Ntsdexts.dll
Windows XP and later Ntsdexts.dll
Additional Information
For information about the global atom table, see the Microsoft Windows SDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!igrep
The !igrep extension searches for a pattern in disassembly.
Syntax
!igrep [Pattern [StartAddress]]
Parameters
Pattern
Specifies the pattern to search for. If omitted, the last Pattern is used.
StartAddress
Specifies the hexadecimal address at which to begin searching. If omitted, the current program counter is used.
DLL
Windows 2000
Ntsdexts.dll
Windows XP and later Unavailable

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!locks (!ntsdexts.locks)
The !locks extension in Ntsdexts.dll displays a list of critical sections associated with the current process.
This extension command should not be confused with the !kdext*.locks extension command.
Syntax
!locks [Options]
Parameters
Options
Specifies the amount of information to be displayed. Any combination of the following options can be used:
-v
Causes the display to include all critical sections, even those that are not currently owned.
-o

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 608 of 1651

(Windows XP and later) Causes the display to only include orphaned information (pointers that do not actually point to valid critical sections).
DLL
Windows 2000
Ntsdexts.dll
Windows XP and later Ntsdexts.dll
Comments
This extension command shows all critical sections that have been initialized by calling RtlInitializeCriticalSection. If there are no critical sections, then no output will
result.
Here is an example:
0:000> !locks
CritSec w3svc!g_pWamDictator+a0 at 68C2C298
LockCount
0
RecursionCount
1
OwningThread
d1
EntryCount
1
ContentionCount
0
*** Locked
CritSec SMTPSVC+66a30 at 67906A30
LockCount
0
RecursionCount
1
OwningThread
d0
EntryCount
1
ContentionCount
0
*** Locked
Additional Information
For other commands and extensions that can display critical section information, see Displaying a Critical Section. For information about critical sections, see the Microsoft
Windows SDK documentation, the Windows Driver Kit (WDK) documentation, and Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!mapped_file
The !mapped_file extension displays the name of the file that backs the file mapping that contains a specified address.
Syntax
!mapped_file Address
Parameters
Address
Specifies the address of the file mapping. If Address is not in a mapping, the command fails.
DLL
Windows 2000
Uext.dll
Windows XP and later Uext.dll
The !mapped_file extension can only be used during live, nonremote debugging.
Comments
Here are three examples. The first two addresses used are mapped from a file, and the third is not.
0:000> !mapped_file 4121ec
Mapped file name for 004121ec: '\Device\HarddiskVolume2\CODE\TimeTest\Debug\TimeTest.exe'
0:000> !mapped_file 77150000
Mapped file name for 77150000: '\Device\HarddiskVolume2\Windows\System32\kernel32.dll'
0:000> !mapped_file 80310000
No information found for 80310000: error 87
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

For more information about file mapping, see

Page 609 of 1651

MapViewOfFile in the Windows SDK.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!runaway
The !runaway extension displays information about the time consumed by each thread.
Syntax
!runaway [Flags]
Parameters
Flags
Specifies the kind of information to be displayed. Flags can be any combination of the following bits. The default value is 0x1.
Bit 0 (0x1)
Causes the debugger to show the amount of user time consumed by each thread.
Bit 1 (0x2)
Causes the debugger to show the amount of kernel time consumed by each thread.
Bit 2 (0x4)
Causes the debugger to show the amount of time that has elapsed since each thread was created.
DLL
Windows 2000

Uext.dll
Ntsdexts.dll
Windows XP and later Uext.dll
Ntsdexts.dll

The !runaway extension can only be used during live debugging or when debugging crash dump files created by .dump /mt or .dump /ma.
Comments
This extension is a quick way to find out which threads are spinning out of control or consuming too much CPU time.
The display identifies each thread by the debugger's internal thread numbering and by the thread ID in hexadecimal. The debugger IDs are also shown.
Here is an example:

0:001> !runaway 7
User Mode Time
Thread
Time
0:55c
0:00:00.0093
1:1a4
0:00:00.0000
Kernel Mode Time
Thread
Time
0:55c
0:00:00.0140
1:1a4
0:00:00.0000
Elapsed Time
Thread
Time
0:55c
0:00:43.0533
1:1a4
0:00:25.0876
Additional Information
For information about threads in user mode, see Controlling Processes and Threads. For more information about analyzing processes and threads, see Microsoft Windows
Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!threadtoken
The !threadtoken extension displays the impersonation state of the current thread.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 610 of 1651

Syntax
!threadtoken
DLL
Windows 2000
Ntsdexts.dll
Windows XP and later Unavailable
Comments
The !threadtoken extension is obsolete in Windows XP and later versions of Windows. Use !token instead.
If the current thread is impersonating, the token that this thread is using will be displayed.
Otherwise, a message reading "Thread is not impersonating" will appear. The process token will then be displayed.
Tokens will be displayed in the same format that !handle uses when displaying token handles.
Here is an example:
0:000> ~
. 0 id: 1d0.55c
# 1 id: 1d0.1a4

Suspend: 1 Teb 7ffde000 Unfrozen

Suspend: 1 Teb 7ffdd000 Unfrozen

0:000> !threadtoken
***Thread is not impersonating, using process token***
Auth Id
0 : 0x1c93d
Type
Primary
Imp Level Anonymous
Token Id 0 : 0x5e8c19
Mod Id
0 : 0x5e8c12
Dyn Chg
0x1f4
Dyn Avail 0x1a4
Groups
26
Privs
17
User
S-1-5-21-2127521184-1604012920-1887927527-74790
Groups
26
S-1-5-21-2127521184-1604012920-1887927527-513
S-1-1-0
S-1-5-32-544
S-1-5-32-545
S-1-5-21-2127521184-1604012920-1887927527-277551
S-1-5-21-2127521184-1604012920-1887927527-211604
S-1-5-21-2127521184-1604012920-1887927527-10546
S-1-5-21-2127521184-1604012920-1887927527-246657
S-1-5-21-2127521184-1604012920-1887927527-277552
S-1-5-21-2127521184-1604012920-1887927527-416040
S-1-5-21-2127521184-1604012920-1887927527-96548
S-1-5-21-2127521184-1604012920-1887927527-262644
S-1-5-21-2127521184-1604012920-1887927527-155802
S-1-5-21-2127521184-1604012920-1887927527-158763
S-1-5-21-2127521184-1604012920-1887927527-279132
S-1-5-21-2127521184-1604012920-1887927527-443952
S-1-5-21-2127521184-1604012920-1887927527-175772
S-1-5-21-2127521184-1604012920-1887927527-388472
S-1-5-21-2127521184-1604012920-1887927527-443950
S-1-5-21-2127521184-1604012920-1887927527-266975
S-1-5-21-2127521184-1604012920-1887927527-158181
S-1-5-21-2127521184-1604012920-1887927527-279435
S-1-5-5-0-116804
S-1-2-0
S-1-5-4
S-1-5-11
Privileges
17
SeUndockPrivilege ( Enabled Default )
SeTakeOwnershipPrivilege ( )
SeShutdownPrivilege ( )
SeDebugPrivilege ( )
SeIncreaseBasePriorityPrivilege ( )
SeAuditPrivilege ( )
SeSyncAgentPrivilege ( )
SeLoadDriverPrivilege ( )
SeSystemEnvironmentPrivilege ( Enabled )
SeRemoteShutdownPrivilege ( )
SeProfileSingleProcessPrivilege ( )
SeCreatePagefilePrivilege ( )
SeCreatePermanentPrivilege ( )
SeSystemProfilePrivilege ( Enabled )
SeBackupPrivilege ( )
SeMachineAccountPrivilege ( )

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 611 of 1651

SeEnableDelegationPrivilege ( Enabled )
Additional Information
For information about threads and impersonation, see the Microsoft Windows SDK documentation and Microsoft Windows Internals by Mark Russinovich and David
Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!uniqstack
The !uniqstack extension displays all of the stacks for all of the threads in the current process, excluding stacks that appear to have duplicates.
Syntax
!uniqstack [ -b | -v | -p ] [ -n ]
Parameters
-b
Causes the display to include the first three parameters passed to each function.
-v
Causes the display to include frame pointer omission (FPO) information. On x86-based processors, the calling convention information is also displayed.
-p
Causes the display to include the full parameters for each function that is called in the stack trace. This listing will include each parameter's data type, name, and value.
This requires full symbol information.
-n
Causes frame numbers to be displayed.
DLL
Windows 2000
Uext.dll
Windows XP and later Uext.dll
Comments
This extension is similar to the k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace) command, except that it does not display duplicate stacks.
For example:
0:000> !uniqstack
Processing 14 threads, please wait
.

Id: f0f0f0f0.15c Suspend: 1 Teb: 00000000`7fff8000 Unfrozen

Priority: 0
Child-SP
Child-BSP
RetAddr
Call Site
00000000`0006e5e0 00000000`00070420 00000000`6b009840 wow64!Wow64NotifyDebugger+0x40 [d:\xpclient\base\wow64\wow64\wow64.c @ 581]
00000000`0006e600 00000000`000703d0 00000000`6b03db00 wow64!Wow64KiRaiseException+0x1a0 [d:\xpclient\base\wow64\wow64\wow64.c @ 6
00000000`0006e950 00000000`000703b0 00000000`6b008520 wow64!whNtRaiseException+0x40
00000000`0006e950 00000000`00070368 00000000`6b1845e0 wow64!Wow64SystemService+0x220 [d:\xpclient\base\wow64\wow64\wow64.c @ 1100
00000000`0006e9b0 00000000`00070310 00000000`6b009980 wow64cpu!CpuSimulate+0x3a0 [d:\xpclient\base\wow64\cpu\ia64\cpu\cpumain.c @
00000000`0006e9d0 00000000`000702d0 00000000`6b009ff0 wow64!RunCpuSimulation+0x60 [d:\xpclient\base\wow64\wow64\wow64.c @ 1168]
00000000`0006e9e0 00000000`00070248 00000000`77ea4a10 wow64!Wow64LdrpInitialize+0x5d0 [d:\xpclient\base\wow64\wow64\wow64.c @ 248
00000000`0006f290 00000000`000700e0 00000000`77ea5d60 ntdll!LdrpInitializeProcess+0x2150 [d:\xpclient\base\ntdll\ldrinit.c @ 1817
00000000`0006f4c0 00000000`00070028 00000000`77ed6000 ntdll!LdrpInitialize+0x560 [d:\xpclient\base\ntdll\ldrinit.c @ 553]
00000000`0006f550 00000000`00070000 00000000`77ed9000 ntdll!LdrInitializeThunk+0x20 [D:\xpclient\base\ntdll\daytona\..\ia64\ldrth
00000000`0006f550 00000000`00070000 00000000`77ca78a0 ntdll!KiUserApcDispatch+0x50 [D:\xpclient\base\ntos\rtl\user\..\ia64\trampo
00000000`0006fff0 00000000`00070000 00000000`00000000 0x77ca78a0
.

Id: f0f0f0f0.718 Suspend: 1 Teb: 00000000`7fff4000 Unfrozen

Priority: 0
Child-SP
Child-BSP
RetAddr
Call Site
00000000`0043eb50 00000000`00440250 00000000`6b008520 wow64!whNtDelayExecution+0x150 [d:\xpclient\base\wow64\whnt32\obj\ia64\whnt
00000000`0043eb80 00000000`00440208 00000000`6b1845e0 wow64!Wow64SystemService+0x220 [d:\xpclient\base\wow64\wow64\wow64.c @ 1100
00000000`0043ebe0 00000000`004401a8 00000000`6b009980 wow64cpu!CpuSimulate+0x3a0 [d:\xpclient\base\wow64\cpu\ia64\cpu\cpumain.c @
00000000`0043ec00 00000000`00440168 00000000`6b009ff0 wow64!RunCpuSimulation+0x60 [d:\xpclient\base\wow64\wow64\wow64.c @ 1168]
00000000`0043ec10 00000000`004400e0 00000000`77ea5f50 wow64!Wow64LdrpInitialize+0x5d0 [d:\xpclient\base\wow64\wow64\wow64.c @ 248
00000000`0043f4c0 00000000`00440028 00000000`77ed6000 ntdll!LdrpInitialize+0x750 [d:\xpclient\base\ntdll\ldrinit.c @ 626]
00000000`0043f550 00000000`00440000 00000000`77ed9000 ntdll!LdrInitializeThunk+0x20 [D:\xpclient\base\ntdll\daytona\..\ia64\ldrth
00000000`0043f550 00000000`00440000 00000000`7de05690 ntdll!KiUserApcDispatch+0x50 [D:\xpclient\base\ntos\rtl\user\..\ia64\trampo
00000000`0043fff0 00000000`00440000 00000000`00000000 kernel32!MulDiv+0x110 [D:\xpclient\base\win32\client\i386\critsect.asm @ 55
. 13

Id: f0f0f0f0.494 Suspend: 1 Teb: 00000000`7ef98000 Unfrozen

Priority: 0
Child-SP
Child-BSP
RetAddr
Call Site

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 612 of 1651

00000000`00feffe0 00000000`00ff0040 00000000`77e94f30 ntdll!DbgBreakPoint+0x10 [D:\xpclient\base\ntos\rtl\user\..\ia64\debugstb.s

00000000`00feffe0 00000000`00ff0040 00000000`00000000 ntdll!DbgUiRemoteBreakin+0x90 [d:\xpclient\base\ntdll\dlluistb.c @ 269]
Total threads: 14
Duplicate callstacks: 11 (windbg thread #s follow):
2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Additional Information
For more information about stack traces and other ways to display stack traces, see Viewing the Call Stack.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!vadump
The !vadump extension displays all virtual memory ranges and their corresponding protection information.
Syntax
!vadump [-v]
Parameters
-v
Causes the display to include information about each original allocation region as well. Because individual addresses within a region can have their protection altered
after memory is allocated (by VirtualProtect, for example), the original protection status for this larger region may not be the same as that of each range within the
region.
DLL
Windows 2000
Uext.dll
Windows XP and later Uext.dll
Comments
Here is an example:
0:000> !vadump
BaseAddress:
RegionSize:
State:
Protect:
BaseAddress:
RegionSize:
State:
Protect:
Type:
.........

00000000
00010000
00010000
00000001

MEM_FREE
PAGE_NOACCESS

00010000
00001000
00001000
00000004
00020000

MEM_COMMIT
PAGE_READWRITE
MEM_PRIVATE

In this display, the State line shows the state of the memory range beginning at the specified BaseAddress. The possible state values are MEM_COMMIT, MEM_FREE, and
MEM_RESERVE.
The Protect line shows the protection status of this memory range. The possible protection values are PAGE_NOACCESS, PAGE_READONLY, PAGE_READWRITE,
PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, and PAGE_GUARD.
The Type line shows the memory type. The possible values are MEM_IMAGE, MEM_MAPPED, and MEM_PRIVATE.
Here is an example using the -v parameter:
0:000> !vadump -v
BaseAddress:
AllocationBase:
RegionSize:
State:
Protect:
BaseAddress:
AllocationBase:
AllocationProtect:
RegionSize:
State:
Protect:
Type:
.........

00000000
00000000
00010000
00010000
00000001
00010000
00010000
00000004
00001000
00001000
00000004
00020000

MEM_FREE
PAGE_NOACCESS

PAGE_READWRITE
MEM_COMMIT
PAGE_READWRITE
MEM_PRIVATE

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 613 of 1651

When -v is used, the AllocationProtect line shows the default protection that the entire region was created with. The Protect line shows the actual protection for this specific
address.
Additional Information
To view memory protection information for a single virtual address, use !vprot. For information about memory protection, see Microsoft Windows Internals by Mark
Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!vprot
The !vprot extension displays virtual memory protection information.
Syntax
!vprot [Address]
Parameters
Address
Specifies the hexadecimal address whose memory protection status is to be displayed.
DLL
Windows 2000

Uext.dll
Ntsdexts.dll
Windows XP and later Uext.dll

Comments
The !vprot extension command can be used for both live debugging and dump file debugging.
Here is an example:
0:000> !vprot 30c191c
BaseAddress: 030c1000
AllocationBase: 030c0000
AllocationProtect: 00000080 PAGE_EXECUTE_WRITECOPY
RegionSize: 00011000
State: 00001000 MEM_COMMIT
Protect: 00000010 PAGE_EXECUTE
Type: 01000000 MEM_IMAGE
In this display, the AllocationProtect line shows the default protection that the entire region was created with. Note that individual addresses within this region can have their
protection altered after memory is allocated (for example, if VirtualProtect is called). The Protect line shows the actual protection for this specific address. The possible
protection values are PAGE_NOACCESS, PAGE_READONLY, PAGE_READWRITE, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE,
PAGE_WRITECOPY, PAGE_EXECUTE_WRITECOPY, and PAGE_GUARD.
The State line also applies to the specific virtual address passed to !vprot. The possible state values are MEM_COMMIT, MEM_FREE, and MEM_RESERVE.
The Type line shows the memory type. The possible values are MEM_IMAGE, MEM_MAPPED, and MEM_PRIVATE.
Additional Information
To view memory protection information for all memory ranges owned by the target process, use !vadump. For information about memory protection, see Microsoft Windows
Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Specialized Extensions
This section of the reference discusses extension commands in the extension DLLs that are used less often.
These include:
Logger Extensions (Logexts.dll)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 614 of 1651

NDIS Extensions (Ndiskd.dll)

RPC Extensions (Rpcexts.dll)
ACPI Extensions (Acpikd.dll and Kdexts.dll)
NDIS Extensions (Ndiskd.dll)
Graphics Driver Extensions (Gdikdx.dll)
Kernel Streaming Extensions (Ks.dll)
SCSI Miniport Extensions (SCSIkd.dll and Minipkd.dll)
Kernel-Mode Driver Framework Extensions (Wdfkd.dll)
User-Mode Driver Framework Extensions (Wudfext.dll)
WMI Tracing Extensions (Wmitrace.dll)
OEM Support Extensions (Kdex2x86.dll)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Logger Extensions (Logexts.dll)

Extension commands related to the Logger and LogViewer tools can be found in Logexts.dll.
This DLL appears in the winext directory. It can be used with all Windows operating systems.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!logexts.help
The !logexts.help extension displays a Help text in the Command Prompt window showing all Logexts.dll extension commands.
Syntax
!logexts.help
DLL
Windows 2000
Logexts.dll
Windows XP and later Logexts.dll
Additional Information
For more information, see Logger and LogViewer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!logexts.logb
The !logexts.logb extension displays or flushes the output buffer.
Syntax
!logexts.logb p
!logexts.logb f
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0:001> !logm
Excluded modules:
LOGEXTS.DLL
KERNEL32.DLL
USER32.DLL
GDI32.DLL
ADVAPI32.DLL

Page 618 of 1651

[mandatory]
[mandatory]

0:001> !logm x winmine.exe

Excluded modules:
Logexts.dll
[mandatory]
kernel32.dll
[mandatory]
winmine.exe
0:001> !logm x user32.dll gdi32.dll
Excluded modules:
Logexts.dll
[mandatory]
kernel32.dll
[mandatory]
user32.dll
gdi32.dll
0:001> !logm i winmine.exe mymodule2.dll
Included modules:
winmine.exe
mymodule2.dll
Additional Information
For more information, see Logger and LogViewer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!logexts.logo
The !logexts.logo extension sets or displays the Logger output options.
Syntax
!logexts.logo {e|d} {d|t|v}
!logexts.logo
Parameters
e|d
Specifies whether to enable (e) or disable (d) the indicated output type.
d|t|v
Specifies the output type. Three types of Logger output are possible: messages sent directly to the debugger (d), a text file (t), or a verbose .lgv file (v).
DLL
Windows 2000
Logexts.dll
Windows XP and later Logexts.dll
Comments
If !logexts.logo is used without any parameters, then the current logging status, the output directory, and the current settings for the debugger, text file, and verbose log are
displayed:
0:000> !logo
Logging currently enabled.
Output directory: MyLogs\LogExts\
Output settings:
Debugger
Text file
Verbose log

Disabled
Enabled
Enabled

In the previous example, the output directory is a relative path, so it is located relative to the directory in which the debuggers were started.
To disable verbose logging, you would use the following command:
0:000> !logo d v
Debugger
Text file

Disabled
Enabled

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Verbose log

Page 619 of 1651

Disabled

Text file and .lgv files will be placed in the current output directory. To read an .lgv file, use LogViewer.
Additional Information
For more information, see Logger and LogViewer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

NDIS Extensions (Ndiskd.dll)

Extension commands that are useful for debugging NDIS (Network Driver Interface Specification) drivers can be found in Ndiskd.dll.
The Windows 2000 version of this extension DLL appears in the w2kfre and w2kchk directories. The Windows XP and later version of this extension DLL appear in the
winxp directory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.dbglevel
The !ndiskd.dbglevel extension sets the NDIS debug level.
Syntax
!ndiskd.dbglevel [Level]
Parameters
Level
Specifies the amount of debug tracing in NDIS components that are selected within the !ndiskd.dbgsystems extension. If Level is omitted, the current level of debug
tracing is displayed.
Only one level can be selected. The following levels are possible:
Value Meaning
INFO All available debug information is traced. This is the highest level of tracing possible.
LOG Log information is traced.
WARN Warnings and errors are traced.
ERR
Errors are traced.
FATAL Only fatal errors, which can cause the operating system to crash, are traced. This is the lowest level of tracing possible.
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.dbgsystems
The !ndiskd.dbgsystems extension controls which NDIS components will transmit debug information.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 620 of 1651

!ndiskd.dbgsystems [Values]
Parameters
Values
Selects various NDIS components to trace and watch for debug information. If no Values are specified, the current NDIS components selected are displayed.
If multiple components are selected, separate them with spaces. If a previously-selected component is repeated, its debug monitoring will be toggled off. The following
values are possible:
Value
Meaning
INIT
Traces adapter initialization.
CONFIG
Traces adapter configuration.
SEND
Traces sending data over the network.
RECV
Traces receiving data from the network.
PROTOCOL Traces protocol operations.
BIND
Traces binding operations.
BUS_QUERY Traces bus queries.
REGISTRY Traces registry operations.
MEMORY
Traces memory management.
FILTER
Traces filter operations.
REQUEST
Traces requests.
WORK_ITEM Traces work-item operations.
PNP
Traces Plug and Play operations.
PM
Traces Power Management operations.
OPEN
Traces operations that open reference objects.
LOCKS
Traces locking operations.
RESET
Traces resetting operations.
WMI
Traces Windows Management Instrumentation operations.
NDIS_CO
Traces Connection-Oriented NDIS.
REFERENCE Traces reference operations.
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.filter
The !ndiskd.mopen extension displays a filter block.
Syntax
!ndiskd.filter FilterBlock
Parameters
FilterBlock
Specifies the address of the filter block to be displayed.
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Vista and later Ndiskd.dll
Comments
Here is an example:
kd> !filter 0
Filter 00000000:
Miniport 0000000

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 621 of 1651

InstanceContext
: 0000000c
NextFilter
: 00000004
FilterDriver
: 00000008
Miniport
: 00000010
FilterFriendlyName : 00000018
State
: Illegal Value
Reference
: 564
FakeStatus
: 572
PendingRequests
: 576
NextGlobalFilter
: 00000244
LowerFilter
: 00000248
HigherFilter
: 0000024c
SendNetBurfferListsHandler
ReceiveNetBufferListsHandler
RequestHandler
PnPEventHandler
CancelSendHandler

00000000,
00000000,
00000000,
00000000,
00000000

SendNetBufferListsCompleteHandler
ReturnNetBufferListsHandler
RequestCompleteHandler
StatusHandler

00000000
00000000
00000000
00000000

Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.filters
The !ndiskd.filters extension displays a list of all filter blocks.
Syntax
!ndiskd.filters
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.findpacket
The !ndiskd.findpacket extension finds the specified packets.
Syntax
!ndiskd.findpacket v VirtualAddress
!ndiskd.findpacket p PoolAddress
Parameters
VirtualAddress
Specifies a virtual address that is contained in the desired packet.
PoolAddress
Specifies a pool address. All unreturned packets in this pool will be displayed.
DLL
Windows 2000
Unavailable
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 622 of 1651

!ndiskd.gminiports
The !ndiskd.gminiports extension displays a list of all miniports, including those that have not yet started.
Syntax
!ndiskd.gminiports
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.help
The !ndiskd.help extension displays a Help text in the Command Prompt window showing all Ndiskd.dll extension commands.
Syntax
!ndiskd.help
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.int_ctxt
The !ndiskd.int_ctxt extension displays the second argument of ndisMIsr.
Syntax
!ndiskd.int_ctxt

NDIS_MINIPORT_INTERRUPT

Parameters
NDIS_MINIPORT_INTERRUPT
Specifies the value of the miniport interrupt.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 623 of 1651

Windows 2000
Ndiskd.dll
Windows XP
Unavailable
Windows Vista and later Unavailable
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.nbpools
The !ndiskd.nbpools extension displays a list of all allocated net buffer list pools.
Syntax
!ndiskd.nbpools
DLL
Windows 2000
Unavailable
Windows XP
Unavailable
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.ndis
The !ndiskd.ndis extension displays some useful NDIS information.
Syntax
!ndiskd.ndis
DLL
Windows 2000
Unavailable
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.pkt
The !ndiskd.pkt extension displays information about a packet.
Syntax
!ndiskd.pkt Packet Verbosity
Parameters
Packet
Specifies the address of the packet.
Verbosity
Specifies the amount of detail to be displayed.
DLL

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 627 of 1651

Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.pktpool
The !ndiskd.pktpool extension displays the contents of an NDIS packet pool.
Syntax
!ndiskd.pktpool PktPool Number
Parameters
PktPool
Specifies a pointer to the NDIS packet pool.
DLL
Windows 2000
Ndiskd.dll
Windows XP
Unavailable
Windows Vista and later Unavailable
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.pktpools
The !ndiskd.pktpools extension displays a list of all allocated packet pools.
Syntax
!ndiskd.pktpools
DLL
Windows 2000
Unavailable
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.protocol
The !ndiskd.protocol extension displays the contents of a protocol block.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 628 of 1651

Syntax
!ndiskd.protocol ProtocolBlock
Parameters
ProtocolBlock
Specifies the address of the protocol block.
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ndiskd.protocols
The !ndiskd.protocols extension displays a list of all protocols and their open objects.
Syntax
!ndiskd.protocols
DLL
Windows 2000
Ndiskd.dll
Windows XP
Ndiskd.dll
Windows Vista and later Ndiskd.dll
Additional Information
For information about NDIS drivers, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

RPC Extensions (Rpcexts.dll)

008
00d
03b
008
007
007
007
004
008
008
008
002
002
002
003
000
002
002
004
003
004
003
001
000
004
001
005
001
004
003
000

82273fdc
8d9f4e40
8d9f4e40
82273fdc
367abb81
367abb81
367abb81
3ba0ffc0
82273fdc
82273fdc
8d9f4e40
e60c73e6
0b0a6584
0b0a6584
00000136
412f241e
0b0a6584
e60c73e6
e60c73e6
00000136
00000136
00000132
2f5f6520
629b9f66
faedcf59
629b9f66
00000134
2f5f6520
00000132
00000134
19bb5061

0000.003e
0000.002d
0000.0013
0000.001f
0000.0033
0000.002d
0000.0036
0000.002d
0000.0002
0000.0002
0000.0007
0000.0002
0000.0008
0000.0008
0000.0011
0000.0002
0000.0011
0000.0013
0000.0011
0000.0013
0000.0002
0000.000b
0000.001e
0000.000f
0000.0003
0000.000f
0000.0002
0000.0014
0000.0002
0000.0003
0000.0002

00000009
00000001
00000001
00000009
00000001
00000001
00000001
00000001
00000009
00000009
00000001
00000009
00000009
00000009
00000009
00000009
00000009
00000009
00000001
00000009
00000001
00000009
00000009
00000009
00000009
00000009
00000001
00000001
00000009
0000000b
00000001

00000000
0000033f
00000002
00000000
00000074
0000000a
00000063
00000005
00000000
00000000
000002b1
baadf00d
baadf00d
baadf00d
baadf00d
baadf00d
baadf00d
baadf00d
baadf00d
00000003
baadf00d
00000000
00120006
00000000
00000012
00000000
00000016
0020007d
00000000
00300038
00000001

0003a949
0003831a
00024e43
000118f3
0001042d
0002a3e4
0003b7b8
0002dd79
000245c6
00037d50
0004e900
0004ad30
0001187b
00011cdc
00034845
00012491
000492e7
0004ab78
0002bc25
00031d8d
00032e05
00034953
00035bac
000279ff
0003836b
0003657e
0003836b
000351b2
0003b786
0002d896
0004caa5

0294.02f0
0000.0031
0000.002f
022c.019c
0000.0034
0000.0037
0000.0039
0000.002e
01c0.037c
020c.0394
0000.0048
020c.03a4
00c4.012c
022c.019c
020c.02b4
0294.02b8
026c.0118
0378.038c
0378.024c
0378.00b8
020c.026c
0170.0240
020c.03b4
00a8.0194
0378.024c
020c.02ec
0378.024c
020c.0258
0170.01ac
020c.021c
0000.0003

For a similar example using the DbgRpc tool, see Get RPC Call Information.
Additional Information
For more information about debugging Microsoft Remote Procedure Call (RPC), see RPC Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rpcexts.getclientcallinfo
The !rpcexts.getclientcallinfo extension searches the system's RPC state information for client call (CCALL) information.
Syntax
!rpcexts.getclientcallinfo [ CallID | 0 [ IfStart | 0 [ ProcNum | 0xFFFF [ProcessID|0] ] ] ]
!rpcexts.getclientcallinfo -?
Parameters
CallID
Specifies the call ID. This parameter is optional; include it if you only want to display calls matching a specific CallID value.
IfStart
Specifies the first DWORD of the interface UUID on which the call was made. This parameter is optional; include it if you only want to display calls matching a specific
IfStart value.
ProcNum
Specifies the procedure number of this call. (The RPC Run-Time identifies individual routines from an interface by numbering them by position in the IDL file the
first routine in the interface is 0, the second 1, and so on.) This parameter is optional; include it if you only want to display calls matching a specific ProcNum value.
ProcessID
Specifies the process ID (PID) of the client process that owns the calls you want to display. This parameter is optional; omit it if you want to display calls owned by
multiple processes.
-?
Displays some brief Help text for this extension in the Command Prompt window.
DLL
Windows 2000
Unavailable
Windows XP and later Rpcexts.dll
Comments
This extension can only be used with CDB or with user-mode WinDbg. It is only available if full RPC state information is being gathered.
Here is an example:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 632 of 1651

0:002> !rpcexts.getclientcallinfo
Searching for call info ...
PID CELL ID
PNO IFSTART TIDNUMBER CALLID
LASTTIME PS CLTNUMBER ENDPOINT
-----------------------------------------------------------------------------03d4 0000.0001 0000 19bb5061 0000.0000 00000001 0004ca9b 07 0000.0002 1118
For a similar example using the DbgRpc tool, see Get RPC Client Call Information.
Additional Information
For more information about debugging Microsoft Remote Procedure Call (RPC), see RPC Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rpcexts.getdbgcell
The !rpcexts.getdbgcell extension displays RPC state information for the specified cell.
Syntax
!rpcexts.getdbgcell ProcessID CellID1.CellID2
!rpcexts.getdbgcell -?
Parameters
ProcessID
Specifies the process ID (PID) of the process whose server contains the desired cell.
CellID1.CellID2
Specifies the number of the cell to be displayed.
-?
Displays some brief Help text for this extension in the Command Prompt window.
DLL
Unavailable
Windows 2000
Windows XP and later Rpcexts.dll
Comments
This extension can only be used with CDB or with user-mode WinDbg.
Here is an example:
0:002> !rpcexts.getdbgcell c4 0.19
Getting cell info ...
Call
Status: Active
Procedure Number: 11
Interface UUID start (first DWORD only): 82273FDC
Call ID: 0x0 (0)
Servicing thread identifier: 0x0.3E
Call Flags: cached, LRPC
Last update time (in seconds since boot):1453.459 (0x5AD.1CB)
Caller (PID/TID) is: d0.1ac (208.428)
For a similar example using the DbgRpc tool, see Get RPC Cell Information.
Additional Information
For more information about debugging Microsoft Remote Procedure Call (RPC), see RPC Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rpcexts.getendpointinfo
The !rpcexts.getendpointinfo extension searches the system's RPC state information for endpoint information.
Syntax

Comments
This extension displays the per-thread RPC information. A field in the per-thread RPC information is the extended error information for this thread.
Here is an example:
0:001> !rpcexts.thread 7ffdd000
RPC TLS at 692e70
HandleToThread - 0x6c
SavedProcedure - 0x0
SavedParameter - 0x0
ActiveCall - 0x0
Context - 0x0
CancelTimeout - 0xffffffff
SecurityContext - 0x0
ExtendedStatus - 0x0
ThreadEEInfo - 0xb015f0
ThreadEvent at - 0x00692E78
fCallCancelled - 0x0
buffer cache array at - 0x00692E84
fAsync - 0x0
Additional Information
For more information about debugging Microsoft Remote Procedure Call (RPC), see RPC Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

*
Specifies that all breakpoints should be enabled.
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
All breakpoints are enabled when they are created. Breakpoints are only disabled if you have used the !amli bd extension.
To determine the breakpoint number of a breakpoint, use the !amli bl extension.
Additional Information
For information about related commands and their uses, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!amli bl
The !amli bl extension displays a list of all AML breakpoints.
Syntax
Syntax in Windows 2000
!acpikd.amli bl
Syntax in Windows XP and later
!amli bl
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
The AMLI Debugger supports a maximum of ten breakpoints.
Here is an example of the !amli bl extension:
kd>
0:
1:
2:
3:

!amli bl
<e> ffffffff80e5e2f1:[\_SB.LNKD._SRS]
<e> ffffffff80e5d969:[\_SB.LNKB._STA]
<d> ffffffff80e630c9:[\_WAK]
<e> ffffffff80e612c9:[\_SB.MBRD._CRS]

Syntax in Windows XP and later

!amli ds [/v] [Address]
Parameters
/v
Causes the display to be verbose. In Windows 2000, this option is available only if you are using the checked build of this extension (w2kchk\Acpikd.dll).
Address
Specifies the address of the context block whose stack is desired. If Address is omitted, the current context is used.
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Additional Information
For information about related commands and their uses, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!amli find
The !amli find extension finds an ACPI namespace object.
Syntax
Syntax in Windows 2000
!acpikd.amli find Name
Syntax in Windows XP and later
!amli find Name
Parameters
Name
Specifies the name of the namespace object (without the path).
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
The !amli find command takes the name of the object and returns the full path and name. The Name parameter must be the final segment of the full path and name.
Here are some examples. The following command will find all declarations of the object _SRS:
kd> !amli find _srs
\_SB.LNKA._SRS
\_SB.LNKB._SRS
\_SB.LNKC._SRS
\_SB.LNKD._SRS
This is not simply a text search. The command !amli find srs does not display any hits, because the final segment of each of these declarations is "_SRS", not "SRS". The
command !amli find LNK similarly does not return hits. The command !amli find LNKB would display the single node that terminates in "LNKB", not the four children of
this node shown in the previous display:
kd> !amli find lnkb
\_SB.LNKB.
If you need to see the children of a node, use the !amli dns command with the /s parameter.
Here is another example, issued from the AMLI Debugger prompt. This shows all declarations of the object _BST in the namespace:
AMLI(? for help)-> find _bst
\_SB.PCI0.ISA.BAT1._BST
\_SB.PCI0.ISA.BAT2._BST

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 646 of 1651

Additional Information
For information about related commands and their uses, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!amli lc
The !amli lc extension lists all active ACPI contexts.
Syntax
Syntax in Windows 2000
!acpikd.amli lc
Syntax in Windows XP and later
!amli lc
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
Each context corresponds to a method currently running in the AML interpreter.
Here is an example:
AMLI(? for help)-> lc
Ctxt=80e3f000, ThID=00000000,
Ctxt=80e41000, ThID=00000000,
Ctxt=80e9a000, ThID=00000000,
Ctxt=80ea8000, ThID=00000000,
*Ctxt=80e12000, ThID=80e6eda8,

Flgs=A--C-----,
Flgs=A--C-----,
Flgs=A--C-----,
Flgs=A--C-----,
Flgs=---CR----,

pbOp=00000000,
pbOp=00000000,
pbOp=00000000,
pbOp=00000000,
pbOp=80e5d5ac,

Obj=\_SB.LNKA._STA
Obj=\_SB.LNKB._STA
Obj=\_SB.LNKC._STA
Obj=\_SB.LNKD._STA
Obj=\_SB.LNKA._STA

The Obj field gives the full path and name of the method as it appears in the ACPI tables.
The Ctxt field gives the address of the context block. The asterisk (*) indicates the current context. This is the context that was being executed by the interpreter when the
break occurred.
The abbreviation pbOp indicates the instruction pointer (pointer to binary op codes).
There are nine flags that can be displayed in the Flgs section. If a flag is not set, a hyphen is displayed instead. The full list of flags is as follows:
Flag
Meaning
A Asynchronous evaluation
N Nested evaluation
Q In the ready queue
C Needs a callback
R Running
W Ready
T Time-out
D Timer dispatch
P
Timer pending
Additional Information
For information about related commands and their uses, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!amli ln

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 647 of 1651

The !amli ln extension displays the specified method or the method containing a given address.
Syntax
Syntax in Windows 2000
!acpikd.amli ln [ MethodName | CodeAddress ]
Syntax in Windows XP and later
!amli ln [ MethodName | CodeAddress ]
Parameters
MethodName
Specifies the full path of the method name. If MethodName specifies an object that is not actually a method, an error results.
CodeAddress
Specifies the address of the AML code that is contained in the desired method. If CodeAddress is prefixed with two percent signs (%%), it is interpreted as a physical
address. Otherwise, it is interpreted as a virtual address.
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
If neither MethodName nor CodeAddress is specified, the method associated with the current context is displayed.
The following command shows the method being currently run:
kd> !amli ln
c29accf5: \_WAK
The method _WAK is shown, with address 0xC29ACCF5.
Additional Information
For information about related commands and their uses, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!amli r
The !amli r extension displays information about the current context or the specified context.
Syntax
Syntax in Windows 2000
!acpikd.amli r [ContextAddress]
Syntax in Windows XP and later
!amli r [ContextAddress]
Parameters
Address
Specifies the address of the context block to be displayed. The address of a context block can be determined from the Ctxt field in the !amli lc display. If ContextAddress
is prefixed with two percent signs (%%), it is interpreted as a physical address. Otherwise, it is interpreted as a virtual address. If this parameter is omitted, the current
context is displayed.
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
If the AMLI Debugger prompt appears suddenly, this is a useful command to use.
For example, the following command will display the current context of the interpreter:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 648 of 1651

AMLI(? for help)-> r

Context=c18b4000*, Queue=00000000, ResList=00000000
ThreadID=c15a6618, Flags=00000010
StackTop=c18b5eec, UsedStackSize=276 bytes, FreeStackSize=7636 bytes
LocalHeap=c18b40c0, CurrentHeap=c18b40c0, UsedHeapSize=88 bytes
Object=\_WAK, Scope=\_WAK, ObjectOwner=c18b4108, SyncLevel=0
AsyncCallBack=ff06b5d0, CallBackData=0, CallBackContext=c99efddc
MethodObject=\_WAK
80e0ff5c: Local0=Unknown()
80e0ff70: Local1=Unknown()
80e0ff84: Local2=Unknown()
80e0ff98: Local3=Unknown()
80e0ffac: Local4=Unknown()
80e0ffc0: Local5=Unknown()
80e0ffd4: Local6=Unknown()
80e0ffe8: Local7=Unknown()
80e0e040: RetObj=Unknown()
Next AML Pointer: ffffffff80e630df:[\_WAK+16]
ffffffff80e630df
ffffffff80e630e5
ffffffff80e630e5
ffffffff80e630eb

:
:
:
:

If(S4BW
{
| Store(Zero, S4BW)
}

!amli set
The !amli set extension sets or displays the AMLI Debugger options.
Syntax
Syntax in Windows 2000
!acpikd.amli set Options
Syntax in Windows XP and later
!amli set Options
Parameters
Options
Specifies one or more options to be set. Separate multiple options with spaces. Possible values include:
spewon
(Windows XP and later) Causes full debug output to be sent from the target computer. This option should be left on at all times for effective AML debugging. See
the Comments section for details.
spewoff
(Windows XP and later) Suppresses debug output.
verboseon
Turns on verbose mode. This causes the AMLI Debugger to display the names of AML methods as they are evaluated.
verboseoff
Turns off verbose mode.
traceon
Activates ACPI tracing. This produces much more output than the verboseon option. This option is very useful for tracking SMI-related hard hangs.
traceoff
Deactivates ACPI tracing.
nesttraceon
Activates nest tracing. This option is only effective if the traceon option is also selected.
nesttraceoff
Deactivates nest tracing.
lbrkon
Breaks into the AMLI Debugger when DDB loading is completed.
lbrkoff
Deactivates the lbrkon option.
errbrkon
Breaks into the AMLI Debugger whenever the interpreter has a problem evaluating AML code.
errbrkoff
Deactivates the errbrkon option.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 652 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!nstree
The !nstree extension displays an ACPI namespace object and its children in the namespace tree.
Syntax
Syntax in Windows 2000
!acpikd.nstree [Address]
Syntax in Windows XP and later
!nstree [Address]
Parameters
Address
Specifies the address of the namespace object. This object and the entire namespace tree subordinate to it will be displayed. If Address is omitted, the entire namespace
tree is displayed.
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Comments
This extension is equivalent to !amli dns /s.
Additional Information
For more information, see ACPI Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!rsdt
The !rsdt extension displays the ACPI Root System Description Table.
Syntax
Syntax in Windows 2000
!acpikd.rsdt
Syntax in Windows XP and later
!rsdt
DLL
Windows 2000
Acpikd.dll
Windows XP and later Kdexts.dll
Additional Information
For more information, see ACPI Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 653 of 1651

Graphics Driver Extensions (Gdikdx.dll)

Extension commands that are useful for debugging the Graphics Driver Interface (GDI) can be found in Gdikdx.dll.
The Windows 2000 version of this extension DLL appears in the w2kfre and w2kchk directories. There is no version of this DLL for Windows XP or later versions of
Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!gdikdx.verifier
The !gdikdx.verifier extension displays the status of Driver Verifier during the verification of a graphics driver.
Syntax
!gdikdx.verifier [-Flags]
Parameters
Flags
Specifies what information will be displayed in the output from this command. Any combination of the following (preceded by a hyphen) is allowed:
d
Causes the display to include statistics on Memory Pool Tracking. This includes the address, size, and tag of each pool.
h (or ?)
Displays some brief Help text for this command in the Debugger Command window.
DLL
Windows 2000
Gdikdx.dll
Windows XP and later Unavailable
Comments
When verifying drivers that are not graphics drivers, the standard kernel-mode extension !verifier should be used instead of !gdikdx.verifier.
Regardless of which flags are selected, this extension will display the Driver Verifier options that are active. It will also display statistics on the frequency of random failure.
Additional Information
For information about Driver Verifier, see the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel Streaming Extensions (Ks.dll)

Extension commands that are useful for debugging kernel streaming drivers and AVStream drivers can be found in Ks.dll.
Most of the sample output in these reference pages was generated by debugging the filter-centric sample Avssamp.sys. This sample is included in the Windows Driver Kit.
If you wish to use the Ks.dll extensions with Windows 2000, you must copy Ks.dll from the kdexts directory to the w2kfre directory.
You need special symbols to use this extension. For more information, see the

Debugging Tools for Windows Web site.

You can get additional information for many of the extension commands in this section simply by entering the command into the debugger with no arguments.
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.help

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 654 of 1651

The !ks.help extension displays a help text showing all AVStream-specific Ks.dll extension commands.
Syntax
!ks.help
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.kshelp
The !ks.kshelp extension displays a help text showing original KS 1.0-specific Ks.dll extension commands.
Syntax
!ks.kshelp
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.pchelp
The !ks.pchelp extension displays a help text showing PortCls-specific Ks.dll extension commands.
Syntax
!ks.pchelp
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.allstreams
The !ks.allstreams extension walks the entire device tree and finds every kernel streaming device in the system.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 655 of 1651

Syntax
!ks.allstreams [Flags] [Level]
Parameters
Flags
Optional. Specifies the kind of information to be displayed. Flags can be any combination of the following bits. The default value is 0x1:
Bit 0 (0x1)
Causes the display to include streams.
Bit 2 (0x4)
Causes the display to include proxy instances.
Bit 3 (0x8)
Causes the display to include queued IRPs.
Bit 4 (0x10)
Causes the display to include an unformatted display of all streams.
Bit 5 (0x20)
Causes the display to include an unformatted display of all stream formats.
Level
Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a
value of 7.
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Comments
This command can take some time to execute (a minute is not unusual).
Here is an example of the !ks.allstreams display:
kd> !allstreams
6 Kernel Streaming FDOs found:
Functional Device 82a17690
Functional Device 8296eb08
Functional Device 82490388
Functional Device 82970cb8
Functional Device 824661b8
Functional Device 8241c020

[\Driver\smwdm]
[\Driver\wdmaud]
[\Driver\sysaudio]
[\Driver\MSPQM]
[\Driver\MSPCLOCK]
[\Driver\avssamp]

Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.dump
The !ks.dump extension displays the specified object.
Syntax
!ks.dump Object [Level] [Flags]
Parameters
Object
Specifies a pointer to an AVStream structure, an AVStream class object, or a PortCls object. Can also specify a pointer to an an IRP or a file object.
Level
Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a
value of 7. You can see more information about levels by issuing a !ks.dump command with no arguments.
Flags
Optional. Specifies the kind of information to be displayed. Flags can be any combination of the following bits.
Bit 0 (0x1)
Display all queued IRPs.
Bit 1 (0x2)
Display all pending IRPs.
Bit 2 (0x4)
Analyze a stalled graph for suspects.
Bit 3 (0x8)
Show all pin states.
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Comments
The !ks.dump command recognizes most AVStream objects, including pins, filters, factories, devices, pipes, and stream pointers. This command also recognizes some stream
class structures, including stream objects, filter instances, device extensions, and SRBs.
Following is an example of the !ks.dump display for a filter:
kd> !dump 829493c4
Filter object 829493c4 [CKsFilter = 82949350]
Descriptor
f7a233c8:
Context
829dce28
Following is an example of the !ks.dump display for a pin:
kd> !dump 8160DDE0 7
Pin object 8160DDE0 [CKsPin = 8160DD50]
DeviceState
KSSTATE_RUN
ClientState
KSSTATE_RUN
ResetState
KSRESET_END
CKsPin object 8160DD50 [KSPIN = 8160DDE0]
State
KSSTATE_RUN
Processing Mutex
8160DFD0 is not held
And Gate &
8160DF88
And Gate Count
1

Some important parts of this display are included in the following table.
Parameter Meaning
DeviceState The state that the pin was requested to enter. If different from ClientState, this is the state that the minidriver will transition to next.
ClientState The state that the minidriver is actually in. This reflects the state of the pipe.
ResetState Indicates whether or not the object is in the middle of a flush.
KSRESET_BEGIN indicates a flush.
KSRESET_END indicates no flush.
State

The internal state of the pin's transport to non-AVStream filters.

Following is an example of the !ks.dump display for a stream class driver:

kd> !dump 81a0a170 7
Device Extension 81a0a228:
Device Object
81a0a170 [\Driver\TESTCAP]
Next Device Object
81bd56d8 [\Driver\PnpManager]
Physical Device Object 81bd56d8 [\Driver\PnpManager]
REGISTRY FLAGS:
Page out driver when closed
No suspend if running

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 659 of 1651

MINIDRIVER Data:
Device Extension
81a0a44c
Interrupt Routine
00000000
Synchronize Routine
STREAM!StreamClassSynchronizeExecution
Receive Device SRB
testcap!AdapterReceivePacket
Cancel Packet
testcap!AdapterCancelPacket
Timeout Packet
testcap!AdapterTimeoutPacket
Size (d / r / s / f)
1a0(416), 14(20), 978(2424), 0(0)
Sync Mode
Driver Synchronizes
Filter Type 0:
Symbolic Links:
Information Paged Out
Instances:
816b7bd8
Note that the sizes are listed both in hexadecimal numbers, and then, parenthetically in the decimal equivalent. The Size abbreviations in this display are listed in the
following table.
Size Explanation
d Device
r
Request
s
Stream
f
Filter. If the filter size is 0, the filter is single instance. If it is greater than 0, it is multi-instance.
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.dumpbag
The !ks.dumpbag extension displays the contents of the object bag for the specified object.
Syntax
!ks.dumpbag Object [Level]
Parameters
Object
Specifies a pointer to a valid client viewable object structure, or to the private class object.
Level
Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a
value of 7.
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Comments
Here is an example of the !ks.dumpbag display for a filter:
kd> !dumpbag 829493c4
Filter 829493c4 [CKsFilter = 82949350]:
Object Bag 829493d0:
Object Bag Item 829dce28:
Reference Count
: 1
Item Cleanup Handler
: f7a21730
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Child Count
1
Bound Child Count 1
Necessary Count
0
Specific Instances:
8293f580
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.graph
The !ks.graph extension command displays a textual description of the kernel mode graph in topologically sorted order.
Syntax
!ks.graph Object [Level] [Flags]
Parameters
Object
Specifies a pointer to the object to use as a starting point for the graph. Must be a pointer to one of the following: file object, IRP, pin, or filter.
Level
Optional. Specifies the level of detail to display on a 0-7 scale with progressively more information displayed for higher values. To display all available details, supply a
value of 7. The levels for !ks.graph are the same as those for !ks.dump.
Flags
Optional. Specifies the kind of information to be displayed. Flags can be any combination of the following bits.
Bit 0 (0x1)
Display a list of IRPs queued to each pin instance in the graph.
Bit 1 (0x2)
Display a list of IRPs that are pending from each pin instance in the graph. Only IRPs that the pin knows it is waiting for are displayed.
Bit 4 (0x10)
Analyze a stalled graph for suspect filters.
DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Comments
This command may take a bit of time to process.
Issue a !ks.graph command with no arguments for help.
Here is an example of the !ks.graph display, with the address of a filter object:
kd> !graph 829493c4
Attempting a graph build on 829493c4...

Please be patient...

Graph With Starting Point 829493c4:

"avssamp" Filter 82949350, Child Factories 1
Output Factory 0 [Video/General Capture]:
Pin 8293f4f0 (File 82503498) Irps(q/p) = 2, 0
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!ks.libexts
The !ks.libexts extension provides access to Microsoft-supplied library extensions that are statically linked to the extension module.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 670 of 1651

DLL
Windows 2000
winxp\Ks.dll
Windows XP and later Ks.dll
Comments
For help, issue a !ks.topology command with no arguments.
Note that this command may take a few moments to execute.
Additional Information
For more information, see Kernel Streaming Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SCSI Miniport Extensions (Scsikd.dll and Minipkd.dll)

Extension commands that are useful for debugging SCSI miniport drivers can be found in Scsikd.dll and Minipkd.dll.
You can use the Scsikd.dll extension commands with any version of Windows. However, you can only use the Minipkd.dll extension commands with Windows XP and later
versions of Windows. Commands in Minipkd.dll are only applicable to SCSIport-based miniports.
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!scsikd.help
The !scsikd.help extension displays help text for Scsikd.dll extension commands.
Syntax
!scsikd.help
DLL
Windows 2000
Scsikd.dll
Windows XP and later Scsikd.dll
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!scsikd.classext
The !scsikd.classext extension displays the specified class Plug and Play (PnP) device.
Syntax
!scsikd.classext [Device [Level]]
Parameters
Device
Specifies the device object or device extension of a class PnP device. If Device is omitted, a list of all class PnP extensions is displayed.
Level

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 671 of 1651

Specifies the amount of detail to display. This parameter can take 0, 1, or 2 as values, with 2 giving the most detail. The default is 0.
DLL
Windows 2000
Scsikd.dll
Windows XP and later Scsikd.dll
Comments
Here is an example of the !scsikd.classext display:
0: kd> !scsikd.classext
' !scsikd.classext 8633e3f0
' !scsikd.classext 86347b48
' !scsikd.classext 86347360
' !scsikd.classext 861d1898

'
'
'
'

(
) "IBM
" / "DDYS-T09170M
(paging device) "IBM
" / "DDYS-T09170M
(
) "UNISYS " / "003451ST34573WC
(
) "" / "MATSHITA CD-ROM CR-177"

"
"
"
/

/ "S93E"
/ "S80D"
/ "5786"
"7T03" /

/ "
XBY45906"
/ "
VDA60491"
/ "HN0220750000181300L6"
""

usage: !classext <class fdo> <level [0-2]>

Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!scsikd.scsiext
The !scsikd.scsiext extension displays detailed information about the specified SCSI port extension.
Syntax
!scsikd.scsiext Device
Parameters
Device
Specifies the device object or device extension of a SCSI port extension.
DLL
Windows 2000
Scsikd.dll
Windows XP and later Scsikd.dll
Comments
Here is an example of the !scsikd.scsiext display, where the SCSI port extension has been specified by a functional device object (FDO); this can be obtained from the DO
field or DevExt field in the !minipkd.adapters display:
kd> !scsikd.scsiext 816f9a40
Scsiport functional device extension at address 816f9af8
Common Extension:
Initialized
DO 0x816f9a40 LowerObject 0x816e8030 SRB Flags 00000000
Current Power (D0,S0) Desired Power D-1 Idle 00000000
Current PnP state 0x0
Previous state 0xff
DispatchTable f9aee200
UsePathCounts (P0, H0, C0)
Adapter Extension:
Port 2
IsPnp VirtualSlot HasInterrupt
LowerPdo 0x816e8030
HwDevExt 0x8170a004
Active Requests 0xffffffff
MaxBus 0x01
MaxTarget 0x10
MaxLun 0x08
Port Flags (0x00001000): PD_DISCONNECT_RUNNING
NonCacheExt 0x81702000 IoBase 0x00002000
Int 0x1a
RealBus# 0x0 RealSlot# 0x2
Timeout 0xffffffff
DpcFlags 0x00000000
Sequence 0x00000003
Srb Ext Header 0x817061a0
No. Requests 0x00000012
QueueTag BitMap 0x00000000
Hint 0x00000000
MaxQueueTag 0xfe (@0x816f9c58)
LuExt Size 0x00000038
SrbExt Size 0x00000188
SG List Size - Small 17
Large 0
Emergency - SrbData 0x816f9830 Blocked List @0x816f9e94
CommonBuff - Size: 0x00006000
PA: 0x0000000001702000 VA: 0x81702000
Ke Objects - Int1: 0x8175ba50
Int2: 0x00000000
Dma: 0x816f9340
Lookaside - SrbData @ 0x816f9e40 SgList @0x00000000 Remove: @0x00000000
Resources - Raw: 0x817ba190
Translated: 0x81709678

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

!minipkd.exports
The !minipkd.exports extension displays the addresses of the miniport exports for the specified adapter.
Syntax
!minipkd.exports Adapter
Parameters
Adapter
Specifies the address of an adapter.
DLL
Windows 2000
Unavailable
Windows XP and later Minipkd.dll
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!minipkd.lun
The !minipkd.lun extension displays detailed information about the specified Logical Unit Extension (LUN).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 675 of 1651

Syntax
!minipkd.lun LUN
!minipkd.lun Device
Parameters
LUN
Specifies the address of the LUN.
Device
Specifies the physical device object (PDO) for the LUN.
DLL
Windows 2000
Unavailable
Windows XP and later Minipkd.dll
Comments
A LUN is typically referred to as a device. Thus, this extension displays information about a device on an adapter.
The LUN can be specified either by its address (which can be found in the LUN field of the !minipkd.adapters display), or by its physical device object (which can be found
in the DevObj field of the !minipkd.adapters display).
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!minipkd.portconfig
The !minipkd.portconfig extension displays information about the specified PORT_CONFIGURATION_INFORMATION data structure.
Syntax
!minipkd.portconfig PortConfig
Parameters
PortConfig
Specifies the address of a PORT_CONFIGURATION_INFORMATION data structure.
DLL
Windows 2000
Unavailable
Windows XP and later Minipkd.dll
Comments
The PortConfig address can be found in the Port Config Info field of the !minipkd.adapter display.
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!minipkd.req
The !minipkd.req extension displays information about all of the currently active requests on the specified adapter or device.
Syntax
!minipkd.req Adapter
!minipkd.req Device

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 676 of 1651

Parameters
Adapter
Specifies the address of the adapter.
Device
Specifies the physical device object (PDO) for the Logical Unit Extension (LUN) device.
DLL
Windows 2000
Unavailable
Windows XP and later Minipkd.dll
Comments
The PDO for a LUN can be found in the DevObj field of the !minipkd.adapters display.
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!minipkd.srb
The !minipkd.srb extension displays the specified SCSI request block (SRB) data structure.
Syntax
!minipkd.srb SRB
Parameters
SRB
Specifies the address of an SRB.
DLL
Windows 2000
Unavailable
Windows XP and later Minipkd.dll
Comments
The addresses of all currently active requests can be found in the SRB fields of the output from the !minipkd.req command.
This extension displays the status of the SRB, the driver it is addressed to, the SCSI that issued the SRB and its address, and a hexadecimal flag value. If 0x10000 is set in the
flag value, this request is currently in the miniport.
Additional Information
For more information, see SCSI Miniport Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel-Mode Driver Framework Extensions (Wdfkd.dll)

Extension commands that are useful for debugging Kernel-Mode Driver Framework (KMDF) drivers are implemented in Wdfkd.dll.
These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions; these restrictions are noted on the
individual reference pages.
For more information about how to use these extensions, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 677 of 1651

Debugging Tools for Windows

!wdfkd.help
The !wdfkd.help extension displays help information about all Wdfkd.dll extension commands.
Syntax
!wdfkd.help
DLL
Wdfkd.dll
Additional Information
The !wdfkd.help extension is equivalent to the !wdfkd.wdfhelp extension.
For more information about debugging framework-based drivers, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

context: dt 0x8352cff0 RAW_PDO_CONTEXT (size is 0xc bytes)
<no associated attribute callbacks>
!WDFDEVICE 0x7cad31c8
!wdfobject 0x8352ce30
kd> dt 0x8352cff0 RAW_PDO_CONTEXT
+0x000 ChildList
: 0x7ce710c8 WDFCHILDLIST__
+0x004 BusGenerationTimer : 0x7d8bd0b0 WDFTIMER__
+0x008 BusGenerationCount : 0
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdevice
The !wdfkd.wdfdevice extension displays information that is associated with a WDFDEVICE-typed object handle.
Syntax
!wdfkd.wdfdevice Handle [Flags]
Parameters
Handle
A handle to a WDFDEVICE-typed object.
Flags
Optional. The kind of information to display. Flags can be any combination of the following bits:
Bit 0 (0x1)
The display will include verbose information about the device, such as the associated WDFCHILDLIST-typed handles, synchronization scope, and execution level.
Bit 1 (0x2)
The display will include detailed power state information.
Bit 2 (0x4)
The display will include detailed power policy state information.
Bit 3 (0x8)
The display will include detailed Plug and Play (PnP) state information.
Bit 4 (0x10)
The display will include the device object's callback functions.
DLL
Wdfkd.dll
Comments
The following example uses the !wdfkd.wdfdevice extension on a WDFDEVICE handle that represents a physical device object (PDO), without specifying any flags.
kd> !wdfdevice 0x7cad31c8
Dumping WDFDEVICE 0x7cad31c8
=================================
WDM PDEVICE_OBJECTs:

self 81fb00e8

Pnp state: 119 ( WdfDevStatePnpStarted )

Power state: 31f ( WdfDevStatePowerDx )
Power Pol state: 508 ( WdfDevStatePwrPolWaitingUnarmed )
Parent WDFDEVICE 7ca7b1c0
Parent states:
Pnp state: 119 ( WdfDevStatePnpStarted )
Power state: 307 ( WdfDevStatePowerD0 )
Power Pol state: 565 ( WdfDevStatePwrPolStarted )
No pended pnp or power irps
Device is the power policy owner for the stack
The following example displays the same device object as the preceding example, but this time with a flag value of 0xF. This flag value, a combination of the bits 0x1, 0x2,
0x4, and 0x8, causes the display to include verbose device information, power state information, power policy state information, and PnP state information.
kd> !wdfdevice 0x7cad31c8 f

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 681 of 1651

Dumping WDFDEVICE 0x7cad31c8

=================================
WDM PDEVICE_OBJECTs:

self 81fb00e8

Pnp state: 119 ( WdfDevStatePnpStarted )

state history:
WdfDevStatePnpObjectCreated (0x100)
WdfDevStatePnpInit (0x105)
WdfDevStatePnpInitStarting (0x106)
WdfDevStatePnpHardwareAvailable (0x108)
WdfDevStatePnpEnableInterfaces (0x109)
WdfDevStatePnpStarted (0x119)

Power state history:

[0] WdfDevStatePowerD0StartingConnectInterrupt (0x310)
[1] WdfDevStatePowerD0StartingDmaEnable (0x311)
[2] WdfDevStatePowerD0StartingStartSelfManagedIo (0x312)
[3] WdfDevStatePowerDecideD0State (0x313)
[4] WdfDevStatePowerD0BusWakeOwner (0x309)
[5] WdfDevStatePowerGotoDx (0x31a)
[6] WdfDevStatePowerGotoDxIoStopped (0x31c)
[7] WdfDevStatePowerDx (0x31f)
Power policy state history:
[0] WdfDevStatePwrPolStarting (0x501)
[1] WdfDevStatePwrPolStartingSucceeded (0x502)
[2] WdfDevStatePwrPolStartingDecideS0Wake (0x504)
[3] WdfDevStatePwrPolStartedIdleCapable (0x505)
[4] WdfDevStatePwrPolTimerExpiredNoWake (0x506)
[5] WdfDevStatePwrPolTimerExpiredNoWakeCompletePowerDown (0x507)
[6] WdfDevStatePwrPolWaitingUnarmedQueryIdle (0x509)
[7] WdfDevStatePwrPolWaitingUnarmed (0x508)
WDFCHILDLIST Handles:
!WDFCHILDLIST 0x7ce710c8
SyncronizationScope is WdfSynchronizationScopeNone
ExecutionLevel is WdfExecutionLevelDispatch
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdevicequeues
The !wdfkd.wdfdevicequeues extension displays information about all of the framework queue objects that belong to a specified device.
Syntax
!wdfkd.wdfdevicequeues Handle
Parameters
Handle
A handle to a WDFDEVICE-typed object.
DLL
Wdfkd.dll
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 682 of 1651

The following example shows the display from the !wdfdevicequeues extension.
kd> !wdfdevicequeues 0x7cad31c8
Dumping queues of WDFDEVICE 0x7cad31c8
=====================================
Number of queues: 3
---------------------------------Queue: 1 (!wdfqueue 0x7d67d1e8)
Manual, Not power-managed, PowerOn, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone
Number of driver owned requests: 0
Number of waiting requests: 0

This is WDF internal queue for create requests.

---------------------------------Queue: 2 (!wdfqueue 0x7ce7d1e8)
Parallel, Power-managed, PowerOff, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone
Number of driver owned requests: 0
Number of waiting requests: 0

EvtIoDefault: (0xf221fad0) wdfrawbusenumtest!EvtIoQueueDefault

---------------------------------Queue: 3 (!wdfqueue 0x7cd671e8)
Parallel, Power-managed, PowerOff, Can accept, Can dispatch, ExecutionLevelDispatch, SynchronizationScopeNone
Number of driver owned requests: 0
Number of waiting requests: 0

EvtIoDeviceControl: (0xf2226ac0) wdfrawbusenumtest!RawBus_RawPdo_EvtDeviceControl

Additional Information
For more information, see Kernel-Mode Driver Framework Debugging and !wdfkd.wdfqueue.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdmaenabler
The !wdfkd.wdfdmaenabler extension displays information about a WDF direct memory access (DMA) object, and its transaction and common buffer objects.
Syntax
!wdfkd.wdfdmaenabler Handle
Parameters
Handle
A handle to a framework DMA enabler object (WDFDMAENABLER).
DLL
Wdfkd.dll
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdmaenablers
The !wdfkd.wdfdmaenablers extension displays all WDF direct memory access (DMA) objects associated with a specified device object. It also displays their associated
transaction and common buffer objects.
Syntax

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 683 of 1651

!wdfkd.wdfdmaenablers Handle
Parameters
Handle
A handle to a framework device object (WDFDEVICE).
DLL
Wdfkd.dll
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdmatransaction
The !wdfkd.wdfdmatransaction extension displays information about a WDF direct memory access (DMA) transaction object.
Syntax
!wdfkd.wdfdmatransaction Handle
Parameters
Handle
A handle to a framework DMA transaction object (WDFDMATRANSACTION).
DLL
Wdfkd.dll
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfdriverinfo
The !wdfkd.wdfdriverinfo extension displays information about the specified driver, including its device tree, the version of the Kernel-Mode Driver Framework (KMDF)
library that the driver was compiled with, and a list of the framework device objects that the driver created.
Syntax
!wdfkd.wdfdriverinfo [DriverName [Flags] ]
Parameters
DriverName
Optional. The name of the driver. DriverName must not include the .sys file name extension.
Flags
Optional. Flags that specify the kind of information to display. Flags can be any combination of the following bits:
Bit 0 (0x1)
The display will include verifier settings for the driver, and will also include a count of WDF objects. This flag can be combined with bit 6 (0x40) to display internal
objects.
Bit 4 (0x10)
The display will include the KMDF handle hierarchy for the driver.
Bit 5 (0x20)
The display will include context and callback function information for each handle. This flag is valid only when bit 4 (0x10) is set.
Bit 6 (0x40)
The display will include additional information for each handle. This flag is valid only when bit 4 (0x10) is set. This flag can be combined with bit 0 (0x1) to display
internal objects.
Bit 7 (0x80)
The handle information will be displayed in a more compact format.
Bit 8 (0x100)
The display will left align internal type information. This flag is valid only when bit 4 (0x10) is set.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 684 of 1651

Bit 9 (0x200)
The display will include handles that the driver potentially leaked. KMDF version 1.1 and later support this flag. This flag is valid only when bit 4 (0x10) is set.
Bit 10 (0x400)
The display will include the device tree in verbose form.
DLL
Wdfkd.dll
Comments
If you omit the DriverName parameter, the default driver is used. You can display the default driver by using the !wdfkd.wdfgetdriver extension; you can set the default
driver by using the !wdfkd.wdfsetdriver extension.
The following example shows the display from the !wdfkd.wdfdriverinfo extension.
kd> !wdfdriverinfo wdfrawbusenumtest
---------------------------------Default driver image name:
wdfrawbusenumtest
WDF library image name:
Wdf01000
FxDriverGlobals 0x83b7af18
WdfBindInfo
0xf22250ec
Version
v1.5 build(1234)
---------------------------------WDFDRIVER: 0x7cbc90d0
!WDFDEVICE 0x7ca7b1c0
context: dt 0x83584ff8 ROOT_CONTEXT (size is 0x1 bytes)
<no associated attribute callbacks>
!WDFDEVICE 0x7cad31c8
context: dt 0x8352cff0 RAW_PDO_CONTEXT (size is 0xc bytes)
<no associated attribute callbacks>
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wdfkd.wdfextendwatchdog
The !wdfkd.wdfextendwatchdog extension extends the time-out period (from 10 minutes to 24 hours) of the framework's watchdog timer during power transitions.
Syntax
!wdfkd.wdfextendwatchdog Handle [Extend]
Parameters
Handle
A handle to a WDFDEVICE-typed object.
Extend
Optional. A value that indicates whether to enable or disable extension of the time-out period. If Extend is 0, extension is disabled, and the time-out period is 10 minutes.
If Extend is 1, extension is enabled and the time-out period is 24 hours. The default value is 1.
DLL
Wdfkd.dll
Comments
The framework starts an internal watchdog timer every time it calls a power policy or power event callback function for a driver that is not power pageable (that is, the
DO_POWER_PAGABLE bit is clear). If the callback function causes paging I/O and therefore blocks, the operating system hangs because no paging device is available to
service the request.
If the time-out period elapses, the framework issues bug check 0x10D (WDF_VIOLATION). For details, see Bug Check 0x10D.
Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 685 of 1651

December 09, 2009

Debugging Tools for Windows

!wdfkd.wdffindobjects
The !wdfkd.wdffindobjects extension searches memory for WDF objects.
Syntax
!wdfkd.wdffindobjects [ StartAddress [Flags] ]
Parameters
StartAddress
Optional. Specifies the address at which the search must begin. If this is omitted, the search will begin from where the most recent !wdfkd.wdffindobjects search ended.
Flags
Optional. Specifies the kind of information to display. Flags can be any combination of the following bits. The default value is 0x0. Flags cannot be used unless
StartAddress is specified.
Bit 0 (0x1)
Displays verbose output.
Bit 1 (0x2)
Displays internal type information for each handle.
DLL
Wdfkd.dll
Comments
The following examples show the output of the !wdffindobjects extension. The 0x1 flag is set in the second example.
1: kd> !wdffindobjects 0xfffffa600211b668
Address
Value
------------------ -----------------0xfffffa600211b668 0x0000000000000008
0xfffffa600211b670 0xfffffa8002e7b1f0
0xfffffa600211b678 0x0000000000000004
0xfffffa600211b680 0x0000000000000001
0xfffffa600211b688 0xfffffa8006aa3640
0xfffffa600211b690 0x0000000000000000
0xfffffa600211b698 0xfffff80001e61f78
0xfffffa600211b6a0 0x0000000000000010
0xfffffa600211b6a8 0x0000000000010286
0xfffffa600211b6b0 0xfffffa600211b6c0
0xfffffa600211b6b8 0x0000000000000000
0xfffffa600211b6c0 0xfffffa8006aa3640
0xfffffa600211b6c8 0x0000057ffd184e08
0xfffffa600211b6d0 0x0000000000000000
0xfffffa600211b6d8 0x0000057ffc51ea18
0xfffffa600211b6e0 0x0000000000000000
1: kd> !wdffindobjects 0xfffffa600211b668
Address
Value
------------------ -----------------0xfffffa600211b668 0x0000000000000008
0xfffffa600211b670 0xfffffa8002e7b1f0
0xfffffa600211b678 0x0000000000000004
0xfffffa600211b680 0x0000000000000001
0xfffffa600211b688 0xfffffa8006aa3640
0xfffffa600211b690 0x0000000000000000
0xfffffa600211b698 0xfffff80001e61f78
0xfffffa600211b6a0 0x0000000000000010
0xfffffa600211b6a8 0x0000000000010286
0xfffffa600211b6b0 0xfffffa600211b6c0
0xfffffa600211b6b8 0x0000000000000000
0xfffffa600211b6c0 0xfffffa8006aa3640
0xfffffa600211b6c8 0x0000057ffd184e08
0xfffffa600211b6d0 0x0000000000000000
0xfffffa600211b6d8 0x0000057ffc51ea18
0xfffffa600211b6e0 0x0000000000000000

Object
-----------------!WDFREQUEST 0x0000057ffd184e08

!WDFUSBPIPE 0x0000057ff955c9b8

!WDFUSBPIPE 0x0000057ff955c9b8
!WDFREQUEST 0x0000057ffd184e08
!WDFMEMORY 0x0000057ffc51ea18

1
Type
------

Object
------------------

Object

!WDFREQUEST 0x0000057ffd184e08

Object

!WDFUSBPIPE 0x0000057ff955c9b8

Object
Handle

!WDFUSBPIPE 0x0000057ff955c9b8
!WDFREQUEST 0x0000057ffd184e08

Handle

!WDFMEMORY 0x0000057ffc51ea18

Additional Information
For more information, see Kernel-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 686 of 1651

Debugging Tools for Windows

!wdfkd.wdfforwardprogress
The !wdfkd.wdfforwardprogress extension displays information about the forward progress of a specified framework queue object.
Syntax
!wdfkd.wdfforwardprogress Handle
Parameters
Handle
A handle to a framework queue object.
DLL
Wdfkd.dll
Comments
This extension will succeed only if the specified framework queue object is configured to support forward progress. If this extension is used with other objects, an error
message will be displayed.
The following example shows the display from a !wdfkd.wdfforwardprogress extension.
kd> !wdfkd.wdfforwardprogress 0x79af3250
Dumping forward progress fields for WDFQUEUE 0x79af3250
=================================================
ForwardProgressReservedPolicy: UseExamine (0x2)
Total reserved requests: 44
Number of available
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST
!WDFREQUEST

reserved requests in list:

0x7bcaf4c0 (Reserved) !IRP
0x7bc67eb0 (Reserved) !IRP
0x7bccf678 (Reserved) !IRP
0x7bb6ce40 (Reserved) !IRP
0x7be30a58 (Reserved) !IRP
0x79af37d0 (Reserved) !IRP
0x7bc7f428 (Reserved) !IRP
0x7bbd40f0 (Reserved) !IRP
0x7bd333a8 (Reserved) !IRP
0x7bd241d8 (Reserved) !IRP
0x7bd594e0 (Reserved) !IRP
0x7bd80d10 (Reserved) !IRP
0x78ea2d50 (Reserved) !IRP
0x792020f0 (Reserved) !IRP
0x7bc37258 (Reserved) !IRP
0x7bbc1fb0 (Reserved) !IRP
0x7bbc4fb0 (Reserved) !IRP
0x7be0cb80 (Reserved) !IRP
0x7bc84890 (Reserved) !IRP
0x78acbd18 (Reserved) !IRP
0x7bcf1ad8 (Reserved) !IRP
0x7bead540 (Reserved) !IRP
0x7922c0f0 (Reserved) !IRP
0x7a34a0f0 (Reserved) !IRP
0x625195d0 (Reserved) !IRP
0x7bc33640 (Reserved) !IRP
0x7bba9f28 (Reserved) !IRP
0x7bba44c8 (Reserved) !IRP
0x7bb77cd8 (Reserved) !IRP
0x7a2b89a8 (Reserved) !IRP
0x7a41ab88 (Reserved) !IRP
0x7bc7cc88 (Reserved) !IRP
0x7bd37180 (Reserved) !IRP
0x7bca40f0 (Reserved) !IRP
0x64b4af20 (Reserved) !IRP
0x7bd01a40 (Reserved) !IRP
0x7a25cfb0 (Reserved) !IRP
0x7bba9330 (Reserved) !IRP
0x7bd14a40 (Reserved) !IRP
0x7bcc0210 (Reserved) !IRP
0x7a54eb00 (Reserved) !IRP

Number of reserved requests in

!WDFREQUEST 0x7bf0ab80
!WDFREQUEST 0x7bc53ca8
!WDFREQUEST 0x7bced8b8

The following example shows the output of the !wdfinterrupt extension with bit 0 set in the Flags parameter (so the output displays information about the IDT).
kd> !wdfkd.wdfinterrupt 0x7a988698

Dumping WDFINTERRUPT 0x7a988698

=========================
Interrupt Type: Line-based, Connected, Enabled
Vector: 0xa1 (!idt 0xa1)
Irql: 0x9
Mode: LevelSensitive
Polarity: WdfInterruptPolarityUnknown
ShareDisposition: CmResourceShareShared
FloatingSave: FALSE
Interrupt Priority Policy: WdfIrqPriorityUndefined
Processor Affinity Policy: WdfIrqPolicyOneCloseProcessor
Processor Group: 0
Processor Affinity: 0x3
dt nt!KINTERRUPT 0x8594eb28
EvtInterruptIsr: 1394ohci!Interrupt::WdfEvtInterruptIsr (0x8d580552)
EvtInterruptDpc: 1394ohci!Interrupt::WdfEvtInterruptDpc (0x8d580682)
Dumping IDT:
a1:

85167a58 ndis!ndisMiniportIsr (KINTERRUPT 85167a00)

Wdf01000!FxInterrupt::_InterruptThunk (KINTERRUPT 85987500)

Page 700 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User-Mode Driver Framework Extensions (Wudfext.dll)

Extension commands that are useful for debugging User-Mode Driver Framework drivers are implemented in Wudfext.dll.
You can use the Wudfext.dll extension commands in Microsoft Windows XP and later operating systems. Some extensions have additional restrictions on the Windows
version or UMDF version that is required; these restrictions are noted on the individual reference pages.
For ways to use these extensions, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CurrentStackLocation: 2 (StackLocation[ 1 ])
StackLocation[ 0 ]
UNINITIALIZED
> StackLocation[ 1 ]
IWDFRequest: ????
IWDFDevice:
0x000f2f80
IWDFFile:
0x003a7648
Completion:
Callback:
0x00000000
Context:
0x00000000
Parameters: (RequestType: WdfRequestRead)
Buffer length:
0x400
Key:
0x00000000
Offset:
0x0
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.umirps
The !wudfext.umirps extension displays the list of pending user-mode I/O request packets (UM IRPs) in the host process.
Syntax
!wudfext.umirps [NumberOfIrps [Flags] ]
Parameters
NumberOfIrps
Optional. Specifies the number of pending UM IRPs to display information about. If NumberOfIrps is an asterisk (*) or is omitted, all UM all UM IRPs will be displayed.
Flags
Optional. Specifies the type of information to be displayed. Flags can be any combination of the following bits. The default value is 0x01.
Bit 0 (0x01)
Displays details about the pending IRPs.
DLL
Unavailable
Windows 2000
Windows XP and later Wudfext.dll
Comments
The list of pending UM IRPs that are displayed have either been presented to the driver or are waiting to be presented to the driver.
By default, !wudfext.umirps shows all UM IRPs. However, you can use the NumberOfIrps parameter to limit this display.
The following is an example of the !wudfext.umirps display:
kd> !umirps 0xa
Number of pending IRPS: 0xc8
#### CWudfIrp
Type
---- ---------------- ---------0000
3dd280
READ
0001
3dd380
WRITE
0002
3dd480
READ
0003
3dd580
READ
0004
3dd680
WRITE
0005
3dd780
READ
0006
3dd880
WRITE
0007
3dd980
READ
0008
3dda80
READ
0009
3ddb80
WRITE

UniqueId
---------------dc
dd
de
df
e0
e1
e2
e3
e4
e5

KernelIrp
--------856f02f0
85b869e0
85377850
93bba4e8
84cb9d70
85bec150
86651db0
85c22818
9961d150
85c15148

To determine the corresponding kernel-mode IRP, use the !wudfext.wudfdownkmirp extension. Alternatively, you can use the values in the UniqueId and KernelIrp
columns to match a UMDF IRP (or UM IRP) to a corresponding kernel IRP. You can pass the values in the CWudfIrp column to the !wudfext.umirp extension to determine
the framework IWDFRequest objects that each layer in the device stack can access.
Additional Information
For more information, see User-Mode Driver Framework Debugging.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 704 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfdevice
The !wudfext.wudfdevice extension displays the Plug and Play (PnP) and power-management state systems for a device.
Syntax
!wudfext.wudfdevice pWDFDevice
Parameters
pWDFDevice
Specifies the address of the IWDFDevice interface to display PnP or power-management state about.
DLL
Unavailable
Windows 2000
Windows XP and later Wudfext.dll
Comments
You can use the !wudfext.wudfdevice extension to determine the current PnP or power-management state of the device that the pWDFDevice parameter specifies.
The following is an example of the !wudfext.wudfdevice display:
kd> !wudfdevice 0xf2f80
Pnp Driver Callbacks:
IPnpCallback: 0x0
IPnpCallbackHardware: 0x0
IPnpSelfManagedIo: 0x0
Pnp State Machine:
CurrentState: WdfDevStatePnpStarted
Pending UMIrp: 0x00000000
Could not read event queue depth, assuming 8
Event queue:
Processed/in-process events:
PnpEventAddDevice
PnpEventStartDevice
PnpEventPwrPolStarted
Pending events:
State History:
WdfDevStatePnpInit
WdfDevStatePnpInitStarting
WdfDevStatePnpHardwareAvailable
WdfDevStatePnpEnableInterfaces
WdfDevStatePnpStarted
Power State Machine:
CurrentState:
WdfDevStatePowerD0
Pending UMIrp:
0x00000000
IoCallbackFailure: false
Could not read event queue depth, assuming 8
Event queue:
Processed/in-process events:
PowerImplicitD0
Pending events:
State History:
WdfDevStatePowerStartingCheckDeviceType
WdfDevStatePowerD0Starting
WdfDevStatePowerD0StartingConnectInterrupt
WdfDevStatePowerD0StartingDmaEnable
WdfDevStatePowerD0StartingStartSelfManagedIo
WdfDevStatePowerDecideD0State
WdfDevStatePowerD0
Power Policy State Machine:
CurrentState
: WdfDevStatePwrPolStartingSucceeded
PowerPolicyOwner
: false
PendingSystemPower UMIrp : 0x00000000
PowerFailed
: false
Could not read event queue depth, assuming 8
Event queue:
Processed/in-process events:
PwrPolStart
PwrPolPowerUp
Pending events:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 705 of 1651

State History:
WdfDevStatePwrPolStarting
WdfDevStatePwrPolStarted
WdfDevStatePwrPolStartingSucceeded
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfdevicequeues
The !wudfext.wudfdevicequeues extension displays information about all the I/O queues for a device.
Syntax
!wudfext.wudfdevicequeues pWDFDevice
Parameters
pWDFDevice
Specifies the address of the IWDFDevice interface for which to display information about all of its associated I/O queues. The !wudfext.wudfdriverinfo extension
command determines the address of IWDFDevice.
DLL
Unavailable
Windows 2000
Windows XP and later Wudfext.dll
Comments
The following is an example of the !wudfext.wudfdevicequeues display:
kd> !wudfdevicequeues 0xf2f80
-------------------------------------------------Queue: 1 (!wudfqueue 0x000f3500)
WdfIoQueueDispatchSequential, POWER MANAGED, WdfIoQueuePowerOn, CAN ACCEPT, CAN DISPATCH
Number of driver owned requests: 1
IWDFIoRequest 0x000fa7c0
CWdfIoRequest 0x000fa748
Number of waiting requests: 199
IWDFIoRequest 0x000fa908
CWdfIoRequest 0x000fa890
IWDFIoRequest 0x000faa50
CWdfIoRequest 0x000fa9d8

IWDFIoRequest 0x000fa678
CWdfIoRequest 0x000fa600
Driver's callback interfaces.
IQueueCallbackRead 0x000f343c
IQueueCallbackDeviceIoControl 0x000f3438
IQueueCallbackWrite 0x000f3440

Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfdownkmirp
The !wudfext.downkmmirp extension displays the kernel-mode I/O request packet (IRP) that corresponds to the specified user-mode I/O request packet (UM IRP).
Syntax
!wudfext.wudfdownkmirp Address
Parameters
Address

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 706 of 1651

Specifies the address of the UM IRP whose corresponding kernel-mode IRP is to be displayed.
DLL
Windows 2000
Unavailable
Windows XP and later Wudfext.dll
Comments
You can use the !wudfext.umirps extension command to display a list of all outstanding UM IRPs in the host process.
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfdriverinfo
The !wudfext.wudfdriverinfo extension displays information about a UMDF driver within the current host process.
Syntax
!wudfext.wudfdriverinfo Name
Parameters
Name
Specifies the name of the UMDF driver to display information about.
DLL
Unavailable
Windows 2000
Windows XP and later Wudfext.dll
Comments
The !wudfext.wudfdriverinfo extension iterates through each level in each device stack and displays the driver and device information for each entry that matches the driver
whose name is specified in the Name parameter.
You can use !wudfext.wudfdriverinfo to quickly find the device object for your driver.
The following is an example of the !wudfext.wudfdriverinfo display:
kd> !wudfdriverinfo wudfechodriver
IWDFDriver: 0xf2db8
!WDFDEVICE 0xf2f80
!devstack 0x34e4e0 @ level 0
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfdumpobjects
The !wudfext.wudfdumpobjects extension displays outstanding UMDF objects.
Syntax
!wudfext.wudfdumpobjects ObjTrackerAddress
Parameters
ObjTrackerAddress
Specifies the address to track leaked objects. This address is displayed in the driver-stop message in the debugger when a leak occurs.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 707 of 1651

DLL
Unavailable
Windows 2000
Windows XP with UMDF version 1.7 and later Wudfext.dll
Comments
If the UMDF object tracking option (TrackObjects) has been enabled in WDF Verifier, you can use !wudfext.wudfdumpobjects to see any leaked objects that remain after
the driver unloads.
If the TrackObjects option has been enabled, the address of the object tracker is automatically displayed when a leak is detected. Use this address as ObjTrackerAddress
when executing !wudfext.wudfdumpobjects.
This extension can be used at any time, even if UMDF has not broken in to the debugger.
If UMDF is version 1.9 or above, you can use either !wudfext.umdevstack or !wudfext.umdevstacks to determine the address of the object tracker. This address can then be
passed to !wudfext.wudfdumpobjects. Here is an example:
0: kd> !umdevstacks
Number of device stacks: 1
Device Stack: 0x038c6f08
Pdo Name: \Device\USBPDO-11
Number of UM devices: 1
Device 0
Driver Config Registry Path: WUDFOsrUsbFx2
UMDriver Image Path: D:\Windows\system32\DRIVERS\UMDF\WUDFOsrUsbFx2.dll
Fx Driver: IWDFDriver 0x3076ff0
Fx Device: IWDFDevice 0x3082e70
IDriverEntry: WUDFOsrUsbFx2!CMyDriver 0x0306eff8
Open UM files (use !umfile <addr> for details):
0x04a8ef84
Device XFerMode: CopyImmediately RW: Buffered CTL: Buffered
Object Tracker Address: 0x03074fd8
Object
Tracking ON
Refcount Tracking OFF
DevStack XFerMode: CopyImmediately RW: Buffered CTL: Buffered
0: kd> !wudfdumpobjects 0x03074fd8
WdfTypeDriver
Object: 0x03076fb0, Interface: 0x03076ff0
WdfTypeDevice
Object: 0x03082e30, Interface: 0x03082e70
WdfTypeIoTarget Object: 0x03088f50, Interface: 0x03088f90
WdfTypeIoQueue
Object: 0x0308ce58, Interface: 0x0308ce98
WdfTypeIoQueue
Object: 0x03090e58, Interface: 0x03090e98
WdfTypeIoQueue
Object: 0x03092e58, Interface: 0x03092e98
WdfTypeIoTarget Object: 0x03098f40, Interface: 0x03098f80
WdfTypeFile
Object: 0x0309cfa0, Interface: 0x0309cfe0
WdfTypeUsbInterface
Object: 0x030a0f98, Interface: 0x030a0fd8
WdfTypeRequest Object: 0x030a2ef8, Interface: 0x030a2f38
WdfTypeIoTarget Object: 0x030a6f30, Interface: 0x030a6f70
WdfTypeIoTarget Object: 0x030aaf30, Interface: 0x030aaf70
WdfTypeIoTarget Object: 0x030aef30, Interface: 0x030aef70
WdfTypeRequest Object: 0x030c6ef8, Interface: 0x030c6f38
WdfTypeRequest Object: 0x030ceef8, Interface: 0x030cef38
WdfTypeMemoryObject
Object: 0x030d6fb0, Interface: 0x030d6ff0
WdfTypeMemoryObject
Object: 0x030dcfb0, Interface: 0x030dcff0
WdfTypeFile
Object: 0x030e4fa8, Interface: 0x030e4fe8
WdfTypeFile
Object: 0x030e6fa8, Interface: 0x030e6fe8
WdfTypeFile
Object: 0x030e8fa8, Interface: 0x030e8fe8
WdfTypeRequest Object: 0x030eaef8, Interface: 0x030eaf38
WdfTypeMemoryObject
Object: 0x030ecfb0, Interface: 0x030ecff0
WdfTypeMemoryObject
Object: 0x030eefb0, Interface: 0x030eeff0
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudffile
The !wudfext.wudffile extension displays information about a framework file.
Syntax
!wudfext.wudffile pWDFFile [TypeName]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 708 of 1651

Parameters
pWDFFile
Specifies the address of the IWDFFile interface to display information about.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Windows 2000
Unavailable
Windows XP with UMDF version 1.7 and later Wudfext.dll
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudffilehandletarget
The !wudfext.wudffilehandletarget extension displays information about a file-handle-based I/O target.
Syntax
!wudfext.wudffilehandletarget pWDFFileHandleTarget [TypeName]
Parameters
pWDFFileHandleTarget
Specifies the address of the IWDFIoTarget interface to display information about. The !wudfext.wudfobject extension command determines the address of
IWDFIoTarget.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Unavailable
Windows 2000
Windows XP with UMDF version 1.7 and later Wudfext.dll
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfiotarget
The !wudfext.wudfiotarget extension displays information about an I/O target including the taget's state and list of sent requests.
Syntax
!wudfext.wudfiotarget pWDFTarget [TypeName]
Parameters
pWDFTarget
Specifies the address of the IWDFIoTarget interface to display information about. The !wudfext.wudfobject extension command determines the address of
IWDFIoTarget.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Windows 2000

WdfIoQueuePowerOn, CAN ACCEPT, CAN DISPATCH

0x000fa748
0x000fa890
0x000fa9d8
0x000fab20
0x000fa4b8
0x000fa600

!wudfext.wudfrefhist
The !wudfext.wudfrefhist extension displays the reference count stack history for a UMDF object.
Syntax
!wudfext.wudfrefhist ObjectAddress
Parameters
ObjectAddress
Specifies the address of the UMDF object whose reference count stack history is to be displayed. Note that this is the address of the object itself, not of the interface.
DLL
Windows 2000
Unavailable
Windows XP and later Wudfext.dll
Comments
The ObjectAddress parameter must be the address of the UMDF object, not the address of the interface (which is used by many other UMDF extensions). To determine the
address of the UMDF object, the !wudfext.wudfdumpobjects extension can be used; this extension displays both the UMDF object address and the interface address.
Alternatively, if you know the address of the interface, you can use it as the argument of the !wudfext.wudfobject extension; the resulting display will include the object
address (displayed after the symbol "Fx:").
If the reference count tracking option (TrackRefCounts) has been enabled in WDF Verifier, you can use !wudfext.wudfrefhist to display each call stack that increments or
decrements an object's reference count. You can determine whether a call stack is causing a memory leak by examining its AddRef and Release calls for references that are
being added and not released.
This extension can be used at any time, even if UMDF has not broken in to the debugger.
If this extension does not display the desired information, make sure that the relevant data is paged in and then try again.
Here is an example of the !wudfext.wudfrefhist display:
kd> !wudfrefhist 0x4e1fc78
----------------------------------------------------------------------2 (++)
----------------------------------------------------------------------WUDFx!CWdfObject::TrackRefCounts+0xf7
WUDFx!CWdfObject::AddRef+0x41
WUDFx!CWdfIoQueue::AddRef+0x1a
WUDFx!CWdfDevice::CreateIoQueue+0x432

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 712 of 1651

0x044e8719
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
0x044e73e3
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
0x044e714e
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
WUDFx!CWdfDriver::OnAddDevice+0x7b4
WUDFx!CWUDF::AddDevice+0x28
wudfhost!CWudfDeviceStack::OnAddDevice+0x158
wudfhost!CLpcNotification::OnAddDevice+0x150
wudfhost!CLpcNotification::Message+0x115
wudfhost!WdfLpcPort::ProcessMessage+0x1d9
wudfhost!WdfLpcCommPort::ProcessMessage+0x1ff
wudfhost!WdfLpcConnPort::ProcessMessage+0xf8
wudfhost!WdfLpc::WorkerThread+0x2b8
----------------------------------------------------------------------3 (++)
----------------------------------------------------------------------WUDFx!CWdfObject::TrackRefCounts+0xf7
WUDFx!CWdfObject::AddRef+0x41
WUDFx!CWdfIoQueue::AddRef+0x1a
WUDFx!CWdfIoQueue::QueryInterface+0xe8
WUDFx!CWdfDevice::CreateIoQueue+0x516
0x044e8719
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
0x044e73e3
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
0x044e714e
<Symbol name not found, hr=0x80004005>
WUDFx!CWdfDevice::CreateIoQueue+0x0
WUDFx!CWdfDriver::OnAddDevice+0x7b4
WUDFx!CWUDF::AddDevice+0x28
wudfhost!CWudfDeviceStack::OnAddDevice+0x158
wudfhost!CLpcNotification::OnAddDevice+0x150
wudfhost!CLpcNotification::Message+0x115
wudfhost!WdfLpcPort::ProcessMessage+0x1d9
wudfhost!WdfLpcCommPort::ProcessMessage+0x1ff
wudfhost!WdfLpcConnPort::ProcessMessage+0xf8
----------------------------------------------------------------------2 (--)
----------------------------------------------------------------------WUDFx!CWdfObject::TrackRefCounts+0xf7
WUDFx!CWdfObject::Release+0x41
WUDFx!CWdfIoQueue::Release+0x1a
. . . .
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfrequest
The !wudfext.wudfrequest extension displays information about an I/O request.
Syntax
!wudfext.wudfrequest pWDFRequest
Parameters
pWDFRequest
Specifies the address of the WDFIoRequest interface to display information about. The !wudfext.wudfqueue extension command determines the address of
WDFIoRequest.
DLL
Windows 2000
Unavailable
Windows XP and later Wudfext.dll
Comments
The following is an example of the !wudfext.wudfrequest display:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 713 of 1651

kd> !wudfrequest 0x000fa530

CWdfIoRequest 0x000fa4b8
Type: WdfRequestRead
IWDFIoQueue: 0x000f3500
Completed: No
Canceled: No
UM IRP: 0x00429108 UniqueId: 0xf4 Kernel Irp: 0x0x936ef160
Type: WudfMsg_READ
ClientProcessId: 0x1248
Device Stack: 0x003be4e0
IoStatus
hrStatus: 0x0
Information: 0x0
Driver/Framework created IRP: No
Data Buffer: 0x00000000 / 0
IsFrom32BitProcess: Yes
CancelFlagSet: No
Cancel callback: 0x000fa534
Total number of stack locations: 2
CurrentStackLocation: 2 (StackLocation[ 1 ])
StackLocation[ 0 ]
UNINITIALIZED
> StackLocation[ 1 ]
IWDFRequest: ????
IWDFDevice:
0x000f2f80
IWDFFile:
0x00418cf0
Completion:
Callback:
0x00000000
Context:
0x00000000
Parameters: (RequestType: WdfRequestRead)
Buffer length:
0x400
Key:
0x00000000
Offset:
0x0

!wudfext.wudfusbinterface
The !wudfext.wudfusbinterface extension displays information about a USB interface object.
Syntax
!wudfext.wudfusbinterface pWDFUSBInterface [TypeName]
Parameters
pWDFUSBInterface
Specifies the address of the IWDFUsbInterface interface to display information about. The !wudfext.wudfobject extension command determines the address of
IWDFUsbInterface.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Windows 2000
Unavailable
Windows XP with UMDF version 1.7 and later Wudfext.dll
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 714 of 1651

!wudfext.wudfusbpipe
The !wudfext.wudfusbpipe extension displays information about a USB pipe object.
Syntax
!wudfext.wudfusbpipe pWDFUSBPipe [TypeName]
Parameters
pWDFUSBPipe
Specifies the address of the IWDFUsbTargetPipe interface to display information about. The !wudfext.wudfobject extension command determines the address of
IWDFUsbTargetPipe.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Windows 2000
Unavailable
Windows XP with UMDF version 1.7 and later Wudfext.dll
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wudfext.wudfusbtarget
The !wudfext.wudfusbtarget extension displays information about a USB I/O target.
Syntax
!wudfext.wudfusbtarget pWDFUSBTarget [TypeName]
Parameters
pWDFUSBTarget
Specifies the address of the IWDFUsbTargetDevice interface to display information about. The !wudfext.wudfobject extension command determines the address of
IWDFUsbTargetDevice.
TypeName
Optional. Specifies the type of the interface (for example, IWDFDevice). If a value for TypeName is supplied, the extension uses the value as the type of the interface. If
an asterisk (*) is supplied as TypeName, or if TypeName is omitted, the extension attempts to automatically determine the type of the supplied interface.
DLL
Unavailable
Windows 2000
Windows XP with UMDF version 1.7 and later Wudfext.dll
Additional Information
For more information, see User-Mode Driver Framework Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WMI Tracing Extensions (Wmitrace.dll)

Variable
Description
type
string
The friendly name of the message GUID of the trace message. By default, the friendly name of a message GUID is the name of the
directory in which the trace provider was built.
string
Source file and line number.
This variable represents the friendly name of the trace message. By default, the friendly name of a trace message is the name of the
source file and the line number of the code that generated the trace message.

ULONG

Thread ID.
Identifies the thread that generated the trace message.

%4
%5

string
string

Time stamp of the time that the trace message was generated.
Kernel time.
Displays the elapsed execution time for kernel-mode instruction, in CPU ticks, at the time that the trace message was generated.

string

User time.
Displays the elapsed execution time for user-mode instruction, in CPU ticks, at the time that the trace message was generated.

LONG

Sequence number.
Displays the local or global sequence number of the trace message. Local sequence numbers, which are unique only to this trace
session, are the default.

ULONG

Process ID.
Identifies the process that generated the trace message.

ULONG

CPU number.
Identifies the CPU on which the trace message was generated.

%!FUNC!

string

Function name.
Displays the name of the function that generated the trace message.

%!FLAGS%
%!LEVEL!
%!COMPNAME!

string
string
string

Displays the name of the trace flags that enable the trace message.
Displays the value of the trace level that enables the trace message.
Component name.
Displays the name of the component of the provider that generated the trace message. The component name appears only if it is
specified in the tracing code.

%!SUBCOMP!

string

Subcomponent name.
Displays the name of the subcomponent of the provider that generated the trace message. The subcomponent name appears only if it
is specified in the tracing code.

The symbol within exclamation marks is a conversion character that specifies the format and precision of the variable. For example, %8!04X! specifies the process ID
formatted as a four-digit, unsigned, hexadecimal number.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file
from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 722 of 1651

Comments
When used with no parameters, !wmitrace.setprefix displays the current value of the trace message prefix.
The trace message prefix consists of data about the trace message that is prepended to each trace message during Windows software trace preprocessor (WPP) software
tracing. This data originates in the trace log (.etl) file and the trace message format (.tmf) file. You can customize the format and data in trace message prefix.
The default trace message prefix is as follows:
[%9!d!]%8!04X!.%3!04X!::%4!s! [%1!s!]
and produces the following prefix:
[CPUNumber]ProcessID.ThreadID::SystemTime [ProviderDirectory]
You can change the format and data in the trace message prefix outside of the debugger by setting the %TRACE_FORMAT_PREFIX% environment variable. For an example
that illustrates how to set the trace message prefix outside of the debugger, see "Example 7: Customizing the Trace Message Prefix" in the Windows Driver Kit (WDK)
documentation. If the trace message prefix of your messages varies from the default, this environment variable might be set on your computer.
The prefix that you set by using this extension command affects only the debugger output. The trace message prefix that appears in the trace log is determined by the default
value and the value of the %TRACE_FORMAT_PREFIX% environment variable.
This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested
providers do not use trace message format (TMF) files, and therefore this extension does not affect them.
Example
The following command changes the trace message prefix in the debugger output to the following format:
!wmitrace.setprefix %2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:
This extension command sets the trace message prefix to the following format:
SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime:
As a result, the trace messages are prepended with the specified information in the specified format. The following code example is taken from a trace of the Tracedrv sample
driver in the WDK.
tracedrv_c258: TracedrvDispatchDeviceControl: 0af4.0c64: 07/25/2003-13:55:39.998:

IOCTL = 1

Additional Information
For a conceptual overview of event tracing, see the Microsoft Windows SDK documentation. For information about trace message format files, see the "Trace Message
Prefix" topic in the WDK documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.start
The !wmitrace.start extension starts the Event Tracing for Windows (ETW) logger on the target computer.
Syntax
!wmitrace.start LoggerName [-cir Size | -seq Size] [-f File] [-b Size] [-max Num] [-min Num] [-kd] [-ft Time]
Parameters
LoggerName
Supplies a name to be used for the trace session. LoggerName cannot contain spaces or quotation marks.
-cir Size
Causes the log file to be written in a circular manner. Size specifies the maximum file size, in bytes. When the file reaches this length, new data will be written to the file
in a circular manner, overwriting the file from beginning to end. This cannot be combined with the -seq parameter. If neither -cir nor -seq is specified, the file is written
in buffered mode.
-seq Num
Causes the log file to be written in a sequential manner. Size specifies the maximum file size, in bytes. When the file reaches this length, the oldest data will be deleted
from the beginning of the file whenever new data is appended to the end. This cannot be combined with the -cir parameter. If neither -cir nor -seq is specified, the file is
written in buffered mode.
-f File
Specifies the name of the log file to be created on the target computer. File must include an absolute directory path, and cannot contain spaces or quotation marks.
-b Size
Specifies the size of each buffer, in kilobytes. The permissible range of Size is between 1 and 2048, inclusive.
-max Num
Specifies the maximum number of buffers to use. Num can be any positive integer.
-min Num
Specifies the minimum number of buffers to use. Num can be any positive integer.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 723 of 1651

-kd
Enables KD filter mode. Messages will be sent to the kernel debugger and displayed on the screen.
-ft Time
Specifies the duration of the flush timer, in seconds.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 7 and later versions of Windows.
Comments
After using this extension, you must resume program execution (for example, by using the g (Go) command) in order for it to take effect. After a brief time, the target
computer automatically breaks into the debugger again.
When the trace session is started, the system assigns it an ordinal number (the logger ID). The session can then be referred to either by the logger name or the logger ID.
To stop the ETW logger, use !wmitrace.stop.
Additional Information
For more details on the parameters of this extension, see StartTrace Function and EVENT_TRACE_PROPERTIES on MSDN. For a conceptual overview of event
tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.stop
The !wmitrace.stop extension stops the Event Tracing for Windows (ETW) logger on the target computer.
Syntax
!wmitrace.stop { LoggerID | LoggerName }
Parameters
LoggerID
Specifies the trace session. LoggerID is an ordinal number that the system assigns to each trace session on the computer.
LoggerName
Specifies the trace session. LoggerName is the text name that was specified when the trace session was started.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 7 and later versions of Windows.
Comments
After using this extension, you must resume program execution (for example, by using the g (Go) command) in order for it to take effect. After a brief time, the target
computer automatically breaks into the debugger again.
To start the ETW logger, use !wmitrace.start.
Additional Information
For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about tracing tools, see the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.strdump
The !wmitrace.strdump extension displays the WMI event trace structures. You can limit the display to the structures for a particular trace session.
Syntax
!wmitrace.strdump [ LoggerID | LoggerName ]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 724 of 1651

Parameters
LoggerID
Limits the display to the event trace structures for the specified trace session. LoggerID specifies the trace session. It is an ordinal number that the system assigns to each
trace session on the computer. If no parameter is specified, all trace sessions are displayed.
LoggerName
Limits the display to the event trace structures for the specified trace session. LoggerName is the text name that was specified when the trace session was started. If no
parameter is specified, all trace sessions are displayed.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file
from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory.
Comments
To find the logger ID of a trace session, use the !wmitrace.strdump extension. Alternatively, you can use the Tracelog command tracelog -l to list the trace sessions and
their basic properties, including the logger ID.
Additional Information
For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about Tracelog, see the "Tracelog" topic in the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.tfp
The !wmitrace.tfp extension command is obsolete. Use !wmitrace.setprefix instead.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.tmffile
The !wmitrace.tmffile extension specifies a trace message format (TMF) file. The file specified by this extension is used to format trace messages displayed or written by
other WMI tracing extensions.
Syntax
!wmitrace.tmffile TMFFile
Parameters
TMFFile
Specifies a trace message format file.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file
from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory.
Comments
Trace message format files (.tmf) are structured text files that are created during Windows software trace preprocessor (WPP) software tracing. These files contain instructions
for formatting trace binary trace messages so that they can be displayed in human-readable form.
In order to display the trace message in a trace buffer (!wmitrace.logdump) or write them to a file (!wmitrace.logsave), you must first identify the TMF files for the trace
messages.
You can use !wmitrace.searchpath to specify a directory in which TMF files are stored. The system then searches the directory for a TMF file that contains instructions for
the messages that it is formatting. (It uses the message GUID to associate the message with the correct TMF file.)
However, you can use !wmitrace.tmffile to specify a particular TMF file. You must use !wmitrace.tmffile if the TMF file name is not a message GUID followed by the .tmf
extension. Otherwise, the system will not find it.
If you do not use either !wmitrace.searchpath or !wmitrace.tmffile, the system uses the value of the TRACE_FORMAT_SEARCH_PATH environment variable. If that

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 725 of 1651

variable is not present, it uses the default.tmf file. If the system cannot find formatting information for a trace message, it writes a "No format information found" error
message, instead of the trace message content.
This extension is only useful during WPP software tracing, and earlier (legacy) methods of Event Tracing for Windows. Trace events that are produced by other manifested
providers do not use trace message format (TMF) files, and therefore this extension cannot be used with them.
Additional Information
For a conceptual overview of event tracing, see the Microsoft Windows SDK. For information about trace message format files, see the "Trace Message Format File" topic in
the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

!wmitrace.traceoperation
The !wmitrace.traceoperation extension displays the progress messages from the tracing components in Windows.
Syntax
!wmitrace.traceoperation {0 | 1 | 2}
Parameters
0
Disables the display of tracing progress messages.
1
Enables the display of tracing progress messages. All messages generated by the WMI tracing debugger extensions are displayed.
2
Enables the display of tracing progress messages. All messages generated by the WMI tracing debugger extensions or by Tracefmt are displayed.
DLL
This extension is exported by Wmitrace.dll.
This extension is available in Windows 2000 and later versions of Windows. If you want to use this extension with Windows 2000, you must first copy the Wmitrace.dll file
from the winxp subdirectory of the Debugging Tools for Windows installation directory to the w2kfre subdirectory.
Comments
This extension causes the tracing components to display verbose output. This feature is useful to troubleshoot software tracing.
Additional Information
For a conceptual overview of event tracing, see the Microsoft Windows SDK.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OEM Support Extensions (kdex2x86.dll)

The OEM Support Extensions can be found in the w2kfre\kdex2x86.dll subdirectory of the Debugging Tools for Windows installation directory.
You can use these extensions only with Windows 2000 targets.
These extensions are not described in this documentation. For descriptions of these extensions, see the OEM Support Tools documentation. To get this documentation, along
with the entire OEM Support Tools package, go to Knowledge Base Article Q253066 and follow the instructions on that page.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SieExtPub.dll
The SieExtPub.dll extension module is not part of Microsoft Debugging Tools for Windows. To get extensions from SieExtPub.dll (for example, !critlist), download the
Debug Diagnostic Tool from the Microsoft Download Center. At the download center, search for "Debug Diagnostic Tool".

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 726 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger-Related APIs
This reference section includes:
Symbol Server API
The dbgeng.h Header File
The wdbgexts.h Header File
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Symbol Server API

The SymbolServerXxx routines are needed if you want to write your own symbol server.
These routines are part of the DbgHelp interface. For full documentation regarding the DbgHelp and ImageHlp interfaces, see the "Debug Help Library" documentation
(dbghelp.chm). This can be found in the sdk\help subdirectory of the Debugging Tools for Windows installation directory.
If you do not see this documentation in your current debugger installation, it is because you did not perform a full install. See Debugger Installation for details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The dbgeng.h Header File

Routines in the dbgeng.h header file are used to write DbgEng extensions.
For details on the dbgeng.h header file and information about how to write debugger extensions, see
For information about how to write debugger extensions, see Writing DbgEng Extensions and Using the Debugger Engine API.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The wdbgexts.h Header File

Routines in the wdbgexts.h header file are used to write DbgEng extensions and WdbgExts extensions.
For details on the wdbgexts.h header file and information about how to write debugger extensions, see Writing WdbgExts Extensions.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Error and Warning Messages

This reference section describes some of the error and warning messages that the debugger can display.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 727 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dbgerr001: PEB is Paged Out

Debugger error dbgerr001 displays the message "PEB is paged out." This error indicates that the process environment block (PEB) is not accessible.
To load symbols, the debugger looks at the list of modules loaded by the operating system. The pointer to the user-mode module list is one of the items stored in the PEB.
In order to reclaim memory, the Memory Manager may page out user-mode data to make space for other process or kernel mode components.
When this error occurs, it means that the debugger has detected that the PEB data structure for this process is no longer readable. Most likely, is has been paged out to disk.
Without this data structure, the debugger cannot determine what images the symbols should be loaded for.
Note This only affects symbol files for the user-mode modules. Kernel-mode modules and symbols are not affected, as they are tracked in a different list.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dbgerr002: Bad Pointer

Debugger error dbgerr002 displays the message "Bad pointer." This error indicates a problem retrieving a symbol file.
The symbol server has the file indexed, but is being redirected to another location to find the file. No file is accessible at this other location.
Two common causes of this problem are:

The path is a UNC path, and the computer containing this server is not available.
The path indicates a directory or file that has been deleted.

If your symbol store was created by using SymStore, you can find the full path to this file by examining file.ptr. For details, see Using SymStore.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dbgerr003: Mismatched Symbols

Debugger error dbgerr003 displays the message "File has mismatched symbols." This error indicates that DbgHelp found the symbol file represented by File, but that the
symbol file is not the correct version, or that DbgHelp cannot confirm that the symbol file is the correct version.
The debugger might load the specified symbol file despite this error, depending on other requirements in the path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dbgerr004: Page Not Present in Dump File

Debugger error dbgerr004 displays the message "Page number not present in dump file." This error indicates that the debugger needed a memory page that was not included
in the dump file being debugged.
The specified number is the page frame number (PFN) corresponding to the location in the physical memory of the original page.
To suppress this error message, use the .ignore_missing_pages 1 command. This command allows debugging to proceed, but does not display this error message.
Kernel-mode memory dumps come in three sizes, and the smaller sizes do not include all the memory pages. For details, see Varieties of Kernel-Mode Dump Files.
User-mode memory dumps also come in various sizes. See User-Mode Dump Files for details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 728 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dbgerr005: Private Symbols Required

Debugger error dbgerr005 displays the message "Private symbols (symbols.pri) are required for locals." This error indicates that the debugger is unable to perform an action
because private symbols are not present.
During kernel-mode debugging, the debugger needs symbols for Microsoft Windows. During user-mode debugging, the debugger needs symbols for the target application,
and often needs symbols for Windows as well.
Some basic symbols, such as function names and global variables, are needed for even the most rudimentary debugging. These are called public symbols. Symbols such as
data structure names, global variables visible in only one object file, local variables, and line number information are not always required for debugging, although they are
useful for a more in-depth debugging session. These are called private symbols.
Many software manufacturers, including Microsoft, produce two versions of their symbol files. The version released to their customers contains only public symbols. The
version used internally contains both public and private symbols.
Most debugging actions can be performed with public symbols alone. But certain actions such as displaying local variables require private symbols. When an action of
this sort is attempted and private symbols are not available, this error message is displayed.
When you see this message, it is usually best to simply continue debugging. The information you were unable to obtain is probably not essential to properly debugging the
target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Stack Unwind Information Not Available

When the debugger is examining the call stack, it may display the message "Stack unwind information not available. Following frames may be wrong."
This warning indicates that the debugger is not certain that the frames in the call stack listed after this message are correct.
To trace the call stack, the debugger examines the stack and analyzes the functions that have used the stack. This lets it identify the chain of return addresses that form the call
stack. However, this procedure requires symbol information for each module containing the functions that used the stack.
If this symbol information is not available, the debugger is forced to make a best guess about which frames are return addresses. This warning information is displayed to
indicate the uncertain nature of the call stack after this point.
If the stack does not appear correct to you, you may need to use more complicated techniques to determine the stack. See Getting a Stack Trace for more details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

No Header Information Available

The debugger identifies the proper symbols by examining the headers of the relevant modules. If these module headers are paged out, the debugger (and the symbol server) ar
unable to find the proper symbols. When this occurs, "No Header Information Available" is displayed within the symbol error message.
For information about how to debug a target when module headers are paged out, see Reading Symbols from Paged-Out Headers.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WinDbg Graphical Interface Features

This section discusses the elements of the WinDbg graphical user interface. These elements include the following:
Debugging Information Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 729 of 1651

File Menu
Edit Menu
View Menu
Debug Menu
Window Menu
Help Menu
Toolbar Buttons
Shortcut Keys
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Information Windows

This section discusses the components of the following debugging information windows:
Debugger Command Window
Watch Window
Locals Window
Registers Window
Memory Window
Calls Window
Disassembly Window
Scratch Pad
Processes and Threads Window
Source Window
For more information about how to use these windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Command Window

The Debugger Command window is the primary debugging information window in WinDbg. You can enter debugger commands and view the command output in this
window.
Note This window displays "Command" in the title bar. However, this documentation always refers to this window as "the Debugger Command window" to avoid confusing
it with the Command Prompt windows that are used to issue Microsoft MS-DOS commands.
When you are debugging in user mode, the Debugger Command window corresponds to the whole CDB window. When you are debugging in kernel mode, the Debugger
Command window corresponds to the KD window. However, certain commands work differently in the different debuggers. For more information about the differences, see
the topics about each command.
Opening the Debugger Command Window
To open or switch to the WinDbg Debugger Command window, in the WinDbg window, on the View menu, click Command. (You can also press ALT+1 or click the
Command (Alt+1) button (

) on the toolbar. ALT+SHIFT+1 will close the Debugger Command window.)

The following figure shows an example of a Locals window.

The Locals window can contain four columns. The Name and Value columns are always displayed, and the Type and Location columns are optional. To display the Type
and Location columns, click the Typecast and Locations buttons, respectively, on the toolbar.
Using the Locals Window
In the Locals window, you can do the following:

The Name column displays the name of each local variable. If a variable is a data structure, a check box appears next to its name. To expand or collapse the display of
structure members, select or clear the check box.
The Value column displays the current value of each variable.
To enter a new value for the variable, double-click the current value and type the new value, or edit the old value. (The cut, copy, and paste commands are
available to use for editing.) You can type any C++ expression.
To save the new value, press ENTER.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 733 of 1651

To discard the new value, press ESC.

If you type an invalid value, the old value will reappear when you press ENTER.

Integers of type int are displayed as decimal values; integers of type UINT are displayed in the current radix. To change the current radix, use the n (Set Number Base)
command in the Debugger Command window.

The Type column (if it is displayed in the Locals window) shows the current data type of each variable. Each variable is displayed in the format that is proper for its
own data type. Data structures have their type names in the Type column. Other variable types display "Enter new type" in this column.
If you double-click "Enter new type", you can cast the type by entering a new data type. This cast alters the current display of this variable only in the Locals window; it
does not change anything in the debugger or on the target computer. Moreover, if you enter a new value in the Value column, the text you enter will be parsed based on
the actual type of the symbol, rather than any new type you may have entered in the Type column. If you close and reopen the Locals window, you will lose the data
type changes.
You can also enter an extension command in the Type column. The debugger will pass the address of the symbol to this extension, and will display the resulting output
in a series of collapsible rows beneath the current row. For example, if the symbol in this row is a valid address for a thread environment block, you can enter !teb in the
Type column to run the !teb extension on this symbol's address.

The Location column (if it is displayed in the Locals window) shows the offset of each member of a data structure.
If a local variable is an instance of a class that contains Vtables, the Name column displays the Vtables and you can expand them to show the function pointers. If a
Vtable is contained in a base class that points to a derived implementation, the notation _vtcast_Class is displayed to indicate the members that are being added because
of the derived class. These members expand like the derived class type.
The local context determines which set of local variables will be displayed in the Locals window. When the local context changes for any reason, the Locals window is
automatically updated. By default, the local context matches the current position of the program counter. For more information about how to change the local context,
see Local Context.

Toolbar and Shortcut Menu

The Locals window has a toolbar that contains two buttons (Typecast and Locations) and a shortcut menu with additional commands. To access the menu, right-click the title
bar of the window or click the icon near the upper-right corner of the window ( ). The toolbar and menu contain the following buttons and commands:

(Toolbar and menu) Typecast turns the display of the Type column on and off.
(Toolbar and menu) Locations turns the display of the Location column on and off.
(Menu only) Display 16-bit values as Unicode displays Unicode strings in this window. This command turns on and off a global setting that affects the Locals window,
the Watch window, and debugger command output. This command is equivalent to using the .enable_unicode (Enable Unicode Display) command.
(Menu only) Always display numbers in default radix causes integers to be displayed in the default radix instead of displaying them in decimal format. This
command turns on and off a global setting that affects the Locals window, the Watch window, and debugger command output. This command is equivalent to using
the .force_radix_output (Use Radix for Integers) command.
Note The Always display numbers in default radix command does not affect long integers. Long integers are displayed in decimal format unless
the .enable_long_status (Enable Long Integer Display) command is set. The .enable_long_status command affects the display in the Locals window, the Watch
window, and in debugger command output; there is no equivalent for this command in the menu in the Locals window.

(Menu only) Open memory window for selected value opens a new docked Memory window that displays memory starting at the address of the selected expression.
(Menu only) Invoke dt for selected memory value runs the dt (Display Type) command with the selected symbol as its parameter. The result appears in the Debugger
Command window. The -n option is automatically used to differentiate the symbol from a hexadecimal address. No other options are used. Note that the content
produced using this menu selection is identical to the content produced when running the dt command from the command line, but the format is slightly different.
(Menu only) Toolbar turns the toolbar on and off.
(Menu only) Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Locals window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Locals window. This option is only available for Source or Memory windows.
(Menu only) Always floating causes the window to remain undocked even if it is dragged to a docking location.
(Menu only) Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked,
tabbed, and floating windows, see Positioning the Windows.
(Menu only) Help opens this topic in the Debugging Tools for Windows documentation.
(Menu only) Close closes this window.

Additional Information
For more information about controlling local variables, an overview of using variables and changing the scope, and a description of other memory-related commands, see
Reading and Writing Memory. For more information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques
that you can use to control debugging information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Registers Window
The Registers window displays the registers and flags from the current target processor.
Opening the Registers Window
To open or switch to the Registers window, in the WinDbg window, on the View menu, click Registers. (You can also press ALT+4 or click the Registers (Alt+4) button (
) on the toolbar. ALT+SHIFT+4 will close the Registers window.)
The following figure shows an example of a Registers window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 734 of 1651

The Registers window contains two columns. The Reg column lists all of the registers for the target processor. The Value column displays the current value of each register.
This window also contains a Customize button on the toolbar that opens the Customize Register List dialog box.
Using the Registers Window
In the Registers window, you can do the following:

The Value column displays the current value of each register. The value of the most recently changed register is displayed in red text.
To enter a new value, double-click a Value cell, and then type a new value or edit the old value. (The cut, copy, and paste commands are available to use for
editing.)
To save the new value, press ENTER.
To discard the new value, press ESC.
If you type an invalid value, the old value will reappear when you press ENTER.
Register values are displayed in the current radix and you must type new values in the same radix. To change the current radix, use the n (Set Number Base) command
in the Debugger Command window.
In user mode, the Registers window displays the registers that are associated with the current thread. For more information about the current thread, see Controlling
Processes and Threads.
In kernel mode, the Registers window displays the registers that are associated with the current register context. You can set the register context to match a specific
thread, context record, or trap frame. Only the most important registers for the specified register context are actually displayed; you cannot change their values.

Toolbar and Shortcut Menu

The Registers window has a toolbar that contains a Customize button and has a shortcut menu with additional commands. To access the menu, right-click the title bar or click
the icon near the upper-right corner of the window (

). The toolbar and menu contain the following button and commands:

(Toolbar and menu) Customize opens the Customize Register List dialog box, which is described in the following section within this topic.
(Menu only) Toolbar turns the toolbar on and off.
(Menu only) Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Registers window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Registers window. This option is only available for Source or Memory windows.
(Menu only) Always floating causes the window to remain undocked even if it is dragged to a docking location.
(Menu only) Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked,
tabbed, and floating windows, see Positioning the Windows.
(Menu only) Help opens this topic in the Debugging Tools for Windows documentation.
(Menu only) Close closes this window.

Customize Register List Dialog Box

To change the list of registers that are displayed, click the Customize button. The Customize Register List dialog box will appear.
In this dialog box, you can edit the list of registers to change the order in which registers are displayed. (You cannot actually delete a register from the list; if you do, it will
reappear at the end.) There must be a space between register names.
If you select the Display modified register values first check box, the register whose values have been changed most recently appears at the top.
If you select the Do not display subregisters check box, subregisters are not displayed. For example, eax will be displayed, but not ax, ah, or al.
Click OK to save your changes or Cancel to discard your changes.
If you are debugging a multi-processor computer with more than one kind of processor, WinDbg stores the customization settings for each processor type separately. This
separation enables you to customize the display of each processor's registers simultaneously.
Additional Information
For more information about registers and their manipulation, see Reading and Writing Registers and Flags. For more information about the register context and other context
settings, see Changing Contexts. For more information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques
that you can use to control debugging information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 735 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Memory Window
The Memory window displays a formatted range of memory. You can open more than one Memory window at the same time. (This behavior differs from the other debugging
information windows.)
Opening the Memory Window
To open a Memory window, in the WinDbg window, on the View menu, click Memory. (You can also press ALT+5 or click the Memory (Alt+5) button (
toolbar. ALT+SHIFT+5 will close the active Memory window.)

) on the

The following figure shows an example of a Memory window.

The Memory window displays data in several columns. The column on the left side of the window shows the beginning address of each line. The remaining columns display
the requested information, from left to right. If you select Bytes in the Display format menu, the ASCII characters that correspond to these bytes are displayed in the right
side of the window.
Note By default, the Memory window displays virtual memory. This type of memory is the only type of memory that is available in user mode. In kernel mode, you can use
the Memory Options dialog box to display physical memory and other data spaces. The Memory Options dialog box is described later in this topic.
Using the Memory Window
In the Memory window, you can do the following:

To write to memory, click inside the Memory window and type new data. You can edit only hexadecimal datayou cannot directly edit ASCII and Unicode characters.
Changes take effect as soon as you type new information.
To see other sections of memory, use the Previous and Next buttons on the Memory window toolbar, or press the PAGE UP or PAGE DOWN keys. These buttons and
keys display the immediately preceding or following sections of memory. If you request an invalid page, an error message appears.
To navigate within the window, use the RIGHT ARROW, LEFT ARROW, UP ARROW, and DOWN ARROW keys. If you use these keys to move off of the page, a
new page is displayed. Before you use these keys, you should resize the Memory window so that it does not have scroll bars. This sizing enables you to distinguish
between the actual page edge and the window cutoff.
To change the memory location that is being viewed, enter a new address into the address box at the top of the Memory window. Note that the Memory window
refreshes its display while you enter an address, so you could get error messages before you have completed typing the address.
Note The address that you enter into the box is interpreted in the current radix. If the current radix is not 16, you should prefix a hexadecimal address with 0x. To
change the default radix, use the n (Set Number Base) command in the Debugger Command window. The display within the Memory window itself is not affected by
the current radix.

To change the data type that the window uses to display memory, use the Display format menu in the Memory window toolbar. Supported data types include short
words, double words, and quad-words; short, long, and quad integers and unsigned integers; 10-byte, 16-byte, 32-byte, and 64-byte real numbers; ASCII characters;
Unicode characters; and hexadecimal bytes. The display of hexadecimal bytes includes ASCII characters as well.

Toolbar and Shortcut Menu

The Memory window has a toolbar that contains two buttons, a menu, and a box and has a shortcut menu with additional commands. To access the menu, right-click the title
bar or click the icon near the upper-right corner of the window (

). The toolbar and shortcut menu contain the following choices:

(Toolbar only) The address box enables you to specify a new address or offset. The exact meaning of this box depends on the memory type you are viewing. For
example, if you are viewing virtual memory, the box enables you to specify a new virtual address or offset.
(Toolbar only) Display format enables you to select a new display format.
(Toolbar and menu) Previous (on the toolbar) and Previous page (on the shortcut menu) causes the previous section of memory to be displayed.
(Toolbar and menu) Next (on the toolbar) and Next page (on the shortcut menu) causes the next section of memory to be displayed.
(Menu only) Toolbar turns the toolbar on and off.
(Menu only) Auto-fit columns ensures that the number of columns displayed in the Memory window fits the width of the Memory window..

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 736 of 1651

(Menu only) Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Memory window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type sets the selected Memory window as the tab-dock target for other Memory windows. All Memory windows
opened after one is chosen as the tab-dock target will automatically be grouped with that window in a tabbed collection.
(Menu only) Always floating causes the window to remain undocked even if it is dragged to a docking location.
(Menu only) Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked,
tabbed, and floating windows, see Positioning the Windows.
(Menu only) Properties opens the Memory Properties dialog box, which is described in the following section within this topic.
(Menu only) Help opens this topic in the Debugging Tools for Windows documentation.
(Menu only) Close closes this window.

Memory Options Dialog Box

When you click Properties on the shortcut menu, the Memory Options dialog box appears.
In kernel mode, there are six memory types available as tabs in this dialog box: Virtual Memory, Physical Memory, Bus Data, Control Data, I/O (I/O port information),
and MSR (model-specific register information). Click the tab that corresponds to the information that you want to access.
In user mode, only the Virtual Memory tab is available.
Each tab enables you to specify the memory that you want to display:

In the Virtual Memory tab, in the Offset box, specify the address or offset of the beginning of the memory range that you want to view.
In the Physical Memory tab, in the Offset box, specify the physical address of the beginning of the memory range that you want to view. The Memory window can
display only described, cacheable physical memory. If you want to display physical memory that has other attributes, use the d* (Display Memory) command or the !
d* extension.
In the Bus Data tab, in the Bus Data Type menu, specify the bus data type. Then, use the Bus number, Slot number, and Offset boxes to specify the bus data that you
want to view.
In the Control Data tab, use the Processor and Offset text boxes to specify the control data that you want to view.
In the I/O tab, in the Interface Type menu, specify the I/O interface type. Use the Bus number, Address space, and Offset boxes to specify the data that you want to
view.
In the MSR tab, in the MSR box, specify the model-specific register that you want to view.

Each tab also includes a Display format menu. This menu has the same effect as the Display format menu in the Memory window.
Click OK in the Memory Options dialog box to cause your changes to take effect.
Additional Information
For more information about memory manipulation and a description of other memory-related commands, see Reading and Writing Memory. For more information about
docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques that you can use to control debugging information windows,
see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Calls Window
The Calls window displays the current call stack information.
Opening the Calls Window
To open or switch to the Calls window, in the WinDbg window, on the View menu, click Call Stack. (You can also press ALT+6 or click the Calls (Alt+6) button (
the toolbar. ALT+SHIFT+6 will close the Calls Window.)

) on

The following figure shows an example of a Calls window.

The Calls window displays the call stack information in several columns, most of which can be visible or hidden. If none of the optional columns are visible, only the name or
offset of each function is displayed.
Using the Calls Window
To move to the corresponding call location in the Source window or Disassembly window, double-click a line of the call stack, or select a line and press ENTER. This action
also changes the local context to the selected stack frame. For more information about running to or from this point, see Controlling the Target.
In user mode, the stack trace is based on the stack of the current thread. For more information about the stack of the current thread, see Controlling Processes and Threads.
In kernel mode, the stack trace is based on the current register context. You can set the register context to match a specific thread, context record, or trap frame. For more
information about setting the register context, see Register Context.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 737 of 1651

Toolbar and Shortcut Menu

The Calls window has a toolbar that contains several buttons and has a shortcut menu with additional commands. To access this menu, right-click the title bar or click the icon
near the upper-right corner of the window (

). The toolbar and menu contain the following buttons and commands:

(Toolbar and menu) Raw args displays the first three parameters that are passed to the function. On an x86-based processor, this display includes the first three
parameters that are passed to the function ("Args to Child"). On an Itanium-based processor, this display includes the parameters that are passed to the function
("Arguments to Callee"), if the Nonvolatile regs button is also turned on.
Func info displays Frame Pointer Omission (FPO) data and other internal information about the function. This command is available only on an x86-based processor.
Source displays source module names and line numbers after the function names (if the debugger has this information).
Addrs displays various frame-related addresses. On an x86-based processor, this display includes the base pointer for the stack frame ("ChildEBP") and the return
address ("RetAddr"). On an Itanium-based processor, this display includes a pointer to the function that is being called ("Callee-BSP") and the return address ("ReturnRA"), unless both the Args and Nonvolatile regs buttons are turned on as well.
Headings displays column headings at the top of each column.
Nonvolatile regs displays the nonvolatile portion of the register context. This command is available only on an Itanium-based processor.
Frame nums displays frame numbers. Frames are always numbered consecutively, beginning with zero.
Arg types displays detailed information about the arguments that are expected and received by the functions in the stack.
More changes the length of the stack trace. Each time you click More, the stack display increases by ten frames, if a stack trace of this length is available.
Less changes the length of the stack trace. Each time you click Less, the stack display decreases by ten frames, unless this change would cause the stack display to be
shorter than ten frames total.
(Menu only) Copy stack to clipboard copies the current contents of the Calls window to the clipboard.
(Menu only) Toolbar turns the toolbar on and off.
(Menu only) Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Calls window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Calls window. This option is only available for Source or Memory windows.
(Menu only) Always floating causes the window to remain undocked even if it is dragged to a docking location.
(Menu only) Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked,
tabbed, and floating windows, see Positioning the Windows.
(Menu only) Help opens this topic in the Debugging Tools for Windows documentation.
(Menu only) Close closes this window.

Additional Information
For more information about stack traces and for other ways to display stack traces, see Viewing the Call Stack. For more information about the register context and the local
context, see Changing Contexts. For more information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques
that you can use to control debugging information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Disassembly Window
The Disassembly window displays executable code in assembly language.
Opening the Disassembly Window
To open or switch to the Disassembly window, in the WinDbg window, on the View menu, click Disassembly. (You can also press ALT+7 or click the Disassembly (Alt+7)
button (

) on the toolbar. ALT+SHIFT+7 will close the Disassembly Window.)

The following figure shows an example of a Disassembly window.

The debugger takes a section of memory, interprets it as binary machine instructions, and then disassembles it to produce an assembly-language version of the machine
instructions. The resulting code is displayed in the Disassembly window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 738 of 1651

Using the Disassembly Window

In the Disassembly window, you can do the following:

To disassemble a different section of memory, in the Offset box, type the address of the memory you want to disassemble. (You can press ENTER after typing the
address, but you do not have to.) The Disassembly window displays code before you have completed the address; you can disregard this code.
To see other sections of memory, click the Previous or Next button or press the PAGE UP or PAGE DOWN keys. These commands display disassembled code from
the preceding or following sections of memory, respectively. By pressing the RIGHT ARROW, LEFT ARROR, UP ARROW, and DOWN ARROW keys, you can
navigate within the window. If you use these keys to move off of the page, a new page will appear.
If you want to disassemble a section of memory that does not contain machine instructions, the debugger displays error messages.
The line that represents the current program counter is highlighted in green, unless you select a line with the mouse or by using one of the Edit | Go to Xxx commands.
If you select a line with the mouse or a Edit | Go to Xxx command, the selected line is green and the line that represents the current program counter is not highlighted.
Lines at which breakpoints are set are highlighted. An enabled breakpoint is highlighted in in red, a disabled breakpoint is highlighted in yellow, and a breakpoint that
coincides with the current program counter is highlighted in purple.

Toolbar and Shortcut Menu

The Disassembly window has a toolbar that contains two buttons and a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon
that appears near the upper-right corner of the window (

). The toolbar and menu contain the following commands:

(Toolbar only) The Offset box enables you to specify a new address for disassembly.
(Toolbar and menu) Previous (on the toolbar) and Previous page (on the shortcut menu) causes the debugger to disassemble and display the instructions immediately
prior to the current display.
(Toolbar and menu) Next (on the toolbar) or Next page (on the shortcut menu) causes the debugger to disassemble and display the instructions immediately after the
current display.
(Menu only) Go to current address opens the Source window with the source file that corresponds to the selected line in the Disassembly window and highlights this
line.
(Menu only) Disassemble before current instruction causes the current line to be placed in the middle of the Disassembly window. This command is the default
option. If this command is cleared the current line will appear at the top of the Disassembly window, which saves time because reverse-direction disassembly can be
time-consuming.
(Menu only) Highlight instructions from the current source line causes all of the instructions that correspond to the current source line to be highlighted. Often, a
single source line will correspond to multiple assembly instructions. If code has been optimized, these assembly instructions might not be consecutive. This command
enables you to find all of the instructions that were assembled from the current source line.
(Menu only) Show source line for each instruction displays the source line number that corresponds to each assembly instruction.
(Menu only) Show source file for each instruction displays the source file name that corresponds to each assembly instruction.
(Menu only) Toolbar turns the toolbar on and off.
(Menu only) Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Disassembly window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Disassembly window. This option is only available for Source or Memory windows.
(Menu only) Always floating causes the window to remain undocked even if it is dragged to a docking location.
(Menu only) Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked,
tabbed, and floating windows, see Positioning the Windows.
(Menu only) Help opens this topic in the Debugging Tools for Windows documentation.
(Menu only) Close closes this window.

Additional Information
For more information about assembly debugging and related commands and a full explanation of the assembly display, see Debugging in Assembly Mode. For more
information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques that you can use to control debugging
information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Scratch Pad
The Scratch Pad window is a clipboard on which you can type and save text.
Opening the Scratch Pad Window
To open or switch to the Scratch Pad window, in the WinDbg window, on the View menu, click Scratch Pad. (You can also press ALT+8 or click the Scratch Pad (Alt+8)
button (

) on the toolbar.)

The following figure shows an example of a Scratch Pad window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 739 of 1651

Using the Scratch Pad Window

In the Scratch Pad window, you can do the following:

To type in the Scratch Pad window, click in the window where you want to add text and begin typing. You can also use standard copy-and-paste features. The contents
of the Scratch Pad window do not affect the operation of the debugger. This window exists solely to help with text editing.
If you close the Scratch Pad window, your text is preserved and is available when you reopen the window. You can also save text from the Scratch Pad window by
associating it with a file.

The Scratch Pad window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of the
window (

). This menu contains the following commands:

(Menu only) Associate with file opens a dialog box through which you can select a text file. After the file is selected, the current text in the Scratch Pad is cleared and
replaced with the text in the selected file. While Scratch Pad is associated with this file, all new text typed into Scratch Pad is saved to the file. Association with the file
can be ended either by selecting the End file association short-cut menu option or by closing and reopening Scratch Pad.
(Menu only) End file association ends Scratch Pad's association with a specified text file. All text in Scratch Pad prior to selecting this option is saved in the file. All
text typed in Scratch Pad after the association is ended is no longer saved in the text file.
Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes Scratch Pad and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for Scratch Pad. This option is only available for Source or Memory windows.
Always floating causes the window to remain undocked even if it is dragged to a docking location.
Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and
floating windows, see Positioning the Windows.
Help opens this topic in the Debugging Tools for Windows documentation.
Close closes this window.

Additional Information
For more information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques that you can use to control
debugging information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Processes and Threads Window

The Processes and Threads window displays information about the systems, processes, and threads that are being debugged. This window also enables you to select a new
system, process, and thread to be active.
Opening the Processes and Threads Window
To open or switch to the Processes and Threads window, in the WinDbg window, on the View menu, click Processes and Threads. (You can also press ALT+9 or click the
Processes and Threads (Alt+9) button ( ) on the toolbar. ALT+SHIFT+9 will close the Processes and Threads Window.)
The following figure shows an example of a Processes and Threads window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 740 of 1651

The Processes and Threads window displays a list of all processes that are currently being debugged. The threads in the process appear under each process. If the debugger is
attached to multiple systems, the systems are shown at the top level of the tree, with the processes subordinate to them, and the threads subordinate to the processes.
Each system listing includes the server name and the protocol details. The system that the debugger is running on is identified as <Local>.
Each process listing includes the internal decimal process ordinal that the debugger uses, the hexadecimal process ID, and the name of the application that is associated with
the process.
Each thread listing includes the internal decimal thread ordinal that the debugger uses and the hexadecimal thread ID.
Using the Processes and Threads Window
In the Processes and Threads window, you can do the following:

To expand or collapse each part of the tree, click the plus sign (+) or minus sign ().
The current or active system, process, and thread appear in bold type. To make a new system, process, or thread active, click its line in the window.

The Processes and Threads window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner
of the window ( ). The menu contains the following commands:

Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Processes and Threads window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Processes and Threads window. This option is only available for Source or Memory
windows.
Always floating causes the window to remain undocked even if it is dragged to a docking location.
Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and
floating windows, see Positioning the Windows.
Help opens this topic in the Debugging Tools for Windows documentation.
Close closes this window.

Additional Information
For other methods of displaying or controlling systems, see Debugging Multiple Targets. For other methods of displaying or controlling processes and threads, see Controlling
Processes and Threads. For more information about docked, tabbed, and floating windows, see Positioning the Windows. For more information about all techniques that you
can use to control debugging information windows, see Using Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Command Browser Window

The Command Browser window displays and stores the text results of a debugger command. This window creates a command reference that enables you to view the results of
a specific command without re-entering the command. The Command Browser window also provides navigation through the stored commands, so you can more quickly
access commands than with the Debugger Command window.
Opening the Command Browser Window
To open or switch to the Command Browser window, in the WinDbg window, on the View menu, click Command Browser. (You can also press CTRL+N or click the
Command Browser (Ctrl+N) button ( ) on the toolbar. ALT+SHIFT+N will close the Command Browser Window.)
The following figure shows an example of a Command Browser window.

The Command Browser window has a menu in which you can enter or select commands, several navigation buttons, and a pane that shows the results of the current
command.
Using the Command Browser Window

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 741 of 1651

In the Command Browser window, you can do the following:

To enter a command, type it in the Command box.

To view the results of a previously entered command, use the Start, Prev, and Next buttons to scroll through the command list, or select one of the preceding 20
commands from the Command menu. To find a command that is not one of the preceding 20 commands, use the Next button.

The Command Browser window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon near the upper-right corner of
the window ( ). The context menu contains the following commands:

Start, Prev, and Next move the cursor to the start of the command history or to the previous or next command, respectively.
Add to Recent Commands puts the current command into the Recent Commands menu of the View menu in the WinDbg window. Recent commands are saved in the
workspace.
Toolbar turns the toolbar on and off.
Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Command Browser window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type is unavailable for the Command Browser window. This option is only available for Source or Memory windows.
Always floating causes the window to remain undocked even if it is dragged to a docking location.
Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and
floating windows, see Positioning the Windows.
Close closes this window.

Source Window
The Source window displays source files that have been loaded into the debugger.
Opening the Source Window
The debugger opens a source window when it loads a new source file. To restore or switch to an open Source window, in the WinDbg window, on the Window menu, select
the window from the list of windows at the bottom of the menu.
The following figure shows an example of a Source window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 742 of 1651

Each source file resides in its own Source window. The title of each Source window is the full path of the source file.
Using the Source Window
Each Source window displays the text of one source file. You cannot edit a source file in the debugger. For more information about changing the font and tab settings, see
Changing Text Properties.
To select an entire word or token in a Source window, double-click the word or C++ token.
Shortcut Menu
Each Source window has a shortcut menu with additional commands. To access the menu, right-click the title bar or click the icon that appears near the upper-right corner of
the window (

). The menu contains the following commands:

Set instruction pointer to current line changes the value of the instruction pointer to the instruction that corresponds to the current line. This command is equivalent to
using the Edit | Set Current Instruction command or pressing CTRL+SHIFT+I.
Edit this file opens the source file in a text editor. The editor is determined by the WinDiff editor registry information or by the value of the
WINDBG_INVOKE_EDITOR environment variable. For example, consider if the value of WINDBG_INVOKE_EDITOR is the following.
c:\my\path\myeditor.exe -file %f -line %l
In this case, Myeditor.exe will open to the one-based line number of the current source file. The %l option indicates that line numbers should be read as one-based,
while %f indicates that the current source file should be used. Other substitution possibilities include %L, which indicates that line numbers are zero-based, and %p,
which can also indicate that the current source file should be used.

Copy copies the current selection to the clipboard. If there is no current selection, this command has no effect.
Copy file path to clipboard copies the file path of the Source window to the clipboard.
Evaluate selection evaluates the currently-selected text by using the C++ expression evaluator. The result appears in the Debugger Command window. If the selected
text includes more than one line, a syntax error results. This command is equivalent to using the Edit | Evaluate Selection command, pressing CTRL+SHIFT+V, or
using the ?? (Evaluate C++ Expression) command with the selected text as its argument.
Display selected type displays the data type of the selected object. This display appears in the Debugger Command window. If the selected text includes more than a
single object, a syntax error or other irregular results might be displayed. This command is equivalent to using the Edit | Display Selected Type command or pressing
CTRL+SHIFT+Y.
(Menu only) Open memory window for selected value opens a new docked Memory window that displays memory starting at the address of the selected expression.
(Menu only) Add selection to Watch window appends the selected source token to Watch window.
Disassemble at current line causes the instruction that corresponds to the current line to appear in the Disassembly window. The selected line is highlighted in the
Source window and in the Disassembly window, but this command affects only the displaythe instruction pointer is not changed. If the Disassembly window is
closed when this command is clicked, it is opened.
Select source language displays a list of programming languages. Select the programming language that you used to generate the source file, and then click OK to
enable basic syntax highlighting for the current Source window. Select <None> to disable syntax highlighting for the current Source window.
Dock or Undock causes the window to enter or leave the docked state.
(Menu only) Move to new dock closes the Source window and opens it in a new dock.
(Menu only) Set as tab-dock target for window type sets the selected Source window as the tab-dock target for other Source windows. All Source windows opened

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 743 of 1651

after one is chosen as the tab-dock target are automatically grouped with that window in a tabbed collection. The Source Window marked as the tab-dock target will not
close when Window | Close All Source Windows is selected. This allows you to set a placeholder window that will not be closed unless you want it to be.
Always floating causes the window to remain undocked even if it is dragged to a docking location.
Move with frame causes the window to move when the WinDbg frame is moved, even if the window is undocked. For more information about docked, tabbed, and
floating windows, see Positioning the Windows.
Help opens this topic in the Debugging Tools for Windows documentation.
Close closes this window.

Source Window Colors and Hover Evaluation

If the debugger recognizes the source file name extension, the Source window displays certain syntax elements in color. To turn off or change the colors, do the following:

To turn the syntax colors off in a single window, open the Source window's shortcut menu, click Select source language, and then click <None>.
To turn the syntax colors off for all Source windows, select Options from the View menu. Then clear the Parse Source Languages check box.
To change the syntax colors, select Options from the View menu. Then, in the Colors area, select a syntax element and click the Change button to change the color.
The parsing method that is used for the highlighting is determined by the programming language that is associated with the file extension for the source file. To change
the programming language that is associated with a specific file extension, use the File Extensions for Source Languages dialog box. To open this dialog box, in the
WinDbg window, on the View menu, click Source language file extensions.

The line that represents the current program counter is highlighted in green. However, if you select a line with the mouse or by using one of the Edit | Go to Xxx commands,
the selected line is green and the line that represents the current program counter is not highlighted. Lines at which breakpoints are set are highlighted as well. Enabled
breakpoints are highlighted in red and disabled breakpoints are highlighted in yellow. If a breakpoint coincides with the current program counter, it is highlighted in purple.
If you select a Source window and then use the mouse to hover over a symbol in that window, the symbol will be evaluated. The evaluation is the same as that produced by
the dt (Display Type) command. To deactivate this evaluation, select Options from the View menu. Then clear the Evaluate on hover check box.
Additional Information
For more information about source debugging and related commands, see Debugging in Source Mode. For more information about docked, tabbed, and floating windows, see
Positioning the Windows. For more information about all techniques that you can use to control debugging information windows, see Using Debugging Information
Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 744 of 1651

File | Disconnect Network Drive

File | Recent Files
File | Exit
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Open Source File

Click Open Source File on the File menu to load a specific source file.
This command is equivalent to pressing CTRL+O or clicking the Open source file (Ctrl+O) button (

Dialog Box
When you click Open Source File, the Open Source File dialog box appears. To open a file, do the following:
1. In the Look in list, select the directory where the file is located. The directory last opened is selected by default.
2. In the Files of type list, select the type of file that you want to open. Only files with the chosen extensions are displayed in the Open Source File dialog box.
Note You can also use wildcard patterns in the File name box to display only files with a certain extension. The new wildcard pattern is retained in a session until you
change it. You can use any combination of wildcard patterns, separated by semicolons. For example, entering *.INC; *.H; *.CPP displays all files with these
extensions. The maximum number of characters in a line is 251.
3. If you find the file you want, double-click the file name, or click the file name and click Open.
-ORTo discard changes and close the dialog box, click Cancel.
The names of the four files that you opened most recently in WinDbg are displayed when you point to Recent files on the File menu. To open one of these files, click its
name.
Additional Information
For more information about source files and source paths and for other ways to load source files, see Source Path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Close Current Window

Click Close Current Window on the File menu to close the active debugging information window.
This command is equivalent to pressing CTRL+F4.
You can also close a debugging information window by clicking the Close button in the upper-right corner of the information window inside the WinDbg window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Open Executable

Click Open Executable on the File menu to start a new user-mode process and debug it.
This command is equivalent to pressing CTRL+E. You can use this command only when WinDbg is in dormant mode.
Dialog Box
When you click Open Executable, the Open Executable dialog box appears, and you can do the following:

Enter the full path of the executable file in the File name box. Alternatively, you can use the dialog box to locate and select the proper file. You must specify the exact
path to the executable file. Unlike the Microsoft Windows Run dialog box and a Command Prompt window, the Open Executable dialog box does not search the

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 745 of 1651

current path for an executable name.

If you want to use command-line arguments with the executable file, enter them in the Arguments box.
If you want to change the starting directory from the default directory enter the directory path in the Start directory box.
If you want WinDbg to attach to any child processes (additional processes that the original target process started), select Debug child processes also.

After you make your selections, click Open.

Note When you use this command to open a source file, the path to that file is automatically appended to the source path.
If WinDbg is connected to a process server, you cannot use the Open Executable command.
Additional Information
For more information and other methods of starting new processes for debugging, see Spawning a New Process (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Attach to a Process

Click Attach to a Process on the File menu to debug a user-mode application that is currently running.
This command is equivalent to pressing F6. You can use this command only when WinDbg is in dormant mode.
Dialog Box
When you click Attach to a Process, the Attach to Process dialog box appears,and you can do the following:

Select the line that contains the proper process ID and name (or enter the process ID in the Process ID box).
Note Each listed process has an associated plus sign (+). You can click the plus sign to display information about that process' command line, services, and child
processes.
Note If WinDbg is connected to a process server, the Attach to Process dialog box will display processes that are running on the remote computer. For more
information about process servers, see Activating a Smart Client.

If you want to attach noninvasively to a process, select the Noninvasive check box.

After you make your selections, click OK.

Additional Information
For more information and other methods of attaching to a process, see Attaching to a Running Process (User Mode) and Noninvasive Debugging (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Open Crash Dump

Click Open Crash Dump on the File menu to open a user-mode or kernel-mode crash dump file and to analyze it.
This command is equivalent to pressing CTRL+D. You can use this command only when WinDbg is in dormant mode.
Dialog Box
When you click Open Crash Dump, the Open Crash Dump dialog box appears. Enter the full path of the crash dump file in the File name box, or use the Look in list to
find and select the proper path and file name. (Dump files typically end with the .dmp or .mdmp extension.)
After you choose the proper file, click Open.
Additional Information
For more information about analyzing crash dump files, see Analyzing a User-Mode Dump File with WinDbg or Analyzing a Kernel-Mode Dump File with WinDbg.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 746 of 1651

File | Connect to Remote Session

Click Connect to Remote Session on the File menu to make WinDbg a debugging client and to connect to an active debugging server.
This command is equivalent to pressing CTRL+R. You can use this command only when WinDbg is in dormant mode.
You cannot use this command to connect to a process server or a KD connection server; for that purpose, use File | Connect to Remote Stub instead.
Connect to Remote Debugger Session Dialog Box
When you click Connect to Remote Session, the Connect to Remote Debugger Session dialog box appears. You can use this dialog box to enter the remote connection
parameters or to browse a list of debugging servers.
To manually specify the remote connection parameters, enter one of the following strings in the Connection string box:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
The various parameters in the preceding options have the following possible values:
Server
The network name of the computer on which the debugging server was created. Do not precede this name with backslashes (\\).
PipeName
If you use the NPIPE or SPIPE protocol, PipeName is the name that was given to the pipe when the server was created.
Socket
If you use the TCP or SSL protocol, Socket is the same socket port number that was used when the server was created.
COMPort
If you use the COM protocol, COMPort specifies the COM port to use. The "COM" prefix is optional (for example, both "com2" and "2" are correct).
BaudRate
If you use the COM protocol, BaudRate should match the baud rate that you chose when the server was created.
COMChannel
If you use the COM protocol, COMChannel should match the channel number that you chose when the server was created.
Protocol
(Windows 2000 and later) If you use the SSL or SPIPE protocol, Protocol should match the secure protocol that you used when the server was created.
Cert
(Windows 2000 and later) If you use the SSL or SPIPE protocol, you should use the identical certuser=Cert or machuser=Cert parameter that was used when the server
was created.
clicon
Specifies that the debugging server will try to connect to the client through a reverse connection. The client must use clicon if and only if the server is using clicon. In
most cases, the debugging client is started before the debugging server when a reverse connection is used.
Password
If you used a password when the server was created, you must supply Password to create the debugging client. This value must match the original password. Passwords
are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005".
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when you are using TCP to connect to the Internet.
In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
Instead of manually specifying the remote connection parameters, you can press the Browse button in the Connect to Remote Debugger Session dialog box and use the
Browse Remote Servers dialog box.
Browse Remote Servers Dialog Box
In the Browse Remote Servers dialog box, in the Machine text box, enter the name of the computer that the debugging server is running on. (The two initial backslashes are
optional: "MyBox" and "\\MyBox" are both correct.) Then, press the Refresh button.
The Servers area lists all of the debugging servers that are running on that computer. Select any of the listed servers and then press ENTER or click OK. (You can also
double-click one of the listed servers.) The proper connection string for the debugging server that you selected will now appear in the Connection string box in the Connect
to Remote Debugger Session dialog box.
If the server is password-protected, the connection string includes Password=*. You must replace the asterisk (*) with the actual password.
After you specify the server and password, click OK to open the connection.
This list of servers in the Browse Remote Servers dialog box can also include servers that no longer exist but were shut down improperly. If you connect to one of these
nonexistent servers, you will receive an error message.
The list of servers does not include process servers and KD connection servers; you can list those servers only by using the File | Connect to Remote Stub command or by
running cdb -QR Server from a Command Prompt window.
Additional Information
For more information and for other methods of joining a remote debugging session, see Activating a Debugging Client.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 747 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Connect to Remote Stub

Click Connect to Remote Stub on the File menu to make WinDbg a smart client and connect to a process server or a KD connection server.
This command is equivalent to using the -premote command line option in user mode, or the -k kdsrv transport protocol command-line option in kernel mode. You can use
this command only when WinDbg is in dormant mode.
You cannot use this command to connect to a debugging server; for that purpose, use File | Connect to Remote Session instead.
Connect to Remote Stub Server Dialog Box
When you click Connect to Remote Stub, the Connect to Remote Stub Server dialog box appears. You can use this dialog box to enter the remote connection parameters
or to browse a list of process servers and KD connection servers.
To manually specify the remote connection parameters, enter one of the following strings in the Connection string box:
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
The various parameters in the preceding options have the following possible values:
Server
The network name of the computer on which the process server or KD connection server was created. Do not precede this name with backslashes (\\).
PipeName
If you use the NPIPE or SPIPE protocol, PipeName is the name that was given to the pipe when the server was created.
Socket
If you use the TCP or SSL protocol, Socket is the same socket port number that was used when the server was created.
COMPort
If you use the COM protocol, COMPort specifies the COM port to use. The "COM" prefix is optional (for example, both "com2" and "2" are correct).
BaudRate
If you use the COM protocol, BaudRate should match the baud rate that you chose when the server was created.
COMChannel
If you use the COM protocol, COMChannel should match the channel number that you chose when the server was created.
Protocol
(Windows 2000 and later) If you use the SSL or SPIPE protocol, Protocol should match the secure protocol that you used when the server was created.
Cert
(Windows 2000 and later) If you use the SSL or SPIPE protocol, you should use the identical certuser=Cert or machuser=Cert parameter that was used when the server
was created.
clicon
Specifies that the process server or KD connection server will try to connect to the client through a reverse connection. The client must use clicon if and only if the server
is using clicon. In most cases, the smart client is started before the server when a reverse connection is used.
Password
If you used a password when the server was created, you must supply Password to create the smart client. This value must match the original password. Passwords are
case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005".
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when you are using TCP to connect to the Internet.
In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
Instead of manually specifying the remote connection parameters, you can press the Browse button in the Connect to Remote Stub Server dialog box and use the Browse
Remote Servers dialog box.
Browse Remote Servers Dialog Box
In the Browse Remote Servers dialog box, in the Machine text box, enter the name of the computer that the process server or KD connection server is running on. (The two
initial backslashes are optional: "MyBox" and "\\MyBox" are both correct.) Then, press the Refresh button.
The Servers area lists all of the process servers and KD connection servers that are running on that computer. Select any of the listed servers and then press ENTER or click
OK. (You can also double-click one of the listed servers.) The proper connection string for the process server that you selected will now appear in the Connection string box
in the Connect to Remote Stub Server dialog box.
If the server is password-protected, the connection string includes Password=*. You must replace the asterisk (*) with the actual password.
After you specify the server and password, click OK to open the connection.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 748 of 1651

The list of servers in the Browse Remote Servers dialog box can also include servers that no longer exist but were shut down improperly. If you connect to one of these
nonexistent servers, you will receive an error message.
The list of servers does not include debugging servers. To view those servers, use the File | Connect to Remote Session command.
Additional Information
For more information and for other methods of joining a remote stub session, see Activating a Smart Client and Activating a Smart Client (Kernel Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Kernel Debug

Click Kernel Debug on the File menu to debug a target computer in kernel mode.
This command is equivalent to pressing CTRL+K. You can use this command only when WinDbg is in dormant mode.
Dialog Box
When you click Kernel Debug, the Kernel Debugging dialog box appears with three tabs:

The COM tab indicates that the connection will use a COM port. In the Baud Rate box, enter the baud rate. In the Port box, enter the name of the COM port.
The 1394 tab indicates that the connection will use 1394. In the Channel box, enter the 1394 channel number. 1394 debugging is supported only if both the host
computer and target computer are running Windows XP or later versions of the Windows operating system.
The USB 2.0 tab indicates that the connection will use USB 2.0. In the Target Name box, enter the connection string. This must match the string specified with the
targetname boot option. For information on this boot option prior to Windows Vista, see /debug. For information on this boot option in Windows Vista and later
versions of Windows, see BCDEdit / dbgsettings. USB 2.0 debugging is supported only if the host computer is running Windows 2000 or a later version of Windows,
and the target computer is running Windows Vista or a later version.
The Local tab indicates that WinDbg will perform local kernel debugging. Local kernel debugging is supported only on Windows XP and later.

Additional Information
For more information about settings for kernel debugging, see Choosing Kernel Debugging Settings.
For more information and for other methods of beginning a kernel debugging session, see Attaching to a Target Computer (Kernel Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Symbol File Path

Click Symbol File Path on the File menu to display, set, or append to the symbol path.
This command is equivalent to pressing CTRL+S.
Symbol Search Path Dialog Box
When you click Symbol File Path, the Symbol Search Path dialog box appears. This dialog box displays the current symbol path. If the Symbol path box is blank, there is
no current symbol path.
You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons.
Click OK to save changes, or click Cancel to discard changes.
If you select the Reload check box, the debugger will reload all loaded symbols and images after you click OK. The Reload command is equivalent to using
the .reload (Reload Module) command.
You can also click Browse to open the Browse For Folder dialog box.
Browse For Folder Dialog Box
In the Browse For Folder dialog box, you can browse through the folders on your computer or your network. You can also click the Make New Folder button to create a
new folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears.
Click OK to append the selected folder to the symbol path and return to the Symbol Search Path dialog box.
Additional Information
For more information and for other ways to change the symbol path, see Symbol Path.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 749 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Source File Path

Click Source File Path on the File menu to display, set, or append to the source path.
This command is equivalent to pressing CTRL+P.
Source Search Path Dialog Box
When you click Source File Path, the Source Search Path dialog box appears. This dialog box displays the current source path. If the Source path box is blank, there is no
current source path.
You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons.
If you are performing remote debugging, the Local check box will be available. Select this box to edit your debugging client's local source path; clear it to edit the debugging
server's source path.
Click OK to save changes, or click Cancel to discard changes.
You can also click Browse to open the Browse For Folder dialog box.
Browse For Folder Dialog Box
In the Browse For Folder dialog box, you can browse through the folders on your computer or your network. You can also click the Make New Folder button to create a
new folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears.
Click OK to append the selected folder to the source path and return to the Source Search Path dialog box.
Additional Information
For more information and for other ways to change this path, see Source Path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Image File Path

Click Image File Path on the File menu to display, set, or append to the executable image path.
This command is equivalent to pressing CTRL+I.
Executable Image Search Path Dialog Box
When you click Image File Path, the Executable Image Search Path dialog box appears. This dialog box displays the current executable image path. If the Image path box
is blank, there is no current executable image path.
You can enter a new path or edit the old path. If you want to search more than one directory, separate the directory names with semicolons.
Click OK to save changes, or click Cancel to discard changes.
If you select the Reload check box, the debugger will reload all loaded image and symbol files after you click OK. This command is equivalent to using the .reload (Reload
Module) command.
You can also click Browse to open the Browse For Folder dialog box.
Browse For Folder Dialog Box
In the Browse For Folder dialog box, you can browse through the folders on your computer or your network. You can also use the Make New Folder button to create a new
folder. If you right-click a file or folder in this dialog box, a standard Windows shortcut menu appears.
Click OK to append the selected folder to the executable image path and return to the Executable Image Search Path dialog box.
Additional Information
For more information and for other ways to change this path, see Executable Image Path.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 750 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

File | Open Workspace

Click Open Workspace on the File menu to open a saved workspace.
This command is equivalent to pressing CTRL+W.
Dialog Box
When you click Open Workspace, the Open Workspace dialog box appears. This dialog box contains a list of all named workspaces in the Workspaces area. Default or
implicit workspaces are not listed since opening them directly will cause problems with the implicit ordering. If you want to open an implicit workspace directly, you must
save it explicitly. For more information on named and default workspaces, see Creating and Opening a Workspace.
Enter the name of the workspace that you want to open in the Workspace box or select the workspace name in the Workspaces area. Then, click OK to open the selected
workspace, or click Cancel to return the debugger to its previous state.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Save Workspace

Click Save Workspace on the File menu to save the current workspace under its current workspace name.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Save Workspace As

Click Save Workspace As on the File menu to save the current workspace under a new workspace name.
Dialog Box
When you click Save Workspace As, the Save Workspace As dialog box appears. This dialog box contains a list of all existing workspace names in the Workspaces area.
The name of the current workspace is shown in the Workspace box.
Enter the name that you want to use to save the workspace in the Workspace box, select the workspace name in the Workspaces area, or just leave the current name as it
exists.
Click OK to save the workspace, or click Cancel to not save the workspace.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Clear Workspace

Click Clear Workspace on the File menu to erase items in the current workspace.
Dialog Box

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 751 of 1651

When you click Clear Workspace, the Clear Workspace dialog box appears. This dialog box contains a list of all of the items that are contained in the current workspace in
the Items in Workspace area.
Use the Clear and Clear All buttons to remove items from the Items in Workspace area. If you make an error, use the Save and Save All buttons to return items to this list.
Click OK to make these changes, or click Cancel to discard these changes.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Delete Workspaces

Click Delete Workspaces on the File menu to delete one or more existing workspaces.
Dialog Box
When you click Delete Workspaces, the Delete Workspaces dialog box appears. In this dialog box, select the workspace that you want to delete and click Delete.
Click Close to close the dialog box.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Open Workspace in File

Click Open Workspace in File on the File menu to load a workspace that was previously saved to a file.
Dialog Box
When you click Open Workspace in File, the Open Workspace in File dialog box appears. In this dialog box, enter the name of the file that you want to load, or use the
Look in list to navigate to the file and select it. (Workspace files should use the .wew extension.)
Click OK to load the workspace, or click Cancel to close the dialog box.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Save Workspace to File

Click Save Workspace to File on the File menu to save the current workspace to a file.
Dialog Box
When you click Save Workspace to File, the Save Workspace to File dialog box appears. In this dialog box, enter the name of the file that you want to save the workspace
as. Then, use the Save in list to navigate to the directory where you want to save the file, or select a specific file you want to overwrite. (The default file extension is .wew.)
Click OK to save the file, or click Cancel to exit.
Additional Information
For more information about the different levels of workspaces and how to use them, see Using Workspaces.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 752 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Map Network Drive

Click Map Network Drive on the File menu to add network connections and assign drive letters to these connections.
Dialog Box
When you click Map Network Drive, the Map Network Drive dialog box appears. Use the Drive and Folder menus to choose a server and share and assign a drive letter to
it.
This dialog box works exactly like the corresponding feature of Windows Explorer.
The File | Map Network Drive command affects only the network connections of the computer on which WinDbg is running. If you are using WinDbg as a client in a remote
debugging session and you want to change the network connections of the server, you must use a .shell net use command.
Additional Information
For more information about accessing the command shell, see Using Shell Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Disconnect Network Drive

Click Disconnect Network Drive on the File menu to remove network connections.
Dialog Box
When you click Disconnect Network Drive, the Disconnect Network Drives dialog box appears. In the Network Drives box, select the connection you want to remove and
click OK.
This dialog box works exactly like the corresponding feature of Windows Explorer.
The File | Disconnect Network Drive command affects only the network connections of the computer on which WinDbg is running. If you are using WinDbg as a client in a
remote debugging session and you want to change the network connections of the server, you must use a .shell net use command.
Additional Information
For more information about accessing the command shell, see Using Shell Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Recent Files

Point to Recent Files on the File menu to display a list of the four source files that you most recently opened in WinDbg.
To open one of these files, click its name from the menu.
Additional Information
For more information about source files and source paths, and for other ways to load source files, see Source Path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

File | Exit

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 753 of 1651

Click Exit on the File menu to end the debugging session and exit WinDbg.
This command is equivalent to pressing ALT+F4.
Additional Information
For more information about exiting WinDbg or ending the debugging session, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Cut
Click Cut on the Edit menu to delete any text that you have selected and to move it to the clipboard.
This command is equivalent to pressing CTRL+X or SHIFT+DELETE or clicking the Cut (Ctrl+X) button (

) on the toolbar.

You can use the Cut command on the Edit menu only with docked or tabbed windows, but you can use the shortcut keys and the toolbar button with any window that
supports this feature.
Additional Information
For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see Cutting and Pasting Text.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 754 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Copy
Click Copy on the Edit menu to copy to the clipboard any text that you have selected.
This command is equivalent to pressing CTRL+C or CTRL+INSERT or clicking the Copy (Ctrl+C) button (

) on the toolbar.

You can use the Copy command only with docked or tabbed windows. You can use the shortcut keys and the toolbar button with any window that supports this feature.
Additional Information
For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see Cutting and Pasting Text.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Paste
Click Paste on the Edit menu to paste text from the clipboard to the current cursor location.
This command is equivalent to pressing CTRL+V or SHIFT+INSERT or clicking the Paste (Ctrl+V) button (

) on the toolbar.

You can use the Paste command only with docked or tabbed windows. But you can use the shortcut keys and the toolbar button with any window that supports this feature.
Additional Information
For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see Cutting and Pasting Text.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Select All

Click Select All on the Edit menu to select all of the text in the active Debugger Command window, Disassembly window, Source window, or dialog box.
This command is equivalent to pressing CTRL+A.
Additional Information
For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see Cutting and Pasting Text.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Write Window Text to File

Click Write Window Text to File on the Edit menu to save all of the text in the active debugging information window to a file.
This command is available only if the active window is the Debugger Command window, Calls window, or Scratch Pad.
Dialog Box
When you click Write Windows Text to File, the Write Window Text to File dialog box appears. In this dialog box, enter the name of the file where you want to save the
window text. You can browse in the Save in list to the directory that you want or select a specific file that you want to overwrite. The default file name extension is .txt.
Click Save to save the file or click Cancel to exit.
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 755 of 1651

For more information about how to select, copy, cut, and paste text and about how these operations vary from window to window, see Cutting and Pasting Text.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Add to Command Output

Click Add to Command Output on the Edit menu to insert a comment into the Debugger Command window.
Type a comment into the Text box and then click OK.
Your comment appears in the Debugger Command window and in any open log file. However, the comment does not appear in any Windows debuggers that are remotely
connected to your session.
Additional Information
For more information about other features of the Debugger Command window, see Using Debugger Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Clear Command Output

Click Clear Command Output on the Edit menu to clear all of the text from the Debugger Command window and clear the command history.
Additional Information
For more information about other features of the Debugger Command window, see Using Debugger Commands.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Evaluate Selection

Click Evaluate Selection on the Edit menu to evaluate the current selection in the Source window and display the result in the Debugger Command window.
This command is equivalent to pressing CTRL+SHIFT+V, clicking Evaluate selection on the Source window's shortcut menu, or using the ?? (Evaluate C++ Expression)
command together with the selected text as its argument.
If the selected text includes more than one line, a syntax error results. If no text is selected in a Source window, you cannot use this command.
Additional Information
For more information about other features of Source windows, see Source Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Display Selected Type

Click Display Selected Type on the Edit menu to determine the data type of the current selection in the Source window and to display the type in the Debugger Command
window.
This command is equivalent to pressing CTRL+SHIFT+Y or clicking Display selected type on the Source window's shortcut menu.
If the selected text includes more than a single object, a syntax error or other irregular results might be displayed. If no text is selected in a Source window, you cannot use this
command.
Additional Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 756 of 1651

For more information about other features of Source windows, see Source Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Find
Click Find on the Edit menu to find text in the active debugging information window.
Note The active window must be the Debugger Command window or a Source window.
This command is equivalent to pressing CTRL+F.
Dialog Box
When you click Find, the Find dialog box appears. In this dialog box, in the Find what box, enter the text that you want to find. If there is already text selected, this text
automatically appears in the Find what box.
In the Direction area, click Up or Down to specify the direction of your search. The search begins wherever the cursor is in the window. You can put the cursor at any
location by using the mouse pointer.
Select Match whole word only if you want to search for a single whole word. (If you select this option when you search for multiple words, you always receive a failed
search.))
Select Match case to perform a case-sensitive search.
The Find command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations.
After you close the Find dialog box, you can repeat the search in a forward direction by using the Edit | Find Next command or pressing F3. You can repeat the search in a
backward direction by pressing SHIFT+F3.
Additional Information
For more information about other ways to find text in debugging information windows, see Moving Through a Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Find Next

Click Find Next on the Edit menu to repeat the previous search and find the next match.
This command is equivalent to pressing F3.
To repeat the search in a backward direction, press SHIFT+F3.
If you have not previously performed any searches, use the Edit | Find Next command, press F3, or press SHIFT+F3 to open the Find dialog box (similar to the Edit | Find
command).
Additional Information
For more information about other ways of finding text in debugging information windows, see Moving Through a Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Go to Address
Click Go to Address on the Edit menu to go to an address in the target's virtual address space.
This command is equivalent to pressing CTRL+G.
Dialog Box
When you click Go to Address, the View Code Offset dialog box appears. In this dialog box, enter the address that you want to move to. This address can be an expression

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 757 of 1651

(such as a function, symbol, or integer memory address) or any valid address expression. If the address is ambiguous, the dialog box displays a list that contains all of the
ambiguous items.
Note If you put the cursor on a line within the Disassembly window or a Source window and then use the Go to Address command, the address of the line that you have
selected will appear in the View Code Offset dialog box. You can use this address or replace it with any address of your choice.
After you click OK, the debugger moves the caret (^) to the beginning of the function or address in the Disassembly window or a Source window.
You can use the Go to Address command in any window that is currently active. If the debugger is in disassembly mode, WinDbg finds the address in the Disassembly
window. If the debugger is in source mode, WinDbg finds the address in a Source window. If the address cannot be found in a Source window, WinDbg finds it in the
Disassembly window. If the appropriate window is not open, WinDbg opens it.
The Go to Address command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations.
Additional Information
For more information about other ways of finding text in debugging information windows, see Moving Through a Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Go to Line
Click Go to Line on the Edit menu to search for a specific line in the currently-active Source window. If the active window is not a Source window, this command has no
effect.
This command is equivalent to pressing CTRL+L.
Dialog Box
When you click Go to Line, the Go to Line dialog box appears. In this dialog box, enter the line number that you want to find and then click OK. The debugger will move
the caret (^) to that line. If the line number is bigger than the last line in the file, the cursor will move to the end of the file.
The Go to Line command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations.
Additional Information
For more information about other ways of finding text in debugging information windows, see Moving Through a Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Go to Current Instruction

Click Go to Current Instruction on the Edit menu to open the debugging information window that contains the current instruction and to highlight this instruction.
This command is equivalent to pressing ALT+ASTERISK (using the ASTERISK key on the numeric keypad).
If the current instruction corresponds to a known source file, WinDbg opens the Source window that contains this source file. If no such window exists, WinDbg opens one.
The current line is highlighted.
If the current instruction is not in a known source file and the Disassembly window is open, WinDbg opens the Disassembly window and the current line is highlighted.
However, if the Disassembly window is closed, the Go to Current Instruction command does not open it.
This command only changes the WinDbg display. This command does not affect the execution of the target or any other debugger operations.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Set Current Instruction

Click Set Current Instruction on the Edit menu to change the value of the instruction pointer to the instruction that corresponds to the current line in the active Source
window.
This command is equivalent to pressing CTRL+SHIFT+I or clicking Set instruction pointer to current line on the Source window's shortcut menu.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 758 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Breakpoints
Click Breakpoints on the Edit menu to display or control breakpoints.
This command is equivalent to pressing ALT+F9. If a Source window or the Disassembly window is not active, you can also press F9 or click the Insert or remove
breakpoint (F9) button (

) on the toolbar.

However, if a Source window or the Disassembly window is open, the Insert or remove breakpoint (F9) button and the F9 key set a breakpoint on the current line. (If there
is already a breakpoint set at the current line, this button or key will remove the breakpoint.)
If a statement or call spans multiple lines, WinDbg sets the breakpoint on the last line of the statement or call. You should insert the caret (^) on or before the statement to set
a breakpoint for the whole statement. If the debugger cannot set a breakpoint at the current caret position, it will search in a downward direction for the next allowed position
and insert the breakpoint there.
Dialog Box
When you click Breakpoints, the Breakpoints dialog box appears. This dialog box displays all current breakpoint information and is presented in the following columns:

The breakpoint number. This number is a decimal number that you can use to refer to the breakpoint in future commands.
The breakpoint status. This status can be e (enabled) or d (disabled).
(Unresolved breakpoints only) The letter u. This letter appears if the breakpoint is unresolved (that is, it does not match any currently-loaded module address). For
details, see Unresolved Breakpoints (bu Breakpoints).
The virtual address of the breakpoint. If you have enabled the loading of source line numbers, the display includes file and line number information instead of address
offsets. If the breakpoint is unresolved, the address appears at the end of the listing instead of here.
(Processor breakpoints only) Type and size information. This information can be e (execute), r (read/write), w (write), or i (input/output). These types are followed with
the size of the block, in bytes. For details, see Processor Breakpoints (ba Breakpoints).
The number of passes that are remaining until the breakpoint becomes active, followed by the initial number of passes in parentheses. The number of times that the
program counter passes through the breakpoint without breaking is one less than the value of this number. Therefore, this number is never lower than 1. Note also that
this number counts only the times the application executes through this point. In other words, stepping over this point does not count. After the full count has been
reached, you can reset the count only by clearing and resetting the breakpoint.
The associated process and thread. If thread is given with three asterisks (***), this breakpoint is not a thread-specific breakpoint.
The module and function, with offset, that correspond to the breakpoint address. If the breakpoint is unresolved, the breakpoint address appears here, in parentheses. If
the breakpoint is set on a valid address but symbol information is missing, this column will be blank.
The command string that is automatically executed when this breakpoint is hit. This command string is displayed in quotation marks. If the breakpoint is hit, the
commands in this command string are executed until application execution resumes. Any command that resumes program execution (such as g or t) will stop the
execution of the command list.

If you select any breakpoint, you can then click the Remove, Disable, or Enable button. The Remove button permanently removes the breakpoint. The Disable button
temporarily deactivates the breakpoint. The Enable button re-enables a disabled breakpoint.
The Remove All button permanently removes all breakpoints.
You can also enter commands in the Command box in the following ways:

If you enter a bp (Set Breakpoint), bu (Set Unresolved Breakpoint), bm (Set Symbol Breakpoint), ba (Break on Access), bc (Breakpoint Clear), bd (Breakpoint
Disable), or be (Breakpoint Enable) command, the Command box works as if you were entering the command in the Debugger Command window. However, the
command itself must be in lowercase letters. The command cannot begin with a thread specifier. If you want to use a thread specifier, enter it in the Thread box without
the initial tilde (~).
If you enter any other text, the text will be treated as the argument string for a bu (Set Unresolved Breakpoint) command. That is, the debugger prefixes your entry
with bu and a space and then executes it as a command.

When you are entering a new breakpoint, you can also do the following:

Create a thread-specific breakpoint by entering a thread specifier in the Thread box. Do not include the tilde (~) character that is typically prefixed to a thread specifier.
Create a conditional breakpoint by entering a condition in the Condition box. The condition can be any evaluable expression, and it will be evaluated according to the
current expression syntax (see Evaluating Expressions). For more information about these types of breakpoints, see Setting a Conditional Breakpoint.

Additional Information
For more information about how to use breakpoints, other breakpoint commands and methods of controlling breakpoints, and setting breakpoints in user space from a kernel
debugger, see Using Breakpoints. For more information about conditional breakpoints, see Setting a Conditional Breakpoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Edit | Open/Close Log File

Click Open/Close Log File on the Edit menu to write to a new log file, append to an existing log file, or close an open log file.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 759 of 1651

Dialog Box
When you click Open/Close Log File, the Open/Close Log File dialog box appears. This dialog box displays the current log file, if one is already open.
If the Log file name box is blank, you can enter a log file name. If this file already exists, WinDbg overwrites the existing file, unless you select the Append check box. If
you specify a file name but no path, WinDbg puts the file in the default directory that you started WinDbg from.
If the Log file name box already displays a file name, you can click Close Open Log File to close the file. If you clear the Log file name box and enter a new log file name,
the previous log file will be closed.
Click OK to save changes, or click Cancel to discard changes.
If you click OK when no log file name appears in the Log file name box, it has no effect. That is, WinDbg does not close a log file or open a log file.
However, if a log file is already active and you click OK without clearing its name or selecting Append, WinDbg deletes the log file and uses a new file that has the same
name.
Additional Information
For more information and for other ways to write to log files, see Keeping a Log File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 760 of 1651

View | Command
Click Command on the View menu to open the Debugger Command window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+1 or clicking the Command (Alt+1) button (

) on the toolbar.

For more information about this window and its uses, see Debugger Command Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Watch
Click Watch on the View menu to open the Watch window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+2 or clicking the Watch (Alt+2) button (

) on the toolbar.

For more information about this window and its uses, see Watch Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Locals
Click Locals on the View menu to open the Locals window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+3 or clicking the Locals (Alt+3) button (

) on the toolbar.

For more information about this window and its uses, see Locals Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Registers
Click Registers on the View menu to open the Registers window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+4 or clicking the Registers (Alt+4) button (

) on the toolbar.

For more information about this window and its uses, see Registers Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Memory
Click Memory on the View menu to open a new Memory window.
Note You can have multiple Memory windows open at the same time. Each window can display a different region of memory. Only the Memory window and the Source
window have this ability. All other debugging information windows are limited to a single instance.
The View command is equivalent to pressing ALT+5 or clicking the Memory window (Alt+5) button (

) on the toolbar.

For more information about this window and its uses, see Memory Window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 761 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Call Stack

Click Call Stack on the View menu to open the Calls window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+6 or clicking the Call stack (Alt+6) button (

) on the toolbar.

For more information about this window and its uses, see Calls Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Disassembly
Click Disassembly on the View menu to open the Disassembly window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+7 or clicking the Disassembly (Alt+7) button (

) on the toolbar.

For more information about this window and its uses, see Disassembly Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Scratch Pad

Click Scratch Pad on the View menu to open the Scratch Pad. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+8 or clicking the Scratch Pad (Alt+8) button (

) on the toolbar.

For more information about this window and its uses, see Scratch Pad.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Processes and Threads

Click Processes and Threads on the View menu to open the Processes and Threads window. If this window is already open, it becomes active.
This command is equivalent to pressing ALT+9 or clicking the Processes and Threads (Alt+9) button (

) on the toolbar.

For more information about this window and its uses, see Processes and Threads Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Command Browser

Click Command Browser on the View menu to open the Command Browser window. If this window is already open, it becomes active.
This command is equivalent to pressing CTRL+N or clicking the Command Browser (Ctrl+N) button (

) on the toolbar..

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 762 of 1651

For more information about this window and its uses, see Command Browser Window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Verbose Output

Click Verbose Output on the View menu to turn verbose mode on and off.
This command is equivalent to pressing CTRL+ALT+V. (and to pressing CTRL+V in KD).
When verbose mode is turned on, some display commands (such as register dumping) produce more detailed output. Every MODULE LOAD operation that is sent to the
debugger is displayed. And every time that a driver or DLL is loaded by the operating system, the debugger is notified.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Show Version

Click Show Version on the View menu to display version information about the debugger and all loaded extension DLLs. This information is displayed in the Debugger
Command window.
This command is equivalent to pressing CTRL+ALT+W (and pressing CTRL+W in KD).
This command has the same effect as the version (Show Debugger Version) command, except that the latter command also displays the version of the Microsoft Windows
operating system.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Toolbar
Select or clear Toolbar on the View menu to cause the toolbar to appear or disappear.
For more information about how to use the toolbar, see Using the Toolbar and Status Bar. For more information about each toolbar button, see Toolbar Buttons.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Status Bar

Select or clear Status Bar on the View menu to cause the status bar to become visible or invisible.
For more information about how to use the status bar, see Using the Toolbar and Status Bar.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Font
Click Font on the View menu to change the font that appears in the debugging information windows.
This command is equivalent to clicking the Font button (

) on the toolbar.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 763 of 1651

Dialog Box
When you click Font, the Font dialog box appears. In this dialog box, you can select the font, style, and size from the appropriate lists,. You can also select the script from a
drop-down menu to get the appropriate alphabet. To accept your changes, click OK.
Click Cancel to cancel changes to the font.
Additional Information
For more information about how to change the character display of the debugging information windows, see Changing Text Properties.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | Options
Click Options on the View menu to open the Options dialog box. This command is equivalent to clicking the button (

) on the toolbar.

Dialog Box
In the Options dialog box, you can select or deselect the following options:
Tab width
The Tab width box controls how tab characters are displayed in any Source window. In the Tab width box, enter the number of spaces that you want to have between
each tab setting. (The default setting is 8. For more information about text properties, see Changing Text Properties.)
Reuse after opening this many
The Reuse after opening this many box controls the number of document, or source, windows that can be open at the same time. If the specified number of source
windows has been reached, opening a new window causes an existing window to close. Windows that are marked as tab-dock targets do not close. The last windows to
close are the ones you used most recently.
Parse source languages
If the Parse source languages check box is selected, the text of source code in all Source windows is colored according to a simple parse of the source syntax. To change
the colors, in the Colors area of the dialog box, select a syntax element and then click Change. (To turn the syntax colors off in a single Source window, open that
window's shortcut menu, click Select source language, and then click <None>.)
Evaluate on hover
If the Evaluate on hover check box is selected (and the Parse source languages check box is selected as well), symbols in a Source window will be evaluated when you
select that window and then hover over a symbol with the mouse. The evaluation is the same as that produced by the dt (Display Type) command.
Enter repeats last command
If the Enter repeats last command check box is selected, you can press the ENTER key at an empty prompt in the Debugger Command window to repeat the previous
command. If you clear this check box, the ENTER key generates a new prompt.
Automatically scroll
The Automatically scroll check box controls the automatic scrolling that occurs when new text is sent to the Debugger Command window. If you want to turn off this
feature, clear the Automatically scroll check box. For more information about this scrolling, see Using Debugger Commands.
Workspace Prompts
In the Workspace Prompts area, you can click one of three options to determine when and how frequently the workspace is saved in WinDbg.
If you click Always ask, when a workspace changes (such as when a debugging session ends), the debugger displays the Workspace save dialog box where you
can save the workspace.
In the Workspace save dialog box, if you click Don't ask again, WinDbg resets the Workspace Prompts option to Never save or Always save.

If you click Always save, the workspace is saved automatically whenever it changes.
If you click Never save, the workspace is not saved when it changes, and you are not prompted to save it.

QuickEdit Mode
If the QuickEdit Mode check box is selected, you can right-click an item to copy or paste, depending on the window selection state. When you clear this check,
QuickEdit is disabled and you can right-click an item to open a shortcut menu for the window. You cannot give individual windows different settings; the QuickEdit
setting applies globally to all windows. By default, this box is selected. The QuickEdit setting is saved in the current workspace.
Colors
To change the color of the source text that is displayed, select an item from the Colors area and then click Change. Select a color, or select a custom color, and then click
OK.
In the Colors menu, you can change the colors of the following items:

The first ten items represent text in the Disassembly window and the Source window.
The Changed data text item represents data entries that have been changed (for example, in the Registers window).
The ten Source Xxx items control the colors that are used for syntax elements in the Source window.
The remaining items refer to different kinds of text in the Debugger Command window.

These color changes take effect when you click OK. To discard these changes, click Cancel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 764 of 1651

View | Source language file extensions

Click Source language file extensions on the View menu to control the file name extensions that WinDbg recognizes as source file name extensions. You can also specify
which programming languages are associated with which file name extensions.
Dialog Box
When you click Source language file extensions, the File Extensions for Source Languages dialog box appears. In this dialog box, you can add or delete file name
extensions by inserting the cursor in the Extensions and languages box and typing the appropriate information. Make sure that you specify the appropriate programming
language for each file name extension. For example, cxx=C++ indicates that a .cxx file name extension is a source file and that the corresponding programming language of
any file that has that extension is C++. Click OK to implement your changes, or click Cancel to discard any changes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

View | WinDbg Command Line

Click WinDbg Command Line on the View menu to display the command that was used to open the current WinDbg session.
The command appears in a small message window. Click OK to close this window.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 765 of 1651

Debugging Tools for Windows

Debug | Go
Click Go on the Debug menu to resume (or begin) execution on the target. This execution will continue until a breakpoint is reached, an exception or event occurs, the
process ends, or the debugger breaks into the target.
This command is equivalent to pressing F5 or clicking the Go (F5) button (

) on the toolbar.

Additional Information
For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Go Unhandled Exception

Click Go Unhandled Exception on the Debug menu to resume execution on the target and to treat the current exception as unhandled.
Additional Information
For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see Controlling the Target. For
more information about exceptions and other events, see Controlling Exceptions and Events.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Go Handled Exception

Click Go Handled Exception on the Debug menu to resume execution on the target and to treat the current exception as handled.
Additional Information
For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see Controlling the Target. For
more information about exceptions and other events, see Controlling Exceptions and Events.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Restart
Click Restart on the Debug menu to stop the target's execution and end the target process and all its threads. This command then restarts the target execution at the beginning
of the process.
This command is equivalent to pressing CTRL+SHIFT+F5 or clicking the Restart (Ctrl+Shift+F5) button (

) on the toolbar.

Additional Information
For more information about the effects of this action, other methods of issuing this command, and other ways to control program execution, see Controlling the Target. For
more information about how to exit WinDbg or end the debugging session, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Stop Debugging

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 766 of 1651

Click Stop Debugging on the Debug menu to stop the target's execution and end the target process and all its threads. This action enables you to start to debug a different
target application.
This command is equivalent to pressing SHIFT+F5 or clicking the Stop debugging (Shift+F5) button (

) on the toolbar.

Debug | Detach Debuggee

Click Detach Debuggee on the Debug menu to detach from the target application and leave it running.
Detaching from the target is supported under one of the following conditions:

(Microsoft Windows XP and later versions of Windows) You are debugging a running user-mode target.
You are noninvasively debugging a user-mode target.

If you are debugging a live target on Windows 2000, the Detach Debuggee command is not available, because this version of Windows does not support detaching from a
target process.
Additional Information
For more information about how to exit the debugger or detach from the target, see Ending the Debugging Session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Break
Click Break on the Debug menu to stop the target's execution and return control to the debugger.
In user mode, this command stops the process and its threads, enabling you to regain control of the debugger. In kernel mode, this command breaks into the target computer.
You can also use this command while the debugger is active. In this situation, the command will truncate long Debugger Command window displays.
The Break command is equivalent to pressing CTRL+BREAK or clicking the Break (Ctrl+Break) button (

) on the toolbar.

User-Mode Effects
In user mode, the Break command causes the target application to break into the debugger. The target application stops, the debugger becomes active, and you can enter
debugger commands.
If the debugger is already active, Break does not affect the target application. However, you can use this command to terminate a debugger command. For example, if you
have requested a long display and do not want to see any more of it, Break will end the display and return you to the debugger command prompt.
When you are performing remote debugging with WinDbg, you can press the Break key on the host computer's keyboard. If you want to issue a break from the target
computer's keyboard, use CTRL+C on an x86-based computer.
You can press the F12 key to open a command prompt when the application that is being debugged is busy. Click one of the target application's windows and press F12 on the
target computer.
Kernel-Mode Effects
In kernel mode, the Break command causes the target computer to break into the debugger. This command locks the target computer and wakes up the debugger.
When you are debugging a system that is still running, you must press the Break key on the host keyboard to open an initial command prompt.
If the debugger is already active, Break does not affect the target computer. However, you can use this command to terminate a debugger command. For example, if you have
requested a long display and do not want to see any more of it, Break will end the display and return you to the debugger command prompt.
You can also use Break to open a command prompt when a debugger command is generating a long display or when the target computer is busy. When you are debugging an
x86-based computer, you can also press CTRL+C on the target keyboard to have the same effect.
The SYSRQ key (or pressing ALT+SYSRQ on an enhanced keyboard) is similar. This key works from the host or target keyboard on any processor. However, this key works
only if you have opened the prompt by pressing CTRL+C at least one time before.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 767 of 1651

You can disable the SYSRQ key by editing the registry. In the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\i8042prt\Parameters registry key, create a
value named BreakOnSysRq and set it equal to DWORD 0x0. Then, restart the computer. After you have restarted the computer, you can press the SYSRQ key on the target
computer's keyboard and it will not break into the kernel debugger.
Additional Information
The corresponding key in KD and CDB is CTRL+C. For more information about other ways to control program execution, see Controlling the Target.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Step Into

Click Step Into on the Debug menu to execute a single instruction on the target. If the instruction is a function call, the debugger steps into the function.
This command is equivalent to pressing F11 or F8 or clicking the Step into (F11 or F8) button (

) on the toolbar.

Debug | Step Over

Click Step Over on the Debug menu to execute a single instruction on the target. If the instruction is a function call, the whole function is executed.
This command is equivalent to pressing F10 or clicking the Step over (F10) button (

) on the toolbar.

Debug | Step Out

Click Step Out on the Debug menu to resume running on the target. This command executes the rest of the current function and breaks when the function return is completed.
This command is equivalent to pressing SHIFT+F11 or clicking the Step out (Shift+F11) button (

) on the toolbar.

Debug | Run to Cursor

Click Run to Cursor on the Debug menu to resume running on the target. If you insert the cursor on an instruction in the Disassembly window or a Source window and then
execute this action, WinDbg executes all instructions from the current instruction up to the instruction you have selected.
This command is equivalent to pressing F7 or CTRL+F10 or clicking the Run to cursor (Ctrl+F10 or F7) button (

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

) on the toolbar.

9/18/2010

Introduction

Page 768 of 1651

Debug | Source Mode

Select Source Mode on the Debug menu to switch the debugger to source mode. Clear Source Mode to switch the debugger to assembly mode.
You can click the Source mode on button (shown on the left in the following figure) to change the debugger to source mode or click the Source mode off button (shown on
the right in the following figure) to change the debugger to assembly mode.

When source mode is active, ASM is unavailable on the status bar. When assembly mode is active, ASM is displayed on the status bar.
Additional Information
For more information about source-mode debugging, see Debugging in Source Mode. For more information about assembly-mode debugging, see Debugging in Assembly
Mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Resolve Unqualified Symbols

Select Resolve Unqualified Symbols on the Debug menu to resolve symbols that have no module prefix.
If you clear Resolve Unqualified Symbols, the debugger cannot resolve symbols that have no module prefix. If you do not select Resolve Unqualified Symbols and a
variable that has no prefix is not already loaded, the debugger does not load any additional symbols to resolve it. You can still use unqualified symbols when this option is
clear, but only if they have been previously loaded.
Although we always recommend that you use module qualifiers, you can clear the Resolve Unqualified Symbols option to avoid loading symbols that resolve incorrect or
misspelled symbols when module qualifiers are not used.
Additional Information
For more information about symbols, loading symbols, and verifying symbols, see Symbols.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Event Filters

Click Event Filters on the Debug menu to open the Event Filters dialog box. In this dialog box, you can configure the break status and handling status of exceptions and
events.
Dialog Box
The Event Filters dialog box lists all events that the debugger recognizes. You may add numbered exceptions to the list that will then be displayed.
To change the break status for an event, select the event and then click one of the Execution option buttons (Enabled, Disabled, Output, or Ignore).
To change the handling status for an event, select the event and then click one of the Continue option buttons (Handled or Not Handled).
To add a new numbered exception, click Add. When the Exception Filter dialog box appears, enter the exception code, click the appropriate button for the break status and
handling status, and then click OK.
To remove a numbered exception, select the exception and then click Remove. You cannot remove the standard events.
When you set the status for the Load module or Unload module events, you can limit this status to a specific module. Click Argument, enter the name of the module or the
base address of the module in the Filter Argument dialog box, and then click OK. You can use wildcards when you specify the base address. If you do not specify a module,
the break occurs when any module is loaded or unloaded.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 769 of 1651

When you set the status for the Debuggee output event, you can limit this status to a specific output pattern. Click Argument, enter the output pattern in the Filter
Argument dialog box, and then click OK. If you do not specify an output pattern, the break occurs for any output.
If you want to set automatic commands that are executed if the event breaks into the debugger, select the event and then click Commands. The Filter Command dialog box
will appear. Enter any commands that you want into the Command or Second-chance Command box. Separate multiple commands by using semicolons and do not enclose
these commands in quotation marks.
Additional Information
For more information about break status and handling status, all event codes, the default status for all events, and other methods of controlling this status, see Controlling
Exceptions and Events.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Modules
Click Modules on the Debug menu to display the current list of loaded modules.
Dialog Box
When you click Modules, the Module List dialog box appears. This dialog box lists all modules that are currently loaded into memory.
Module List is divided into the following columns:

The Name column specifies the module name.

The Start and End columns specify the first and last address of the module's memory image.
The Timestamp column specifies the build date and time for the module.
The Checksum column specifies the checksum value.
The Symbols column displays information about the symbols that this module uses. For more information about the values that appear in this column, see Symbol
Status Abbreviations.
The Symbol file column specifies the path and file name of the associated symbol file. If the debugger is unaware of any symbol file, the name of the executable file is
given instead.

If you click the title bar of a column, the display is sorted by the data in that column. If you click the title bar again, the sort order reverses.
If you select a line and then click Reload, that module's symbol information is reloaded.
If you select a line and press CTRL+C, the whole line is copied to the clipboard.
Click Close to close this dialog box.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Kernel Connection | Cycle Baud Rate

Point to Kernel Connection and then click Cycle Baud Rate on the Debug menu to change the baud rate that is used in the kernel debugging connection.
This command is equivalent to pressing CTRL+ALT+A. (You can also press CTRL+A in KD.)
This command cycles through all available baud rates for the kernel debugging connection. Supported baud rates are 19200, 38400, 57600, and 115200. Every time that you
use this command, the next baud rate is selected. If the baud rate is already at 115200, it is reduced to 19200.
You cannot use this command to change the baud rate at which you are debugging. The baud rate of the host computer and the target computer must match, and you cannot
change the baud rate of the target computer without restarting the computer. Therefore, you must change the baud rate only if the two computers are trying to communicate at
different rates. In this case, you must change the host computer's baud rate to match that of the target computer.
To change the target computer's baud rate, see Configuring Software on the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Kernel Connection | Cycle Initial Break

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 770 of 1651

Point to Kernel Conection and then click Cycle Initial Break on the Debug menu to change the conditions on which the debugger automatically breaks into the target
computer.
This command is equivalent to pressing CTRL+ALT+K. (You can also press CTRL+K in KD.)
This command causes the kernel debugger to cycle through the following three states:
No break
The debugger does not break into the target computer unless you press CTRL+BREAK or Debug | Break.
Break on reboot
The debugger breaks into a restarted target computer after the kernel initializes. This command is equivalent to starting WinDbg with the -b command-line option.
Break on first module load
The debugger breaks into a restarted target computer after the first kernel module is loaded. (This action causes the break to occur earlier than in the Break on reboot
state.) This command is equivalent to starting WinDbg with the -d command-line option.
When you use the Cycle Initial Break command, the new break state is displayed.
Additional Information
For more information about related commands and an explanation of how the restart process affects the debugger, see Crashing and Rebooting the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug | Kernel Connection | Resynchronize

Point to Kernel Connection and then click Resynchronize on the Debug menu to cause the debugger to try to reestablish a kernel debugging connection with the target
computer.
This command is equivalent to pressing CTRL+ALT+R. (You can also press CTRL+R in KD.)
Use this command if the target is not responding.
Additional Information
For more information about reestablishing contact with the target, see Synchronizing with the Target Computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window Menu
This section describes the following commands on the Window menu of WinDbg:
Window | Close All Source Windows
Window | Close All Error Windows
Window | Open Dock
Window | Dock All
Window | Undock All
Window | Cascade Floating Windows
Window | Horizontally Tile Floating Windows
Window | Vertically Tile Floating Windows
Window | MDI Emulation
Window | Automatically Open Disassembly
List of Open Windows
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 771 of 1651

Debugging Tools for Windows

Window | Close All Source Windows

Click Close All Source Windows on the Window menu to close all Source windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window | Close All Error Windows

Click Close All Error Windows on the Window menu to close all error message boxes that have opened from source files that were not found.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window | Open Dock

Click Open Dock on the Window menu to create a new dock. A dock is an independent window that you can drag debugging information windows to. For more information
about docks, see Creating New Docks.
Additional Information
For more information about docked, tabbed, and floating windows, see Positioning the Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window | Dock All

Click Dock All on the Window menu to dock all of the floating windows, except for those with Always floating selected on their shortcut menus.
WinDbg automatically positions each floating window. If a window has never been docked before, WinDbg moves it to a new untabbed location. If a window has been
docked before, WinDbg moves it to its most recent docking location, which might be either tabbed or untabbed.
Additional Information
For more information about docked, tabbed, and floating windows, see Positioning the Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window | Undock All

Click Undock All on the Window menu to change all of the docked windows to floating windows.
WinDbg returns each docked window to the position that it occupied the last time that it was a floating window.
Additional Information
For more information about docked, tabbed, and floating windows, see Positioning the Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 772 of 1651

Debugging Tools for Windows

Window | MDI Emulation

Select MDI Emulation on the Window menu to cause WinDbg to emulate the Multiple Document Interface (MDI) style of windowing. This kind of windowing differs from
docking mode because all windows are floating, but floating windows are constrained within the frame window. This behavior emulates the behavior of WinDbg before
docking mode was introduced.
Clear MDI Emulation on the Window menu to return WinDbg to docking mode.
Additional Information
For more information about docked, tabbed, and floating windows, see Positioning the Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Window | Automatically Open Disassembly

Select Automatically Open Disassembly on the Window menu to cause the Disassembly window to open every time WinDbg begins a debugging session.
If you clear this command, you can still open the Disassembly window by clicking Disassembly on the View menu, pressing ALT+7, or clicking the Disassembly (Alt+F7)
button (

) on the toolbar.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

List of Open Windows

At the bottom of the Window menu, there is a list of all currently open debugging information windows. Click any window from this list to open the window.
For more information about how to use each window, see Debugging Information Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Help | Contents

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 773 of 1651

Click Contents on the Help menu to open the Contents tab in this Help documentation.
This command is equivalent to pressing F1.
Additional Information
For more information about how to use this Help file, see Using the Help File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Help | Index
Click Index on the Help menu to open the Index tab in this Help documentation.
Additional Information
For more information about how to use this Help file, see Using the Help File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Help | Search
Click Search on the Help menu to open the Search tab in this Help documentation.
Additional Information
For more information about how to use this Help file, see Using the Help File.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Help | About
Click About on the Help menu to open a message box that shows the version information for the WinDbg binaries that you are using.
Click OK to close this message box.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Toolbar Buttons
Except for the breakpoint button, each button on the toolbar is equivalent to a menu command. For a full description of each button's effects, see the page for the
corresponding menu command.
The buttons on the toolbar have the following effects.
Button

Description
Opens a source file as a read-only file. Equivalent to File | Open Source File.
Removes the selected text from the active window and puts it on the clipboard. Equivalent to Edit | Cut.
Copies the selected text from the active window to the clipboard. Equivalent to Edit | Copy.
Pastes the text on the clipboard to where the cursor is located. Equivalent to Edit | Paste.
Starts or resumes execution. Execution continues until a breakpoint is reached, an exception or event occurs, the process ends, or the debugger breaks into the target.
Equivalent to Debug | Go.
Restarts execution at the beginning of the process. Equivalent to Debug | Restart.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 774 of 1651

Stops execution and terminates the target process permanently. Equivalent to Debug | Stop Debugging.
In user mode, this button stops the process and its threads. In kernel mode, this button breaks into the target computer. Control is returned to the debugger. This
button is also useful for cutting off long Debugger Command window displays. Equivalent to Debug | Break.
Executes a single instruction. If the instruction is a function call, the debugger steps into the function. Equivalent to Debug | Step Into.
Executes a single instruction. If the instruction is a function call, the debugger executes the whole function in one step. Equivalent to Debug | Step Over.
Executes the rest of the current function, and breaks when the function return is completed. Equivalent to Debug | Step Out.
Executes all instructions from the current instruction up to the instruction marked in the active Disassembly window or Source window. Equivalent to Debug | Run
to Cursor.
If the active window is a Source or Disassembly window: Inserts a breakpoint at the current line. (If there already is a breakpoint set at the current line, this button
removes the breakpoint.)
Otherwise: Opens the Breakpoints dialog box like Edit | Breakpoints.
Opens or activates the Debugger Command window. Equivalent to View | Command.
Opens or activates the Watch window. Equivalent to View | Watch.
Opens or activates the Locals window. Equivalent to View | Locals.
Opens or activates the Registers window. Equivalent to View | Registers.
Opens a new Memory window. Equivalent to View | Memory.
Opens or activates the Calls window. Equivalent to View | Call Stack.
Opens or activates the Disassembly window. Equivalent to View | Disassembly.
Opens or activates the Scratch Pad. Equivalent to View | Scratch Pad.
Switches between source-mode and assembly-mode debugging. Equivalent to selecting or clearing Debug | Source Mode.
Enables you to change the font that is used in the debugging information windows. Equivalent to View | Font.
Displays the Options dialog box. Equivalent to View | Options.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Keyboard Shortcuts
You can use the following keyboard shortcuts to switch between windows. For more information about how to move between the windows, see Positioning the Windows.
Keys
Effect
CTRL+TAB Switches between debugging information windows. By using this key repeatedly, you can scan through all of the windows, regardless of whether they are
floating, docked by themselves, or part of a tabbed collection of docked windows.
ALT+TAB Switches between the windows that are currently on your desktop. You can also use this keyboard shortcut to switch between the WinDbg frame and any
additional docks you have created.
You can use the following keyboard shortcuts instead of the mouse to select menu commands. For more information about each command, see the individual command
topics.
Keys
Menu equivalent
F1
Help | Contents
F3
Edit | Find Next
SHIFT+F3
Same as Edit | Find Next, except the search is performed in the reverse direction.
ALT+F4
File | Exit
CTRL+F4
File | Close Current Window
F5
Debug | Go
SHIFT+F5
Debug | Stop Debugging
CTRL+SHIFT+F5 Debug | Restart
File | Attach to a Process
F6
F7
Debug | Run to Cursor
F8
Debug | Step Into
F9
If the active window is a Source or Disassembly window: Inserts a breakpoint at the current line. (If there already is a breakpoint set at the current line,
this button removes the breakpoint.)
Otherwise: Opens the Breakpoints dialog box like Edit | Breakpoints.
ALT+F9
F10
CTRL+F10
F11
SHIFT+F11
ALT+1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

ALT+SHIFT+1
ALT+2
ALT+SHIFT+2
ALT+3
ALT+SHIFT+3
ALT+4
ALT+SHIFT+4
ALT+5
ALT+SHIFT+5
ALT+6
ALT+SHIFT+6
ALT+7
ALT+SHIFT+7
ALT+8
ALT+SHIFT+8
ALT+9
ALT+SHIFT+9
CTRL+A
CTRL+C
CTRL+D
CTRL+E
CTRL+F
CTRL+G
CTRL+I
CTRL+SHIFT+I
CTRL+K
CTRL+L
CTRL+O
CTRL+P
CTRL+R
CTRL+S
CTRL+V
CTRL+SHIFT+V
CTRL+W
CTRL+X
CTRL+SHIFT+Y
ALT+*
(number keypad)
SHIFT+DELETE
SHIFT+INSERT
CTRL+INSERT
CTRL+BREAK

Page 775 of 1651

Closes the Command window.

The following shortcut keys are equivalent to KD / CDB control keys.

Keys
Menu equivalent
KD / CDB control key
CTRL+ALT+A Debug | Kernel Connection | Cycle Baud Rate CTRL+A
CTRL+ALT+D
CTRL+D (Toggle Debug Info)
CTRL+ALT+K Debug | Kernel Connection | Cycle Initial Break CTRL+K
CTRL+ALT+R Debug | Kernel Connection | Resynchronize
CTRL+R
CTRL+ALT+V View | Verbose Output
CTRL+V
CTRL+ALT+W View | Show Version
CTRL+W
You can use the following keyboard shortcuts to move the caret (^) in most of the debugging information windows.
Caret movement
Key
One character left
LEFT
One character right
RIGHT
Word left
CTRL+LEFT
Word right
CTRL+RIGHT
Line up
UP
Line down
DOWN
Page up
PAGE UP
Page down
PAGE DOWN
Beginning of the current line HOME
End of the line
END
Beginning of the file
CTRL+HOME
End of the file
CTRL+END
Note In the Debugger Command window, the UP and DOWN keys browse through the command history. You can use the INSERT key to turn insert mode on and off.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 776 of 1651

Use the following keyboard shortcuts to select text.

Select
Keys
Character to the left
SHIFT+LEFT
Character to the right
SHIFT+RIGHT
Word to the left
SHIFT+CTRL+LEFT
Word to the right
SHIFT+CTRL+RIGHT
Current line
SHIFT+DOWN if the caret is in column 1
Line above
SHIFT+UP if the caret is in column 1
To the end of the line
SHIFT+END
To the beginning of the line SHIFT+HOME
Screen up
SHIFT+PAGE UP
Screen down
SHIFT+PAGE DOWN
To beginning of file
SHIFT+CTRL+HOME
To end of file
SHIFT+CTRL+END
Use the following keyboard shortcuts to delete text.
Delete
Key
Character to the right of caret DELETE
Character to the left of caret BACKSPACE
Selected text
DELETE

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Techniques
This section includes:
Elementary Debugging Techniques
Messages from the Target
Bug Checks (Blue Screens)
Processor Architecture
RPC Debugging
ACPI Debugging
NDIS Debugging
Kernel Streaming Debugging
SCSI Miniport Debugging
Kernel-Mode Driver Framework Debugging
User-Mode Driver Framework Debugging
Plug and Play Debugging
Advanced Debugging Techniques
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Elementary Debugging Techniques

This section includes:
Using the !analyze Extension
Setting a Conditional Breakpoint

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 777 of 1651

Executing Until a Specified State is Reached

Converting Virtual Addresses to Physical Addresses
Tracking Down a Processor Hog
Extracting Information from a Dump File
Determining the ACL of an Object
Displaying a Critical Section
Debugging an Application Failure
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the !analyze Extension

The first step in debugging a crashed target computer or application is to use the !analyze extension command.
This extension performs a tremendous amount of automated analysis. The results of this analysis are displayed in the Debugger Command window.
You should use the -v option for a fully verbose display of data. For details on other options, see the !analyze reference page.
This topic contains:
A User-Mode !analyze -v Example
A Kernel-Mode !analyze -v Example
The Followup Field and the triage.ini File
Additional !analyze Techniques

A User-Mode !analyze -v Example

In this example, the debugger is attached to a user-mode application that has encountered an exception.
0:000> !analyze -v
*******************************************************************************
*
*
*
Exception Analysis
*
*
*
*******************************************************************************
Debugger SolutionDb Connection::Open failed 80004005
If you are connected to the internet, the debugger attempts to access a database of crash solutions maintained by Microsoft. In this case, an error message was displayed,
indicating that either your machine was unable to access the internet or the web site was not working.
FAULTING_IP:
ntdll!PropertyLengthAsVariant+73
77f97704 cc
int

The FAULTING_IP field shows the instruction pointer at the time of the fault.
EXCEPTION_RECORD: ffffffff -- (.exr ffffffffffffffff)
ExceptionAddress: 77f97704 (ntdll!PropertyLengthAsVariant+0x00000073)
ExceptionCode: 80000003 (Break instruction exception)
ExceptionFlags: 00000000
NumberParameters: 3
Parameter[0]: 00000000
Parameter[1]: 00010101
Parameter[2]: ffffffff
The EXCEPTION_RECORD field shows the exception record for this crash. This information can also be viewed by using the .exr (Display Exception Record) command.
BUGCHECK_STR:

80000003

The BUGCHECK_STR field shows the exception code. The name is a misnomer the term bug check actually signifies a kernel-mode crash. In user-mode debugging, the
exception code will be displayed in this case, 0x80000003.
DEFAULT_BUCKET_ID:

APPLICATION_FAULT

The DEFAULT_BUCKET_ID field shows the general category of failures that this failure belongs to.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

PROCESS_NAME:

Page 778 of 1651

MyApp.exe

The PROCESS_NAME field specifies the name of the process that raised the exception.
LAST_CONTROL_TRANSFER:

from 01050963 to 77f97704

The LAST_CONTROL_TRANSFER field shows the last call on the stack. In this case, the code at address 0x01050963 called a function at 0x77F97704. You can use these
addresses with the ln (List Nearest Symbols) command to determine what modules and functions these addresses reside in.
STACK_TEXT:
0006b9dc 01050963
0006b9f0 010509af
0006da04 01029f4e
0006db6c 010590c3
0006fe04 77e11d0a
0006fe24 77e11bc8
0006feb0 77e172b4
0006febc 010518bf
0006fec8 01057c5d
0006ff70 01062cbf
0006ffc0 77e9ca90
0006fff0 00000000

00000000
00000002
01069850
000e01ea
000e01ea
01057da1
0006fee4
0006fee4
0006fee4
00000001
77f82b95
01062bc0

0006ba04
0006ba04
0000034f
0006fee4
00000111
000e01ea
00000001
00000000
77f82b95
00683ed8
77f83920
00000000

000603fd
77e1a449
01069828
0006feec
0000413c
00000111
010518bf
01057c5d
77f83920
00682b88
7ffdf000
000000c8

ntdll!PropertyLengthAsVariant+0x73
MyApp!FatalErrorBox+0x55 [D:\source_files\MyApp\util.c @ 541]
MyApp!ShowAssert+0x47 [D:\source_files\MyApp\util.c @ 579]
MyApp!SelectColor+0x103 [D:\source_files\MyApp\colors.c @ 849]
MyApp!MainWndProc+0x1322 [D:\source_files\MyApp\MyApp.c @ 1031]
USER32!UserCallWinProc+0x18
USER32!DispatchMessageWorker+0x2d0
USER32!DispatchMessageA+0xb
MyApp!ProcessQCQPMessage+0x3b [D:\source_files\MyApp\util.c @ 2212]
MyApp!main+0x1e6 [D:\source_files\MyApp\MyApp.c @ 263]
MyApp!mainCRTStartup+0xff [D:\source_files\MyApp\crtexe.c @ 338]
KERNEL32!BaseProcessStart+0x3d

The STACK_TEXT field shows a stack trace of the faulting component.

FOLLOWUP_IP:
MyApp!FatalErrorBox+55
01050963 5e
FOLLOWUP_NAME:

pop

esi

dbg

SYMBOL_NAME:

MyApp!FatalErrorBox+55

MODULE_NAME:

MyApp

IMAGE_NAME:

MyApp.exe

DEBUG_FLR_IMAGE_TIMESTAMP:

383490a9

When !analyze determines the instruction that has probably caused the error, it displays it in the FOLLOWUP_IP field. The SYMBOL_NAME, MODULE_NAME,
IMAGE_NAME, and DBG_FLR_IMAGE_TIMESTAMP fields show the symbol, module, image name, and image timestamp corresponding to this instruction.
STACK_COMMAND:

.ecxr ; kb

The STACK_COMMAND field shows the command that was used to obtain the STACK_TEXT. You can use this command to repeat this stack trace display, or alter it to
obtain related stack information.
BUCKET_ID:

80000003_MyApp!FatalErrorBox+55

The BUCKET_ID field shows the specific category of failures that the current failure belongs to. This category helps the debugger determine what other information to
display in the analysis output.
Followup: dbg
--------For information about the FOLLOWUP_NAME and the Followup fields, see The Followup Field and the triage.ini File.
There are a variety of other fields that may appear:

If control was transferred to an invalid address, then the FAULTING_IP field will contain this invalid address. Instead of the FOLLOWUP_IP field, the
FAILED_INSTRUCTION_ADDRESS field will show the disassembled code from this address, although this disassembly will probably be meaningless. In this
situation, the SYMBOL_NAME, MODULE_NAME, IMAGE_NAME, and DBG_FLR_IMAGE_TIMESTAMP fields will refer to the caller of this instruction.
If the processor misfires, you may see the SINGLE_BIT_ERROR, TWO_BIT_ERROR, or POSSIBLE_INVALID_CONTROL_TRANSFER fields.
If memory corruption seems to have occurred, the CHKIMG_EXTENSION field will specify the !chkimg extension command that should be used to investigate.

A Kernel-Mode !analyze -v Example

In this example, the debugger is attached to a computer that has just crashed.
kd> !analyze -v
*******************************************************************************
*
*
*
Bugcheck Analysis
*
*
*
*******************************************************************************
DRIVER_IRQL_NOT_LESS_OR_EQUAL (d1)
An attempt was made to access a pagable (or completely invalid) address at an
interrupt request level (IRQL) that is too high. This is usually
caused by drivers using improper addresses.
If kernel debugger is available get stack backtrace.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 779 of 1651

The first element of the display shows the bug check code and information about this type of bug check. Some of the text displayed may not apply to this specific instance.
For more details on each bug check, see the Bug Check Code Reference section.
Arguments:
Arg1: 00000004,
Arg2: 00000002,
Arg3: 00000001,
Arg4: f832035c,

memory referenced
IRQL
value 0 = read operation, 1 = write operation
address which referenced memory

The bug check parameters are displayed next. They are each followed by a description. For example, the third parameter is 1, and the comment following it explains that this
indicates that a write operation failed.
Debugging Details:
-----------------WRITE_ADDRESS:
CURRENT_IRQL:

00000004 Nonpaged pool

The next few fields vary depending on the nature of the crash. In this case, we see WRITE_ADDRESS and CURRENT_IRQL fields. These are simply restating the
information shown in the bug check parameters. By comparing the statement "Nonpaged pool" to the bug check text that reads "an attempt was made to access a pagable (or
completely invalid) address," we can see that the address was invalid. The invalid address in this case was 0x00000004.
FAULTING_IP:
USBPORT!USBPORT_BadRequestFlush+7c
f832035c 894204
mov
[edx+0x4],eax
The FAULTING_IP field shows the instruction pointer at the time of the fault.
DEFAULT_BUCKET_ID:

DRIVER_FAULT

The DEFAULT_BUCKET_ID field shows the general category of failures that this failure belongs to.
BUGCHECK_STR:

0xD1

The BUGCHECK_STR field shows the bug check code, which we have already seen. In some cases additional triage information is appended.
TRAP_FRAME: f8950dfc -- (.trap fffffffff8950dfc)
.trap fffffffff8950dfc
ErrCode = 00000002
eax=81cc86dc ebx=81cc80e0 ecx=81e55688 edx=00000000 esi=81cc8028 edi=8052cf3c
eip=f832035c esp=f8950e70 ebp=f8950e90 iopl=0
nv up ei pl nz ac po nc
cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000
efl=00010216
USBPORT!USBPORT_BadRequestFlush+7c:
f832035c 894204
mov
[edx+0x4],eax
ds:0023:00000004=????????
.trap
Resetting default context
The TRAP_FRAME field shows the trap frame for this crash. This information can also be viewed by using the .trap (Display Trap Frame) command.
LAST_CONTROL_TRANSFER:

from f83206e0 to f832035c

The LAST_CONTROL_TRANSFER field shows the last call on the stack. In this case, the code at address 0xF83206E0 called a function at 0xF832035C. You can use the
ln (List Nearest Symbols) command to determine what module and function these addresses reside in.
STACK_TEXT:
f8950e90 f83206e0
f8950eb0 804f5561
f8950fb4 804f5644
f8950fe0 8052c47c
f8950ff4 8052c16a

024c7262
81cc8644
6e4be98e
8053cf20
efdefd44

00000000
81cc8028
00000000
00000000
00000000

f8950edc
6d9a2f30
ffdff000
00002e42
00000000

USBPORT!USBPORT_BadRequestFlush+0x7c
USBPORT!USBPORT_DM_TimerDpc+0x10c
nt!KiTimerListExpire+0xf3
nt!KiTimerExpiration+0xb0
nt!KiRetireDpcList+0x31

The STACK_TEXT field shows a stack trace of the faulting component.

FOLLOWUP_IP:
USBPORT!USBPORT_BadRequestFlush+7c
f832035c 894204
mov
[edx+0x4],eax
The FOLLOWUP_IP field shows the disassembly of the instruction that has probably caused the error.
FOLLOWUP_NAME:

usbtri

SYMBOL_NAME:

USBPORT!USBPORT_BadRequestFlush+7c

MODULE_NAME:

USBPORT

IMAGE_NAME:

USBPORT.SYS

DEBUG_FLR_IMAGE_TIMESTAMP:

3b7d868b

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Page 782 of 1651

For more information about which numbers are sign-extended by the debugger, see Sign Extension.
Conditional Breakpoints in WinDbg
In WinDbg, you can create a conditional breakpoint by clicking Breakpoints from the Edit menu, entering a new breakpoint address into the Command box, and entering a
condition into the Condition box.
For example, typing mymod!myFunc+0x3A into the Command box and myVar < 7 into the Condition box is equivalent to issuing the following command:
0:000> bu mymod!myFunc+0x3A "j(myVar<7) '.echo "Breakpoint hit, condition myVar<7"'; 'gc'"
0:000> bu mymod!myFunc+0x3A ".if(myVar<7) {.echo "Breakpoint hit, condition myVar<7"} .else {gc}"
Restrictions on Conditional Breakpoints
If you are controlling the user-mode debugger from the kernel debugger, you cannot use conditional breakpoints or any other breakpoint command string that contains the
gc (Go from Conditional Breakpoint) or g (Go) commands. If you use these commands, the serial interface might not be able to keep up with the number of breakpoint
passes, and you will be unable to break back into CDB.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Executing Until a Specified State is Reached

There are several ways to cause the target to execute until a specified state is reached.
Using a Breakpoint to Control Execution
One method is to use a breakpoint. The simplest breakpoint halts execution when the program counter reaches a specified address. A more complex breakpoint can:

be triggered only when this address is executed by a specific thread,

allow a specified number of passes through this address before being triggered,
automatically issue a specified command when it is triggered, or
watch a specified address in non-executable memory, being triggered when that memory is read or written to.

For details on how to set and control breakpoints, see Using Breakpoints.
A more complicated way to execute until a specified state is reached is to use a conditional breakpoint. This kind of breakpoint is set at a certain address, but is only triggered
if a specified condition holds. For details, see Setting a Conditional Breakpoint.
Breakpoints and Pseudo-Registers
In specifying the desired state, it is often helpful to use automatic pseudo-registers. These are variables controlled by the debugger which allow you to reference a variety of
values related to the target state.
For example, the following breakpoint uses the $thread pseudo-register, which is always equal to the value of the current thread. It resolves to the value of the current thread
when it is used in a command. By using $thread as the argument of the /t parameter of the bp (Set Breakpoint) command, you can create a breakpoint that will be triggered
every time that NtOpenFile is called by the thread which was active at the time you issued the bp command:
kd> bp /t @$thread nt!ntopenfile
This breakpoint will not be triggered when any other thread calls NtOpenFile.
For a list of automatic psuedo-registers, see Pseudo-Register Syntax.
Using a Script File to Control Execution
Another way to execute until a specified state is reached is to create a script file that calls itself recursively, testing the desired state in each iteration.
Typically, this script file will contain the .if and .else tokens. You can use a command such as t (Trace) to execute a single step, and then test the condition in question.
For example, if you wish to execute until the eax register contains the value 0x1234, you can create a script file called eaxstep.txt that contains the following line:
.if (@eax == 1234) { .echo Value of eax is 1234. } .else { t ; $<eaxstep.txt }
Then issue the following command from the Debugger Command window:
t "$<eaxstep.txt"
This t command will execute a single step, and then execute the quoted command. This command happens to be $< (Run Script File), which runs the eaxstep.txt file. The
script file tests the value of eax, runs the t command, and then calls itself recursively. This continues until the eax register equals 0x1234, at which point the .echo (Echo
Comment) command prints a message to the Debugger Command window, and execution stops.
For details on script files, see Using Script Files and Using Debugger Command Programs.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 783 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Converting Virtual Addresses to Physical Addresses

Most debugger commands use virtual addresses, not physical addresses, as their input and output. However, there are times that having the physical address can be useful.
There are two ways to convert a virtual address to a physical address: by using the !vtop extension, and by using the !pte extension.
Address Conversion Using !vtop
Suppose you are debugging a target computer on which the MyApp.exe process is running and you want to investigate the virtual address 0x0012F980. Here is the procedure
you would use with the !vtop extension to determine the corresponding physical address.
Converting a virtual address to a physical address using !vtop
1. Make sure that you are working in hexadecimal. If necessary, set the current base with the N 16 command.
2. Determine the byte index of the address. This number is equal to the lowest 12 bits of the virtual address. Thus, the virtual address 0x0012F980 has a byte index of
0x980.
3. Determine the directory base of the address by using the !process extension:
kd> !process 0 0
**** NT ACTIVE PROCESS DUMP ****
....
PROCESS ff779190 SessionId: 0 Cid: 04fc
Peb: 7ffdf000 ParentCid: 0394
DirBase: 098fd000 ObjectTable: e1646b30 TableSize:
8.
Image: MyApp.exe
4. Determine the page frame number of the directory base. This is simply the directory base without the three trailing hexadecimal zeros. In this example, the directory
base is 0x098FD000, so the page frame number is 0x098FD.
5. Use the !vtop extension. The first parameter of this extension should be the page frame number. The second parameter of !vtop should be the virtual address in
question:
kd> !vtop 98fd 12f980
Pdi 0 Pti 12f
0012f980 09de9000 pfn(09de9)
The second number shown on the final line is the physical address of the beginning of the physical page.
6. Add the byte index to the address of the beginning of the page: 0x09DE9000 + 0x980 = 0x09DE9980. This is the desired physical address.
You can verify that this computation was done correctly by displaying the memory at each address. The !d* extension displays memory at a specified physical address:
kd> !dc 9de9980
# 9de9980 6d206e49 726f6d65 00120079 0012f9f4 In memory.......
# 9de9990 0012f9f8 77e57119 77e8e618 ffffffff .....q.w...w....
# 9de99a0 77e727e0 77f6f13e 77f747e0 ffffffff .'.w>..w.G.w....
# 9de99b0 .....
The d* (Display Memory) command uses a virtual address as its argument:
kd> dc 12f980
0012f980 6d206e49 726f6d65 00120079 0012f9f4
0012f990 0012f9f8 77e57119 77e8e618 ffffffff
0012f9a0 77e727e0 77f6f13e 77f747e0 ffffffff
0012f9b0 .....

In memory.......
.....q.w...w....
.'.w>..w.G.w....

Because the results are the same, this indicates that the physical address 0x09DE9980 does indeed correspond to the virtual address 0x0012F980.
Address Conversion Using !pte
Again, assume you are investigating the virtual address 0x0012F980 belonging to the MyApp.exe process. Here is the procedure you would use with the !pte extension to
determine the corresponding physical address:
Converting a virtual address to a physical address using !pte
1. Make sure that you are working in hexadecimal. If necessary, set the current base with the N 16 command.
2. Determine the byte index of the address. This number is equal to the lowest 12 bits of the virtual address. Thus, the virtual address 0x0012F980 has a byte index of
0x980.
3. Set the process context to the desired process:
kd> !process 0 0
**** NT ACTIVE PROCESS DUMP ****
....
PROCESS ff779190 SessionId: 0 Cid: 04fc
Peb: 7ffdf000 ParentCid: 0394
DirBase: 098fd000 ObjectTable: e1646b30 TableSize:
8.
Image: MyApp.exe

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 784 of 1651

kd> .process /p ff779190

Implicit process is now ff779190
.cache forcedecodeuser done
4. Use the !pte extension with the virtual address as its argument. This displays information in two columns. The left column describes the page directory entry (PDE) for
this address; the right column describes its page table entry (PTE):
kd> !pte 12f980
VA 0012f980
PDE at
C0300000
PTE at C00004BC
contains 0BA58067
contains 09DE9067
pfn ba58 ---DA--UWV
pfn 9de9 ---DA--UWV
5. Look in the last row of the right column. The notation "pfn 9de9" appears. The number 0x9DE9 is the page frame number (PFN) of this PTE. Multiply the page frame
number by 0x1000 (for example, shift it left 12 bits). The result, 0x09DE9000, is the physical address of the beginning of the page.
6. Add the byte index to the address of the beginning of the page: 0x09DE9000 + 0x980 = 0x09DE9980. This is the desired physical address.
This is the same result obtained by the earlier method.
Converting Addresses By Hand
Although the !ptov and pte extensions supply the fastest way to convert virtual addresses to physical addresses, this conversion can be done manually as well. A description
of this process will shed light on some of the details of the virtual memory architecture.
Memory structures vary in size, depending on the processor and the hardware configuration. This example is taken from an x86 system that does not have Physical Address
Extension (PAE) enabled.
Using 0x0012F980 again as the virtual address, you first need to convert it to binary, either by hand or by using the .formats (Show Number Formats) command:
kd> .formats 12f980
Evaluate expression:
Hex:
0012f980
Decimal: 1243520
Octal:
00004574600
Binary: 00000000 00010010 11111001 10000000
Chars:
....
Time:
Thu Jan 15 01:25:20 1970
Float:
low 1.74254e-039 high 0
Double: 6.14381e-318
This virtual address is a combination of three fields. Bits 0 to 11 are the byte index. Bits 12 to 21 are the page table index. Bits 22 to 31 are the page directory index.
Separating the fields, you have:
0x0012F980

00000000 00

010010 1111

1001 10000000

This exposes the three parts of the virtual address:

Page directory index = 0y0000000000 = 0x0

Page table index = 0y0100101111 = 0x12F
Byte index = 0y100110000000 = 0x980

You then need three additional pieces of information for your system.

The size of each PTE. This is 4 bytes on non-PAE x86 systems.

The size of a page. This is 0x1000 bytes.
The PTE_BASE virtual address. On a non-PAE system, this is 0xC0000000.

Using this data, you can compute the address of the PTE itself:
PTE address

PTE_BASE
+ (page directory index) * PAGE_SIZE
+ (page table index) * sizeof(MMPTE)
=
0xc0000000
+ 0x0
* 0x1000
+ 0x12F * 4
=
0xC00004BC

This is the address of the PTE. The PTE is a 32-bit DWORD. Examine its contents:
kd> dd 0xc00004bc L1
c00004bc 09de9067
This PTE has value 0x09DE9067. It is made of two fields:

The low 12 bits of the PTE are the status flags. In this case, these flags equal 0x067 or in binary, 0y000001100111. For an explanation of the status flags, see the !
pte reference page.
The high 20 bits of the PTE are equal to the page frame number (PFN) of the PTE. In this case, the PFN is 0x09DE9.

The first physical address on the physical page is the PFN multiplied by 0x1000 (shifted left 12 bits). The byte index is the offset on this page. Thus,the physical address you
are looking for is 0x09DE9000 + 0x980 = 0x09DE9980. This is the same result obtained by the earlier methods.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 785 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Tracking Down a Processor Hog

If one application is consuming ("hogging") all the processor's attention, other processes will end up "starving" and unable to run.
Use the following procedure to correct a bug of this sort.
Debugging an application that is using all the CPU cycles
1. Identify which application is causing this problem: Use Task Manager or Perfmon to find which process is using 99% or 100% of the processor's cycles. This may tell
you the offending thread as well.
2. Attach WinDbg, KD, or CDB to this process.
3. Identify which thread is causing the problem: Break into the offending application. Use the !runaway 3 extension to take a "snapshot" of where all the CPU time is
going. Use g (Go) and wait a few seconds. Then break in and use !runaway 3 again.
0:002> !runaway 3
User Mode Time
Thread
Time
4e0
0:12:16.0312
268
0:00:00.0000
22c
0:00:00.0000
Kernel Mode Time
Thread
Time
4e0
0:00:05.0312
268
0:00:00.0000
22c
0:00:00.0000
0:002> g
0:001> !runaway 3
User Mode Time
Thread
Time
4e0
0:12:37.0609
3d4
0:00:00.0000
22c
0:00:00.0000
Kernel Mode Time
Thread
Time
4e0
0:00:07.0421
3d4
0:00:00.0000
22c
0:00:00.0000
Compare the two sets of numbers and look for the thread whose user-mode time or kernel-mode time has increased the most. Because !runaway sorts by descending
CPU time, the offending thread is usually the one at the top of the list. In this case, thread 0x4E0 is causing the problem.
4. Use the ~ (Thread Status) and ~s (Set Current Thread) commands to make this the current thread:
0:001> ~
0 Id: 3f4.3d4 Suspend: 1 Teb: 7ffde000 Unfrozen
. 1 Id: 3f4.22c Suspend: 1 Teb: 7ffdd000 Unfrozen
2 Id: 3f4.4e0 Suspend: 1 Teb: 7ffdc000 Unfrozen
0:001> ~2s
5. Use kb (Display Stack Backtrace) to obtain a stack trace of this thread:
0:002> kb
FramePtr
0b4ffc74
0b4ffce4
0b4ffd20
0b4ffe20
0b4ffe5c
0b4ffeb0
0b4ffed0
0b4fff40
0b4fff60
0b4fff90

RetAddr
77f6c600
01836060
01843eba
01855924
77e112e6
77e11215
77e1a3b1
77e181e4
77e1a5df
77e1ac1c

Param1
Param2
000000c8.00000000
0184f440 00000001
02b5b920 00000102
0b4ffef0 00145970
01843e16 0b4ffef0
0b4ffef0 00000000
0b4ffef0 00000000
02b1e0b0 00000074
02b1e0b0 00000074
77e15eaf 00149210

Param3
77fa5ad0
0b4ffe20
02b1e0e0
0b4ffef0
0b4fff34
0b4fff34
0b4fff34
0b4fff90
00149210
0b4fffec

Function Name
BuggyProgram!CreateMsgFile+0x1b
BuggyProgram!OpenDestFileStream+0xb3
BuggyProgram!SaveMsgToDestFolder+0xb3
BuggyProgram!DispatchToConn+0xa4
RPCRT4!DispatchToStubInC+0x34
RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0
RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41
RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b
RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91
RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76

6. Set a breakpoint on the return address of the currently-running function. In this case, the return address is shown on the first line as 0x77F6C600. The return address is
equivalent to the function offset shown on the second line (BuggyProgram!OpenDestFileStream+0xB3). If no symbols are available for the application, the function
name may not appear. Use the g (Go) command to execute until this return address is reached, using either the symbolic or hexadecimal address:
0:002> g BuggyProgram!OpenDestFileStream+0xb3
7. If this breakpoint is hit, repeat the process. For example, suppose this breakpoint is hit. The following steps should be taken:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0:002> kb
FramePtr
0b4ffce4
0b4ffd20
0b4ffe20
0b4ffe5c
0b4ffeb0
0b4ffed0
0b4fff40
0b4fff60
0b4fff90

Page 786 of 1651

RetAddr
01836060
01843eba
01855924
77e112e6
77e11215
77e1a3b1
77e181e4
77e1a5df
77e1ac1c

Param1
0184f440
02b5b920
0b4ffef0
01843e16
0b4ffef0
0b4ffef0
02b1e0b0
02b1e0b0
77e15eaf

Param2
00000001
00000102
00145970
0b4ffef0
00000000
00000000
00000074
00000074
00149210

Param3
0b4ffe20
02b1e0e0
0b4ffef0
0b4fff34
0b4fff34
0b4fff34
0b4fff90
00149210
0b4fffec

Function Name
BuggyProgram!OpenDestFileStream+0xb3
BuggyProgram!SaveMsgToDestFolder+0xb3
BuggyProgram!DispatchToConn+0xa4
RPCRT4!DispatchToStubInC+0x34
RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0
RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41
RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b
RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91
RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76

0:002> g BuggyProgram!SaveMsgToDestFolder+0xb3
If this is hit, continue with:
0:002> kb
FramePtr
0b4ffd20
0b4ffe20
0b4ffe5c
0b4ffeb0
0b4ffed0
0b4fff40
0b4fff60
0b4fff90

RetAddr
01843eba
01855924
77e112e6
77e11215
77e1a3b1
77e181e4
77e1a5df
77e1ac1c

Param1
02b5b920
0b4ffef0
01843e16
0b4ffef0
0b4ffef0
02b1e0b0
02b1e0b0
77e15eaf

Param2
00000102
00145970
0b4ffef0
00000000
00000000
00000074
00000074
00149210

Param3
02b1e0e0
0b4ffef0
0b4fff34
0b4fff34
0b4fff34
0b4fff90
00149210
0b4fffec

Function Name
BuggyProgram!SaveMsgToDestFolder+0xb3
BuggyProgram!DispatchToConn+0xa4
RPCRT4!DispatchToStubInC+0x34
RPCRT4!?DispatchToStubWorker@RPC_INTERFACE@@AAEJPAU_RPC_MESSAGE@@IPAJ@Z+0xb0
RPCRT4!?DispatchToStub@RPC_INTERFACE@@QAEJPAU_RPC_MESSAGE@Z+0x41
RPCRT4!?ReceiveOriginalCall@OSF_SCONNECTION@Z+0x14b
RPCRT4!?DispatchPacket@OSF_SCONNECTION@+0x91
RPCRT4!?ReceiveLotsaCalls@OSF_ADDRESS@@QAEXXZ+0x76

0:002> g BuggyProgram!DispatchToConn+0xa4
8. Finally you will find a breakpoint that is not hit. In this case, you should assume that the last g command set the target running and it did not break. This means that the
SaveMsgToDestFolder() function will never return.
9. Break into the thread again and set a breakpoint on BuggyProgram!SaveMsgToDestFolder+0xB3 with the bp (Set Breakpoint) command. Then use the g command
repeatedly. If this breakpoint hits immediately, regardless of how many times you have executed the target, it is very likely that you have identified the offending
function:
0:002> bp BuggyProgram!SaveMsgToDestFolder+0xb3
0:002> g
0:002> g
10. Use the p (Step) command to proceed through the function until you identify the place where the looping sequence of instructions are. You can then analyze the
application's source code to identify the cause of the spinning thread. The cause will usually turn out to be a problem in the logic of a while, do-while, goto, or for loop.
See Also
Process Hangs or Consumes 100 Percent of CPU
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Extracting Information from a Dump File

Certain kinds of information, such as the name of the target computer, are easily available during live debugging. When debugging a dump file it takes a little more work to
determine this information.
Finding the Computer Name in a Kernel-Mode Dump File
If you need to determine the name of the computer on which the crash dump was made, you can use the !peb extension and look for the value of COMPUTERNAME it its
output.
Or you can use the following command:
0: kd> x srv!SrvComputerName
be8ce2e8 srv!SrvComputerName

= _UNICODE_STRING "AIGM-MYCOMP-PUB01"

Finding the IP Address in a Kernel-Mode Dump File

To determine the IP address of the computer on which the crash dump was made, find a thread stack that shows some send/receive network activity. Open one of the send
packets or receive packets. The IP address will be visible in that packet.
Finding the Process ID in a User-Mode Dump File
To determine the process ID of the target application from a user-mode dump file, use the | (Process Status) command. This will display all the processes being debugged at
the time the dump was written. The process marked with a period (.) is the current process. Its process ID is given in hexadecimal after the id: notation.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 787 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Determining the ACL of an Object

You can use the debugger to examine the access control list (ACL) of an object.
The following method can be used if you are performing kernel debugging. To use it while you are performing user-mode debugging, you need to redirect control to a kernel
debugger. See Controlling the User-Mode Debugger from the Kernel Debugger for details.
First, use the !object debugger extension with the name of the object in question:
kd> !object \BaseNamedObjects\AgentToWkssvcEvent
Object: ffbb8a98 Type: (80e30e70) Event
ObjectHeader: ffbb8a80
HandleCount: 2 PointerCount: 3
Directory Object: e14824a0 Name: AgentToWkssvcEvent
This shows that the object header has address 0xFFBB8A80. Use the dt (Display Type) command with this address and the nt!_OBJECT_HEADER structure name:
kd> dt nt!_OBJECT_HEADER ffbb8a80
+0x000 PointerCount
: 3
+0x004 HandleCount
: 2
+0x004 NextToFree
: 0x00000002
+0x008 Type
: 0x80e30e70
+0x00c NameInfoOffset
: 0x10 ''
+0x00d HandleInfoOffset : 0 ''
+0x00e QuotaInfoOffset : 0 ''
+0x00f Flags
: 0x20 ' '
+0x010 ObjectCreateInfo : 0x8016b460
+0x010 QuotaBlockCharged : 0x8016b460
+0x014 SecurityDescriptor : 0xe11f08b6
+0x018 Body
: _QUAD
The security descriptor pointer value is shown as 0xE11F08B6. The lowest 3 bits of this value represent an offset past the beginning of this structure, so you should ignore
them. In other words, the SECURITY_DESCRIPTOR structure actually begins at 0xE11F08B6 & ~0x7. Use the !sd extension on this address:
kd> !sd e11f08b0
->Revision: 0x1
->Sbz1
: 0x0
->Control : 0x8004
SE_DACL_PRESENT
SE_SELF_RELATIVE
->Owner
: S-1-5-32-544
->Group
: S-1-5-18
->Dacl
:
->Dacl
: ->AclRevision: 0x2
->Dacl
: ->Sbz1
: 0x0
->Dacl
: ->AclSize
: 0x44
->Dacl
: ->AceCount
: 0x2
->Dacl
: ->Sbz2
: 0x0
->Dacl
: ->Ace[0]: ->AceType: ACCESS_ALLOWED_ACE_TYPE
->Dacl
: ->Ace[0]: ->AceFlags: 0x0
->Dacl
: ->Ace[0]: ->AceSize: 0x14
->Dacl
: ->Ace[0]: ->Mask : 0x001f0003
->Dacl
: ->Ace[0]: ->SID: S-1-5-18
->Dacl
->Dacl
->Dacl
->Dacl
->Dacl

:
:
:
:
:

->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:
->Ace[1]:

->Sacl

is NULL

->AceType: ACCESS_ALLOWED_ACE_TYPE
->AceFlags: 0x0
->AceSize: 0x18
->Mask : 0x00120001
->SID: S-1-5-32-544

This displays the security information for this object.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 788 of 1651

Displaying a Critical Section

Critical sections can be displayed in user mode by a variety of different methods. The exact meaning of each field depends on the version of Microsoft Windows version you
are using.
Displaying Critical Sections
Critical sections can be displayed by the !ntsdexts.locks extension, the !critsec extension, the !cs extension, and the dt (Display Type) command.
The !ntsdexts.locks extension displays a list of critical sections associated with the current process. If the -v option is used, all critical sections are displayed. Here is an
example:
0:000> !locks
CritSec ntdll!FastPebLock+0 at 77FC49E0
LockCount
0
RecursionCount
1
OwningThread
c78
EntryCount
0
ContentionCount
0
*** Locked
....
Scanned 37 critical sections
If you know the address of the critical section you wish to display, you can use the !critsec extension. This displays the same collection of information as !ntsdexts.locks. For
example:
0:000> !critsec 77fc49e0
CritSec ntdll!FastPebLock+0 at 77FC49E0
LockCount
0
RecursionCount
1
OwningThread
c78
EntryCount
0
ContentionCount
0
*** Locked
The !cs extension is only available in Microsoft Windows XP and later versions of Windows. It can display a critical section based on its address, search an address range for
critical sections, and even display the stack trace associated with each critical section. Some of these features require full Windows symbols to work properly. If Application
Verifier is active, !cs -t can be used to display the critical section tree. See the !cs reference page for details and examples.
The information displayed by !cs is slightly different than that shown by !ntsdexts.locks and !critsec. For example:
0:000> !cs 77fc49e0
----------------------------------------Critical section
= 0x77fc49e0 (ntdll!FastPebLock+0x0)
DebugInfo
= 0x77fc3e00
LOCKED
LockCount
= 0x0
OwningThread
= 0x00000c78
RecursionCount
= 0x1
LockSemaphore
= 0x0
SpinCount
= 0x00000000
The dt (Display Type) command can be used to display the literal contents of the RTL_CRITICAL_SECTION structure. For example:
0:000> dt
+0x000
+0x004
+0x008
+0x00c
+0x010
+0x014

RTL_CRITICAL_SECTION 77fc49e0
DebugInfo
: 0x77fc3e00
LockCount
: 0
RecursionCount
: 1
OwningThread
: 0x00000c78
LockSemaphore
: (null)
SpinCount
: 0

Interpreting Critical Section Fields in Windows XP and Windows 2000

The most important fields of the critical section structure are as follows:

In Microsoft Windows 2000, and Windows XP, the LockCount field indicates the number of times that any thread has called the EnterCriticalSection routine for this
critical section, minus one. This field starts at -1 for an unlocked critical section. Each call of EnterCriticalSection increments this value; each call of
LeaveCriticalSection decrements it. For example, if LockCount is 5, this critical section is locked, one thread has acquired it, and five additional threads are waiting
for this lock.
The RecursionCount field indicates the number of times that the owning thread has called EnterCriticalSection for this critical section.
The EntryCount field indicates the number of times that a thread other than the owning thread has called EnterCriticalSection for this critical section.

A newly initialized critical section looks like this:

0:000> !critsec 433e60
CritSec mymodule!cs+0 at 00433E60
LockCount
NOT LOCKED

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

RecursionCount
OwningThread
EntryCount
ContentionCount

Page 789 of 1651

0
0
0
0

The debugger displays "NOT LOCKED" as the value for LockCount. The actual value of this field for an unlocked critical section is -1. You can verify this with the
dt (Display Type) command:
0:000> dt
+0x000
+0x004
+0x008
+0x00c
+0x010
+0x014

RTL_CRITICAL_SECTION 433e60
DebugInfo
: 0x77fcec80
LockCount
: -1
RecursionCount
: 0
OwningThread
: (null)
LockSemaphore
: (null)
SpinCount
: 0

When the first thread calls the EnterCriticalSection routine, the critical section's LockCount, RecursionCount, EntryCount and ContentionCount fields are all
incremented by one, and OwningThread becomes the thread ID of the caller. EntryCount and ContentionCount are not incremented. For example:
0:000> !critsec 433e60
CritSec mymodule!cs+0 at 00433E60
LockCount
0
RecursionCount
1
OwningThread
4d0
EntryCount
0
ContentionCount
0
At this point, four different things can happen.
1. The owning thread calls EnterCriticalSection again. This will increment LockCount and RecursionCount. EntryCount is not incremented.
0:000> !critsec 433e60
CritSec mymodule!cs+0 at 00433E60
LockCount
1
RecursionCount
2
OwningThread
4d0
EntryCount
0
ContentionCount
0
2. A different thread calls EnterCriticalSection. This will increment LockCount and EntryCount. RecursionCount is not incremented.
0:000> !critsec 433e60
CritSec mymodule!cs+0 at 00433E60
LockCount
1
RecursionCount
1
OwningThread
4d0
EntryCount
1
ContentionCount
1
3. The owning thread calls LeaveCriticalSection. This will decrement LockCount (to -1) and RecursionCount (to 0), and will reset OwningThread to 0.
0:000> !critsec 433e60
CritSec mymodule!cs+0 at 00433E60
LockCount
NOT LOCKED
RecursionCount
0
OwningThread
0
EntryCount
0
ContentionCount
0
4. Another thread calls LeaveCriticalSection. This produces the same results as the owning thread calling LeaveCriticalSection it will decrement LockCount (to -1)
and RecursionCount (to 0), and will reset OwningThread to 0.
When any thread calls LeaveCriticalSection, Windows decrements LockCount and RecursionCount. This feature has both good and bad aspects. It allows a device driver
to enter a critical section on one thread and leave the critical section on another thread. However, it also makes it possible to accidentally call LeaveCriticalSection on the
wrong thread, or to call LeaveCriticalSection too many times and cause LockCount to reach values lower than -1. This corrupts the critical section and causes all threads to
wait indefinitely on the critical section.
Interpreting Critical Section Fields in Windows Server 2003 SP1 and Later
In Microsoft Windows Server 2003 Service Pack 1 and later versions of Windows, the LockCount field is parsed as follows:

The lowest bit shows the lock status. If this bit is 0, the critical section is locked; if it is 1, the critical section is not locked.
The next bit shows whether a thread has been woken for this lock. If this bit is 0, then a thread has been woken for this lock; if it is 1, no thread has been woken.
The remaining bits are the ones-complement of the number of threads waiting for the lock.

As an example, suppose the LockCount is -22. The lowest bit can be determined in this way:
0:009> ? 0x1 & (-0n22)
Evaluate expression: 0 = 00000000
The next-lowest bit can be determined in this way:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 790 of 1651

0:009> ? (0x2 & (-0n22)) >> 1

Evaluate expression: 1 = 00000001
The ones-complement of the remaining bits can be determined in this way:
0:009> ? ((-1) - (-0n22)) >> 2
Evaluate expression: 5 = 00000005
In this example, the first bit is 0 and therefore the critical section is locked. The second bit is 1, and so no thread has been woken for this lock. The complement of the
remaining bits is 5, and so there are five threads waiting for this lock.
Additional Information
For information about how to debug critical section time outs, see Critical Section Time Outs. For general information about critical sections, see the Microsoft Windows
SDK, the Windows Driver Kit (WDK), or Microsoft Windows Internals by Mark Russinovich and David Solomon.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging an Application Failure

There are a variety of errors possible in user-mode applications.
The most common kinds of failures include access violations, alignment faults, exceptions, critical section time-outs (deadlocks), and in-page I/O errors.
Access violations and data type misalignments are among the most common. They usually occur when an invalid pointer is dereferenced. The blame could lie with the
function that caused the fault, or with an earlier function that passed an invalid parameter to the faulting function.
User-mode exceptions have many possible causes. If an unknown exception occurs, locate it in ntstatus.h or winerror.h if possible.
Critical section timeouts (or possible deadlocks) occur when one thread is waiting for a critical section for a long time. These are difficult to debug and require an in-depth
analysis of the stack trace.
In-page I/O errors are almost always hardware failures. You can double-check the status code in ntstatus.h to verify.
See Advanced Debugging Techniques for some tips on how to proceed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Messages from the Target

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Debug Print Filter. Using a registry editor, create or open this key. Under
this key, create a value with the name of the desired component, in uppercase. Set it equal to the DWORD value that you wish to use as the component filter mask.
If a kernel debugger is active, it can access the component filter mask value by dereferencing the address stored in the symbol Kd_XXXX_Mask, where XXXX is the
desired component name. You can display the value of this mask in WinDbg or KD with the dd (Display DWORD) command, or enter a new component filter mask
with the ed (Enter DWORD) command. If there is a danger of symbol ambiguity, you may wish to specify this symbol as nt!Kd_XXXX_Mask.

Filter masks stored in the registry take effect during boot. Filter masks created by the debugger take effect immediately, and persist until Windows is rebooted. A value set in
the registry can be overridden by the debugger, but the component filter mask will return to the value specified in the registry if the system is rebooted.
There is also a system-wide mask called WIN2000. This is equal to 0x1 by default, though it can be changed through the registry or the debugger like all other components.
When filtering is performed, each component filter mask is first ORed with the WIN2000 mask. In particular, this means that components whose masks have never been
specified default to 0x1.
Criteria for Displaying the Message
When DbgPrintEx is called in kernel-mode code, Windows compares the message importance bit field specified by Level with the filter mask of the component specified by
ComponentId.
Note Recall that when the Level parameter is between 0 and 31, the importance bit field is equal to 1 << Level, but when the Level parameter is 32 or higher, the importance
bit field is simply equal to Level.
Windows performs an AND operation on the importance bit field and the component filter mask. If the result is nonzero, the message is sent to the debugger.
Example
Here is an example.
Suppose that before the last boot, you created the following values in the Debug Print Filter key:

IHVVIDEO, with a value equal to DWORD 0x2

IHVBUS, equal to DWORD 0x7FF

Now you issue the following commands in the kernel debugger:

kd> ed Kd_IHVVIDEO_Mask 0x8
kd> ed Kd_IHVAUDIO_Mask 0x7
At this point, the IHVVIDEO component has a filter mask of 0x8, the IHVAUDIO component has a filter mask of 0x7, and the IHVBUS component has a filter mask of
0x7FF.
However, because these masks are automatically ORed with the WIN2000 system-wide mask (which is usually equal to 0x1), the IHVVIDEO mask is effectively equal to
0x9. Indeed, components whose filter masks have not been set at all (for instance, IHVSTREAMING or DEFAULT) will have a filter mask of 0x1.
Now suppose that the following function calls occur in various drivers:
DbgPrintEx( DPFLTR_IHVVIDEO_ID,
DbgPrintEx( DPFLTR_IHVAUDIO_ID,
DbgPrintEx( DPFLTR_IHVBUS_ID,
DbgPrint( "Fourth message.\n");

DPFLTR_INFO_LEVEL,
7,
DPFLTR_MASK | 0x10,

"First message.\n");
"Second message.\n");
"Third message.\n");

The first message has its Level parameter equal to DPFLTR_INFO_LEVEL, which is 3. Since this is less than 32, it is treated as a bit shift, resulting in an importance bit field
of 0x8. This value is then ANDed with the effective IHVVIDEO component filter mask of 0x9, giving a nonzero result. So the first message is transmitted to the debugger.
The second message has its Level parameter equal to 7. Again, this is treated as a bit shift, resulting in an importance bit field of 0x80. This is then ANDed with the
IHVAUDIO component filter mask of 0x7, giving a result of zero. So the second message is not transmitted.
The third message has its Level parameter equal to DPFLTR_MASK | 0x10. This is greater than 31, and therefore the importance bit field is set equal to the value of Level
in other words, to 0x80000010. This is then ANDed with the IHVBUS component filter mask of 0x7FF, giving a nonzero result. So the third message is transmitted to the
debugger.
The fourth message was passed to DbgPrint instead of DbgPrintEx. In Windows Server 2003 and earlier versions of Windows, messages passed to this routine are always
transmitted. In Windows Vista and later versions of Windows, messages passed to this routine are always given a default filter. The importance bit field is equal to
1 << DPFLTR_INFO_LEVEL, which is 0x00000008. The component for this routine is DEFAULT. Since you have not set the DEFAULT component filter mask, it has a
value of 0x1. When this is ANDed with the importance bit field, the result is zero. So the fourth message is not transmitted.

The DbgPrint Buffer

When DbgPrint, DbgPrintEx, KdPrint, or KdPrintEx transmits a message to the debugger, the formatted string is sent to the DbgPrint buffer. In most cases, the contents of
this buffer are displayed immediately in the Debugger Command window. This display can be disabled by using the Buffer DbgPrint Output option of the Global Flags
Utility (gflags.exe). This display does not automatically appear during local kernel debugging.
During local kernel debugging, and any other time this display has been disabled, the contents of the DbgPrint buffer can only be viewed by using the !dbgprint extension

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 794 of 1651

command.
Any single call to DbgPrint, DbgPrintEx, KdPrint, or KdPrintEx will only transmit 512 bytes of information. Any output longer than this will be lost. The DbgPrint buffer
itself can hold up to 4 KB of data on a free build of Windows, and up to 32 KB of data on a checked build of Windows. On Windows Server 2003 and later versions of
Windows, you can use the KDbgCtrl tool to alter the size of the DbgPrint buffer. See Using KDbgCtrl for details.
If a message is filtered out because of its ComponentId and Level values, it is not transmitted across the debugging connection. Therefore there is no way to display this
message in the debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Determining if a Debugger is Attached

Kernel-mode code can determine the status of kernel debugging by using the following variables and routines:

(Windows XP and later) The KD_DEBUGGER_ENABLED global kernel variable indicates whether kernel debugging is enabled.
(Windows XP and later) The KD_DEBUGGER_NOT_PRESENT global kernel variable indicates whether a kernel debugger is currently attached.
(Windows Server 2003 and later) The KdRefreshDebuggerNotPresent routine refreshes the value of KD_DEBUGGER_NOT_PRESENT.

For complete documentation, see the Windows Driver Kit.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Checks (Blue Screens)

This section includes:
Blue Screen Data
General Troubleshooting Tips
Bug Check Code Reference
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Blue Screen Data

When Microsoft Windows encounters a condition that compromises safe system operation, the system halts. This condition is called a bug check. It is also commonly referred
to as a system crash, a kernel error, or a Stop error.
If crash dumps are enabled on the system, a crash dump file is created.
If a kernel debugger is attached and active, the system causes a break so the debugger can be used to investigate the crash.
If no debugger is attached, a blue text screen appears with information about the error. This screen is called a blue screen, a bug check screen, or a Stop screen.
The exact appearance of the blue screen depends on the cause of the error. The following is an example of one possible blue screen:
STOP: 0x00000079 (0x00000002, 0x00000001, 0x00000002, 0x00000000)
Mismatched kernel and hal image.
Beginning dump of physical memory
Physical memory dump complete. Contact your system administrator or
technical support group.
On the other hand, some blue screens look like this:
STOP: c000021a {Fatal System Error}
The Windows Logon Process system process terminated unexpectedly with
a status of 0x00000001 (0x00000000 0x00000000).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 795 of 1651

The system has been shut down.

The hexadecimal number following the word "STOP" is called the bug check code or Stop code. This is the most important item on the screen.
Each bug check code has four associated parameters. In the first blue screen shown here, all four parameters are displayed after the bug check code. However, in the second
kind of blue screen, these parameters have been rearranged within the explanatory text. Regardless of the amount of rearrangement, they will always appear sequentially. If
fewer than four parameters appear, the remaining parameters can be assumed to be zero.
The remainder of the text on the blue screen gives additional information. For some bug checks, this may be an explanation of what happened or suggestions for how you can
deal with the problem. If a kernel-mode dump file has been written, this will usually be indicated as well.
Under some conditions, Windows will display only the first line of the blue screen. This can occur if the vital services needed for the display have been affected by the error.
Bug Check Symbolic Names
Each bug check code also has an associated symbolic name. These names usually do not appear on the blue screen. In these examples, the first screen shows bug check 0x79
(MISMATCHED_HAL), while the second shows bug check 0xC000021A (STATUS_SYSTEM_PROCESS_TERMINATED).
To deliberately cause a bug check from a kernel-mode driver, you need to pass the bug check's symbolic name to the KeBugCheck or KeBugCheckEx function. This should
only be done in circumstances where no other option is available. For more details on these functions, see the Windows Driver Kit.
Reading Bug Check Information from the Debugger
If a debugger is attached, a bug check will cause the target computer to break into the debugger. In this case, the blue screen might not appear, or might appear with less text;
the full details on this crash will be sent to the debugger and appear in the debugger window. To see this information a second time, use the .bugcheck (Display Bug Check
Data) command.
The debugger will also display additional information regarding the current problem. To see this information a second time, use the !analyze extension command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

General Troubleshooting Tips

When a bug check occurs as a result of code you have written, you should use the kernel debugger to analyze the problem, and then fix the bugs in your code. For full details,
see the individual bug check code in the Bug Check Code Reference section.
However, you might also encounter bug checks that are not caused by your own code. In this case, you probably will not be able to fix the actual cause of the problem, so
your goal should be to work around the problem, and if possible isolate and remove the hardware or software component that is at fault.
Many problems can be resolved through basic troubleshooting procedures, such as verifying instructions, reinstalling key components, and verifying file dates. Also,
diagnostic tools such as Winmsd, Network General Sniffer, and Microsoft Windows Resource Kit Tools Help might isolate and resolve these issues.
For general troubleshooting of Windows bug check codes, follow these suggestions:

If you recently added hardware to the system, try removing or replacing it. Or check with the manufacturer to see if any patches are available.
You can try running the hardware diagnostics supplied by the system manufacturer.
Check with the manufacturer to see if an updated system BIOS or firmware is available.
Make sure that any expansion board is properly seated and all cables are completely connected.
Confirm that any new hardware is listed in the Microsoft Windows Marketplace Tested Products List.
If new device drivers or system services have been added recently, try removing or updating them.
Important Use Safe Mode when removing or disabling components. Using Safe Mode loads only the minimum required drivers and system services during the
Windows startup. To enter Safe Mode, restart your computer, and press F8 at the character-mode menu that displays the operating system choices. At the resulting
Windows Advanced Options menu, choose Safe Mode.

Run a virus detection program. Viruses can infect all types of hard disks formatted for Windows, and resulting disk corruption can generate system bug check codes.
Make sure the virus detection program checks the Master Boot Record for infections.
Verify that the system has the latest Service Pack installed. To detect which Service Pack, if any, is installed on your system, click Start, click Run, type winver, and
then press ENTER. The About Windows dialog box displays the Windows version number and the version number of the Service Pack, if one has been installed.
Disable BIOS memory options such as caching or shadowing.
Check the System Log and Application Log in Event Viewer to see if any additional error messages have been logged recently. These might pinpoint the cause of the
error.

Kernel debugging is especially useful when other troubleshooting techniques fail, or for a recurring problem. Remember to capture the exact text in the bug check information
section of the error message. To isolate a complex problem and develop a viable workaround or a program replacement, you must record the exact actions that lead to the
failure.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check Code Reference

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 796 of 1651

This section contains descriptions of the common bug checks, including the parameters passed to the blue screen.
It also describes how you can diagnose the fault which led to the bug check, and possible ways to deal with the error.
If a specific bug check code does not appear in this reference, use the !analyze extension command (in kernel mode) with the following syntax:
kd> !analyze -show Code
This will display information about the specified bug check code. If your default radix is not 16, you should prefix Code with "0x".
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1: APC_INDEX_MISMATCH

The APC_INDEX_MISMATCH bug check has a value of 0x00000001. This indicates that there has been a mismatch in the APC state index.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the system function (system call)
2
The value of the following bit computation:
Thread->ApcStateIndex << 8 | Previous ApcStateIndex

3
4

The value of Thread->KernelApcDisable

The value of the previous KernelApcDisable

Cause
The most common cause of this bug check is when a file system has a mismatched sequence of KeEnterCriticalRegion calls and KeLeaveCriticalRegion calls.
Comments
This is a kernel internal error which can occur only on a checked build. This error occurs on exit from a system call.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2: DEVICE_QUEUE_NOT_BUSY

The DEVICE_QUEUE_NOT_BUSY bug check has a value of 0x00000002.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3: INVALID_AFFINITY_SET

The INVALID_AFFINITY_SET bug check has a value of 0x00000003.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 797 of 1651

Bug Check 0x4: INVALID_DATA_ACCESS_TRAP

The INVALID_DATA_ACCESS_TRAP bug check has a value of 0x00000004.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5: INVALID_PROCESS_ATTACH_ATTEMPT

The INVALID_PROCESS_ATTACH_ATTEMPT bug check has a value of 0x00000005. This generally indicates that the thread was attached to a process in a situation
where that is not allowed. For example, this bug check could occur if KeAttachProcess was called when the thread was already attached to a process (which is illegal), or if
the thread returned from certain function calls in an attached state (which is invalid),
This bug check appears very infrequently.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The pointer to the dispatcher object for the target process, or if the thread is already attached, the pointer to the object for the original process.
2
The pointer to the dispatcher object of the process that the current thread is currently attached to.
3
The value of the threads APC state index.
4
A non-zero value indicates that a DPC is running on the current processor.
Comment
This bug check can occur if the driver calls the KeAttachProcess function and the thread is already attached to another process. It is better to use the KeStackAttachProcess
function. If the current thread was already attached to another process, the KeStackAttachProcess function saves the current APC state before it attaches the current thread to
the new process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x6: INVALID_PROCESS_DETACH_ATTEMPT

The INVALID_PROCESS_DETACH_ATTEMPT bug check has a value of 0x00000006.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x7: INVALID_SOFTWARE_INTERRUPT

The INVALID_SOFTWARE_INTERRUPT bug check has a value of 0x00000007.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x8: IRQL_NOT_DISPATCH_LEVEL

The IRQL_NOT_DISPATCH_LEVEL bug check has a value of 0x00000008.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 798 of 1651

This bug check appears very infrequently.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9: IRQL_NOT_GREATER_OR_EQUAL

The IRQL_NOT_GREATER_OR_EQUAL bug check has a value of 0x00000009.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA: IRQL_NOT_LESS_OR_EQUAL

The IRQL_NOT_LESS_OR_EQUAL bug check has a value of 0x0000000A. This indicates that Microsoft Windows or a kernel-mode driver accessed paged memory at
DISPATCH_LEVEL or above.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory referenced
2
IRQL at time of reference
3
0: Read
1: Write
4

Address which referenced memory

Cause
This bug check is issued if paged memory (or invalid memory) is accessed when the IRQL is too high.
The error that generates this bug check usually occurs after the installation of a faulty device driver, system service, or BIOS.
If you encounter bug check 0xA while upgrading to a later version of Windows, this error might be caused by a device driver, a system service, a virus scanner, or a backup
tool that is incompatible with the new version.
Resolving the Problem
If a kernel debugger is available, obtain a stack trace.
To resolve an error caused by a faulty device driver, system service, or BIOS
1. Restart your computer.
2. Press F8 at the character-based menu that displays the operating system choices.
3. Select the Last Known Good Configuration option from the Windows Advanced Options menu. This option is most effective when only one driver or service is
added at a time.
To resolve an error caused by an incompatible device driver, system service, virus scanner, or backup tool
1. Check the System Log in Event Viewer for error messages that might identify the device or driver that caused the error.
2. Try disabling memory caching of the BIOS.
3. Run the hardware diagnostics supplied by the system manufacturer, especially the memory scanner. For details on these procedures, see the owner's manual for your
computer.
4. Make sure the latest Service Pack is installed.
5. If your system has small computer system interface (SCSI) adapters, contact the adapter manufacturer to obtain updated Windows drivers. Try disabling sync
negotiation in the SCSI BIOS, checking the cabling and the SCSI IDs of each device, and confirming proper termination.
6. For integrated device electronics (IDE) devices, define the onboard IDE port as Primary only. Also, check each IDE device for the proper master/subordinate/standalone setting. Try removing all IDE devices except for hard disks.
If the message appears during an installation of Windows, make sure that the computer and all installed peripherals are listed in the Microsoft Windows Marketplace Tested
Products List.
Here is a debugging example:
kd> .bugcheck

[Lists bug check data.]

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 799 of 1651

Bugcheck code 0000000a

Arguments 00000000 0000001c 00000000 00000000
kd> kb
ChildEBP
8013ed5c
8013eecc
8013eecc
8013ed5c
8013ef64

[Lists the stack trace.]

RetAddr Args to Child
801263ba 00000000 00000000 e12ab000
801389ee 0000000a 00000000 0000001c
00000000 0000000a 00000000 0000001c
801263ba 00000000 00000000 e12ab000
00000246 fe551aa1 ff690268 00000002

NT!_DbgBreakPoint
NT!_KeBugCheckEx+0x194
NT!_KiTrap0E+0x256

kd> kv
ChildEBP
8013ed5c
8013eecc
8013eecc
8013ed5c
8013ef64

[Lists the trap frames.]

NT!_DbgBreakPoint (FPO: [0,0,0])

NT!_KeBugCheckEx+0x194
NT!_KiTrap0E+0x256 (FPO: [0,0] TrapFrame @ 8013eee8)

NT!_KeBugCheckEx+0x194

kd> .trap 8013eee8

[Gets the registers for the trap frame at the time of the fault.]
eax=dec80201 ebx=ffdff420 ecx=8013c71c edx=000003f8 esi=00000000 edi=87038e10
eip=00000000 esp=8013ef5c ebp=8013ef64 iopl=0
nv up ei pl nz na pe nc
cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000
efl=00010202
ErrCode = 00000000
00000000 ???????????????
[The current instruction pointer is NULL.]
kd> kb
[Gives the stack trace before the fault.]
ChildEBP RetAddr Args to Child
8013ef68 fe551aa1 ff690268 00000002 fe5620d2 NT!_DbgBreakPoint
8013ef74 fe5620d2 fe5620da ff690268 80404690
NDIS!_EthFilterIndicateReceiveComplete+0x31
8013ef64 00000246 fe551aa1 ff690268 00000002 elnkii!_ElnkiiRcvInterruptDpc+0x1d0
Comments
Before upgrading to a new version of Windows, remove all third-party device drivers and system services, and disable any virus scanners. Contact the software manufacturers
to obtain updates of these third-party tools.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xB: NO_EXCEPTION_HANDLING_SUPPORT

The NO_EXCEPTION_HANDLING_SUPPORT bug check has a value of 0x0000000B.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC: MAXIMUM_WAIT_OBJECTS_EXCEEDED

The MAXIMUM_WAIT_OBJECTS_EXCEEDED bug check has a value of 0x0000000C. This indicates that the current thread exceeded the permitted number of wait
objects.
Parameters
None
Cause
This bug check results from the improper use of KeWaitForMultipleObjects or FsRtlCancellableWaitForMultipleObjects.
The caller may pass a pointer to a buffer in this routine's WaitBlockArray parameter. The system will use this buffer to keep track of wait objects.
If a buffer is supplied, the Count parameter may not exceed MAXIMUM_WAIT_OBJECTS. If no buffer is supplied, the Count parameter may not exceed
THREAD_WAIT_OBJECTS.
If the value of Count exceeds the allowable value, this bug check is issued.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 800 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD: MUTEX_LEVEL_NUMBER_VIOLATION

The MUTEX_LEVEL_NUMBER_VIOLATION bug check has a value of 0x0000000D.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xE: NO_USER_MODE_CONTEXT

The NO_USER_MODE_CONTEXT bug check has a value of 0x0000000E.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF: SPIN_LOCK_ALREADY_OWNED

The SPIN_LOCK_ALREADY_OWNED bug check has a value of 0x0000000F. This indicates that a request for a spin lock has been initiated when the spin lock was already
owned.
Parameters
None
Cause
Typically, this error is caused by a recursive request for a spin lock. It can also occur if something similar to a recursive request for a spin lock has been initiatedfor
example, when a spin lock has been acquired by a thread, and then that same thread calls a function, which also tries to acquire a spin lock. The second attempt to acquire a
spin lock is not blocked in this case because doing so would result in an unrecoverable deadlock. If the calls are made on more than one processor, then one processor will be
blocked until the other processor releases the lock.
This error can also occur, without explicit recursion, when all threads and all spin locks are assigned an IRQL. Spin lock IRQLs are always greater than or equal to DPC level,
but this is not true for threads. However, a thread that is holding a spin lock must maintain an IRQL greater than or equal to that of the spin lock. Decreasing the thread IRQL
below the IRQL level of the spin lock that it is holding allows another thread to be scheduled on the processor. This new thread could then attempt to acquire the same spin
lock.
Resolving the Problem
Ensure that you are not recursively acquiring the lock. And, for threads that hold a spin lock, ensure that you are not decreasing the thread IRQL to a level below the IRQL of
the spin lock that it is holding.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10: SPIN_LOCK_NOT_OWNED

The SPIN_LOCK_NOT_OWNED bug check has a value of 0x00000010.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 801 of 1651

December 09, 2009

Debugging Tools for Windows

Bug Check 0x11: THREAD_NOT_MUTEX_OWNER

The THREAD_NOT_MUTEX_OWNER bug check has a value of 0x00000011.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x12: TRAP_CAUSE_UNKNOWN

The TRAP_CAUSE_UNKNOWN bug check has a value of 0x00000012. This indicates that an unknown exception has occurred.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The unexpected interrupt
2
The unknown floating-point exception
3
The enabled and asserted status bits. See the processor definition for details.
4
Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x13: EMPTY_THREAD_REAPER_LIST

The EMPTY_THREAD_REAPER_LIST bug check has a value of 0x00000013.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x14: CREATE_DELETE_LOCK_NOT_LOCKED

The CREATE_DELETE_LOCK_NOT_LOCKED bug check has a value of 0x00000014.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x15: LAST_CHANCE_CALLED_FROM_KMODE

The LAST_CHANCE_CALLED_FROM_KMODE bug check has a value of 0x00000015.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 802 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Bug Check 0x16: CID_HANDLE_CREATION

The CID_HANDLE_CREATION bug check has a value of 0x00000016.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x17: CID_HANDLE_DELETION

The CID_HANDLE_DELETION bug check has a value of 0x00000017.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x18: REFERENCE_BY_POINTER

The REFERENCE_BY_POINTER bug check has a value of 0x00000018. This indicates that the reference count of an object is illegal for the current state of the object.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Object type of the object whose reference count is being lowered.
2
Object whose reference count is being lowered.
3
Reserved
4
Reserved
Cause
The reference count of an object is illegal for the current state of the object. Each time a driver uses a pointer to an object, the driver calls a kernel routine to increase the
reference count of the object by one. When the driver is done with the pointer, the driver calls another kernel routine to decrease the reference count by one.
Drivers must match calls to the routines that increase (reference) and decrease (dereference) the reference count. This bug check is caused by an inconsistency in the objects
reference count. Typically, the inconsistency is caused by a driver that decreases the reference count of an object too many times, making extra calls that dereference the
object. This bug check can occur because an object's reference count goes to zero while there are still open handles to the object. It might also occur when the objects
reference count drops below zero, whether or not there are open handles to the object.
Resolving the Problem
Make sure that the driver matches calls to the routines that increase and decrease the reference count of the object. Make sure that your driver does not make extra calls to
routines that dereference the object (see Parameter 2).
You can use a debugger to help analyze this problem. To find the handle and pointer count on the object, use the !object debugger command.
kd> !object address
Where address is the address of the object given in Parameter 2.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x19: BAD_POOL_HEADER

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 803 of 1651

The BAD_POOL_HEADER bug check has a value of 0x00000019. This indicates that a pool header is corrupt.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of
Parameter 1.
Parameter
Parameter 2
1
0x2
The pool entry being
checked

Parameter 3
The size of the pool
block

Parameter 4
0

Cause of Error
The special pool pattern check failed.
(The owner has likely corrupted the pool block.)

0x3

The pool entry being

checked

The read-back flink

freelist value

The read-back blink freelist value

The pool freelist is corrupt.

(In a healthy list, the values of Parameters 2, 3, and 4 should
be identical.)

0x5

One of the pool entries

Reserved

0x6

One incorrectly-calculated
entry
0
0
One incorrectly-calculated
entry
The pool entry that should
have been found
The pool entry that should
have been found

Reserved

A pair of adjacent pool entries have headers that contradict

each other. At least one of them is corrupt.
The bad entry that caused the miscalculation The pool block header's previous size is too large.

Reserved
Reserved
Reserved

The bad pool entry

The pool block header size is corrupt.
The bad pool entry
The pool block header size is zero.
The bad entry that caused the miscalculation The pool block header size is corrupted (it is too large).

Reserved

The virtual address of the page that should

have contained the pool entry
Reserved

0x7
0x8
0x9
0xA
0x20

The next pool entry

The other pool entry

The pool block header size is corrupt.

Cause
The pool is already corrupted at the time of the current request.
This may or may not be due to the caller.
Resolving the Problem
The internal pool links must be walked to figure out a possible cause of the problem.
Then you can use special pool for the suspect pool tags, or use Driver Verifier on the suspect driver. The !analyze extension may be of help in pinpointing the suspect driver,
but this is frequently not the case with pool corrupters.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1A: MEMORY_MANAGEMENT

The MEMORY_MANAGEMENT bug check has a value of 0x0000001A. This indicates that a severe memory management error occurred.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 is the only parameter of interest; this identifies the exact violation.
Parameter
1
0x1
0x777
0x778
0x780
0x781
0x1000

0x1010
0x1234
0x1235
0x3451
0x8888
0x8889
0x41283
0x41284

Cause of Error
The fork clone block reference count is corrupt. (This only occurs on checked builds of Windows.)
The caller is unlocking a system cache address that is not currently locked. (This address was either never mapped or is being unlocked twice.)
The system is using the very last system cache view address, instead of preserving it.
The PTEs mapping the argument system cache view have been corrupted.
A caller of MmGetSystemAddressForMdl* tried to map a fully-cached physical page as non-cached. This action would cause a conflicting hardware
translation buffer entry, and so it was refused by the operating system. Since the caller specified "bug check on failure" in the requesting MDL, the system had
no choice but to issue a bug check in this instance.
The caller is unlocking a pageable section that is not currently locked. (This section was either never locked or is being unlocked twice.)
The caller is trying lock a nonexistent pageable section.
The caller is trying to protect an MDL with an invalid mapping.
The PTEs of a kernel thread stack that has been swapped out are corrupted.
Internal memory management structures are corrupted.
The working set index encoded in the PTE is corrupted.
A PTE or the working set list is corrupted.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x41286
0x41785
0x41287
0x61940
0x03030303
Other

Page 804 of 1651

The caller is trying to free an invalid pool address.

The working set list is corrupted.
Internal memory management structures are corrupted. To further investigate the cause, a kernel memory dump file is needed.
A PDE has been unexpectedly invalidated.
The boot loader is broken. (This value applies only to Intel Itanium machines.)
An unknown memory management error occurred.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1B: PFN_SHARE_COUNT

The PFN_SHARE_COUNT bug check has a value of 0x0000001B.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1C: PFN_REFERENCE_COUNT

The PFN_REFERENCE_COUNT bug check has a value of 0x0000001C.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1D: NO_SPIN_LOCK_AVAILABLE

The NO_SPIN_LOCK_AVAILABLE bug check has a value of 0x0000001D.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1E: KMODE_EXCEPTION_NOT_HANDLED

The KMODE_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000001E. This indicates that a kernel-mode program generated an exception which the error
handler did not catch.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The exception code that was not handled
2
The address at which the exception occurred
3
Parameter 0 of the exception
4
Parameter 1 of the exception
Cause
This is a very common bug check. To interpret it, you must identify which exception was generated.
Common exception codes include:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 805 of 1651

0x80000002: STATUS_DATATYPE_MISALIGNMENT
An unaligned data reference was encountered.

0x80000003: STATUS_BREAKPOINT
A breakpoint or ASSERT was encountered when no kernel debugger was attached to the system.

0xC0000005: STATUS_ACCESS_VIOLATION
A memory access violation occurred. (Parameter 4 of the bug check is the address that the driver attempted to access.)

For a complete list of exception codes, see the ntstatus.h file located in the inc directory of the Windows Driver Kit.
Resolving the Problem
If you are not equipped to debug this problem, you should use some basic troubleshooting techniques. If a driver is identified in the bug check message, disable the driver or
check with the manufacturer for driver updates. Try changing video adapters. Check with your hardware vendor for any BIOS updates. Disable BIOS memory options such as
caching or shadowing.
If you plan to debug this problem, you may find it difficult to obtain a stack trace. Parameter 2 (the exception address) should pinpoint the driver or function that caused this
problem.
If exception code 0x80000003 occurs, this indicates that a hard-coded breakpoint or assertion was hit, but the system was started with the /NODEBUG switch. This problem
should rarely occur. If it occurs repeatedly, make sure a kernel debugger is connected and the system is started with the /DEBUG switch.
If exception code 0x80000002 occurs, the trap frame will supply additional information.
If the specific cause of the exception is unknown, the following should be considered:
Hardware incompatibility. First, make sure that any new hardware installed is listed in the Microsoft Windows Marketplace Tested Products List.
Faulty device driver or system service. In addition, a faulty device driver or system service might be responsible for this error. Hardware issues, such as BIOS
incompatibilities, memory conflicts, and IRQ conflicts can also generate this error.
If a driver is listed by name within the bug check message, disable or remove that driver. Disable or remove any drivers or services that were recently added. If the error
occurs during the startup sequence and the system partition is formatted with NTFS file system, you might be able to use Safe Mode to rename or delete the faulty driver. If
the driver is used as part of the system startup process in Safe Mode, you need to start the computer by using the Recovery Console to access the file.
If the problem is associated with Win32k.sys, the source of the error might be a third-party remote control program. If such software is installed, the service can be removed by
starting the system using the Recovery Console and deleting the offending system service file.
Check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing bug check 0x1E. Disabling memory caching
of the BIOS might also resolve the error. You should also run hardware diagnostics, especially the memory scanner, supplied by the system manufacturer. For details on these
procedures, see the owner's manual for your computer.
The error that generates this message can occur after the first restart during Windows Setup, or after Setup is finished. A possible cause of the error is a system BIOS
incompatibility. BIOS problems can be resolved by upgrading the system BIOS version.
To get a stack trace if the normal stack tracing procedures fail
1. Use the kb (Display Stack Backtrace) command to display parameters in the stack trace. Look for the call to NT!PspUnhandledExceptionInSystemThread. (If this
function is not listed, see the note below.)
2. The first parameter to NT!PspUnhandledExceptionInSystemThread is a pointer to a structure, which contains pointers to an except statement:
typedef struct _EXCEPTION_POINTERS {
PEXCEPTION_RECORD ExceptionRecord;
PCONTEXT ContextRecord;
} EXCEPTION_POINTERS, *PEXCEPTION_POINTERS;
ULONG PspUnhandledExceptionInSystemThread(
IN PEXCEPTION_POINTERS ExceptionPointers
)
Use the dd (Display Memory) command on that address to display the necessary data.
3. The first retrieved value is an exception record and the second is a context record. Use the .exr (Display Exception Record) command and the .cxr (Display Context
Record) command with these two values as their arguments, respectively.
4. After the .cxr command executes, use the kb command to display a stack trace that is based on the context record information. This stack trace indicates the calling
stack where the unhandled exception occurred.
Note This procedure assumes that you can locate NT!PspUnhandledExceptionInSystemThread. However, in some cases (such as an access violation crash) you will not
be able to do this. In that case, look for ntoskrnl!KiDispatchException. The third parameter passed to this function is a trap frame address. Use the .trap (Display Trap
Frame) command with this address to set the Register Context to the proper value. You can then perform stack traces and issue other commands.
Here is an example of bug check 0x1E on an x86 processor:
kd> .bugcheck
get the bug check data
Bugcheck code 0000001e
Arguments c0000005 8013cd0a 00000000 0362cffff
kd> kb
FramePtr

RetAddr

Param1

start with a stack trace

Param2
Param3
Function Name

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

8013ed5c
8013eecc
fe40cad0
fe40cad8
fe40cf7c
00000000

801263ba
8013313c
8013318e
801359ff
8013cb8e
00000000

Page 806 of 1651

00000000
0000001e
fe40caf8
fe40cb00
fe43a44c
00000000

00000000
c0000005
801359ff
00000000
ff6ce388
00000000

fe40cb00
8013cd0a
fe40cb00
fe40cb00
00000000
00000000

NT!_DbgBreakPoint
NT!_KeBugCheckEx+0x194
NT!PspUnhandledExceptionInSystemThread+0x18
NT!PspSystemThreadStartup+0x4a
NT!_except_handler3+0x47
NT!KiThreadStartup+0xe

kd> dd fe40caf8 L2
dump EXCEPTION_POINTERS structure
0xFE40CAF8 fe40cd88 fe40cbc4
..@...@.
kd> .exr fe40cd88
Exception Record @ FE40CD88:
ExceptionCode: c0000005
ExceptionFlags: 00000000
Chained Record: 00000000
ExceptionAddress: 8013cd0a
NumberParameters: 00000002
Parameter[0]: 00000000
Parameter[1]: 0362cfff

first DWORD is the exception record

kd> .cxr fe40cbc4

second DWORD is the context record
CtxFlags: 00010017
eax=00087000 ebx=00000000 ecx=03ff0000 edx=ff63d000 esi=0362cfff edi=036b3fff
eip=8013cd0a esp=fe40ce50 ebp=fe40cef8 iopl=0
nv dn ei pl nz ac po cy
vip=0
vif=0
cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000
efl=00010617
0x8013cd0a f3a4
rep movsb
kd> kb
ChildEBP
fe40ce54
fe40ce68
fe40ce9c
fe40ceb8
fe40cef8
fe40cf18
fe40cf30
fe40cf4c
fe40cf7c

RetAddr
80402e09
80403c18
fe43b1e4
fe4385b4
fe439894
fe437d92
fe43a4f5
80133184
8013cb8e

kb gives stack
Args to Child
ff6c4000 ff63d000 03ff0000
ffbc0c28 ff6ce008 ff6c4000
ff6cef90 ffbc0c28 ff6ce009
ff6ce388 6cd00800 ffbc0c28
ff6cd008 ffb6c820 fe40cf4c
ff6cd008 ffb6c820 ff6e4e50
ff6cd008 ffb6c820 00000000
ff6ce388 00000000 00000000
fe43a44c ff6ce388 00000000

for context record

NT!_RtlMoveMemory@12+0x3e
HAL!_HalpCopyBufferMap@20+0x49
HAL!_IoFlushAdapterBuffers@24+0x148
QIC117!_kdi_FlushDMABuffers@20+0x28
QIC117!_cqd_CmdReadWrite@8+0x26e
QIC117!_cqd_DispatchFRB@8+0x210
QIC117!_cqd_ProcessFRB@8+0x134
QIC117!_kdi_ThreadRun@4+0xa9
NT!_PspSystemThreadStartup@8+0x40

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1F: SHARED_RESOURCE_CONV_ERROR

The SHARED_RESOURCE_CONV_ERROR bug check has a value of 0x0000001F.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x20: KERNEL_APC_PENDING_DURING_EXIT

The KERNEL_APC_PENDING_DURING_EXIT bug check has a value of 0x00000020. This indicates that an asynchronous procedure call (APC) was still pending when a
thread exited.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the APC found pending during exit
2
The thread's APC disable count
3
The current IRQL
4
Reserved
Cause
The key data item is the APC disable count (Parameter 2) for the thread. If the count is nonzero, it will indicate the source of the problem.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 807 of 1651

The APC disable count is decremented each time a driver calls KeEnterCriticalRegion, FsRtlEnterFileSystem, or acquires a mutex.
The APC disable count is incremented each time a driver calls KeLeaveCriticalRegion, KeReleaseMutex, or FsRtlExitFileSystem.
Because these calls should always be in pairs, the APC disable count should be zero when a thread exits. A negative value indicates that a driver has disabled APC calls
without re-enabling them. A positive value indicates that the reverse is true.
If you ever see this error, be very suspicious of all drivers installed on the machine especially unusual or non-standard drivers.
This current IRQL (Parameter 3) should be zero. If it is not, the driver's cancellation routine may have caused this bug check by returning at an elevated IRQL. In this case,
carefully note what was running (and what was closing) at the time of the crash, and note all of the installed drivers at the time of the crash. The cause in this case is usually a
severe bug in a driver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x21: QUOTA_UNDERFLOW

The QUOTA_UNDERFLOW bug check has a value of 0x00000021. This indicates that quota charges have been mishandled by returning more quota to a particular block
than was previously charged.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The process that was initially charged, if available.
2
The quota type. For the list of all possible quota type values, see the header file Ps.h in the Windows Driver Kit (WDK).
3
The initial charged amount of quota to return.
4
The remaining amount of quota that was not returned.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x22: FILE_SYSTEM

The FILE_SYSTEM bug check has a value of 0x00000022.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x23: FAT_FILE_SYSTEM

The FAT_FILE_SYSTEM bug check has a value of 0x00000023. This indicates that a problem occurred in the FAT file system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
If FatExceptionFilter is on the stack, this parameter specifies the address of the exception record.
3
If FatExceptionFilter is on the stack, this parameter specifies the address of the context record.
4
Reserved
Cause
One possible cause of this bug check is disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted SCSI and IDE drivers
can also adversely affect the system's ability to read and write to the disk, thus causing the error.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 808 of 1651

Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the
indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a disk corruption problem: Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help
pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You
should also run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. Run Chkdsk /f /r to
detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition.
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x24: NTFS_FILE_SYSTEM

The NTFS_FILE_SYSTEM bug check has a value of 0x00000024. This indicates a problem occurred in ntfs.sys, the driver file that allows the system to read and write to
NTFS drives.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
If NtfsExceptionFilter is on the stack, this parameter specifies the address of the exception record.
3
If NtfsExceptionFilter is on the stack, this parameter specifies the address of the context record.
4
Reserved
Cause
One possible cause of this bug check is disk corruption. Corruption in the NTFS file system or bad blocks (sectors) on the hard disk can induce this error. Corrupted SCSI and
IDE drivers can also adversely affect the system's ability to read and write to disk, thus causing the error.
Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the
indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a disk corruption problem: Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help
pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You
should also run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. Run Chkdsk /f /r to
detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition.
To resolve a nonpaged pool memory depletion problem: Either add new physical memory to the computer (thus increasing the quantity of nonpaged pool memory available to
the kernel), or reduce the number of files on the Services for Macintosh (SFM) volume.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x25: NPFS_FILE_SYSTEM

The NPFS_FILE_SYSTEM bug check has a value of 0x00000025. This indicates that a problem occurred in the NPFS file system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
Reserved

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

3
4

Page 809 of 1651

Reserved
Reserved

Cause
One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However,
during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this
error.
Resolving the Problem
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x26: CDFS_FILE_SYSTEM

The CDFS_FILE_SYSTEM bug check has a value of 0x00000026. This indicates that a problem occurred in the CD file system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
If CdExceptionFilter is on the stack, this parameter specifies the address of the exception record.
3
If CdExceptionFilter is on the stack, this parameter specifies the address of the context record.
4
Reserved
Cause
One possible cause of this bug check is disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted SCSI and IDE drivers
can also adversely affect the system's ability to read and write to the disk, thus causing the error.
Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However, during the
indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this error.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a disk corruption problem: Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help
pinpoint the device or driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You
should also run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer. Run Chkdsk /f /r to
detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition.
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x27: RDR_FILE_SYSTEM

The RDR_FILE_SYSTEM bug check has a value of 0x00000027. This indicates that a problem occurred in the SMB redirector file system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The high 16 bits (the first four hexadecimal digits after the "0x") identify the type of problem. Possible values include:
0xCA550000 RDBSS_BUG_CHECK_CACHESUP
0xC1EE0000 RDBSS_BUG_CHECK_CLEANUP

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 810 of 1651

0xC10E0000 RDBSS_BUG_CHECK_CLOSE
0xBAAD0000 RDBSS_BUG_CHECK_NTEXCEPT

2
3
4

If RxExceptionFilter is on the stack, this parameter specifies the address of the exception record.
If RxExceptionFilter is on the stack, this parameter specifies the address of the context record.
Reserved

Cause
One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However,
during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this
error.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x28: CORRUPT_ACCESS_TOKEN

The CORRUPT_ACCESS_TOKEN bug check has a value of 0x00000028.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x29: SECURITY_SYSTEM

The SECURITY_SYSTEM bug check has a value of 0x00000029.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2A: INCONSISTENT_IRP

The INCONSISTENT_IRP bug check has a value of 0x0000002A. This indicates that an IRP was found to contain inconsistent information.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the IRP that was found to be inconsistent
2
Reserved
3
Reserved
4
Reserved
Cause
An IRP was discovered to be in an inconsistent state. Usually this means some field of the IRP was inconsistent with the remaining state of the IRP. An example would be an
IRP that was being completed, but was still marked as being queued to a driver's device queue.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 811 of 1651

Comments
This bug check code is not currently being used in the system, but exists for debugging purposes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2B: PANIC_STACK_SWITCH

The PANIC_STACK_SWITCH bug check has a value of 0x0000002B. This indicates that the kernel mode stack was overrun.
Parameters
The following parameters are displayed on the blue screen.
Parameter Description
The trap frame
1
2
Reserved
3
Reserved
4
Reserved
Cause
This error normally appears when a kernel-mode driver uses too much stack space. It can also appear when serious data corruption occurs in the kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2C: PORT_DRIVER_INTERNAL

The PORT_DRIVER_INTERNAL bug check has a value of 0x0000002C.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2D: SCSI_DISK_DRIVER_INTERNAL

The SCSI_DISK_DRIVER_INTERNAL bug check has a value of 0x0000002D.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2E: DATA_BUS_ERROR

The DATA_BUS_ERROR bug check has a value of 0x0000002E. This typically indicates that a parity error in system memory has been detected.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Virtual address that caused the fault
2
Physical address that caused the fault

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

3
4

Page 812 of 1651

Processor status register (PSR)

Faulting instruction register (FIR)

Cause
This error is almost always caused by a hardware problem a configuration issue, defective hardware, or incompatible hardware.
The most common hardware problems that can cause this error are defective RAM, Level 2 (L2) RAM cache errors, or video RAM errors. Hard disk corruption can also cause
this error.
This bug check can also be caused when a device driver attempts to access an address in the 0x8xxxxxxx range that does not exist (in other words, that does not have a physical
address mapping).
Resolving the Problem
Resolving a hardware problem: If hardware has recently been added to the system, remove it to see if the error recurs.
If existing hardware has failed, remove or replace the faulty component. You should run hardware diagnostics supplied by the system manufacturer to determine which
hardware component has failed. For details on these procedures, see the owner's manual for your computer. Check that all adapter cards in the computer are properly seated.
Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure that adapter card contacts are clean.
If the problem occurs on a newly installed system, check the availability of updates for the BIOS, the SCSI controller or network cards. Updates of this kind are typically
available on the Web site or the bulletin board system (BBS) of the hardware manufacturer.
If the error occurs after installing a new or updated device driver, the driver should be removed or replaced. If, under this circumstance, the error occurs during startup and the
system partition is formatted with NTFS, you might be able to use Safe Mode to rename or delete the faulty driver.
If the driver is used as part of the system startup process in Safe Mode, you need to start the computer using the Recovery Console in order to access the file.
For additional error messages that might help pinpoint the device or driver that is causing the error, check the System Log in Event Viewer. Disabling memory caching or
shadowing in the BIOS might also resolve this error. In addition, check the system for viruses, using any up-to-date commercial virus scanning software that examines the
Master Boot Record of the hard disk. All Windows file systems can be infected by viruses.
Resolving a hard disk corruption problem: Run Chkdsk /f /r on the system partition. You must restart the system before the disk scan begins. If you cannot start the system
due to the error, use the Recovery Console and run Chkdsk /r.
Warning If your system partition is formatted with the file allocation table (FAT) file system, the long filenames used by Windows can be damaged if Scandisk or another
Microsoft MS-DOS-based hard disk tool is used to verify the integrity of your hard disk from MS-DOS. Always use the version of Chkdsk that matches your Windows
version.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x2F: INSTRUCTION_BUS_ERROR

The INSTRUCTION_BUS_ERROR bug check has a value of 0x0000002F.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x30: SET_OF_INVALID_CONTEXT

The SET_OF_INVALID_CONTEXT bug check has a value of 0x00000030. This indicates that the stack pointer in a trap frame had an invalid value.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The new stack pointer
2
The old stack pointer
3
The trap frame address
4
0
Cause
This bug check occurs when some routine attempts to set the stack pointer in the trap frame to a lower value than the current stack pointer value.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 813 of 1651

If this error were not caught, it would cause the kernel to run with a stack pointer pointing to stack which is no longer valid.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x31: PHASE0_INITIALIZATION_FAILED

The PHASE0_INITIALIZATION_FAILED bug check has a value of 0x00000031. This indicates that system initialization failed.
Parameters
None
Cause
System initialization failed at a very early stage.
Resolving the Problem
A debugger is required to analyze this.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x32: PHASE1_INITIALIZATION_FAILED

The PHASE1_INITIALIZATION_FAILED bug check has a value of 0x00000032. This indicates that system initialization failed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The NT status code that describes why the system initialization failed
2
Reserved
3
Reserved
4
Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x33: UNEXPECTED_INITIALIZATION_CALL

The UNEXPECTED_INITIALIZATION_CALL bug check has a value of 0x00000033.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x34: CACHE_MANAGER

The CACHE_MANAGER bug check has a value of 0x00000034. This indicates that a problem occurred in the file system's cache manager.
Parameters
The following parameters are displayed on the blue screen.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 814 of 1651

Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
Reserved
3
Reserved
4
Reserved
Cause
One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However,
during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this
error.
Resolving the Problem
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x35: NO_MORE_IRP_STACK_LOCATIONS

The NO_MORE_IRP_STACK_LOCATIONS bug check has a value of 0x00000035. This bug check occurs when the IoCallDriver packet has no more stack locations
remaining.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Address of the IRP
2
Reserved
3
Reserved
4
Reserved
Cause
A higher-level driver has attempted to call a lower-level driver through the IoCallDriver interface, but there are no more stack locations in the packet. This will prevent the
lower-level driver from accessing its parameters.
This is a disastrous situation, since the higher level driver is proceeding as if it has filled in the parameters for the lower level driver (as required). But since there is no stack
location for the latter driver, the former has actually written off the end of the packet. This means that some other memory has been corrupted as well.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x36: DEVICE_REFERENCE_COUNT_NOT_ZERO

The DEVICE_REFERENCE_COUNT_NOT_ZERO bug check has a value of 0x00000036. This indicates that a driver attempted to delete a device object that still had a
positive reference count.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the device object
2
Reserved
3
Reserved
4
Reserved
Cause
A device driver has attempted to delete one of its device objects from the system, but the reference count for that object was non-zero.
This means there are still outstanding references to the device. (The reference count indicates the number of reasons why this device object cannot be deleted.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 815 of 1651

This is a bug in the calling device driver.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x37: FLOPPY_INTERNAL_ERROR

The FLOPPY_INTERNAL_ERROR bug check has a value of 0x00000037.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x38: SERIAL_DRIVER_INTERNAL

The SERIAL_DRIVER_INTERNAL bug check has a value of 0x00000038.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x39: SYSTEM_EXIT_OWNED_MUTEX

The SYSTEM_EXIT_OWNED_MUTEX bug check has a value of 0x00000039. This indicates that the worker routine returned without releasing the mutex object that it
owned.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the worker routine that caused the error.
2
The parameter passed to the worker routine.
3
The address of the work item.
4
Reserved.
Cause
The worker routine returned while it still owned a mutex object. The current worker thread will proceed to run other unrelated work items, and the mutex will never be
released.
Resolving the Problem
A debugger is required to analyze this problem. To find the driver that caused the error, use the ln (List Nearest Symbols) debugger command:
kd> ln address
Where address is the worker routine given in Parameter 1.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3A: SYSTEM_UNWIND_PREVIOUS_USER

The SYSTEM_UNWIND_PREVIOUS_USER bug check has a value of 0x0000003A.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 816 of 1651

This bug check appears very infrequently.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3B: SYSTEM_SERVICE_EXCEPTION

The SYSTEM_SERVICE_EXCEPTION bug check has a value of 0x0000003B. This indicates that an exception happened while executing a routine that transitions from
non-privileged code to privileged code.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The exception that caused the bug check
2
The address of the exception record for the exception that caused the bug check
3
The address of the context record for the exception that caused the bug check
4
0
Cause
This error has been linked to excessive paged pool usage and may occur due to user-mode graphics drivers crossing over and passing bad data to the kernel code.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3C: INTERRUPT_UNWIND_ATTEMPTED

The INTERRUPT_UNWIND_ATTEMPTED bug check has a value of 0x0000003C.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3D: INTERRUPT_EXCEPTION_NOT_HANDLED

The INTERRUPT_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000003D.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3E:

MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED
The MULTIPROCESSOR_CONFIGURATION_NOT_SUPPORTED bug check has a value of 0x0000003E. This indicates that the system has multiple processors, but they
are asymmetric in relation to one another.
Parameters
None
Cause

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 817 of 1651

In order to be symmetric, all processors must be of the same type and level. This system contains processors of different types (for example, a Pentium processor and an
80486 processor).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x3F: NO_MORE_SYSTEM_PTES

The NO_MORE_SYSTEM_PTES bug check has a value of 0x0000003F. This is the result of a system which has performed too many I/O actions. This has resulted in
fragmented system page table entries (PTE).
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
0: system expansion PTE type
1: nonpaged pool expansion PTE type
2
3
4

Size of memory request

Total free system PTEs
Total system PTEs

Cause
In almost all cases, the system is not actually out of PTEs. Rather, a driver has requested a large block of memory, but there is no contiguous block of sufficient size to satisfy
this request.
Often video drivers will allocate large amounts of kernel memory that must succeed. Some backup programs do the same.
Resolving the Problem
A possible work-around: Modify the registry to increase the total number of system PTEs. If this does not help, remove any recently-installed software, especially backup
utilities or disk-intensive applications.
Debugging the problem: The following method can be used to debug bug check 0x3F.
First, get a stack trace, and use the !sysptes 3 extension command.
Then set HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\TrackPtes equal to DWORD 1, and reboot. This
will cause the system to save stack traces.
This allows you to display more detailed information about the PTE owners. For example:
0: kd> !sysptes 4
0x2c47 System PTEs allocated to mapping locked pages
VA
f0e5db48
f0c3fe48
f0db38e8
f8312568
f8363908
f0c54248
f0ddf448
f150bc08
f1392308
eb1bee64
f139b5a8
eb41f400
eb41f198
eb41f1e4
......

MDL
PageCount
eb6ceef0
1
eb634bf0
1
eb65b880
1
eb6df880
1
eb685880
1
eb640880
1
eb5f3160
1
eb6367b0
1
eb6fba70
1
edac5000
200
edd4b000
12
ede92000
20
edf2a000
20
eb110000
10

Caller/CallersCaller
ntkrpamp!MmMapLockedPages+0x15/ntkrpamp!IopfCallDriver+0x35
netbt!NbtTdiAssociateConnection+0x1f/netbt!DelayedNbtProcessConnect+0x17c
mrxsmb!SmbMmAllocateSessionEntry+0x89/mrxsmb!SmbCepInitializeExchange+0xda
rdbss!RxCreateFromNetRoot+0x3d7/rdbss!RxCreateFromNetRoot+0x93
mrxsmb!SmbMmAllocateSessionEntry+0x89/mrxsmb!SmbCepInitializeExchange+0xda
rdbss!RxCreateFromNetRoot+0x3d7/rdbss!RxCreateFromNetRoot+0x93
mrxsmb!MrxSmbUnalignedDirEntryCopyTail+0x387/mrxsmb!MRxSmbCoreInformation+0x36
mrxsmb!MrxSmbUnalignedDirEntryCopyTail+0x387/mrxsmb!MRxSmbCoreInformation+0x36
netbt!NbtTdiOpenAddress+0x1fb/netbt!DelayedNbtProcessConnect+0x17c
VIDEOPRT!pVideoPortGetDeviceBase+0x118/VIDEOPRT!VideoPortMapMemory+0x45
rdbss!FsRtlCopyWrite2+0x34/rdbss!RxDriverEntry+0x149
VIDEOPRT!pVideoPortGetDeviceBase+0x139/VIDEOPRT!VideoPortGetDeviceBase+0x1b
NDIS!NdisReadNetworkAddress+0x3a/NDIS!NdisFreeSharedMemory+0x58
VIDEOPRT!pVideoPortGetDeviceBase+0x139/VIDEOPRT!VideoPortGetDeviceBase+0x1b

If the system runs out of PTEs again after the TrackPtes registry value has been set, bug check 0xD8 (DRIVER_USED_EXCESSIVE_PTES) will be issued instead of 0x3F.
The name of the driver causing this error will be displayed as well.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x4B: STREAMS_INTERNAL_ERROR

The STREAMS_INTERNAL_ERROR bug check has a value of 0x0000004B.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x4C: FATAL_UNHANDLED_HARD_ERROR

The FATAL_UNHANDLED_HARD_ERROR bug check has a value of 0x0000004C.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x4D: NO_PAGES_AVAILABLE

The NO_PAGES_AVAILABLE bug check has a value of 0x0000004D. This indicates that no free pages are available to continue operations.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The total number of dirty pages
2
The number of dirty pages destined for the page file
3
Windows XP and Windows 2000: The size of the nonpaged pool available at the time the bug check occurred
Windows Server 2003 and later: Reserved
Windows 2000: The number of transition pages that are currently stranded

Windows XP and later: The most recent modified write error status.

Cause
To see general memory statistics, use the !vm 3 extension.
This bug check can occur for any of the following reasons:

A driver has blocked, deadlocking the modified or mapped page writers. Examples of this include mutex deadlocks or accesses to paged out memory in file system
drivers or filter drivers. This indicates a driver bug.
If Parameter 1 or Parameter 2 is large, then this is a possibility. Use !vm 3.

A storage driver is not processing requests. Examples of this are stranded queues and non-responding drives. This indicates a driver bug.
If Parameter 1 or Parameter 2 is large, then this is a possibility. Use !vm 8, followed by !process 0 7.

A high-priority realtime thread has starved the balance set manager from trimming pages from the working set, or starved the modified page writer from writing them
out. This indicates a bug in the component that created this thread.
This situation is difficult to analyze. Try using !ready. Try also !process 0 7 to list all threads and see if any have accumulated excessive kernel time as well as what
their current priorities are. Such processes may have blocked out the memory management threads from making pages available.

Windows XP and Windows 2000: Not enough pool is available for the storage stack to write out modified pages. This indicates a driver bug.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 822 of 1651

If Parameter 3 is small, then this is a possibility. Use !vm and !poolused 2.

Windows 2000: All the processes have been trimmed to their minimums and all modified pages written, but still no memory is available. The freed memory must be
stuck in transition pages with non-zero reference counts thus they cannot be put on the freelist.
A driver is neglecting to unlock the pages preventing the reference counts from going to zero which would free the pages. This may be due to transfers that never finish,
causing the driver routines to run endlessly, or to other driver bugs.
If Parameter 4 is large, then this is a possibility. But it is very hard to find the driver. Try the !process 0 1 extension and look for any drivers that have a lot of locked
pages.

If the problem cannot be found, then try booting with a kernel debugger attached from the beginning, and monitor the situation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x4E: PFN_LIST_CORRUPT

The PFN_LIST_CORRUPT bug check has a value of 0x0000004E. This indicates that the page frame number (PFN) list is corrupted.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of
Parameter 1.
Parameter
Parameter 2
1
0x01
The ListHead value that was
corrupted
0x02
The entry in the list that is being
removed
0x07
The page frame number

The number of pages

available
The highest physical page
number
The current share count

0x8F
0x99
0x9A

Old page number

Current page state
Current page state

New page number

Page frame number
Page frame number

Parameter 3

Parameter 4

Cause of Error

The list head was corrupt.

The reference count of the entry being

removed
0

A list entry was corrupt.

0
0
The reference count of the entry that is
being removed

A driver has unlocked a certain page more times

than it locked it.
The free or zeroed page listhead is corrupt.
A page table entry (PTE) or PFN is corrupt.
A driver attempted to free a page that is still locked
for IO.

Cause
This error is typically caused by a driver passing a bad memory descriptor list. For example, the driver might have called MmUnlockPages twice with the same list.
If a kernel debugger is available, examine the stack trace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x4F: NDIS_INTERNAL_ERROR

The NDIS_INTERNAL_ERROR bug check has a value of 0x0000004F.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x50: PAGE_FAULT_IN_NONPAGED_AREA

The PAGE_FAULT_IN_NONPAGED_AREA bug check has a value of 0x00000050. This indicates that invalid system memory has been referenced.
Parameters
The following parameters are displayed on the blue screen.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 823 of 1651

Parameter
Description
1
Memory address referenced
2
0: Read operation
1: Write operation
3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
Bug check 0x50 usually occurs after the installation of faulty hardware or in the event of failure of installed hardware (usually related to defective RAM, be it main memory,
L2 RAM cache, or video RAM).
Another common cause is the installation of a faulty system service.
Antivirus software can also trigger this error, as can a corrupted NTFS volume.
Resolving the Problem
Resolving a faulty hardware problem: If hardware has been added to the system recently, remove it to see if the error recurs. If existing hardware has failed, remove or replace
the faulty component. You should run hardware diagnostics supplied by the system manufacturer. For details on these procedures, see the owner's manual for your computer.
Resolving a faulty system service problem: Disable the service and confirm that this resolves the error. If so, contact the manufacturer of the system service about a possible
update. If the error occurs during system startup, restart your computer, and press F8 at the character-mode menu that displays the operating system choices. At the resulting
Windows Advanced Options menu, choose the Last Known Good Configuration option. This option is most effective when only one driver or service is added at a time.
Resolving an antivirus software problem: Disable the program and confirm that this resolves the error. If it does, contact the manufacturer of the program about a possible
update.
Resolving a corrupted NTFS volume problem: Run Chkdsk /f /r to detect and repair disk errors. You must restart the system before the disk scan begins on a system partition.
If the hard disk is SCSI, check for problems between the SCSI controller and the disk.
Finally, check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the error. Disabling memory caching
of the BIOS might also resolve it.
Comments
Typically, this address is in freed memory or is simply invalid.
This cannot be protected by a try - except handler it can only be protected by a probe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x51: REGISTRY_ERROR

The REGISTRY_ERROR bug check has a value of 0x00000051. This indicates that a severe registry error has occurred.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Reserved
2
Reserved
3
The pointer to the hive (if available)
4
If the hive is corrupt, the return code of HvCheckHive (if available)
Cause
Something has gone wrong with the registry. If a kernel debugger is available, get a stack trace.
This error may indicate that the registry encountered an I/O error while trying to read one of its files. This can be caused by hardware problems or file system corruption.
It may also occur due to a failure in a refresh operation, which is used only in by the security system, and then only when resource limits are encountered.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 824 of 1651

Debugging Tools for Windows

Bug Check 0x52: MAILSLOT_FILE_SYSTEM

The MAILSLOT_FILE_SYSTEM bug check has a value of 0x00000052.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x53: NO_BOOT_DEVICE

The NO_BOOT_DEVICE bug check has a value of 0x00000053.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x54: LM_SERVER_INTERNAL_ERROR

The LM_SERVER_INTERNAL_ERROR bug check has a value of 0x00000054.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x55: DATA_COHERENCY_EXCEPTION

The DATA_COHERENCY_EXCEPTION bug check has a value of 0x00000055.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x56: INSTRUCTION_COHERENCY_EXCEPTION

The INSTRUCTION_COHERENCY_EXCEPTION bug check has a value of 0x00000056.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x57: XNS_INTERNAL_ERROR

The XNS_INTERNAL_ERROR bug check has a value of 0x00000057.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 825 of 1651

This bug check appears very infrequently.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x58: FTDISK_INTERNAL_ERROR

The FTDISK_INTERNAL_ERROR bug check has a value of 0x00000058. This is issued if the system is booted from the wrong copy of a mirrored partition.
Parameters
None
Cause
The hives are indicating that the mirror is valid, but it is not. The hives should actually be pointing to the shadow partition.
This is almost always caused by the primary partition being revived.
Resolving the Problem
Reboot the system from the shadow partition.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x59: PINBALL_FILE_SYSTEM

The PINBALL_FILE_SYSTEM bug check has a value of 0x00000059. This indicates that a problem occurred in the Pinball file system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
Reserved
3
Reserved
4
Reserved
Cause
One possible cause of this bug check is depletion of nonpaged pool memory. If the nonpaged pool memory is completely depleted, this error can stop the system. However,
during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver requiring nonpaged pool memory can also trigger this
error.
Resolving the Problem
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5A: CRITICAL_SERVICE_FAILED

The CRITICAL_SERVICE_FAILED bug check has a value of 0x0000005A.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 826 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Bug Check 0x5B: SET_ENV_VAR_FAILED

The SET_ENV_VAR_FAILED bug check has a value of 0x0000005B.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5C: HAL_INITIALIZATION_FAILED

The HAL_INITIALIZATION_FAILED bug check has a value of 0x0000005C.
This indicates that the HAL initialization failed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5D: UNSUPPORTED_PROCESSOR

The UNSUPPORTED_PROCESSOR bug check has a value of 0x0000005D. This indicates that the computer is attempting to run Windows on an unsupported processor.
Parameters
None
Cause
Windows requires a higher-grade processor than the one you are using.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5E: OBJECT_INITIALIZATION_FAILED

The OBJECT_INITIALIZATION_FAILED bug check has a value of 0x0000005E.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x5F: SECURITY_INITIALIZATION_FAILED

The SECURITY_INITIALIZATION_FAILED bug check has a value of 0x0000005F.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 827 of 1651

Debugging Tools for Windows

Bug Check 0x60: PROCESS_INITIALIZATION_FAILED

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 831 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Bug Check 0x71: SESSION5_INITIALIZATION_FAILED

The SESSION5_INITIALIZATION_FAILED bug check has a value of 0x00000071. This bug check indicates that the initialization of the Microsoft Windows operating
system failed.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
The NT status code that caused the Windows operating system to conclude that initialization failed
2
0
3
0
4
0

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x72: ASSIGN_DRIVE_LETTERS_FAILED

The ASSIGN_DRIVE_LETTERS_FAILED bug check has a value of 0x00000072.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x73: CONFIG_LIST_FAILED

The CONFIG_LIST_FAILED bug check has a value of 0x00000073. This bug check indicates that one of the top-level registry keys, also known as core system hives, cannot
be linked in the registry tree.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
1
2
The NT status code that led the Windows operating system to assume that it failed to load the hive
3
The index of the hive in the hive list
4
A pointer to a UNICODE_STRING structure that contains the file name of the hive
Cause
The registry hive that cannot be linked might be SAM, SECURITY, SOFTWARE, or DEFAULT. The hive is valid, because it was loaded successfully.
Examine Parameter 2 to see why the hive could not be linked in the registry tree. One common cause of this error is that the Windows operating system is out of disk space on
the system drive. (In this situation, this parameter is 0xC000017D, STATUS_NO_LOG_SPACE.) Another common problem is that an attempt to allocate pool has failed. (In
this situation, Parameter 2 is 0xC000009A, STATUS_INSUFFICIENT_RESOURCES.) You must investigate other status codes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x74: BAD_SYSTEM_CONFIG_INFO

The BAD_SYSTEM_CONFIG_INFO bug check has a value of 0x00000074. This bug check indicates that there is an error in the registry.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 832 of 1651

Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
Reserved
2
Reserved
3
Reserved
4
The NT status code (if it is available)
Cause
The BAD_SYSTEM_CONFIG_INFO bug check occurs if the SYSTEM hive is corrupt. However, this corruption is unlikely, because the boot loader, known as NT Loader
(NTLDR) in versions of Windows prior to Vista, checks a hive for corruption when it loads the hive.
This bug check can also occur if some critical registry keys and values are missing. Thee keys and values might be missing if a user manually edited the registry.
Resolving the Problem
Try restarting the computer by selecting "last known good configuration" in the boot options.
If the restart does not fix the problem, the registry damage is too extensive. You must reinstall the OS or use the Emergency Repair Disk (ERD) that you previously created by
using the Windows Backup tool.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x75: CANNOT_WRITE_CONFIGURATION

The CANNOT_WRITE_CONFIGURATION bug check has a value of 0x00000075. This bug check indicates that the SYSTEM registry hive file cannot be converted to a
mapped file.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
1
2
The NT status code that led the Windows operating system to assume that it had failed to convert the hive
3
Reserved
4
Reserved
Cause
The CANNOT_WRITE_CONFIGURATION bug check typically occurs if the system is out of pool and the Windows operating system cannot reopen the hive.
This bug check should almost never occur, because the conversion of the hive file occurs early enough during system initialization so that enough pool should be available.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x76: PROCESS_HAS_LOCKED_PAGES

The PROCESS_HAS_LOCKED_PAGES bug check has a value of 0x00000076. This bug check indicates that a driver failed to release locked pages after an I/O operation, or
that it attempted to unlock pages that were already unlocked.
Parameters
The following parameters appear on the blue screen.
Parameter
Parameter 2
Parameter 3
1
0x00
The pointer to the The number of locked
process object
pages

Parameter 4

Cause of error

The pointer to driver stacks (if they are

The process being terminated has locked memory pages. The driver
enabled). Otherwise, this parameter is zero. must unlock any memory that it might have locked in a process,
before the process terminates.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x01

MDL specified by Current number of locked

the driver
memory pages in that
process

Page 833 of 1651

A pointer to driver stacks for that process

(if they are enabled). Otherwise, this
parameter is zero.

The driver is attempting to unlock process memory pages that are

not locked.

Cause
The driver either failed to unlock pages that it locked (parameter 1 value is 0x0), or the driver is attempting to unlock pages that have not been locked or that have already
been unlocked (parameter 1 value is 0x1).
Resolving the Problem
If the parameter 1 value is 0x0
First use the !search extension on the current process pointer throughout all of physical memory. This extension might find at least one memory descriptor list (MDL) that
points to the current process. Next, use !search on each MDL that you find to obtain the I/O request packet (IRP) that points to the current process. From this IRP, you can
identify which driver is leaking the pages.
Otherwise, you can detect which driver caused the error by editing the registry:
1. In the \\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management registry key, create or edit the
TrackLockedPages value, and then set it equal to DWORD 1.
2. Restart the computer.
The system then saves stack traces, so you can easily identify the driver that caused the problem. If the driver causes the same error again, bug check 0xCB
(DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS) is issued, and the name of the driver that causes this error is displayed on the blue screen and stored in memory at the
location (PUNICODE_STRING) KiBugCheckDriver.
If the parameter 1 value is 0x1
Examine the driver source code that locks and unlocks memory, and try to locate an instance where memory is unlocked without first being locked.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x77: KERNEL_STACK_INPAGE_ERROR

The KERNEL_STACK_INPAGE_ERROR bug check has a value of 0x00000077. This bug check indicates that the requested page of kernel data from the paging file could
not be read into memory.
Parameters
The four parameters that listed in the message have two possible meanings.
If the first parameter is 0, 1, or 2, the parameters have the following meaning.
Parameter
Description
1
0: The page of kernel data was retrieved from page cache.
1: The page was retrieved from a disk.
2: The page was retrieved from a disk, the storage stack returned SUCCESS, but Status.Information is not equal to PAGE_SIZE.
2
3
4

The value that appears in the stack where the signature should be.
0
The address of the signature on the kernel stack

If the first parameter is any value other than 0, 1, or 2, the parameters have the following meaning.
Parameter
Description
1
The status code
2
The I/O status code
3
The page file number
4
The offset into page file
Cause
If the first parameter is 0 or 1, the stack signature in the kernel stack was not found. This error is probably caused by defective hardware, such as a RAM error.
If the first parameter is 2, the driver stack returned an inconsistent status for the read of the page. For example, the driver stack returned a success status even though it did not
read the whole page.
If the first parameter is any value other than 0, 1, or 2, the value of the first parameter is an NTSTATUS error code that the driver stack returns after it tries to retrieve the page
of kernel data. You can determine the exact cause of this error from the I/O status code (the second parameter). Some common status codes include the following:

0xC000009A, or STATUS_INSUFFICIENT_RESOURCES, indicates a lack of nonpaged pool resources. This status code indicates a driver error in the storage stack.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 834 of 1651

(The storage stack should always be able to retrieve this data, regardless of software resource availability.)
0xC000009C, or STATUS_DEVICE_DATA_ERROR, indicates bad blocks (sectors) on the hard disk.
0xC000009D, or STATUS_DEVICE_NOT_CONNECTED, indicates defective or loose cabling, termination, or that the controller does not see the hard disk drive.
0xC000016A, or STATUS_DISK_OPERATION_FAILED, indicates bad blocks (sectors) on the hard disk.
0xC0000185, or STATUS_IO_DEVICE_ERROR, indicates improper termination or defective cabling on SCSI devices or that two devices are trying to use the same
IRQ.

These status codes are the most common ones that have specific causes. For more information about other possible status codes that might be returned, see the Ntstatus.h file
in the Microsoft Windows Driver Kit (WDK).
A virus infection can also cause this bug check.
Resolving the Problem
Resolving a bad block problem: If you can restart the computer after the error, Autochk runs automatically and attempts to map the bad sector to prevent it from being used
anymore.
If Autochk does not scan the hard disk for errors, you can manually start the disk scanner. Run Chkdsk /f /r on the system partition. You must restart the computer before the
disk scan begins. If you cannot start the system because the error, use the Recovery Console and run Chkdsk /r.
Warning If your system partition is formatted with the FAT file system, the long file names that the Windows operating system uses might be damaged if you use Scandisk
or another MS-DOS-based hard disk tool to verify the integrity of your hard disk drive from MS-DOS. Always use the version of Chkdsk that matches your version of the
Windows operating system.
Resolving a defective hardware problem: If the I/O status is 0xC0000185 and the paging file is on an SCSI disk, check the disk cabling and SCSI termination for problems.
Resolving a failing RAM problem: Run the hardware diagnostics that the system manufacturer supplies, especially the memory scanner. For more information about these
procedures, see the owner's manual for your computer.
Check that all the adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure
adapter card contacts are clean.
Check the System Log in Event Viewer for additional error messages that might help identify the device that is causing the error. You can also disable memory caching of the
BIOS to try to resolve this error.
Make sure that the latest Windows Service Pack is installed.
If the preceding steps fail to resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective component on
the motherboard can cause this error.
Resolving a virus infection: Check your computer for viruses by using any up-to-date, commercial virus scanning software that examines the Master Boot Record of the hard
disk. All Windows file systems can be infected by viruses.
See Also
Bug Check 0x7A (KERNEL_DATA_INPAGE_ERROR)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x78: PHASE0_EXCEPTION

The PHASE0_EXCEPTION bug check has a value of 0x00000078.
This bug check occurs when an unexpected break is encountered during HAL initialization. This break can occur if you have set the /break parameter in your boot settings
but have not enabled kernel debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x79: MISMATCHED_HAL

The MISMATCHED_HAL bug check has a value of 0x00000079. This bug check indicates that the Hardware Abstraction Layer (HAL) revision level or configuration does
not match that of the kernel or the computer.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of mismatch.
Parameter
1

Parameter 2

Parameter 3

Parameter 4

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Cause.

9/18/2010

Introduction

0x1

The major processor control block

(PRCB) level of Ntoskrnl.exe.
The build type of Ntoskrnl.exe.
The size of the loader parameter
extension.

0x2
0x3

Page 835 of 1651

The major PRCB level of Hal.dll. Reserved

The build type of Hal.dll.
The major version of the loader
parameter extension.

Reserved
The minor version of the loader
parameter extension.

The PRCB release levels are mismatched.

(Something is out of date.)
The build types are mismatched.
The loader (ntldr) and HAL versions are
mismatched.

When Parameter 1 equals 0x2, the following build type codes are used:

0: Multiprocessor-enabled free build

1: Multiprocessor-enabled checked build
2: Single-processor free build
3: Single-processor checked build

Cause
The MISMATCHED_HAL bug check often occurs when a user manually updates Ntoskrnl.exe or Hal.dll.
The error can also indicate that one of those two files is out of date. For example, the HAL might be designed for Microsoft Windows 2000 and the kernel is designed for
Windows XP. Or the computer might erroneously have a multiprocessor HAL and a single-processor kernel installed, or vice versa.
The Ntoskrnl.exe kernel file is for single-processor systems and Ntkrnlmp.exe is for multiprocessor systems. However, these file names correspond to the files on the
installation media.After you have installed the Windows operating system, the file is renamed to Ntoskrnl.exe, regardless of the source file that is used. The HAL file also uses
the name Hal.dll after installation, but there are several possible HAL files on the installation media. For more information, see "Installing the Checked Build" in the
Windows Driver Kit (WDK).
Resolving the Problem
Restart the computer by using the product CD or the Windows Setup disks. At the Welcome screen, press F10 to start the Recovery Console. Use the Copy command to copy
the correct HAL or kernel file from the original CD into the appropriate folder on the hard disk. The Copy command detects whether the file that you are copying is in the
Microsoft compressed file format. If so, it automatically expands the file that is copied on the target drive.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x7A: KERNEL_DATA_INPAGE_ERROR

The KERNEL_DATA_INPAGE_ERROR bug check has a value of 0x0000007A. This bug check indicates that the requested page of kernel data from the paging file could
not be read into memory.
Parameters
The four parameters that are listed in the message can have three possible meanings. If the first parameter is 1 or 2, or 3 and the third parameter is 0, the parameters have the
following definitions.
Parameter
Description
1
The lock type that was held (1, 2, or 3)
2
The error status (usually an I/O status code)
3
If Lock Type is 1: the current process
If Lock Type is 2 or 3: 0
4

The virtual address that could not be paged into memory

If the first parameter is 3 (and the third parameter is nonzero) or 4, the parameters have the following definitions.
Parameter
Description
1
The lock type that was held (3 or 4)
2
The error status (typically an I/O status code)
3
The address of the InPageSupport structure
4
The faulting address
Otherwise, the parameters have the following definitions.
Parameter
Description
1
The address of the page table entry (PTE)
2
The error status (usually an I/O status code)
3
The PTE contents
4
The faulting address
Cause
Frequently, you can determine the cause of the KERNEL_DATA_INPAGE_ERROR bug check from the error status (Parameter 2). Some common status codes include the
following:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 836 of 1651

0xC000009A, or STATUS_INSUFFICIENT_RESOURCES, indicates a lack of nonpaged pool resources.

0xC000009C, or STATUS_DEVICE_DATA_ERROR, typically indicates bad blocks (sectors) on the hard disk.
0xC000009D, or STATUS_DEVICE_NOT_CONNECTED, indicates defective or loose cabling, termination, or that the controller does not see the hard disk.
0xC000016A, or STATUS_DISK_OPERATION_FAILED, indicates bad blocks (sectors) on the hard disk.
0xC0000185, or STATUS_IO_DEVICE_ERROR, indicates improper termination or defective cabling on SCSI devices or that two devices are trying to use the same
IRQ.

These status codes are the most common ones that have specific causes. For more information about other possible status codes that can be returned, see the Ntstatus.h file in
the Microsoft Windows Driver Kit (WDK).
Another common cause of this error message is defective hardware or failing RAM.
A virus infection can also cause this bug check.
Resolving the Problem
Resolving a bad block problem: An I/O status code of 0xC000009C or 0xC000016A typically indicates that the data could not be read from the disk because of a bad block
(sector). If you can restart the computer after the error, Autochk runs automatically and attempts to map the bad sector to prevent it from being used anymore.
If Autochk does not scan the hard disk for errors, you can manually start the disk scanner. Run Chkdsk /f /r on the system partition. You must restart the computer before the
disk scan begins. If you cannot start the computer because of the error, use the Recovery Console and run Chkdsk /r.
Warning If your system partition is formatted with the FAT file system, the long file names that the Windows operating system uses might be damaged if you use Scandisk
or another MS-DOS-based hard disk tool to verify the integrity of your hard disk from MS-DOS. Always use the version of Chkdsk that matches your version of Windows.
Resolving a defective hardware problem: If the I/O status is C0000185 and the paging file is on an SCSI disk, check the disk cabling and SCSI termination for problems.
Resolving a failing RAM problem: Run the hardware diagnostics that the system manufacturer supplies, especially the memory scanner. For more information about these
procedures, see the owner's manual for your computer.
Check that all the adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores, to ensure
adapter card contacts are clean.
Check the System Log in Event Viewer for additional error messages that might help identify the device that is causing the error. You can also disable memory caching of the
BIOS to try to resolve this error.
Make sure that the latest Windows Service Pack is installed.
If the preceding steps do not resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective component on
the motherboard can cause this error.
Resolving a virus infection: Check your computer for viruses by using any up-to-date, commercial virus scanning software that examines the Master Boot Record of the hard
disk. All Windows file systems can be infected by viruses.
See Also
Bug Check 0x77 (KERNEL_STACK_INPAGE_ERROR)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x7B: INACCESSIBLE_BOOT_DEVICE

The INACCESSIBLE_BOOT_DEVICE bug check has a value of 0x0000007B. This bug check indicates that the Microsoft Windows operating system has lost access to the
system partition during startup.
Parameters
The following parameters appear in the message.
Parameter
Description
1
The address of a UNICODE_STRING structure, or the address of the device object that could not be mounted
2
0
3
0
4
0
To determine the meaning of Parameter 1, look at the data that it points to. If the first word (USHORT) at this address is even, Parameter 1 is the beginning of a Unicode
string. If the first word (USHORT) at this address is 0x3, Parameter 1 is the first field (Type) of a device object.

If this parameter points to a device object, the file system that was supposed to read the boot device failed to initialize or simply did not recognize the data on the boot
device as a file system structure. In this situation, the specified device object is the object that could not be mounted.
If this parameter points to a Unicode string, you must read the first 8 bytes at this address. These bytes form the UNICODE_STRING structure, which is defined as
follows:
USHORT Length;
USHORT MaximumLength;

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 837 of 1651

PWSTR Buffer;
The Length field gives the actual length of the string. The Buffer field points to the beginning of the string (Buffer is always be at least 0x80000000.)
The actual string contains the Advanced RISC Computing (ARC) specification name of the device that the boot was being attempted from. ARC names are a generic
way to identify devices in the ARC environment.
Cause
The INACCESSIBLE_BOOT_DEVICE bug check frequently occurs because of a boot device failure. During I/O system initialization, the boot device driver might have
failed to initialize the boot device (typically a hard disk). File system initialization might have failed because it did not recognize the data on the boot device. Also,
repartitioning the system partition or installing a new SCSI adapter or disk controller might induce this error.
This error can also occur because of incompatible disk hardware. If the error occurred at the initial setup of the system, the system might have been installed on an
unsupported disk or SCSI controller. Some controllers are supported only by drivers that are in the Windows Driver Library (WDL). (These drivers require the user to do a
custom installation.)
Resolving the Problem
This error always occurs while the system is starting. This error frequently occurs before the debugger connection is established, so debugging can be difficult or impossible.
Resolving a failed boot device problem: If a boot device is at fault, you must edit the boot options.For more information about changing these options, see Configuring
Software on the Target Computer .
Resolving an incompatible disk hardware problem: If Setup autodetects the controller, you might have to skip detection and use a specific manufacturer's disk to load the
driver. Also, check the availability of updates for the system BIOS and SCSI controller firmware. Updates of this kind are typically available on the Web site or BBS of the
hardware manufacturer.
Remove any recently added hardware, especially hard disk drives or controllers, to see if the error is resolved. If the problematic hardware is a hard disk drive, the disk
firmware version might be incompatible with your version of the Windows operating system. Contact the manufacturer for updates. If you removed another piece of hardware
and the error is resolved, IRQ or I/O port conflicts likely exist. Reconfigure the new device according to the manufacturer's instructions.
Confirm that all hard disk drivers, hard disk controllers, and SCSI adapters are listed in the Microsoft Windows Marketplace Tested Products List.
If you recently added a driver, restart your computer, and press F8 at the character-based menu that displays the operating system choices. In the Advanced Options menu,
select the Last Known Good Configuration option. This option is most effective when you add only one driver or service at a time.
In addition, check your computer for viruses by using any up-to-date, commercial virus scanning software that examines the Master Boot Record of the hard disk. All
Windows file systems can be infected by viruses.
This error can also occur because of hard disk corruption. Run Chkdsk /f /r on the system partition. You must restart the computer before the disk scan begins. If you cannot
start the computer because of the error, use the Recovery Console and run Chkdsk /r.
If you cannot start the system in the last known good configuration, you should try to start off the Windows CD. Then, you can run Chkdsk from the Repair Console.
Warning If your system partition is formatted with the FAT file system, the long file names that the Windows operating system uses might be damaged if you use Scandisk
or another MS-DOS-based hard disk tool to verify the integrity of your hard disk drive from MS-DOS. Always use the version of Chkdsk that matches your version of
Windows.
If your system has SCSI adapters, contact the adapter manufacturer to obtain updated Windows drivers. Try disabling sync negotiation in the SCSI BIOS, checking the
cabling and the SCSI IDs of each device, and confirming proper termination. For IDE devices, define the onboard IDE port as Primary only. Also check each IDE device for
the proper master/subordinate/stand alone setting. Try removing all IDE devices except for hard disks. Finally, check the System Log in Event Viewer for additional error
messages that might help identify the device or driver that is causing the error.
To analyze this error: Run an lm (List Loaded Modules) command in the debugger. Verify that the following drivers were loaded: disk, classpnp, ftdisk, partmgr, and FAT
or NTFS.
kd> lm
start
80001000
80016000
80019000
8001e000
80086000
802c1000
802cc000
802d4000
802ed000
802f4000
802fb000
802fe000
8039b000
803b8000
803cb000
803d2000
803d9000
80400000
80540000
80547000
80555000

end
80016000
80018c40
8001dfc0
8001ff60
80086980
802cc000
802d39a0
802ed000
802f3820
802fad40
802fdc20
802fef00
803b8000
803cb000
803d1560
803d8e80
803fa000
80540000
80546f20
80554620
80579000

module name
hal
bootvid
pciidex
dmload
pciide
pci
isapnp
ftdisk
mountmgr
fdc
partmgr
wmilib
dmio
atapi
disk
classpnp
fastfat
nt
ksecdd
cnss
ndis

(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(deferred)
(pdb symbols)
(deferred)
(deferred)
(deferred)

\\localsymbols\symbols\exe\ntoskrnl.dbg

You probably have pci or isapnp loaded. Also make sure your controller drivers are loaded. That is, make sure Atapi.sys is loaded with the channel drivers (pciide and pciidex

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 838 of 1651

or intelid) or scsiport.sys is loaded with the appropriate miniport driver.

It is helpful to know as much as possible about the boot device that Windows is installed on. For example, you can investigate the following items:

Find out what type of controller the boot device is connected to (SCSI, IDE, 1394, etc). Find the manufacturer of non-IDE controllers (Adaptec, Symbios, and so on).
Note the SCSI ID of the boot device if you are using SCSI.
Indicate if other devices are attached to the same controller that the boot device is on (CD-ROM drives, zip drives, and so on).
Note the file system that is used on the drive.

The !devnode extension gives you more information, if you know what your boot devices are.
Typically Plug and Play cannot assign resources to the boot device. You can verify this restriction by finding an entry for the service. If the status flags include
DNF_INSUFFICIENT_RESOURCES or do not include DNF_STARTED or DNF_ENUMERATED, you have found the problem. Try !devnode 0 1 scsi or !
devnode 0 1 atapi to save some time instead of dumping the whole device tree.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x7C: BUGCODE_NDIS_DRIVER

The BUGCODE_NDIS_DRIVER bug check has a value of 0x0000007C. This bug check indicates that a problem occurred with an NDIS driver.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1.
Parameter 2
Parameter
1
0x01
The address of the miniport
block
0x02
The address of the miniport
block

Parameter 3
The number of bytes that are
requested
The shared memory page that was
corrupted

0x03

The address of the miniport

block

The page that contains the shared

memory

0x04

The address of
The address of DRIVER_OBJECT
NDIS_M_DRIVER_BLOCK

Parameter 4

Cause of Error

A driver called NdisMAllocateSharedMemory at a

raised IRQL.
The address of
During a call to NdisMAllocateSharedMemory, NDIS
NDIS_WRAPPER_CONTEXT that detected that a previously-allocated shared memory
keeps track of the driver's shared
page had been corrupted.
memory allocations
The virtual address of the shared
A driver called NdisMFreeSharedMemory[Async]
memory
with a shared memory pointer that had already been
freed.
0
AddDevice was called with a driver that is not on the
list of drivers that are registered with NDIS.
The current IRQL

(Enabled only on special instrumented NDIS.)

0x05
0x06
0x07

0x08
0x09

0x0A
0x0B
0x0C

0x0D

0x0E

0x0F
0x10

0x11

The address of the miniport

block

The address of the packet descriptor The address of the packet array that An Ethernet driver indicated that it received a packet by
that the driver uses
contained this packet descriptor
using a packet descriptor that the protocol stack is
currently using.
The address of the miniport The address of the packet descriptor The address of the packet array that An FDDI driver indicated that it received a packet by
block
that the driver uses
contained this packet descriptor
using a packet descriptor that the protocol stack is
currently using.
The address of the miniport The address of
0
A miniport driver did not deregister its interrupt during
block
NDIS_MINIPORT_INTERRUPT
the halt process.
The address of the miniport The address of the miniport driver's 0
A miniport driver stopped without successfully
block
timer queue
canceling all its timers.
(NDIS_MINIPORT_TIMER)
The address of
The address of DRIVER_OBJECT The reference count for the miniport A miniport driver is getting unloaded prematurely.
driver
NDIS_M_DRIVER_BLOCK
The address of the miniport The address of
0
A miniport driver failed its initialization without
block
NDIS_MINIPORT_INTERRUPT
deregistering its interrupt.
The address of the miniport The address of the miniport driver's 0
A miniport driver failed its initialization without
block
timer queue
successfully canceling all its timers.
(NDIS_MINIPORT_TIMER)
The address of the miniport The address of
0
A miniport driver did not deregister its interrupt during
block
NDIS_MINIPORT_INTERRUPT
the halt process. (The halt was called from the initialize
routine after the miniport driver returned success from
its initialize handler.)
The address of the miniport The address of the miniport driver's 0
A miniport driver stopped without successfully
block
timer queue
canceling all its timers. (The halt was called from the
(NDIS_MINIPORT_TIMER)
initialize routine after the miniport driver returned
success from its initialize handler.)
The address of the miniport The reset status
AddressingReset (BOOLEAN)
A miniport driver called NdisMResetComplete
block
without any pending reset request.
The address of the miniport The address of
0
After resuming from a low-power state, a miniport
block
NDIS_MINIPORT_INTERRUPT
driver failed its initialization without deregistering its
interrupt.
The address of the miniport The address of the miniport driver's 0
After resuming from a low-power state, a miniport
block
timer queue
driver failed its initialization without successfully

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x12

The address of the miniport

block

0x13

The address of the miniport

block

0x14

The current IRQL value

0x15

The address of the miniport

block

0x16

The address of the protocol

block

Page 839 of 1651

(NDIS_MINIPORT_TIMER)
canceling all its timers.
The address of the packet descriptor The address of the packet array that A miniport driver indicated that it received a packet by
that the driver uses
contained this packet descriptor
using a packet descriptor that the protocol stack is
currently using.
The address of the packet descriptor The address of the packet array that A Token-Ring miniport driver indicated that it received
that the driver uses
contained this packet descriptor
a packet by using a packet descriptor that the protocol
stack currently uses.
0
0
An NDIS driver called NdisWaitEvent at IRQL >
PASSIVE_LEVEL. The function must be called at
IRQL = PASSIVE_LEVEL.
0
0
An NDIS 6 miniport driver was calling an NDIS 5 API.
An NDIS 6 miniport driver cannot call
NdisMQueryInformationComplete or
NdisMSetInformationComplete.
The address of the context area that The address of the open block
NDIS encountered an invalid handle in a binding
is allocated by the protocol driver
operation.
A protocol drivers ProtocolBindAdapterEx function
returned NDIS_STATUS_SUCCESS, either directly or
asynchronously through
NdisCompleteBindAdapterEx. However, the binding
context information contains an invalid handle to a
block that indicates the open state of the miniport
adapter. In this case, the open handle is not NULL, but
it cannot be referenced.

0x17

The address of the interface

provider block

The NDIS driver was attempting to deregister as a

network interface provider while an interface was still
registered.

Cause
Parameter 1 indicates the specific cause of the BUGCODE_NDIS_DRIVER bug check.
If one of the bug check parameters specifies the address of the miniport block, you can obtain more information by using !ndiskd.miniport together with this address.
If one of the bug check parameters specifies the address of the packet descriptor that the driver uses, you can obtain more information by using !ndiskd.pkt together with this
address.
Comments
This bug check code occurs only on Microsoft Windows Server 2003 and later versions of Windows. In Windows 2000 and Windows XP, the corresponding code is bug
check 0xD2 (BUGCODE_ID_DRIVER).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x7D: INSTALL_MORE_MEMORY

The INSTALL_MORE_MEMORY bug check has a value of 0x0000007D. This bug check indicates that there is not enough memory to start up the Microsoft Windows
operating system.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
The number of physical pages that are found
1
2
The lowest physical page
3
The highest physical page
4
0
Cause
The Windows operating system does not have sufficient memory to complete the startup process.
Resolving the Problem
Install more memory.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 840 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Bug Check 0x7E: SYSTEM_THREAD_EXCEPTION_NOT_HANDLED

The SYSTEM_THREAD_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000007E. This bug check indicates that a system thread generated an exception that
the error handler did not catch.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
The exception code that was not handled
2
The address where the exception occurred
3
The address of the exception record
4
The address of the context record
Cause
The SYSTEM_THREAD_EXCEPTION_NOT_HANDLED bug check is a very common bug check. To interpret it, you must identify which exception was generated.
Common exception codes include the follwoing:

0x80000002: STATUS_DATATYPE_MISALIGNMENT indicates an unaligned data reference was encountered.

0x80000003: STATUS_BREAKPOINT indicates a breakpoint or ASSERT was encountered when no kernel debugger was attached to the system.
0xC0000005: STATUS_ACCESS_VIOLATION indicates a memory access violation occurred.

For a complete list of exception codes, see the Ntstatus.h file that is located in the inc directory of the Microsoft Windows Driver Kit (WDK).
Resolving the Problem
If you are not equipped to debug this problem, you should use some basic troubleshooting techniques.

Make sure you have enough disk space.

If a driver is identified in the bug check message, disable the driver or check with the manufacturer for driver updates.
Try changing video adapters.
Check with your hardware vendor for any BIOS updates.
Disable BIOS memory options such as caching or shadowing.

If you plan to debug this problem, you might find it difficult to obtain a stack trace. Parameter 2 (the exception address) should identify the driver or function that caused this
problem.
If exception code 0x80000003 occurs, a hard-coded breakpoint or assertion was hit, but the system was started with the /NODEBUG switch. This problem should rarely
occur. If it occurs repeatedly, make sure that a kernel debugger is connected and the system is started with the /DEBUG switch.
If exception code 0x80000002 occurs, the trap frame supplies additional information.
If you do not know the specific cause of the exception, consider the following issues:

Hardware incompatibility. Make sure that any new hardware that is installed is listed in the Microsoft Windows Marketplace Tested Products List.
Faulty device driver or system service. A faulty device driver or system service might be responsible for this error. Hardware issues, such as BIOS incompatibilities,
memory conflicts, and IRQ conflicts can also generate this error.

If a driver is listed by name within the bug check message, disable or remove that driver. Disable or remove any drivers or services that were recently added. If the error
occurs during the startup sequence and the system partition is formatted with NTFS file system, you might be able to use Safe Mode to rename or delete the faulty driver. If
the driver is used as part of the system startup process in Safe Mode, you must start the computer by using the Recovery Console to access the file.
If the problem is associated with Win32k.sys, the source of the error might be a third-party remote control program. If such software is installed, you can remove the service
by starting the computer by using the Recovery Console and then deleting the offending system service file.
Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing bug check 0x7E.
You can also disable memory caching of the BIOS might to try to resolve the error. You should also run hardware diagnostics, especially the memory scanner, that the system
manufacturer supplies. For more information about these procedures, see the owner's manual for your computer.
The error that generates this message can occur after the first restart during Windows Setup, or after Setup is finished. A possible cause of the error is lack of disk space for
installation and system BIOS incompatibilities. For problems during Windows installation that are associated with lack of disk space, reduce the number of files on the target
hard disk drive. Check for and delete any temporary files that you do not have to have, Internet cache files, application backup files, and .chk files that contain saved file
fragments from disk scans. You can also use another hard disk drive with more free space for the installation. You can resolve BIOS problems by upgrading the system BIOS
version.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 841 of 1651

Bug Check 0x7F: UNEXPECTED_KERNEL_MODE_TRAP

The UNEXPECTED_KERNEL_MODE_TRAP bug check has a value of 0x0000007F. This bug check indicates that the Intel CPU generated a trap and the kernel failed to
catch this trap.
This trap could be a bound trap (a trap the kernel is not permitted to catch) or a double fault (a fault that occurred while processing an earlier fault, which always results in a
system failure).
Parameters
The first parameter that appears on the blue screen specifies the trap number.
The most common trap codes include the following:

0x00000000, or Divide by Zero Error, indicates that a DIV instruction is executed and the divisor is zero. Memory corruption, other hardware problems, or software
failures can cause this error.
0x00000004, or Overflow, occurs when the processor executes a call to an interrupt handler when the overflow (OF) flag is set.
0x00000005, or Bounds Check Fault, indicates that the processor, while executing a BOUND instruction, finds that the operand exceeds the specified limits. A BOUND
instruction ensures that a signed array index is within a certain range.
0x00000006, or Invalid Opcode, indicates that the processor tries to execute an invalid instruction. This error typically occurs when the instruction pointer has become
corrupted and is pointing to the wrong location. The most common cause of this error is hardware memory corruption.
0x00000008, or Double Fault, indicates that an exception occurs during a call to the handler for a prior exception. Typically, the two exceptions are handled serially.
However, there are several exceptions that cannot be handled serially, and in this situation the processor signals a double fault. There are two common causes of a
double fault:
A kernel stack overflow. This overflow occurs when a guard page is hit, and the kernel tries to push a trap frame. Because there is no stack left, a stack overflow
results, causing the double fault. If you think this overview has occurred, use !thread to determine the stack limits, and then use kb (Display Stack Backtrace)
with a large parameter (for example, kb 100) to display the full stack.
A hardware problem.

The less-common trap codes include the following:

0x00000001 A system-debugger call

0x00000003 A debugger breakpoint
0x00000007 A hardware coprocessor instruction with no coprocessor present
0x0000000A A corrupted Task State Segment
0x0000000B An access to a memory segment that was not present
0x0000000C An access to memory beyond the limits of a stack
0x0000000D An exception not covered by some other exception; a protection fault that pertains to access violations for applications

For other trap numbers, see an Intel architecture manual.

Cause
Bug check 0x7F typically occurs after you install a faulty or mismatched hardware (especially memory) or if installed hardware fails.
A double fault can occur when the kernel stack overflows. This overflow occurs if multiple drivers are attached to the same stack. For example, if two file system filter drivers
are attached to the same stack and then the file system recurses back in, the stack overflows.
Resolving the Problem
Debugging: Always begin with the !analyze extension.
If this extension is not sufficient, use the kv (Display Stack Backtrace) debugger command.

If kv shows a taskGate, use the .tss (Display Task State Segment) command on the part before the colon.
If kv shows a trap frame, use the .trap (Display Trap Frame) command to format the frame.
Otherwise, use the .trap (Display Trap Frame) command on the appropriate frame. (On x86-based platforms, this frame is associated with the procedure NT!KiTrap.)

After using one of these commands, use kv again to display the new stack.
Troubleshooting: If you recently added hardware to the computer, remove it to see if the error recurs. If existing hardware has failed, remove or replace the faulty component.
Run hardware diagnostics that the system manufacturer supplies to determine which hardware component failed.
The memory scanner is especially important. Faulty or mismatched memory can cause this bug check. For more informaiton about these procedures, see the owner's manual
for your computer. Check that all adapter cards in the computer are properly seated. Use an ink eraser or an electrical contact treatment, available at electronics supply stores,
to ensure adapter card contacts are clean.
If the error appears on a newly installed system, check the availability of updates for the BIOS, the SCSI controller, or network cards. These kind of updates are typically
available on the Web site or BBS of the hardware manufacturer.
Confirm that all hard disk drives, hard disk controllers, and SCSI adapters are listed in the Microsoft Windows Marketplace Tested Products List.
If the error occurred after the installation of a new or updated device driver, you should remove or replace the driver. If, under this circumstance, the error occurs during the
startup sequence and the system partition is formatted with NTFS, you might be able to use Safe Mode to rename or delete the faulty driver. If the driver is used as part of the
system startup process in Safe Mode, you have to start the computer by using the Recovery Console in order to access the file.
Also restart your computer, and then press F8 at the character-based menu that displays the operating system choices. At the Advanced Options menu, select the Last
Known Good Configuration option. This option is most effective when you add only one driver or service at a time.
Overclocking (setting the CPU to run at speeds above the rated specification) can cause this error. If you have overclocked the computer that is experiencing the error, return
the CPU to the default clock speed setting.
Check the System Log in Event Viewer for additional error messages that might help identify the device or driver that is causing the error. You can also disable memory

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 842 of 1651

caching of the BIOS to try to resolve the problem.

If you encountered this error while upgrading to a new version of the Windows operating system, the error might be caused by a device driver, a system service, a virus
scanner, or a backup tool that is incompatible with the new version. If possible, remove all third-party device drivers and system services and disable any virus scanners
before you upgrade. Contact the software manufacturer to obtain updates of these tools. Also make sure that you have installed the latest Windows Service Pack.
Finally, if all the above steps do not resolve the error, take the system motherboard to a repair facility for diagnostic testing. A crack, a scratched trace, or a defective
component on the motherboard can also cause this error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x80: NMI_HARDWARE_FAILURE

The NMI_HARDWARE_FAILURE bug check has a value of 0x00000080. This bug check indicates that a hardware malfunction has occurred.
Parameters
None
Cause
A variety of hardware malfunctions can cause the NMI_HARDWARE_FAILURE bug check. The exact cause is difficult to determine.
Resolving the Problem
Remove any hardware or drivers that have been recently installed. Make sure that all memory modules are of the same type.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x81: SPIN_LOCK_INIT_FAILURE

The SPIN_LOCK_INIT_FAILURE bug check has a value of 0x00000081.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x82: DFS_FILE_SYSTEM

The DFS_FILE_SYSTEM bug check has a value of 0x00000082.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x85: SETUP_FAILURE

The SETUP_FAILURE bug check has a value of 0x00000085. This bug check indicates that a fatal error occurred during setup.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation. Parameter 4 is not used. The meaning of the other parameters depends on the
value of Parameter 1.
Parameter

Parameter 2

Parameter 3

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Cause

9/18/2010

Introduction

Page 843 of 1651

1
0x0

The OEM HAL font is not a valid .fon format file, so

setup cannot display text.
This cause indicates that Vgaxxx.fon on the boot floppy or
CD is damaged.

0x1

The precise video initialization failure:

0: NtCreateFile of \device\video0
1: IOCTL_VIDEO_QUERY_NUM_AVAIL_MODES
2: IOCTL_VIDEO_QUERY_AVAIL_MODES

The status code Video initialization failed.

from the NT API
call, if
This failure might indicate that the disk that contains
appropriate
Vga.sys (or another video driver that is appropriate to the
computer) is damaged or that the computer has video
hardware that the Microsoft Windows operating system
cannot communicate with.

3: The desired video mode is not supported. This value indicates an internal setup
error.
4: IOCTL_VIDEO_SET_CURRENT_MODE (unable to set video mode)
5: IOCTL_VIDEO_MAP_VIDEO_MEMORY
6: IOCTL_VIDEO_LOAD_AND_SET_FONT
0x2

Out of memory.

0x3

The precise keyboard initialization failure:

Keyboard initialization failed.

0: NtCreateFile of \device\KeyboardClass0 failed. (Setup did not find a keyboard

connected to the computer.)

This failure might indicate that the disk that contains the
keyboard driver (I8042prt.sys or Kbdclass.sys) is damaged
or that the computer has keyboard hardware that Windows
cannot communicate with. This failure might also mean
that the keyboard layout DLL could not be loaded.

1: Unable to load keyboard layout DLL. (Setup could not load the keyboard layout
file. This failure indicates that the CD or floppy disk is missing a file, such as
Kbdus.dll for the U.S. release or another layout DLL for localized releases.)

0x4

Setup could not resolve the ARC device path name of the
device that setup was started from.
This error is an internal setup error.

0x5

Reserved

Partitioning sanity check failed.

This error indicates a bug in a disk driver.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x8B: MBR_CHECKSUM_MISMATCH

The MBR_CHECKSUM_MISMATCH bug check has a value of 0x0000008B. This bug check indicates that a mismatch has occurred in the MBR checksum.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
The disk signature from MBR
2
The MBR checksum that the OS Loader calculates
3
The MBR checksum that the system calculates
4
Reserved
Cause
The MBR_CHECKSUM_MISMATCH bug check occurs during the boot process when the MBR checksum that the Microsoft Windows operating system calculates does not
match the checksum that the loader passes in.
This error typically indicates a virus.
Resolving the Problem

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 844 of 1651

There are many forms of viruses and not all can be detected. Typically, the newer viruses usually can be detected only by a virus scanner that has recently been upgraded. You
should boot with a write-protected disk that contains a virus scanner and try to clean out the infection.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x8E: KERNEL_MODE_EXCEPTION_NOT_HANDLED

The KERNEL_MODE_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000008E. This bug check indicates that a kernel-mode application generated an
exception that the error handler did not catch.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
The exception code that was not handled
2
The address where the exception occurred
3
The trap frame
4
Reserved
Cause
The KERNEL_MODE_EXCEPTION_NOT_HANDLED bug check is a very common bug check. To interpret it, you must identify which exception was generated.
Common exception codes include the following:

0x80000002: STATUS_DATATYPE_MISALIGNMENT indicates that an unaligned data reference was encountered.

0x80000003: STATUS_BREAKPOINT indicates that a breakpoint or ASSERT was encountered when no kernel debugger was attached to the system.
0xC0000005: STATUS_ACCESS_VIOLATION indicates that a memory access violation occurred.

Make sure you have enough disk space.

If you plan to debug this problem, you might find it difficult to obtain a stack trace. Parameter 2 (the exception address) should identify the driver or function that caused this
problem.
If exception code 0x80000003 occurs, a hard-coded breakpoint or assertion was hit, but the computer was started with the /NODEBUG switch. This problem should rarely
occur. If it occurs repeatedly, make sure that a kernel debugger is connected and that the computer is started with the /DEBUG switch.
If exception code 0x80000002 occurs, the trap frame supplies additional information.
If you do not know the specific cause of the exception, consider the following items:

Hardware incompatibility. Make sure that any new hardware installed is listed in the Microsoft Windows Marketplace Tested Products List.
Faulty device driver or system service. A faulty device driver or system service might be responsible for this error. Hardware issues, such as BIOS incompatibilities,
memory conflicts, and IRQ conflicts can also generate this error.

The INVALID_REGION_OR_SEGMENT bug check has a value of 0x00000099. This bug check indicates that ExInitializeRegion or ExInterlockedExtendRegion was
called with an invalid set of parameters.
Parameters
None
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9A: SYSTEM_LICENSE_VIOLATION

The SYSTEM_LICENSE_VIOLATION bug check has a value of 0x0000009A. This bug check indicates that the software license agreement has been violated.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1.
Parameter
Parameter 2
Parameter 3
1
0x00
0: The product should be WinNT A partial serial number

Parameter 4
The first two characters of the
product type from the product

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Cause
Offline product type changes have been attempted.

9/18/2010

Introduction

Page 848 of 1651

1: The product should be

LanmanNT or ServerNT
0x01
0x02
0x03
0x04
0x05

The registered evaluation time

from source 1
The status code that is associated
with the open failure
The status code that is associated
with the key lookup failure
The status code that is associated
with the key lookup failure
(See the setup code)

options

A partial serial number

The registered evaluation time from Offline changes to the Microsoft Windows evaluation unit
an alternate source
time period have been attempted.
0
The setup key could not be opened.

The SetupType or SetupInProgress value from the setup

key is missing, so setup mode could not be detected.
The SystemPrefix value from the setup key is missing.

An invalid value was found The officially licensed number of

in licensed processors
processors
The status code that is associated 0
0
with the open failure
The status code that is associated 0
0
with the read failure
The status code that is associated 0
0
with the Change Notify failure
The status code that is associated 0
0
with the Change Notify failure
0
0
0
The status code that is associated 0
0
with the change failure
The status code that is associated 0
0
with the change failure
The status code that is associated 0
0
with the failure
The status code that is associated 0
0
with the failure
The status code that is associated 0: set value failed
0
with the failure
1: Change Notify failed

Offline changes to the number of licensed processors have

been attempted.
The ProductOptions key could not be opened.

0x11

The status code that is associated 0: set value failed

with the failure
1: Change Notify failed

A failure occurred in the product options key worker

thread.

0x12

The status code that is associated

with the failure
The status code that is associated
with the failure
The size of the memory allocation
The status code that is associated
with the failure
The status code that is associated
with the failure
The status code that is associated
with the failure
The status code that is associated
with the open failure
0
The status code that is associated
with the failure
0

Unable to open the LicenseInfoSuites key for the suite.

Unable to query the LicenseInfoSuites key for the suite.

0
Reserved

0
0

Unable to allocate memory.

Unable to reset the ConcurrentLimit value for the suite
key.
Unable to open the license key for a suite product.

Reserved

0
0

Unable to reset the ConcurrentLimit value for a suite

product.
Unable to start the Change Notify for the
LicenseInfoSuites.
A suite is running on a system that must be PDC.
A failure occurred when enumerating the suites.

Changes to the policy cache were attempted.

0x06
0x07
0x08
0x09
0x0A
0x0B
0x0C
0x0D
0x0F
0x10

0x13
0x14
0x15
0x16
0x17
0x18
0x19
0x1A
0x1B

The ProductType value could not be read.

Change Notify on ProductOptions failed.
Change Notify on SystemPrefix failed.
An NTW system was converted to an NTS system.
The reference of the setup key failed.
The reference of the product options key failed.
The attempt to open ProductOptions in the worker thread
failed.
The attempt to open the setup key failed.
A failure occurred in the setup key worker thread.

Cause
The Microsoft Windows operating system detects a violation of the software license agreement.
A user might have tried to change the product type of an offline system or change the trial period of an evaluation unit of Windows. For more information about the specific
violation, see the parameter list.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9B: UDFS_FILE_SYSTEM

The UDFS_FILE_SYSTEM bug check has a value of 0x0000009B. This bug check indicates that a problem occurred in the UDF file system.
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 849 of 1651

The following parameters appear on the blue screen.

Parameter
Description
1
The source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier number.
The low 16 bits identify the source line in the file where the bug check occurred.
2
If UdfExceptionFilter is on the stack, this parameter specifies the address of the exception record.
3
If UdfExceptionFilter is on the stack, this parameter specifies the address of the context record.
4
Reserved.
Cause
The UDFS_FILE_SYSTEM bug check might be caused disk corruption. Corruption in the file system or bad blocks (sectors) on the disk can induce this error. Corrupted
SCSI and IDE drivers can also adversely affect the system's ability to read and write to the disk and cause the error.
This bug check might also occur if nonpaged pool memory is full. If the nonpaged pool memory is full, this error can stop the system. However, during the indexing process,
if the amount of available nonpaged pool memory is very low, another kernel-mode driver that requires nonpaged pool memory can also trigger this error.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a disk corruption problem: Check Event Viewer for error messages from SCSI and FASTFAT (System Log) or Autochk (Application Log) that might help identify
the device or driver that is causing the error. Disable any virus scanners, backup application, or disk defragmenter tools that continually monitor the system. You should also
run hardware diagnostics that the system manufacturer supplies. For more information about these procedures, see the owner's manual for your computer. Run Chkdsk /f /r to
detect and resolve any file system structural corruption. You must restart the system before the disk scan begins on a system partition.
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This memory increases the quantity of nonpaged pool memory that is
available to the kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9C: MACHINE_CHECK_EXCEPTION

The MACHINE_CHECK_EXCEPTION bug check has a value of 0x0000009C. This bug check indicates that a fatal machine check exception has occurred.
Parameters
The four parameters that are listed in the message have different meanings, depending on the processor type.
If the processor is based on an older x86-based architecture and has the Machine Check Exception (MCE) feature but not the Machine Check Architecture (MCA) feature (for
example, the Intel Pentium processor), the parameters have the following meaning.
Parameter
Description
1
The low 32 bits of P5_MC_TYPE Machine Service Report (MSR)
2
The address of the MCA_EXCEPTION structure
3
The high 32 bits of P5_MC_ADDR MSR
4
The low 32 bits of P5_MC_ADDR MSR
If the processor is based on a newer x86-based architecture and has the MCA feature and the MCE feature (for example, any Intel Processor of family 6 or higher, such as
Pentium Pro, Pentium IV, or Xeon), or if the processor is an x64-based processor, the parameters have the following meaning.
Parameter
Description
1
The bank number
2
The address of the MCA_EXCEPTION structure
3
The high 32 bits of MCi_STATUS MSR for the MCA bank that had the error
4
The low 32 bits of MCi_STATUS MSR for the MCA bank that had the error
On an Itanium-based processor, the parameters have the following meaning.
Note Parameter 1 indicates the type of violation.
Parameter
Parameter 2
1
0x1
The address of the
log
0x2
The address of the
log
0x3
The address of the
log
0x4
The address of the
log
0x5
The address of the

Parameter 3
The size of the
log
The size of the
log
The size of the
log
The size of the
log
The size of the

Parameter 4

Cause

0
The error
code
The error
code
0

The system abstraction layer (SAL) returned an error for SAL_GET_STATEINFO while processing
MCA.
SAL returned an error for SAL_CLEAR_STATEINFO while it processed MCA.

There are two possible causes:

Firmware (FW) reported a fatal MCA.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 850 of 1651

log

0xB

The address of the

log
The address of the
log
The address of the
log
The address of the
log

0xC
0xD
0xE

The size of the

log
The size of the
log
The size of the
log
The size of the
log

SAL reported a recoverable MCA, but this recovery is not currently supported.
SAL generated an MCA but could not produce an error record.

0
The error
code
The error
code
0

SAL returned an error for SAL_GET_STATEINFO while processing an INIT event.

SAL returned an error for SAL_CLEAR_STATEINFO while it processed an INIT event.

Comments
For more information about Machine Check Architecture (MCA), see the Intel or AMD Web sites.
Note Starting with Windows Vista, this bug check is no longer supported, and has been replaced with bug Check 0x124: WHEA_UNCORRECTABLE_ERROR.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9E: USER_MODE_HEALTH_MONITOR

The USER_MODE_HEALTH_MONITOR bug check has a value of 0x0000009E. This bug check indicates that one or more critical user-mode components failed to satisfy a
health check.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
The process that failed to satisfy a health check in the configured time-out
2
The health monitoring time-out, in seconds
3
Reserved
4
Reserved
Cause
Hardware mechanisms, such as watchdog timers, can detect that basic kernel services are not executing. However, resource starvation issues (including memory leaks, lock
contention, and scheduling priority misconfiguration) can block critical user-mode components without blocking deferred procedure calls (DPCs) or draining the non-paged
pool.
Kernel components can extend watchdog timer functionality to user mode by periodically monitoring critical applications. This bug check indicates that a user-mode health
check failed in a way that prevents graceful shutdown. This bug check restores critical services by restarting or enabling application failover to other servers.
On the Microsoft Windows Server 2003, Enterprise Edition, Windows Server 2003, Datacenter Edition, and Windows 2000 with Service Pack 4 (SP4) operating systems, a
user-mode hang can also cause this bug check. The bug check occurs in this situation only if the user has set HangRecoveryAction to a value of 3.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x9F: DRIVER_POWER_STATE_FAILURE

The DRIVER_POWER_STATE_FAILURE bug check has a value of 0x0000009F. This bug check indicates that the driver is in an inconsistent or invalid power state.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation.
Parameter 1
0x1
0x2

Parameter 2
The device object

The target device's

device object, if it is
available
0x3 (Windows 2000 only)
A pointer to the target
device object
0x3 (Windows XP and later) The physical device

Parameter 3
Reserved
The device object

A pointer to the device

object
The functional device

Parameter 4
Reserved

Cause
The device object that is being freed still has an outstanding power
request that it has not completed.
The driver object, if The device object completed the I/O request packet (IRP) for the
it is available
system power state request, but it failed to call
PoStartNextPowerIrp.
The IRP
The device driver did not properly set the IRP as "pending" or
complete the IRP.
The blocked IRP
A device object has been blocking an IRP for too long a time.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 851 of 1651

object (PDO) of the stack object (FDO) of the

stack
0x100 (Windows 2000 only) A pointer to the
A pointer to the target
nonpaged device object device object
0x101 (Windows 2000 only) The child device object
(FDO)
0x500 (Windows XP and
Reserved
Windows Server 2003 only)

The child device object

(PDO)
The target device's
device object, if
available

A pointer to the
device object to
notify
The parent device
object
Device object

The device objects in the devnode inconsistently used

DO_POWER_PAGABLE.
A parent device object has detected that a child device has not set
the DO_POWER_PAGABLE bit.
The device object completed the IRP for the system power state
request, but it failed to call PoStartNextPowerIrp.

Cause
For a description of the possible causes, see the description of each code in the Parameters section.
The errors that cause Parameter 1 to be 0x3, 0x100, or 0x101 only exist in Microsoft Windows 2000. In Windows XP and later versions of Windows, these errors are
superseded by Driver Verifier tests. For more information about Driver Verifier, see the Driver Verifier section of the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA0: INTERNAL_POWER_ERROR

The INTERNAL_POWER_ERROR bug check has a value of 0x000000A0. This bug check indicates that the power policy manager experienced a fatal error.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1.
Parameter
Parameter 2
1
0x1
1: A device has overrun its maximum number of
reference counts.

Parameter 3

Parameter 4

Except when Parameter 2 is equal to 5, this

parameter indicates the maximum number of
pending IRPs that are allowed.

Reserved

Cause
An error occurred during the handling of
the power I/O request packet (IRP).

2, 3, or 4: (Windows Server 2003, Windows XP,

and Windows 2000 only ) Too many inrush power If Parameter 2 is equal to 5, this parameter is
IRPs have been queued.
reserved.
5: (Windows Server 2003, Windows XP, and
Windows 2000 only) The power IRP has been sent
to a passive level device object.
0x2

Reserved

0x3

The expected checksum

The actual checksum

0x4

The expected checksum

The actual checksum

0x5

Reserved

0x7
0x8

Reserved

An internal failure has occurred while

attempting to process a power event.
The line number The checksum for a hibernation context
of the failure
page does not match its expected
checksum.
The line number The checksum for a page about to be
of the failure
written to the hibernation file does not
match its expected checksum.
Reserved
An unknown shutdown code has been
sent to the system shutdown handler.
Reserved
An unhandled exception has occurred.
A fatal error occurred while processing a
system power event.
(See the following table for more details.)

When Parameter 1 is0x8, a fatal error occurred while processing a system power event. In this situation, Parameter 2 indicates the cause of the error. The meaning of the other
parameters depends on the value of Parameter 2.
Parameter
2
0x100
The device object

Parameter 3

0x101

Exception pointer

0x102

The address of the DUMP_INITIALIZATION_CONTEXT

structure, which contains the information that is passed from the
system to the disk dump driver during the driver's initialization
The address of the POP_HIBER_CONTEXT structure

0x103

Parameter 4

Cause

The address of the POWER_CHANNEL_SUMMARY

structure (a record of device object states)
Reserved

An unknown device type is being

processed.
An unhandled exception
occurred.
The address of the POP_HIBER_CONTEXT structure,
The hibernation working buffer
which contains information about the state of the computer size is not page-aligned.
before hibernation
Reserved
Some working pages were not
accounted for during the
hibernation process.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 852 of 1651

0x104

The address of the POP_HIBER_CONTEXT structure

Reserved

0x105

The address of the POP_HIBER_CONTEXT structure

Reserved

0x106

The MDL

Reserved

0x107

The address of the POP_HIBER_CONTEXT structure

The address of the PO_MEMORY_RANGE_ARRAY

structure

0x108

The address of the POP_HIBER_CONTEXT structure

Reserved

0x109

The expected checksum

The actual checksum

0x10A

The address of the POP_HIBER_CONTEXT structure

The NTSTATUS failure code

0x200

The device object

0x300

The device object

The address of the

DEVICE_OBJECT_POWER_EXTENSION notification
structure
The IRP

0x301

The device object

The IRP

0x400

The IRP stack location

The device object

0x401,
0x402,
or
0x403
0x404

The pending IRP list

The device object

The IRP stack location

The device object

0x500

The IRP

The device object

An attempt was made to map

internal hibernation memory
while the internal memory
structures were locked.
An attempt was made to map
internal hibernation memory with
an unsupported memory type
flag.
A memory descriptor list (MDL)
was created during the
hibernation process that describes
memory that is not pagedaligned.
A data mismatch occurred in the
internal hibernation data
structures.
The disk subsystem failed to
properly write part of the
hibernation file.
The checksum for the processor
state data does not match its
expected checksum.
The disk subsystem failed to
properly write part of the
hibernation file.
An unknown device type is being
checked for an idle state.
An unknown status was returned
from a battery power IRP.
The battery has entered an
unknown state.
A device has overrun its
maximum number of reference
counts.
(Windows Server 2003,
Windows XP, and Windows 2000
only) Too many inrush power
IRPs have been queued.
(Windows Server 2003,
Windows XP, and Windows 2000
only) A power IRP has been sent
to a passive level device object.
An unknown status was returned
from a thermal power IRP.

Cause
For more information about the exact cause for the INTERNAL_POWER_ERROR bug check, see the tables in the Parameters section above.
Resolving the Problem
The following procedures will help you debug certain instances of this bug check.
Debugging bug check 0xA0 when Parameter 1 equals 0x2
1. Examine the stack. Look for the ntoskrnl!PopExceptionFilter function. This function contains the following code as its first argument.
(error_code << 16) | _LINE_
If the caller is PopExceptionFilter, the first argument to this function is of type PEXCEPTION_POINTERS. Note the value of this argument.
2. Use the dt (Display Type) command and specify the value that you found in the previous step as argument.
dt nt!_EXCEPTION_POINTERS argument
. This command displays the structure. Note the address of the context record.
3. Use the .cxr (Display Context Record) command and specify the context record that you found in the previous step as record.
.cxr record
. This command sets the register context to the proper value.
4. Use a variety of commands to analyze the source of the error. Start with kb (Display Stack Backtrace) .
Debugging bug check 0xA0 when Parameter 1 equals 0x7
1. Examine the stack. Look for the ntoskrnl!PopExceptionFilter function. The first argument to this function is of type PEXCEPTION_POINTERS. Note the value of
this argument.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 853 of 1651

2. Use the dt (Display Type) command and specify the value that you found in the previous step as argument.
dt nt!_EXCEPTION_POINTERS argument
This command displays the structure. Note the address of the context record.
3. Use the .cxr (Display Context Record) command and specify the context record that you found in the previous step as record.
.cxr record
This command sets the register context to the proper value.
4. Use a variety of commands to analyze the source of the error. Start with kb (Display Stack Backtrace) .
Debugging bug check 0xA0 when Parameter 1 equals 0x8 and Parameter 2 equals 0x101
1. Use the dt (Display Type) command and specify the value of Parameter 3 as argument.
dt nt!_EXCEPTION_POINTERS argument
This command displays the structure. Note the address of the context record.
2. Use the .cxr (Display Context Record) command and specify the context record that you found the previous step as record.
.cxr record
This command sets the register context to the proper value.
3. Use a variety of commands to analyze the source of the error. Start with kb (Display Stack Backtrace) .
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA1: PCI_BUS_DRIVER_INTERNAL

The PCI_BUS_DRIVER_INTERNAL bug check has a value of 0x000000A1. This bug check indicates that the PCI Bus driver detected inconsistency problems in its internal
structures and could not continue.
Parameters
None
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA2: MEMORY_IMAGE_CORRUPT

The MEMORY_IMAGE_CORRUPT bug check has a value of 0x000000A2. This bug check indicates that corruption has been detected in the image of an executable file in
memory.
Parameters
The following parameters appear on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of Parameter 1.
Parameter
Parameter 2
1
0x02
If Parameter 3 is zero: The page number in the
table page that failed

Parameter 3

Parameter 4

Cause

Zero, or the index that failed to 0

match the run

A table page check failure occurred.

The length (in pages) of the

range

The checksum for the range of

memory listed is incorrect.

If Parameter 3 is nonzero: The page number with

the failing page run index
0x03

The starting physical page number of the range

The page number of the table page

that contains this run

Cause
A cyclic redundancy check (CRC) check on the memory range has failed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 854 of 1651

On a system wake operation, various regions of memory might be checked to guard against memory failures.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA3: ACPI_DRIVER_INTERNAL

The ACPI_DRIVER_INTERNAL bug check has a value of 0x000000A3. This bug check indicates that the ACPI driver detected an internal inconsistency.
Parameters
The following parameters appear on the blue screen.
Parameter Description
1
Reserved
2
Reserved
3
Reserved
4
Reserved
Cause
An inconsistency in the ACPI driver is so severe that continuing to run would cause serious problems.
One possible source of this problem is a BIOS error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA4: CNSS_FILE_SYSTEM_FILTER

The CNSS_FILE_SYSTEM_FILTER bug check has a value of 0x000000A4. This bug check indicates that a problem occurred in the CNSS file system filter.
Parameters
The following parameters appear on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") identify the source file by its identifier
number. The low 16 bits identify the source line in the file where the bug check occurred.
2
Reserved
3
Reserved
4
Reserved
Cause
The CNSS_FILE_SYSTEM_FILTER bug check might occur because nonpaged pool memory is full. If the nonpaged pool memory is completely full, this error can stop the
system. However, during the indexing process, if the amount of available nonpaged pool memory is very low, another kernel-mode driver that requires nonpaged pool
memory can also trigger this error.
Resolving the Problem
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This memory sincrease the quantity of nonpaged pool memory available
to the kernel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xA5: ACPI_BIOS_ERROR

The ACPI_BIOS_ERROR bug check has a value of 0x000000A5. This bug check indicates that the Advanced Configuration and Power Interface (ACPI) BIOS of the
computer is not fully compliant with the ACPI specification.
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 855 of 1651

Four bug check parameters appear on the blue screen. Parameter 1 indicates the kind of the incompatibility. The meaning of the other parameters depends on the value of
Parameter 1.
If the BIOS incompatibility is related to Plug and Play (PnP) or power management, the following parameters are used.
Parameter
Parameter 2
1
0x01
ACPI's deviceExtension

Parameter 3
ACPI's ResourceList

Parameter 4
0: No resource list is found

Cause
ACPI cannot find the System Control Interrupt (SCI) vector in the
resources that are handed to it when ACPI is started.

1: No IRQ resource is found in

list
0x02
0x03
0x04
0x05

0x06
0x07
0x08
0x09
0x0A
0x0B
0x0C

The ACPI object that was

being run
The ACPI extension that
_PRW belongs to
The ACPI extension that
_PRW belongs to

The return value from the

interpreter
A pointer to the method

The ACPI extension that

_PRx belongs to
The ACPI extension that
the method belongs to
The ACPI extension that
the method belongs to
The ACPI extension that
the method belongs to
The ACPI extension that
the method belongs to
The ACPI extension that
_EJD belongs to
The ACPI extension that
ACPI found a dock device
for

A pointer to the _PRx

Aointer to the _PRW

The name of the control

method (in ULONG format)
The DataType returned (see
Amli.h)
The number of elements in the
_PRW

A pointer to the name of the

object to look for
A pointer to the method
The DataType returned (see
Amli.h)
A pointer to the method
The DataType returned (see
Amli.h)
A pointer to the method
The DataType returned (see
Amli.h)
A pointer to the method
The DataType returned (see
Amli.h)
The status that the interpreter The name of the object that
returns
ACPI is trying to find
A pointer to the _EJD
0: BIOS does not claim system
method
is dockage

(See the table later on this page)

ACPI tried to run a control method while creating device extensions
to represent the ACPI namespace, but this control method failed.
ACPI evaluated a _PRW and expected to find an integer as a package
element.
ACPI evaluated a _PRW, and the package that came back failed to
contain at least two elements. The ACPI specification requires that
two elements always be present in a _PRW.
ACPI tried to find a named object, but it could not find the object.
ACPI evaluated a method and expected to receive a buffer in return.
However, the method returned some other data type.
ACPI evaluated a method and expected to receive an integer in
return. However, the method returned some other data type.
ACPI evaluated a method and expected to receive a package in
return. However, the method returned some other data type.
ACPI evaluated a method and expected to receive a string in return.
However, the method returned some other data type.
ACPI cannot find the object that an _EJD string references.
ACPI provides faulty or insufficient information for dock support.

1: Duplicate device extensions

for dock device
0x0D

The ACPI extension that The (ULONG) name of the 0: Base case
ACPI needs the object for method that ACPI looked for
1: Conflict

ACPI could not find a required method or object in the namespace

This bug check code is used if there is no _HID or _ADR present.

0x0E

The NS PowerResource The (ULONG) name of the 0: Base case

that ACPI needs the object method that ACPI looked for
for

0x0F

The current buffer that

ACPI was parsing

ACPI could not find a required method or object in the namespace

for a power resource (or entity other than a "device"). This bug check
code is used if there is no _ON, _OFF, or _STA present for a power
resource.
ACPI could not parse the resource descriptor.

0x10
0x11
0x14

0x15

The buffer's tag

The current buffer that

ACPI was parsing

The buffer's tag

The ACPI Machine

Language (AML) context

1: Failed to load table

The specified length of the

buffer

A pointer to a variable that

contains the ULONGLONG
length of the buffer
The NT status code

(See the table later on this page)

(See the table later on this page)
ACPI could not parse the resource descriptor. The length exceeds
MAXULONG.
ACPI had a fatal error when attempting to load a table.

2: The Parameter Path String

Object was not found
3: Failed to insert Parameter
Data into the ParameterPath
String Object
4: Out of system memory
0x16

A pointer to the parent

NSOBJ

A pointer to the illegal child Reserved

ACPI namespace object

ACPI had a fatal error when processing an xSDT. An object was

declared as a child of a parent that cannot have children.

If an interrupt routing failure or incompatibility has occurred, the following parameters are used.
Parameter
Parameter 2
Parameter 3
Parameter 4
1
0x2001
InterruptModel
The return value from the interpreter
A pointer to the PIC control method
(integer)
0x10001
A pointer to the device A pointer to the parent of the device object A pointer to the _PRT object
object
(See the following Comments section)
0x10002

A pointer to the device A pointer to the string name that ACPI

object
was looking for but could not find

A pointer to the _PRT object

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Cause
ACPI tried to evaluate the PIC control method
but failed.
ACPI tried to do interrupt routing, but failed.

ACPI could not find the link node referenced

in a _PRT.

9/18/2010

Introduction

Page 856 of 1651

(See the following Comments section)

0x10003

A pointer to the device The device ID or function number.

A pointer to the _PRT object
object
This DWORD is encoded as follows: bits (See the following Comments section)
5:0 are the PCI device number, and bits
8:6 are the PCI function number

ACPI could not find a mapping in the _PRT

package for a device.

0x10005

A pointer to the _PRT

object

ACPI found an entry in the _PRT that the

function ID is not all F's for.

A pointer to the current _PRT element.

The device ID or function number.

(This pointer is an index into the _PRT.)

This DWORD is encoded as follows: bits

15:0 are the PCI function number, and bits (The generic format for a _PRT entry is that
31:16 are the PCI device number
the device number is specified, but the
function number is not.)

(See the following

Comments section)

0x10006

A pointer to the link

node.

ACPI found a link node, but it cannot disable

the node.

(This device is missing

the _DIS method.)

(Link nodes must be disabled to allow for

reprogramming.)

0x10007

The vector that could

not be found

0x10008

The invalid interrupt

level.

0x10009

0x1000A

0x1000B

The ACPI table

signature
The I/O port in the
Fixed Table

A pointer to the ACPI table

0x20000

The _PRT contained a reference to a vector

that is not described in the I/O APIC entry's
MAPIC table.
The ACPI SCI interrupt level is invalid.

The Fixed ACPI Description Table (FADT)

could not be located.
The Root System Description Pointer (RSDP)
or Extended System Description Table
(XSDT) could not be located

The length of the ACPI table is not consistent

with the table revision.
The PM_TMR_BLK entry in the Fixed ACPI
Description Table doesn't point to a working
ACPI timer block.

If a miscellaneous failure or incompatibility has occurred, the following parameters are used.
Parameter
Parameter 2
1
0x20000
The I/O port in the Fixed
Table

Parameter Parameter
Cause
3
4
0
0
The PM_TMR_BLK entry in the Fixed ACPI Description Table does not point to a working ACPI
timer block.

If Parameter 1 equals 0x02, the ACPI BIOS could not process the resource list for the PCI root buses. In this case, Parameter 3 specifies the exact problem, and the remaining
parameters have the following definitions.
Parameter 2
The ACPI extension
for the PCI bus
The ACPI extension
for the PCI bus
The ACPI extension
for the PCI bus
The ACPI extension
for the PCI bus
The ACPI extension
for the PCI bus

Parameter 3

0x2

A pointer to the
QUERY_RESOURCE_REQUIREMENTS IRP
0

Cause
ACPI cannot convert the BIOS' resource list into the proper format. This
probably represents an error in the BIOS' list encoding procedure.
ACPI cannot convert the BIOS' resource list into the proper format. This
probably represents an error in the BIOS' list encoding procedure.
ACPI found an empty resource list.

0x3

A pointer to the PNP CRS descriptor

ACPI could not find the current bus number in the CRS.

0x0
0x1

Parameter 4
A pointer to the QUERY_RESOURCES IRP

A pointer to the
A pointer to the E820 memory table
resource list for PCI

The list of resources that PCI claims to decode overlaps with the list of
memory regions that the E820 BIOS interface reports. (This kind of conflict
is never permitted.)

If Parameter 1 equals 0x10, the ACPI BIOS could not determine the system-to-device-state mapping correctly. In this situation, Parameter 3 specifies the exact problem, and
the remaining parameters have the following definitions.
Parameter 2
The ACPI extension whose
mapping is needed
The ACPI extension whose
mapping is needed
The ACPI extension whose
mapping is needed

The SESSION_HAS_VALID_VIEWS_ON_EXIT bug check has a value of 0x000000BA. This indicates that a session driver still had mapped views when the session
unloaded.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The session ID
2
The number of mapped views that are leaking
3
The address of this session's mapped views table
4
The size of this session's mapped views table
Cause
This error is caused by a session driver not unmapping its mapped views prior to a session unload. This indicates a bug in win32k.sys, atmfd.dll, rdpdd.dll, or a video driver.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 860 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xBB: NETWORK_BOOT_INITIALIZATION_FAILED

The NETWORK_BOOT_INITIALIZATION_FAILED bug check has a value of 0x000000BB. This indicates that Windows failed to successfully boot off a network.
Parameters
The following parameters are displayed on the blue screen.
Parameter
1
The part of network initialization that failed. Possible values are:

Description

1: Failure while updating the registry.

2: Failure while starting the network stack. Windows sends IOCTLs to the redirector and datagram receiver, then waits for the redirector to be ready. If it is not
ready within a certain period of time, this error is issued.
3: Failure while sending the DHCP IOCTL to TCP. This is how Windows informs the transport of its IP address.
2
3
4

The failure status

Reserved
Reserved

Cause
This error is caused when Windows is booting off a network, and a critical function fails during I/O initialization.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xBC: NETWORK_BOOT_DUPLICATE_ADDRESS

The NETWORK_BOOT_DUPLICATE_ADDRESS bug check has a value of 0x000000BC. This indicates that a duplicate IP address was assigned to this machine while
booting off a network.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The IP address, shown as a DWORD. An address of the form aa.bb.cc.dd will appear as 0xDDCCBBAA.
2
The hardware address of the other machine. (For an Ethernet connection, see the following note.)
3
The hardware address of the other machine. (For an Ethernet connection, see the following note.)
4
The hardware address of the other machine. (For an Ethernet connection, this will be zero.)
Note When Parameter 4 equals zero, this indicates an Ethernet connection. In that case, the MAC address will be stored in Parameter 2 and Parameter 3. An Ethernet MAC
address of the form aa-bb-cc-dd-ee-ff will cause Parameter 2 to equal 0xAABBCCDD, and Parameter 3 to equal 0xEEFF0000.
Cause
This error indicates that when TCP/IP sent out an ARP for its IP address, it got a response from another machine indicating a duplicate IP address.
When Windows is booting off a network, this is a fatal error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xBE: ATTEMPTED_WRITE_TO_READONLY_MEMORY

The ATTEMPTED_WRITE_TO_READONLY_MEMORY bug check has a value of 0x000000BE. This is issued if a driver attempts to write to a read-only memory
segment.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 861 of 1651

Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Virtual address of attempted write
2
PTE contents
3
Reserved
4
Reserved
If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xBF: MUTEX_ALREADY_OWNED

The MUTEX_ALREADY_OWNED bug check has a value of 0x000000BF. This indicates that a thread attempted to acquire ownership of a mutex it already owned.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the mutex
The thread that caused the error
2
3
0
4
Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC1: SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION

The SPECIAL_POOL_DETECTED_MEMORY_CORRUPTION bug check has a value of 0x000000C1. This indicates that the driver wrote to an invalid section of the
special pool.
Parameters
The following parameters are displayed on the blue screen. Parameter 4 indicates the type of violation.
Parameter 1

Parameter 2
Reserved

Parameter
Cause of Error
4
0x20
A driver attempted to free pool which was not allocated.

Bytes requested

Bytes calculated (actually given

to the caller)
Reserved

0x21,
0x22
0x23

Reserved

0x24

Number of bytes
Address that the driver tried to
free
Reserved

0x30
0x31

Address that the driver

tried to free
Address that the driver
tried to free
Address that the driver
tried to free
Address that the driver
tried to free
Current IRQL
Current IRQL

Address where bits are

corrupted
Address where bits are
corrupted
Pool type
Pool type

Address that the driver

tried to free

Address where one bit is

corrupted

Parameter 3

0x32

A driver attempted to free a bad address.

A driver freed an address, but nearby bytes within the same page have
been corrupted.
A driver freed an address, but bytes occurring after the end of the
allocation have been overwritten.
A driver attempted to allocate pool at an incorrect IRQL.
A driver attempted to free pool at an incorrect IRQL.
A driver freed an address, but nearby bytes within the same page have
a single bit error.

The _POOL_TYPE codes are enumerated in ntddk.h. In particular, zero indicates nonpaged pool and one indicates paged pool.
Cause
A driver has written to an invalid section of the special pool.
Resolving the Problem
Obtain a backtrace of the current thread. This backtrace will usually reveal the source of the error.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 862 of 1651

For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC2: BAD_POOL_CALLER

The BAD_POOL_CALLER bug check has a value of 0x000000C2. This indicates that the current thread is making a bad pool request.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation.
Parameter
1
0x00
0x01,
0x02,
or
0x04
0x06
0x07
0x08
0x09
0x0A

Parameter 2

Parameter 3

Parameter 4

Cause of Error

0
Pointer to pool
header

Pool type
First part of pool header
contents

Pool tag
0

The current thread requested a zero-byte pool allocation.

The pool header has been corrupted.

Reserved
Reserved

Pointer to pool header

Pool header contents

The current thread attempted to free the pool, which was already freed.
The current thread attempted to free the pool, which was already freed.

Current IRQL
Current IRQL
Address of pool

Pool type
Pool type
Allocator's tag

Pool header contents

Address of the block of pool
being freed
Size of allocation, in bytes
Address of pool
Tag being used in the
attempted free

The current thread attempted to allocate the pool at an invalid IRQL.

The current thread attempted to free the pool at an invalid IRQL.
The current thread attempted to free pool memory by using the wrong tag.
(The memory might belong to another component.)

0x0B,
0x0C,
or
0x0D
0x40
0x41
0x42
or
0x43
0x44
0x46
0x47
0x48
0x50
0x60

Address of pool

Pool allocation's tag

Bad quota process pointer

The current thread attempted to release a quota on a corrupted pool allocation.

Starting address Start of system address

space
Starting address Physical page frame
Address being
0
freed

The current thread attempted to free the kernel pool at a user-mode address.

Highest physical page frame

The current thread attempted to free a non-allocated nonpaged pool address.

The current thread attempted to free a virtual address that was never in any pool.

Starting address
Starting address
Starting address
Starting address
Starting address

0
0
Highest physical page frame
Reserved
Size of paged pool, in bytes

The current thread attempted to free a non-allocated nonpaged pool address.

The current thread attempted to free an invalid pool address.
The current thread attempted to free a non-allocated nonpaged pool address.
The current thread attempted to free a non-allocated paged pool address.
The current thread attempted to free a non-allocated paged pool address.

The current thread attempted to free an invalid contiguous memory address.

Reserved
0
Physical page frame
Reserved
Start offset, in pages, from
beginning of paged pool
Starting address 0

(The caller of MmFreeContiguousMemory is passing a bad pointer.)

0x99

Address that is
being freed

The current thread attempted to allocate a pool with a tag of "BIG".

(This would be untrackable and could possibly corrupt the existing tag tables.)

0x9D
0x41286

Incorrect pool tag Pool type

used
Reserved
Reserved

Caller's address

The current thread attempted to allocate a pool with a tag that does not contain
any letters or digits. Using such tags makes tracking pool issues difficult.
Start offset from the beginning The current thread attempted to free a paged pool address in the middle of an
of the paged pool, in pages
allocation.

The _POOL_TYPE codes are enumerated in Ntddk.h. In particular, 0 indicates nonpaged pool and 1 indicates paged pool.
Cause

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 863 of 1651

An invalid pool request has been made by the current thread.

Resolving the Problem
Activate Driver Verifier to obtain more information about these errors. For details, see the Driver Verifier section of the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC4: DRIVER_VERIFIER_DETECTED_VIOLATION

The DRIVER_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000C4. This is the general bug check code for fatal errors found by Driver Verifier.
Parameters
Four bug check parameters are displayed on the blue screen. Parameter 1 identifies the type of violation. The meaning of the remaining parameters varies with the value of
Parameter 1. The parameter values are described in the following table.

0x00
0x01

Parameter 1

Parameter 2
Current IRQL
Current IRQL

Parameter 3
Pool type
Pool type

Parameter 4
0
Size of allocation, in bytes

0x02

Current IRQL

Pool type

Size of allocation, in bytes

0x03 (Windows Vista

and later operating
systems only)
0x10

Reserved

Bad Address

0x11

Current IRQL

Pool type

Address of pool

0x12

Current IRQL

Pool type

Address of pool

0x13
or
0x14
0x15

Reserved

Pointer to pool header

Pool header contents

Timer entry

Pool address being freed

0x16

Reserved

Pool type (-1 for special

pool)
Pool address

0x17

Resource entry

0x30

Current IRQL

Pool type (-1 for special

pool)
Requested IRQL

0
Pool address being freed
0

Cause of Error
The driver requested a zero-byte pool allocation.
The driver attempted to allocate paged memory with IRQL
> APC_LEVEL.
The driver attempted to allocate nonpaged memory with
IRQL > DISPATCH_LEVEL.
The driver attempted to allocate multiple pages of must
succeed pool, but at most one page can be allocated using
this routine.
The driver attempted to free an address that was not
returned from an allocate call.
The driver attempted to free paged pool with IRQL >
APC_LEVEL.
The driver attempted to free nonpaged pool with IRQL >
DISPATCH_LEVEL.
The driver attempted to free memory pool which was
already freed.
The driver attempted to free pool which contains an active
timer.
The driver attempted to free pool at a bad address, or the
driver passed invalid parameters to a memory routine.
The driver attempted to free pool which contains an active
ERESOURCE.
The driver passed an invalid parameter to KeRaiseIrql.
(The parameter was either a value lower than the current
IRQL, or a value higher than HIGH_LEVEL. This may be
the result of using an uninitialized parameter.)

0x31

Current IRQL

Spin lock address

Old IRQL

0x36

Current IRQL

Spin lock number

Old IRQL

0x37

Current IRQL

Thread APC disable count Resource

0x38

Current IRQL

Thread APC disable count Resource

0x39

Current IRQL

Thread APC disable count Mutex

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

The driver attempted to acquire fast mutex with IRQL >

APC_LEVEL.
The driver attempted to release fast mutex at an IRQL other
than APC_LEVEL.
The kernel released a spin lock with IRQL not equal to
DISPATCH_LEVEL.
The kernel released a queued spin lock with IRQL not
equal to DISPATCH_LEVEL.
The driver tried to acquire a resource, but APCs are not
disabled.
The driver tried to release a resource, but APCs are not
disabled.
The driver tried to acquire a mutex "unsafe" with IRQL not
equal to APC_LEVEL on entry.

9/18/2010

Introduction

Page 864 of 1651

0x3A

Current IRQL

Thread APC disable count Mutex

0x3B

Current IRQL

Object to wait for

Time-out parameter

The driver tried to release a mutex "unsafe" with IRQL not

equal to APC_LEVEL on entry.
The driver called KeWaitXxx with IRQL >=
DISPATCH_LEVEL.
(This is permitted only if the driver already owns the
DISPATCHER lock and it passes a time-out value of zero
to the routine.)

0x3C

Handle passed to routine Object type

0x3D

Address of the bad resource

0x3E

0x3F

Object address

New object reference

count.

-1: dereference case

The driver called ObReferenceObjectByHandle with a

bad handle.
The driver passed a bad (unaligned) resource to
ExAcquireResourceExclusive.
The driver called KeLeaveCriticalRegion for a thread that
is not currently in a critical region.
The driver applied ObReferenceObject to an object that
has a reference count of zero, or the driver applied
ObDereferenceObject to an object that has a reference
count of zero.

1: reference case
0x40

Current IRQL

0x41

Current IRQL

0x42

Current IRQL

0x51

Base address of
allocation

0x52

Base address of
allocation

0x53,
0x54,
or
0x59
0x60

Base address of
allocation

0x61

Bytes allocated from

paged pool

0x62

Name of the driver

0x6F

MDL address

Bytes allocated from

paged pool

The driver called KeAcquireSpinLockAtDpcLevel with

IRQL < DISPATCH_LEVEL.
Spin lock address
0
The driver called KeReleaseSpinLockFromDpcLevel
with IRQL < DISPATCH_LEVEL.
Spin lock address
0
The driver called KeAcquireSpinLock with IRQL >
DISPATCH_LEVEL.
Address of the reference
Number of charged bytes
The driver attempted to free memory after having written
beyond the allocation
past the end of the allocation. A bug check with this
parameter occurs only when the Pool Tracking option of
Driver Verifier is active.
Reserved
Number of charged bytes
The driver attempted to free memory after having written
past the end of the allocation. A bug check with this
parameter occurs only when the Pool Tracking option of
Driver Verifier is active.
Reserved
Reserved
The driver attempted to free memory after having written
past the end of the allocation. A bug check with this
parameter occurs only when the Pool Tracking option of
Driver Verifier is active.
Bytes allocated from
Total number of allocations that The driver is unloading without first freeing its pool
nonpaged pool
were not freed
allocations. A bug check with this parameter occurs only
when the Pool Tracking option of Driver Verifier is active.
Bytes allocated from
Total number of allocations that A driver thread is attempting to allocate pool memory while
the driver is unloading. A bug check with this parameter
nonpaged pool
were not freed
occurs only when the Pool Tracking option of Driver
Verifier is active.
Reserved
Total number of allocations that The driver is unloading without first freeing its pool
were not freed, including both
allocations. A bug check with this parameter occurs only
paged and nonpaged pool
when the Pool Tracking option of Driver Verifier is active.
Physical page being locked Highest physical page in the
The driver passed a page to MmProbeAndLockPages that
system
was not in the PFN database.
Spin lock address

(This often results from a driver that attempts to lock its

own private dualport RAM. Such behavior can corrupt
memory on machines with noncontiguous physical RAM.)
0x70

Current IRQL

MDL address

Access mode

0x71

Current IRQL

MDL address

Process address

0x72

Current IRQL

MDL address

Process address

0x73

Current IRQL

In 32-bit Windows: Low 32 Number of bytes

bits of the physical address

The driver called MmProbeAndLockPages with IRQL >

DISPATCH_LEVEL.
The driver called MmProbeAndLockProcessPages with
IRQL > DISPATCH_LEVEL.
The driver called MmProbeAndLockSelectedPages with
IRQL > DISPATCH_LEVEL.
The driver called MmMapIoSpace with IRQL >
DISPATCH_LEVEL.

In 64-bit Windows: the 64bit physical address

0x74

Current IRQL

MDL address

Access mode

0x75

Current IRQL

MDL address

Access mode

0x76

Current IRQL

MDL address

Access mode

0x77

Current IRQL

MDL address

Access mode

0x78

Current IRQL

MDL address

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

The driver called MmMapLockedPages in kernel mode

with IRQL > DISPATCH_LEVEL.
The driver called MmMapLockedPages in user mode with
IRQL > APC_LEVEL.
The driver called MmMapLockedPagesSpecifyCache in
kernel mode with IRQL > DISPATCH_LEVEL.
The driver called MmMapLockedPagesSpecifyCache in
user mode with IRQL > APC_LEVEL.
The driver called MmUnlockPages with IRQL >
DISPATCH_LEVEL.

9/18/2010

Introduction

Page 865 of 1651

0x79

Current IRQL

MDL address

Virtual address being

unmapped
Virtual address being
unmapped
Virtual address being
unmapped
MDL flags

0x7A

Current IRQL

0x7B

Current IRQL

0x7C
0x7D

MDL address

MDL flags

MDL address
Number of bytes

The driver called MmUnmapLockedPages in kernel mode

with IRQL > DISPATCH_LEVEL.
The driver called MmUnmapLockedPages in user mode
with IRQL > APC_LEVEL.
The driver called MmUnmapIoSpace with IRQL >
APC_LEVEL.
The driver called MmUnlockPages, and passed an MDL
whose pages were never successfully locked.
The driver called MmUnlockPages, and passed an MDL
whose pages are from nonpaged pool.
(These should never be unlocked.)

0x80

Current IRQL

Event address

0x81

MDL address

MDL flags

The driver called KeSetEvent with IRQL >

DISPATCH_LEVEL.
The driver called MmMapLockedPages.
(You should use MmMapLockedPagesSpecifyCache
instead, with the BugCheckOnFailure parameter set to
FALSE.)

0x82

MDL address

MDL flags

The driver called MmMapLockedPagesSpecifyCache

with the BugCheckOnFailure parameter equal to TRUE.
(This parameter should be set to FALSE.)

0x83

Start of physical address Number of bytes to map

range to map

0x84
0x85

Start of physical address Number of bytes to map

range to map
MDL address
Number of pages to map

0x86

MDL address

Number of pages to map

0x87

Base physical page of

the existing mapping

Number of pages already

mapped in the existing
mapping

First page frame number that isn't The driver called MmMapIoSpace without having locked
locked down
down the MDL pages. The physical pages represented by
the physical address range being mapped must have been
locked down prior to making this call.
First page frame number that is The driver called MmMapIoSpace without having locked
on the free list
down the MDL pages (or after freeing the MDL pages).
First page frame number that isn't The driver called MmMapLockedPages without having
locked down
locked down the MDL pages.
First page frame number that is The driver called MmMapLockedPages without having
on the free list
locked down the MDL pages (or after freeing the MDL
pages).
MEMORY_CACHING_TYPE The driver called MmMapIoSpace, but the caller's cache
of the existing mapping
type conflicts with an existing mapping.

(Shift left for physical

address)
0x88

Base physical page of

the requested mapping

Number of pages in the

requested mapping

MEMORY_CACHING_TYPE
of the requested mapping

The driver called MmMapIoSpace to map a physical range

as non-cached or write-combined, but the caller's physical
range already has an existing cached mapping.

Pointer to the non-memory

page in the MDL
Base physical page of the
requested mapping

The non-memory page number in

the MDL
MEMORY_CACHING_TYPE
of the requested mapping

An MDL is not marked as "I/O", but it contains nonmemory page addresses.

The driver called MmMapLockedPagesXxx to map a
physical range as non-cached or write-combined, but the
caller's physical range already has an existing cached
mapping.

Reserved

The driver switched stacks, and the current stack is neither

a thread stack nor a DPC stack.

(Shift left for physical

address)
0x89

MDL address

0x8A

MDL address

(Shift left for physical

address)
0x90 (Windows 2000,
Windows XP, and
Windows Server 2003
only)

Reserved

0x91

Reserved

(Typically, the driver doing this should be on the stack

obtained by using the kb (Display Stack Backtrace)
command.)
Reserved

Reserved

0xA0 (Windows
Pointer to the IRP
Device object of the lower Number of the sector in which
Server 2003 and later making the read or write device
the error was detected
operating systems only) request
0xA1 (Windows
Copy of the IRP making
Server 2003 and later the read or write request.
operating systems only) (The actual IRP has been
completed.)
0xA2 (Windows
IRP making the read or
Server 2003 and later write request, or a copy
operating systems only) of this IRP

Device object of the lower Number of the sector in which

device
the error was detected

Device object of the lower Number of the sector in which

device
the error was detected

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

The driver switched stacks using a method that is not

supported by the operating system. The only supported way
to extend a kernel mode stack is by using
KeExpandKernelStackAndCallout.
A cyclic redundancy check (CRC) error was detected on a
hard disk. A bug check with this parameter occurs only
when the Disk Integrity Checking option of Driver
Verifier is active.
A CRC error was detected on a sector (asynchronously). A
bug check with this parameter occurs only when the Disk
Integrity Checking option of Driver Verifier is active.
The CRCDISK checksum copies don't match. This could be
a paging error. A bug check with this parameter occurs only
when the Disk Integrity Checking option of Driver
Verifier is active.

9/18/2010

Introduction

Page 866 of 1651

The driver called MmProbeAndLockPages for an MDL

Missing MDL flag

Number of corrupted
physical pages

Address of first corrupted

physical page

Address of last corrupted

physical page

The system BIOS has corrupted low physical memory

during a sleep transition.

Address of the IRP

Reserved

The driver called IoCallDriver with interrupts disabled.

Address of the driver

dispatch routine

Address of the lookaside Reserved

list

Reserved

The driver has attempted to delete an uninitialized

lookaside list.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 867 of 1651

0xCC (Windows Vista

and later operating
systems only)
0xCD (Windows Vista
and later operating
systems only)
0xD0 (Windows Vista
and later operating
systems only)
0xD1 (Windows Vista
and later operating
systems only)
0xD2 (Windows Vista
and later operating
systems only)
0xD5 (Windows Vista
and later operating
systems only)

Address of the lookaside Starting address of the pool Size of the pool allocation
list
allocation

The driver has attempted to free a pool allocation that

contains an active lookaside list.

Address of the lookaside Block size specified by the Minimum supported block size
list
caller

The driver has attempted to create a lookaside list with an

allocation block size that is too small.

Address of the
Reserved
ERESOURCE structure

Reserved

The driver has attempted to re-initialize an ERESOURCE

structure.

Address of the
Reserved
ERESOURCE structure

Reserved

The driver has attempted to delete an uninitialized

ERESOURCE structure.

0xD6 (Windows Vista

and later operating
systems only)

Address of the
Starting address of the pool Size of the pool allocation
ERESOURCE structure allocation

The driver has attempted to free a pool allocation that

contains an active ERESOURCE structure.

Address of the
Current
IO_REMOVE_LOCK IoReleaseRemoveLock
structure created by the tag
checked build version of
the driver

Reserved

Address of the
IO_REMOVE_LOCK
structure created by the
checked build version of
the driver

Tag that does not match

previous
IoAcquireRemoveLock
tag

Previous
IoAcquireRemoveLock tag

Address of the checked

0xD7
(Windows 7operating build Remove Lock
systems and later only) structure that is used
internally by Driver
Verifier

Address of the Remove

Lock structure that is
specified by the driver

Reserved

0xDA (Windows Vista

and later operating
systems only)
0xDB (Windows Vista
and later operating
systems only)
0xDC (Windows Vista
and later operating
systems only)
0xDD (Windows Vista
and later operating
systems only)
0xDF
(Windows 7operating
systems and later only)

Starting address of the

driver

WMI callback address

inside the driver

Reserved

The current IoReleaseRemoveLock tag does not match the

previous IoAcquireRemoveLock tag. If the driver calling
IoReleaseRemoveLock is not in a checked build,
Parameter 2 is the address of the shadow
IO_REMOVE_LOCK structure created by Driver Verifier
on behalf of the driver. In this case, the address of the
IO_REMOVE_LOCK structure used by the driver is not
used at all, because Driver Verifier is replacing the lock
address for all the remove lock APIs. A bug check with this
parameter occurs only when the I/O Verification option of
Driver Verifier is active.
The current IoReleaseRemoveLockAndWait tag does not
match the previous IoAcquireRemoveLock tag. If the
driver calling IoReleaseRemoveLock is not a checked
build, Parameter 2 is the address of the shadow
IO_REMOVE_LOCK structure created by Driver Verifier
on behalf of the driver. In this case, the address of the
IO_REMOVE_LOCK structure used by the driver is not
used at all, because Driver Verifier is replacing the lock
address for all the remove lock APIs. A bug check with this
parameter occurs only when the I/O Verification option of
Driver Verifier is active.
A Remove Lock cannot be re-initialized, even after it calls
IoReleaseRemoveLockAndWait, because other threads
might still be using that lock (by calling
IoAcquireRemoveLock). The driver should allocate the
Remove Lock inside its device extension, and initialize it a
single time. The lock will be deleted together with the
device extension.
An attempt was made to unload a driver that has not
deregistered its WMI callback function.

Address of the device

object

Reserved

An attempt was made to delete a device object that was not

deregistered from WMI.

Reserved

An invalid RegHandle value was specified as a parameter

of the function EtwUnregister.

Address of the call to

EtwRegister

Starting address of the

unloading driver

Reserved

An attempt was made to unload a driver without calling

EtwUnregister.

0xE0 (Windows Vista

and later operating
systems only)
0xE1 (Windows Vista
and later operating
systems only)
0xE2 (Windows Vista
and later operating
systems only)
0xE3 (Windows Vista
and later operating
systems only)
0xE4 (Windows Vista
and later operating
systems only)
0xE5 (Windows Vista
and later operating
systems only)
0xEA (Windows Vista
and later operating

Synchronization object
address

User-mode address that

is used as a parameter
Address of the
synchronization object

Size ,in bytes, of the

address range that is used
as a parameter
Reserved

Reserved

The synchronization object is in session address space.

Synchronization objects are not allowed in session address
space because they can be manipulated from another
session or from system threads that have no session virtual
address space.
A call was made to an operating system kernel function that
specified a user-mode address as a parameter.
A synchronization object was found to have an address that
was either invalid or pageable.

Address of the call to the User-mode address used as Reserved

API
a parameter in the API

An IRP with Irp->RequestorMode set to KernelMode

was found to have a user-mode address as one of its
members.
A driver has made a call to a kernel-mode ZwXxx routine
with a user-mode address as a parameter.

Address of the call to the Address of the malformed Reserved

API
UNICODE_STRING
structure
Current IRQL
Reserved
Reserved

A driver has made a call to a kernel-mode ZwXxx routine

with a malformed UNICODE_STRING structure as a
parameter.
A call was made to a Kernel API at the incorrect IRQL.

Current IRQL

A driver has attempted to acquire a pushlock while APCs

are enabled.

Address of the IRP

User-mode address present Reserved

in the IRP

The threads APC disable

count

Address of the pushlock

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

systems only)
0xEB (Windows Vista
and later operating
systems only)
0xF0 (Windows Vista
and later operating
systems only)
0xF5 (Windows Vista
and later operating
systems only)
0xF6
(Windows 7operating
systems and later)
0xFA
(Windows 7operating
systems and later)
0xFB
(Windows 7operating
systems and later)

Page 868 of 1651

Current IRQL

The threads APC disable

count

Address of the pushlock

A driver has attempted to release a pushlock while APCs

are enabled.

Address of the
destination buffer

Address of the source

buffer

Number of bytes to copy

A driver called the memcpy function with overlapping

source and destination buffers.

Address of the NULL

handle

Object type

Reserved

A driver passed a NULL handle to

ObReferenceObjectByHandle.

Handle value being

referenced

Address of the current

process

Address inside the driver that

A driver references a user-mode handle as kernel mode.
performs the incorrect reference

Completion routine
address.

IRQL value before it calls Current IRQL value, after it calls The IRP completion routine returned at an IRQL that was
the completion routine
the completion routine
different from the IRQL the routine was called at.

Completion routine
address

Current threads APC

disable count

The threads APC disable count The threads APC disable count was changed by the
before it calls the IRP completion drivers IRP completion routine.
routine
The APC disable count is decremented each time a driver
calls KeEnterCriticalRegion, FsRtlEnterFileSystem, or
acquires a mutex.
The APC disable count is incremented each time a driver
calls KeLeaveCriticalRegion, KeReleaseMutex, or
FsRtlExitFileSystem.
Because these calls should always be in pairs, the APC
disable count should be zero whenever a thread is exited. A
negative value indicates that a driver has disabled APC
calls without re-enabling them. A positive value indicates
that the reverse is true.

0x105

Address of the IRP

The driver uses ExFreePool instead of IoFreeIrp to release

the IRP.

(Windows 7operating
systems and later)
0x10A

The driver attempts to charge pool quota to the Idle process.

(Windows 7operating
systems and later)
The driver attempts to charge pool quota from a DPC
routine. This is incorrect because the current process
context is undefined.

0x10B
(Windows 7operating
systems and later)
0x110
(Windows 7operating
systems and later)

Address of the Interrupt Address of the extended

Address of the extended context The interrupt service routine (ISR) for the driver has
Service Routine
context that was saved
was saved after it executed the
corrupted the extended thread context.
before it executed the ISR ISR

Driver Verifier detected that the system has taken longer

than 20 minutes and shutdown is not complete.

(Windows 7operating
systems and later)

The address of the thread

that is responsible for the
shutdown, which might
be deadlocked

0x11A

Current IRQL

The driver calls KeEnterCriticalRegion at IRQL >

APC_LEVEL.

Current IRQL

The driver calls KeLeaveCriticalRegion at IRQL >

APC_LEVEL.

0x115

(Windows 7operating
systems and later)
0x11B
(Windows 7operating
systems and later)
0x120

Address of the IRQL

value

Address of the Object to

wait on

Address of Timeout value

The thread waits at IRQL > DISPATCH_LEVEL. Callers

of KeWaitForSingleObject or KeWaitForMultipleObjects
must run at IRQL <= DISPATCH_LEVEL.

Address of the IRQL

value

Address of the Object to

wait on

Address of Timeout value

The thread waits at IRQL equals DISPATCH_LEVEL and

the Timeout is NULL. Callers of KeWaitForSingleObject
or KeWaitForMultipleObjects can run at IRQL <=
DISPATCH_LEVEL. If a NULL pointer is supplied for
Timeout, the calling thread remains in a wait state until the
Object is signaled.

(Windows 7operating
systems and later)
0x121
(Windows 7operating
systems and later)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x122

Page 869 of 1651

Address of the IRQL

value

Address of the Object to

wait on

Address of the Timeout value

(Windows 7operating
systems and later)
0x123

Address of the Object to

wait on

(Windows 7operating
systems and later)
0x130

Address of work item

The work item is in session address space. Work items are

not allowed in session address space because they can be
manipulated from another session or from system threads
that have no session virtual address space.

Address of work item

Reserved

Address of the resource

that was the final cause
of the deadlock

Reserved

The driver has called ExFreePool and Driver Verifier

detects an error in one of the internal values that is used to
track pool usage.
Address of the incorrect
Address of a pointer to the
The driver has called ExFreePool and Driver Verifier
value
incorrect memory page
detects an error in one of the internal values that is used to
track pool usage.
Incorrect value
Address of the incorrect value
The driver has called ExFreePool and Driver Verifier
detects an error in one of the internal values that is used to
track pool usage.
Address of the incorrect
Correct value that was expected The driver has called ExFreePool and Driver Verifier
value
detects an error in one of the internal values that is used to
track pool usage.
Pool block address tracked Pointer to the pool block address The pool block address specified by the caller of
by Driver Verifier
that is tracked by Driver Verifier ExFreePool is different from the address tracked by Driver
Verifier.
Number of bytes being
Pointer to the number of bytes
The number of bytes of memory being freed in the call to
freed
tracked by Driver Verifier
ExFreePool is different from the number of bytes tracked
by Driver Verifier.
Self-deadlock: The current thread has tried to recursively
acquire a resource. A bug check with this parameter occurs
only when the Deadlock Detection option of Driver
Verifier is active.
Deadlock: A lock hierarchy violation has been found. A
bug check with this parameter occurs only when the
Deadlock Detection option of Driver Verifier is active.
(Use the !deadlock extension for further information.)

0x1002 (Windows XP
and later operating
systems only)

Address of the resource

Reserved

0x1003 (Windows XP
and later operating
systems only)

Address of the resource

that is being released
deadlocked

Address of the resource

that should have been
released first

Reserved

0x1004 (Windows XP
and later operating
systems only)
0x1005 (Windows XP
and later operating
systems only)

Address of the resource

Address of the thread that Address of the current thread

acquired the resource

Address of the resource

Reserved

0x1006 (Windows XP
and later operating
systems only)

Address of the thread

being deleted

Address of the resource

owned by the thread

Reserved

0x1007 (Windows XP
and later operating
systems only)

Address of the resource

Reserved

0x1008

Lock address

Driver Verifier internal

data

Driver Verifier internal data

Uninitialized resource: A resource has been acquired

without having been initialized first. A bug check with this
parameter occurs only when the Deadlock Detection
option of Driver Verifier is active.
Unexpected release: A resource has been released in an
incorrect order. A bug check with this parameter occurs
only when the Deadlock Detection option of Driver
Verifier is active.
Unexpected thread: The wrong thread releases a resource.
A bug check with this parameter occurs only when the
Deadlock Detection option of Driver Verifier is active.
Multiple initialization: A resource is initialized more than
one time. A bug check with this parameter occurs only
when the Deadlock Detection option of Driver Verifier is
active.
Thread holds resources: A thread is deleted before the
thread can release its resources. A bug check with this
parameter occurs only when the Deadlock Detection
option of Driver Verifier is active.
Unacquired resource: A resource is released before it has
been acquired. A bug check with this parameter occurs only
when the Deadlock Detection option of Driver Verifier is
active.
The driver tried to acquire a lock by using an API that is
mismatched for this lock type.

(operating systems and

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 870 of 1651

later)
0x1009

Lock address

Driver Verifier internal

data

Owner thread address

Driver Verifier internal

data

Lock address

Owner thread address

Address that referenced memory

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 871 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Bug Check 0xC6: DRIVER_CAUGHT_MODIFYING_FREED_POOL

The DRIVER_CAUGHT_MODIFYING_FREED_POOL bug check has a value of 0x000000C6. This indicates that the driver attempted to access a freed memory pool.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory referenced
2
0: Read
1: Write
3

0: Kernel mode
1: User mode

Reserved

Comments
The faulty component will be displayed in the current kernel stack. This driver should be either replaced or debugged.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC7: TIMER_OR_DPC_INVALID

The TIMER_OR_DPC_INVALID bug check has a value of 0x000000C7. This is issued if a kernel timer or delayed procedure call (DPC) is found somewhere in memory
where it is not permitted.
Parameters
The following parameters are displayed on the blue screen.
Parameter Parameter 2
1
0x0
Address of the
timer object
0x1
Address of the
DPC object
0x2
Address of the
DPC routine
0x3
Address of the
DPC object
0x4
Address of the
DPC routine

Parameter 3
Start of memory range being
checked
Start of memory range being
checked
Start of memory range being
checked
Processor number
The threads APC disable count
before the kernel calls the DPC
routine

Parameter 4

Cause of error

End of memory range being

checked
End of memory range being
checked
End of memory range being
checked
Number of processors in the
system
The threads APC disable count
after the DPC routine is called

The timer object was found in a block of memory where a timer object
is not permitted. .
The DPC object was found in a block of memory where a DPC object
is not permitted.
The DPC routine was found in a block of memory where a DPC object
is not permitted.
The processor number for the DPC object is not correct.
The threads APC disable count was changed during DPC routine
execution.
The APC disable count is decremented each time a driver calls
KeEnterCriticalRegion, FsRtlEnterFileSystem, or acquires a mutex.
The APC disable count is incremented each time a driver calls
KeLeaveCriticalRegion, KeReleaseMutex, or FsRtlExitFileSystem.

0x5

Address of the
DPC routine

The threads APC disable count

before the kernel calls the DPC
routine

The threads APC disable count The threads APC disable count was changed during the execution of
after the DPC routine is called timer DPC routine.
The APC disable count is decremented each time a driver calls
KeEnterCriticalRegion, FsRtlEnterFileSystem, or acquires a mutex.
The APC disable count is incremented each time a driver calls
KeLeaveCriticalRegion, KeReleaseMutex, or FsRtlExitFileSystem.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 872 of 1651

Cause
This condition is usually caused by a driver failing to cancel a timer or DPC before freeing the memory where it resides.
Resolving the Problem
If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code.
If you are a system administrator, you should unload the driver if the problem persists.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC8: IRQL_UNEXPECTED_VALUE

The IRQL_UNEXPECTED_VALUE bug check has a value of 0x000000C8. This indicates that the processor's IRQL is not what it should be at this time.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The value of the following bit computation:
(Current IRQL << 16) | (Expected IRQL << 8) | UniqueValue

2
3
4

Zero, or APC->KernelRoutine
Zero, or APC
Zero, or APC->NormalRoutine

You can determine "UniqueValue" by computing (Parameter 1 AND 0xFF). If "UniqueValue" is either zero or one, Parameter 2, Parameter 3, and Parameter 4 will equal the
indicated APC pointers. Otherwise, these parameters will equal zero.
Cause
This error is usually caused by a device driver or another lower-level program that changed the IRQL for some period and did not restore the original IRQL at the end of that
period. For example, the routine may have acquired a spin lock and failed to release it.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC9: DRIVER_VERIFIER_IOMANAGER_VIOLATION

The DRIVER_VERIFIER_IOMANAGER_VIOLATION bug check has a value of 0x000000C9. This is the bug check code for all Driver Verifier I/O Verification
violations.
Parameters
When Driver Verifier is active and I/O Verification is selected, various I/O violations will cause this bug check to be issued. The following parameters will be displayed on
the blue screen. Parameter 1 identifies the type of violation.
Parameter
1
0x01
0x02
0x03
0x04
0x05

Parameter 2

0x06

Address of IRP being freed

Address of IRP being freed
Address of IRP being sent
Address of device object
Address of device object
associated with offending driver
IRP status

0x07

Address of cancel routine

0x08

Address of device object

Parameter 3
0
0
0
0
IRQL before
IoCallDriver
Address of IRP being
completed
Address of IRP being
completed
IRP major function
code

Parameter 4
0
0
0
0
IRQL after
IoCallDriver
0
0
Exception status
code

Cause of Error
The driver attempted to free an object whose type is not IO_TYPE_IRP.
The driver attempted to free an IRP that is still associated with a thread.
The driver passed IoCallDriver an IRP Type not equal to IRP_TYPE.
The driver passed IoCallDriver an invalid device object.
The IRQL changed during a call to the driver dispatch routine.
The driver called IoCompleteRequest with a status marked as pending (or equal
to -1).
The driver called IoCompleteRequest while its cancel routine was still set.
The driver passed IoBuildAsynchronousFsdRequest an invalid buffer.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 873 of 1651

0x09

Address of device object

I/O control code

0x0A

Address of device object

Exception status
code
0

0x0C

Address of I/O status block

0x0D

Address of user event object

0x0E
0x0F

Current IRQL
Address of the device object to
which the IRP is being sent

Address of IRP
Pointer to the IRP

0
Pointer to file
object

The driver passed IoBuildDeviceIoControlRequest an invalid buffer.

The driver passed IoInitializeTimer a device object with an already-initialized
timer.
The driver passed an I/O status block to an IRP, but this block is allocated on a
stack which has already unwound past that point.
The driver passed a user event to an IRP, but this event is allocated on a stack
which has already unwound past that point.
The driver called IoCompleteRequest with IRQL > DISPATCH_LEVEL.
The driver sent a create request with a file object that has been closed, or that had
its open canceled.

In addition to the errors mentioned in the previous table, there are a number of I/O Verification errors that will cause Driver Verifier to halt the system, but which are not
actually bug checks.
These errors cause messages to be displayed on the blue screen, in a crash dump file, and in a kernel debugger. These messages will appear differently in each of these
locations. When these errors occur, the hexadecimal bug check code 0xC9 and the bug check string DRIVER_VERIFIER_IOMANAGER_VIOLATION do not appear on the
blue screen or in the debugger, although they will appear in a crash dump file.
On the blue screen, the following data will be displayed:

The message IO SYSTEM VERIFICATION ERROR.

The message WDM DRIVER ERROR XXX, where XXX is a hexadecimal code representing the specific error. (See the table below for a list of the I/O error codes and
their meanings.)
The name of the driver which caused the error.
The address in the driver's code where the error was detected (Parameter 2).
A pointer to the IRP (Parameter 3).
A pointer to the device object (Parameter 4).

If a kernel-mode crash dump has been enabled, the following information will appear in the crash dump file:

The message BugCheck 0xC9 (DRIVER_VERIFIER_IOMANAGER_VIOLATION).

The hexadecimal I/O error code. (See the table below for a list of the I/O error codes and their meanings.)
The address in the driver's code where the error was detected.
A pointer to the IRP.
A pointer to the device object.

If a kernel debugger is attached to the system which has caused this violation, the following information will be sent to the debugger:

The message WDM DRIVER ERROR, along with an assessment of the severity of the error.
The name of the driver which caused the error.
A descriptive string which explains the cause of this error. Often additional information is passed along, such as a pointer to the IRP. (See the table below for a list of
these descriptive strings and what additional information is specified.)
A query for further action. Possible responses are b (break), i (ignore), z (zap), r (remove), or d (disable). Instructing the operating system to continue allows you to see
what would happen "down the line" if this error had not occurred. Of course, this often will lead to additional bug checks. The "zap" option will actually remove the
breakpoint that caused this error to be discovered.

Note No other bug checks can be ignored in this manner. Only this kind of I/O Verification errors can be ignored, and even these errors can only be ignored if a kernel
debugger is attached.
The following table lists those I/O Verification errors that can appear. In Windows 2000, these errors will only be displayed if I/O Verification is set to Level 2.
I/O Error Severity
Code
0x200
Unknown
0x201
Fatal error
0x202

Fatal error

0x203
0x204
0x205

Fatal error
Fatal error
Fatal error

0x206

Fatal error

0x207

Fatal error

0x208
0x209

Fatal error
Fatal error

0x20A
0x20B
0x20C
0x20D

Fatal error
Fatal error
Fatal error
Fatal error

0x20E

Non-fatal
error
Non-fatal
error

0x20F

Cause of Error
This code covers all unknown I/O Verification errors.
A device is deleting itself while there is another device beneath it in the driver stack. This may be because the caller has forgotten to call
IoDetachDevice first, or the lower driver may have incorrectly deleted itself.
A driver has attempted to detach from a device object that is not attached to anything. This may occur if detach was called twice on the same device
object. (Device object specified.)
A driver has called IoCallDriver without setting the cancel routine in the IRP to NULL. (IRP specified.)
The caller has passed in NULL as a device object. This is fatal. (IRP specified.)
The caller is forwarding an IRP that is currently queued beneath it. The code handling IRPs returning STATUS_PENDING in this driver appears to
be broken. (IRP specified.)
The caller has incorrectly forwarded an IRP (control field not zeroed). The driver should use IoCopyCurrentIrpStackLocationToNext or
IoSkipCurrentIrpStackLocation. (IRP specified.)
The caller has manually copied the stack and has inadvertently copied the upper layer's completion routine. The driver should use
IoCopyCurrentIrpStackLocationToNext. (IRP specified.)
This IRP is about to run out of stack locations. Someone may have forwarded this IRP from another stack. (IRP specified.)
The caller is completing an IRP that is currently queued beneath it. The code handling IRPs returning STATUS_PENDING in this driver appears to
be broken. (IRP specified.)
The caller of IoFreeIrp is freeing an IRP that is still in use. (Original IRP and IRP in use specified.)
The caller of IoFreeIrp is freeing an IRP that is still in use. (IRP specified.)
The caller of IoFreeIrp is freeing an IRP that is still queued against a thread. (IRP specified.)
The caller of IoInitializeIrp has passed an IRP that was allocated with IoAllocateIrp. This is illegal and unnecessary, and has caused a quota leak.
Check the documentation for IoReuseIrp if this IRP is being recycled.
A PNP IRP has an invalid status. (Any PNP IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)
A Power IRP has an invalid status. (Any Power IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x210

0x21C

Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Warning

0x21D

Fatal error

0x21E

Fatal error

0x21F

0x221

Non-fatal
error
Non-fatal
error
Fatal error

0x222

Fatal error

0x223

Fatal error

0x224

Fatal error

0x225

Non-fatal
error
Fatal error

0x211
0x212
0x213
0x214
0x215
0x216
0x217
0x218
0x219
0x21A
0x21B

0x220

0x226
0x227
0x228
0x229
0x22A
0x22B
0x22C
0x22D
0x22E
0x22F
0x230
0x231
0x232
0x233
0x234
0x235
0x236
0x237

Fatal error
Non-fatal
error
Fatal error
Non-fatal
error
Non-fatal
error
Fatal error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Fatal error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Non-fatal
error
Fatal error

Page 874 of 1651

A WMI IRP has an invalid status. (Any WMI IRP must have its status initialized to STATUS_NOT_SUPPORTED.) (IRP specified.)
The caller has forwarded an IRP while skipping a device object in the stack. The caller is probably sending IRPs to the PDO instead of to the device
returned by IoAttachDeviceToDeviceStack. (IRP specified.)
The caller has trashed or has not properly copied the IRP's stack. (IRP specified.)
The caller has changed the status field of an IRP it does not understand. (IRP specified.)
The caller has changed the information field of an IRP it does not understand. (IRP specified.)
A non-successful non-STATUS_NOT_SUPPORTED IRP status for IRP_MJ_PNP is being passed down stack. (IRP specified.) Failed PNP IRPs
must be completed.
The previously-set IRP_MJ_PNP status has been converted to STATUS_NOT_SUPPORTED. (IRP specified.)
The driver has not handled a required IRP. The driver must update the status of the IRP to indicate whether or not it has been handled. (IRP
specified.)
The driver has responded to an IRP that is reserved for other device objects elsewhere in the stack. (IRP specified.)
A non-successful non-STATUS_NOT_SUPPORTED IRP status for IRP_MJ_POWER is being passed down stack. (IRP specified.) Failed POWER
IRPs must be completed.
The previously-set IRP_MJ_POWER status has been converted to STATUS_NOT_SUPPORTED. (IRP specified.)
A driver has returned a suspicious status. This is probably due to an uninitialized variable bug in the driver. (IRP specified.)
The caller has copied the IRP stack but not set a completion routine. This is inefficient use IoSkipCurrentIrpStackLocation instead. (IRP
specified.)
An IRP dispatch handler has not properly detached from the stack below it upon receiving a remove IRP. (Device object, dispatch routine, and IRP
specified.)
An IRP dispatch handler has not properly deleted its device object upon receiving a remove IRP. (Device object, dispatch routine, and IRP
specified.)
A driver has not filled out a dispatch routine for a required IRP major function. (IRP specified.)
IRP_MJ_SYSTEM_CONTROL has been completed by someone other than the ProviderId. This IRP should either have been completed earlier or
should have been passed down. (IRP specified, along with the device object where it was targeted.)
An IRP dispatch handler for a PDO has deleted its device object, but the hardware has not been reported as missing in a bus relations query.
(Device object, dispatch routine, and IRP specified.)
A Bus Filter's IRP dispatch handler has detached upon receiving a remove IRP when the PDO is still alive. Bus Filters must clean up in
FastIoDetach callbacks. (Device object, dispatch routine, and IRP specified.)
An IRP dispatch handler for a bus filter has deleted its device object, but the PDO is still present. Bus filters must clean up in FastIoDetach
callbacks. (Device object, dispatch routine, and IRP specified.)
An IRP dispatch handler has returned a status that is inconsistent with the IRP's IoStatus.Status field. (Dispatch handler routine, IRP, IRP's
IoStatus.Status, and returned Status specified.)
An IRP dispatch handler has returned a status that is illegal (0xFFFFFFFF). This is probably due to an uninitialized stack variable. To debug this
error, use the ln (List Nearest Symbols) command with the specified address.
An IRP dispatch handler has returned without passing down or completing this IRP, or someone forgot to return STATUS_PENDING. (IRP
specified.)
An IRP completion routine is in pageable code. (This is never permitted.) (Routine and IRP specified.)
A driver's completion routine has not marked the IRP pending if the PendingReturned field was set in the IRP passed to it. This may cause
Windows to hang, especially if an error is returned by the stack. (Routine and IRP specified.)
A cancel routine has been set for an IRP that is currently being processed by drivers lower in the stack, possibly stomping their cancel routine.
(Routine and IRP specified.)
The physical device object (PDO) has not responded to a required IRP. (IRP specified.)
The physical device object (PDO) has forgotten to fill out the device relation list with the PDO for the TargetDeviceRelation query. (IRP
specified.)
The code implementing the TargetDeviceRelation query has not called ObReferenceObject on the PDO. (IRP specified.)
The caller has completed a IRP_MJ_PNP it didn't understand instead of passing it down. (IRP specified.)
The caller has completed a successful IRP_MJ_PNP instead of passing it down. (IRP specified.)
The caller has completed an untouched IRP_MJ_PNP (instead of passing the IRP down), or non-PDO has failed the IRP using illegal value of
STATUS_NOT_SUPPORTED. (IRP specified.)
The caller has completed an IRP_MJ_POWER it didn't understand instead of passing it down. (IRP specified.)
The caller has completed a successful IRP_MJ_POWER instead of passing it down. (IRP specified.)
The caller has completed an untouched IRP_MJ_POWER (instead of passing the IRP down), or non-PDO has failed the IRP using illegal value of
STATUS_NOT_SUPPORTED. (IRP specified.)
The version field of the query capabilities structure in a query capabilities IRP was not properly initialized. (IRP specified.)
The size field of the query capabilities structure in a query capabilities IRP was not properly initialized. (IRP specified.)
The address field of the query capabilities structure in a query capabilities IRP was not properly initialized to -1. (IRP specified.)
The UI Number field of the query capabilities structure in a query capabilities IRP was not properly initialized to -1. (IRP specified.)
A driver has sent an IRP that is restricted for system use only. (IRP specified.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x238

Warning

0x239

Warning

0x23A
0x23B

Fatal error
Non-fatal
error

Page 875 of 1651

The caller of IoInitializeIrp has passed an IRP that was allocated with IoAllocateIrp. This is illegal, unnecessary, and negatively impacts
performance in normal use. If this IRP is being recycled, see IoReuseIrp in the Windows Driver Kit.
The caller of IoCompleteRequest is completing an IRP that has never been forwarded via a call to IoCallDriver or PoCallDriver. This may be a
bug. (IRP specified.)
A driver has forwarded an IRP at an IRQL that is illegal for this major code. (IRP specified.)
The caller has changed the status field of an IRP it does not understand. (IRP specified.)

The following table lists additional I/O Verification errors that can appear in Windows XP and later. Some of these errors will only be revealed if Enhanced I/O
Verification is activated.
I/O Error Severity
Code
0x23C
Fatal error
0x23D
Non-fatal
error
0x23E
Non-fatal
error
0x23F
Fatal error
0x240
Fatal error
0x241
Fatal error
0x242
Fatal error
0x243
Fatal error
0x244
Fatal error
0x245
0x246
0x247
0x248
0x249
0x24A
0x24B
0x24C
0x24D

Cause of Error
A driver has completed an IRP without setting the cancel routine in the IRP to NULL. (IRP specified.)
A driver has returned STATUS_PENDING but did not mark the IRP pending via a call to IoMarkIrpPending. (IRP specified.)
A driver has marked an IRP pending but didn't return STATUS_PENDING. (IRP specified.)
A driver has not inherited the DO_POWER_PAGABLE bit from the stack it has attached to. (Device object specified.)
A driver is attempting to delete a device object that has already been deleted via a prior call to IoDeleteDevice.
A driver has detached its device object during a surprise remove IRP. (IRP and device object specified.)
A driver has deleted its device object during a surprise remove IRP. (IRP and device object specified.)
A driver has failed to clear the DO_DEVICE_INITIALIZING flag at the end of AddDevice. (Device object specified.)
A driver has not copied either the DO_BUFFERED_IO or the DO_DIRECT_IO flag from the device object it is attaching to. (Device object
specified.)
A driver has set both the DO_BUFFERED_IO and the DO_DIRECT_IO flags. These flags are mutually exclusive. (Device object specified.)
A driver has failed to copy the DeviceType field from the device object it is attaching to. (Device object specified.)
A driver has failed an IRP that cannot legally be failed. (IRP specified.)
A driver has added a device object that is not a PDO to a device relations query. (IRP and device object specified.)
A driver has enumerated two child PDOs that returned identical Device IDs. (Both device objects specified.)

Fatal error
Fatal error
Fatal error
Fatal error
Non-fatal
error
Fatal error A driver has mistakenly called a file I/O function with IRQL not equal to PASSIVE_LEVEL.
Fatal error A driver has completed an IRP_MN_QUERY_DEVICE_RELATIONS request of type TargetDeviceRelation as successful, but did not properly
fill out the request or forward the IRP to the underlying hardware stack. (Device object specified.)
Non-fatal A driver has returned STATUS_PENDING but did not mark the IRP pending by a call to IoMarkIrpPending. (IRP specified.)
error
Fatal error A driver has passed an invalid device object to a function that requires a PDO. (Device object specified.)

Cause
See the description of each code in the Parameters section for a description of the cause.
Resolving the Problem
This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it.
You might consider removing the driver which caused this problem as well.
If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code.
For full details on Driver Verifier, see the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xCA: PNP_DETECTED_FATAL_ERROR

The PNP_DETECTED_FATAL_ERROR bug check has a value of 0x000000CA. This indicates that the Plug and Play Manager encountered a severe error, probably as a
result of a problematic Plug and Play driver.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 identifies the type of violation.
Parameter
Parameter 2
1
0x1
Address of newly-reported PDO

0x2

Address of purported PDO

Parameter 3

Parameter 4

Address of older Reserved

PDO which has
been duplicated
Address of driver Reserved
object

Cause of Error
Duplicate PDO: A specific instance of a driver has enumerated multiple PDOs
with identical device ID and unique IDs.
Invalid PDO: An API which requires a PDO has been called with random
memory, or with an FDO, or with a PDO which hasn't been initialized.
(An uninitialized PDO is one that has not been returned to Plug and Play by

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 876 of 1651

QueryDeviceRelation or QueryBusRelations.)
0x3

Address of PDO whose IDs were Address of ID

queried
buffer

1: DeviceID
2: UniqueID

Invalid ID: An enumerator has returned an ID which contains illegal

characters or isn't properly terminated. (IDs must contain only characters in the
ranges 0x20 - 0x2B and 0x2D - 0x7F.)

3: HardwareIDs
4: CompatibleIDs
0x4
0x5

Address of PDO with

DOE_DELETE_PENDING set
Address of PDO

0x8

Address of PDO whose stack

returned the invalid bus relation

0x9

Connection type that was passed

0xA

Driver object

0xB

Related PDO

Invalid enumeration of deleted PDO: An enumerator has returned a PDO

which it had previously deleted using IoDeleteDevice.
Reserved
Reserved
PDO freed while linked in devnode tree: The object manager reference count
on a PDO dropped to zero while the devnode was still linked in the tree. (This
usually indicates that the driver is not adding a reference when returning the
PDO in a query IRP.)
Total number of The index (zero-based) at Null pointer returned as a bus relation: One or more of the devices present
PDOs returned as which the first NULL
on the bus is a NULL PDO.
bus relations
PDO was found
Reserved
Reserved
Invalid connection type passed to IoDisconnectInterruptEx: A driver has
passed an invalid connection type to IoDisconnectInterruptEx. The
connection type passed to this routine must match the one returned by a
corresponding successful call to IoConnectInterruptEx.
IRQL after
Combined APC disable Incorrect notify callback behavior: A driver failed to preserve IRQL or
returning from
count after returning
combined APC disable count across a Plug 'n' Play notification.
driver callback
from driver callback
Removal relations Reserved
Deleted PDO reported as relation: One of the removal relations for the
device being removed has already been deleted.
Reserved

Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xCB: DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS

The DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS bug check has a value of 0x000000CB. This indicates that a driver or the I/O manager failed to release locked pages
after an I/O operation.
Parameters
The four parameters listed in the message can have two possible meanings.
If a driver locked these pages, the parameters have the following meaning.
Parameter
Description
1
Calling address in the driver that locked the pages
2
Caller of the calling address in driver that locked the pages
3
Address of the MDL containing the locked pages
4
Number of locked pages
If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
If the I/O manager locked these pages, the parameters have the following meaning.
Parameter
Description
1
Address of the dispatch routine of the top driver on the stack to which the IRP was sent
2
Address of the device object of the top driver on the stack to which the IRP was sent
3
Address of the MDL containing the locked pages
4
Number of locked pages
Comments
This bug check is issued only if the registry value
\\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\TrackLockedPages is equal to DWORD 1. If this value
is not set, the system will issue the less-informative bug check 0x76 (PROCESS_HAS_LOCKED_PAGES).
Starting with Windows Vista, this bug check can also be issued by Driver Verifier when the Pool Tracking option is enabled.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 877 of 1651

Debugging Tools for Windows

Bug Check 0xCC: PAGE_FAULT_IN_FREED_SPECIAL_POOL

The PAGE_FAULT_IN_FREED_SPECIAL_POOL bug check has a value of 0x000000CC. This indicates that the system has referenced memory which was earlier freed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced
2
0: Read
1: Write
3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
The system has accessed memory in the special pool which was already freed by a driver. This usually indicates a system-driver synchronization problem.
For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
Comments
This cannot be protected by a try - except handler it can only be protected by a probe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xCD: PAGE_FAULT_BEYOND_END_OF_ALLOCATION

The PAGE_FAULT_BEYOND_END_OF_ALLOCATION bug check has a value of 0x000000CD. This indicates that the system accessed memory beyond the end of some
driver's pool allocation.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced
2
0: Read
1: Write
3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
The driver allocated n bytes of memory from the special pool. Subsequently, the system referenced more than n bytes from this pool. This usually indicates a system-driver
synchronization problem.
For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
Comments
This cannot be protected by a try - except handler it can only be protected by a probe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 878 of 1651

Bug Check 0xCE:

DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS
The DRIVER_UNLOADED_WITHOUT_CANCELLING_PENDING_OPERATIONS bug check has a value of 0x000000CE. This indicates that a driver failed to cancel
pending operations before unloading.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced
2
0: Read
1: Write
3
4

Address that referenced memory (if known)

Reserved

Bug Check 0xCF:

TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE
The TERMINAL_SERVER_DRIVER_MADE_INCORRECT_MEMORY_REFERENCE bug check has a value of 0x000000CF. This indicates that a driver has been
incorrectly ported to the terminal server.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced
2
0: Read
1: Write
3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
The driver is referencing session space addresses from the system process context. This probably results from the driver queuing an item to a system worker thread.
This driver needs to comply with Terminal Server's memory management rules.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD0: DRIVER_CORRUPTED_MMPOOL

The DRIVER_CORRUPTED_MMPOOL bug check has a value of 0x000000D0. This indicates that the system attempted to access invalid memory at a process IRQL that
was too high.
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 879 of 1651

The following parameters are displayed on the blue screen.

Parameter
Description
1
Memory referenced
2
IRQL at time of reference
3
0: Read
1: Write
4

Address that referenced memory

Cause
The kernel attempted to access pageable memory (or perhaps completely invalid memory) when the IRQL was too high. The ultimate cause of this problem is almost certainly
a driver that has corrupted the system pool.
In most cases, this bug check results if a driver corrupts a large allocation (PAGE_SIZE or larger). Smaller allocations result in bug check 0xC5
(DRIVER_CORRUPTED_EXPOOL).
Resolving the Problem
If you have recently installed any new software, check to see if it is properly installed. Check for updated drivers on the manufacturer's website.
To debug this error, use the special pool option of Driver Verifier. If this fails to reveal the driver that caused the error, use the Global Flags utility to enable the special pool
by pool tag.
For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
An alternate method is to open the \\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management registry key. In this
key, create or edit the ProtectNonPagedPool value, and set it equal to DWORD 1. Then reboot. Then the system will unmap all freed nonpaged pool. This will prevent
drivers from corrupting the pool. (This does not protect the pool from DMA hardware, however.)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD1: DRIVER_IRQL_NOT_LESS_OR_EQUAL

The DRIVER_IRQL_NOT_LESS_OR_EQUAL bug check has a value of 0x000000D1. This indicates that a kernel-mode driver attempted to access pageable memory at a
process IRQL that was too high.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory referenced
2
IRQL at time of reference
3
0: Read
1: Write
8: Execute
4

Address that referenced memory

Cause
A driver tried to access an address that is pageable (or that is completely invalid) while the IRQL was too high.
This bug check is usually caused by drivers that have used improper addresses.
If the first parameter has the same value as the fourth parameter, and the third parameter indicates an execute operation, this bug check was likely caused by a driver that was
trying to execute code when the code itself was paged out. Possible causes for the page fault include the following:

The function was marked as pageable and was running at an elevated IRQL (which includes obtaining a lock).
The function call was made to a function in another driver, and that driver was unloaded.
The function was called by using a function pointer that was an invalid pointer.

Resolving the Problem

To begin debugging, use a kernel debugger to get a stack trace.
If the problem is caused by the driver that you are developing, make sure that the function that was executing at the time of the bug check is not marked as pageable or does
not call any other inline functions that could be paged out.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 880 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD2: BUGCODE_ID_DRIVER

The BUGCODE_ID_DRIVER bug check has a value of 0x000000D2. This indicates that a problem occurred with an NDIS driver.
Parameters
Before this bug check occurs, a message is sent to the DbgPrint buffer. If a debugger is connected, this message will be displayed.
This message indicates the type of violation. The meanings of the bug check parameters depend on this message.
Parameter 1
Parameter 2
Address of the Number of bytes requested
miniport block
Address of the The Status value submitted to
miniport block NdisMResetComplete

Parameter 3

Parameter 4

The AddressingReset value

submitted to
NdisMResetComplete
Address of the Memory page containing address Address of shared memory
miniport block being freed
signature
Address of the Address of the packet that is
miniport block incorrectly included in the packet
array
Address of the Address of the driver object
MiniBlock
Address of the The MiniBlock's reference count
MiniBlock
Address of the Memory page
miniport block

Address of the packet array

Virtual address
being freed

Number of
packets in the
array
0

Wrapper context

Address of
shared memory
signature

Message and Cause

Allocating shared memory at raised IRQL. A driver called
NdisMAllocateSharedMemory with IRQL >= DISPATCH_LEVEL.
Completing reset when one is not pending. A driver called
NdisMResetComplete, but no reset was pending.
Freeing shared memory not allocated. A driver called
NdisMFreeSharedMemory or NdisMFreeSharedMemoryAsync
with an address that is not located in NDIS shared memory.
Indicating packet not owned by it. The miniport's packet array is
corrupt.
NdisAddDevice: AddDevice called with a MiniBlock that is not on
the NdisMiniDriverList.
NdisMUnload: MiniBlock is getting unloaded but it is still on
NdisMiniDriverList.
Overwrote past allocated shared memory. The address being
written to is not located in NDIS shared memory.

In the following instances of this bug check, the meaning of the parameters depends on the message and on the value of Parameter 4.
Parameter 1
Address of the
miniport block
Address of the
miniport block
Address of the
miniport block
Address of the
miniport block

Parameter 2
Address of the miniport
interrupt
Address of the miniport
timer queue
Address of the miniport
interrupt
Address of the miniport
timer queue

Parameter 3
Address of the miniport
timer queue
Address of the miniport
interrupt
Address of the miniport
timer queue
Address of the miniport
interrupt

Parameter
Message and Cause
4
1
Unloading without deregistering interrupt. A miniport driver failed its
initialization without deregistering its interrupt.
2
Unloading without deregistering interrupt. A miniport driver did not deregister
its interrupt during the halt process.
1
Unloading without deregistering timer. A miniport driver failed its initialization
without successfully canceling all its timers.
2
Unloading without deregistering timer. A miniport driver halted without
successfully canceling all its timers.

Comments
This bug check code only occurs on Windows 2000 and Windows XP. In Windows Server 2003 and later, the corresponding code is bug check 0x7C
(BUGCODE_NDIS_DRIVER).
On the checked build of Windows, only the Allocating Shared Memory at Raised IRQL and Completing Reset When One is Not Pending instances of this bug check can
occur. All the other instances of bug check 0xD2 are replaced with ASSERTs. See Breaking Into the Debugger for details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD3: DRIVER_PORTION_MUST_BE_NONPAGED

The DRIVER_PORTION_MUST_BE_NONPAGED bug check has a value of 0x000000D3. This indicates that the system attempted to access pageable memory at a process
IRQL that was too high.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory referenced

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

2
3

Page 881 of 1651

IRQL at time of reference

0: Read
1: Write

Address that referenced memory

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
This bug check is usually caused by drivers that have incorrectly marked their own code or data as pageable.
Resolving the Problem
To begin debugging, use a kernel debugger to get a stack trace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD4:

SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD
The SYSTEM_SCAN_AT_RAISED_IRQL_CAUGHT_IMPROPER_DRIVER_UNLOAD bug check has a value of 0x000000D4. This indicates that a driver did not cancel
pending operations before unloading.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory referenced
2
IRQL at time of reference
3
0: Read
1: Write
4

Address that referenced memory

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
This driver failed to cancel lookaside lists, DPCs, worker threads, or other such items before unload. Subsequently, the system attempted to access the driver's former location
at a raised IRQL.
Resolving the Problem
To begin debugging, use a kernel debugger to get a stack trace. If the driver that caused the error has been identified, activate Driver Verifier and attempt to replicate this bug.
For full details on Driver Verifier, see the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD5: DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL

The DRIVER_PAGE_FAULT_IN_FREED_SPECIAL_POOL bug check has a value of 0x000000D5. This indicates that a driver has referenced memory which was earlier
freed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 882 of 1651

0: Read
1: Write

3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
The Driver Verifier Special Pool option has caught the driver accessing memory which was earlier freed.
For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
Comments
This cannot be protected by a try - except handler it can only be protected by a probe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD6:

DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION
The DRIVER_PAGE_FAULT_BEYOND_END_OF_ALLOCATION bug check has a value of 0x000000D6. This indicates the driver accessed memory beyond the end of
its pool allocation.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Memory address referenced
2
0: Read
1: Write
3
4

Address that referenced memory (if known)

Reserved

If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
The driver allocated n bytes of memory and then referenced more than n bytes. The Driver Verifier Special Pool option detected this violation.
For information about the special pool, consult the Driver Verifier section of the Windows Driver Kit.
Comments
This cannot be protected by a try - except handler it can only be protected by a probe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD7: DRIVER_UNMAPPING_INVALID_VIEW

The DRIVER_UNMAPPING_INVALID_VIEW bug check has a value of 0x000000D7. This indicates a driver is trying to unmap an address that was not mapped.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Virtual address to unmap

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 883 of 1651

1: The view is being unmapped

2: The view is being committed

3
4

0
0

Comments
The driver that caused the error can be determined from the stack trace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD8: DRIVER_USED_EXCESSIVE_PTES

The DRIVER_USED_EXCESSIVE_PTES bug check has a value of 0x000000D8. This indicates that there are no more system page table entries (PTE) remaining.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Pointer to the name of the driver that caused the error (Unicode string), or zero
2
Number of PTEs used by the driver that caused the error (if Parameter 1 is nonzero)
3
Total free system PTEs
4
Total system PTEs
If the driver responsible for the error can be identified, its name is printed on the blue screen and stored in memory at the location (PUNICODE_STRING)
KiBugCheckDriver.
Cause
This is usually caused by a driver not cleaning up its memory use properly. Parameter 1 shows the driver which has consumed the most PTEs. The call stack will reveal which
driver actually caused the bug check.
Resolving the Problem
Both drivers may need to be fixed. The total number of system PTEs may also need to be increased.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xD9: LOCKED_PAGES_TRACKER_CORRUPTION

The LOCKED_PAGES_TRACKER_CORRUPTION bug check has a value of 0x000000D9. This indicates that the internal locked-page tracking structures have been
corrupted.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of
Parameter 1.
Parameter
Parameter 2
1
0x01
The address of the internal lock
tracking structure
0x02
The address of the internal lock
tracking structure
0x03
The address of the first internal
tracking structure found
0x04
The address of the internal lock
tracking structure

Parameter 3
The address of the memory
descriptor list
The address of the memory
descriptor list
The address of the internal lock
tracking structure
The address of the memory
descriptor list

Parameter 4
The number of pages locked for the
current process
The number of pages locked for the
current process
The address of the memory
descriptor list
0

Cause of Error
The MDL is being inserted twice on the same
process list.
The MDL is being inserted twice on the
systemwide list.
The MDL was found twice in the process list
when being freed.
The MDL was found in the systemwide list on
free after it was removed.

Cause
The error is indicated by the value of Parameter 1.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 884 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDA: SYSTEM_PTE_MISUSE

The SYSTEM_PTE_MISUSE bug check has a value of 0x000000DA. This indicates that a page table entry (PTE) routine has been used in an improper way.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of
Parameter 1.
Parameter
Parameter 2
Parameter 3
Parameter 4
1
0x01
The address of the
The address of the
The address of the
internal lock tracking memory descriptor list duplicate internal
structure
lock tracking
structure
0x02
The address of the
The number of
The number of
internal lock tracking mappings that the
mappings that the
structure
system expects to free driver is requesting
to free
0x03
The address of the
The mapping address The mapping address
first internal tracking that the system expects that the driver is
structure found
to free
requesting to free
0x04
The address of the
The page frame number The page frame
internal lock tracking that the system expects number that is
structure
should be first in the
currently first in the
MDL
MDL
0x05
The address of the
The virtual address that The virtual address
first internal tracking the system expects to that the driver is
structure found
free
requesting to free
0x06
The MDL specified The virtual address
The number of
by the driver
specified by the driver mappings to free
(specified by the
driver)
0x07
The initial mapping The number of
Reserved
mappings
0x08
The initial mapping The number of
The number of
mappings the caller is mappings the system
freeing
thinks should be
freed
0x09
The initial mapping The number of
The mapping index
mappings that the caller that the system
is freeing
thinks is already free
0x0A
1: The driver
The number of
The type of mapping
requested "bug check mappings that the caller pool requested
on failure" in the
is allocating
MDL.

Cause of Error
The mapping being freed is a duplicate.

The number of mappings being freed is incorrect.

The mapping address being freed is incorrect.

The first page of the mapped MDL has changed since the MDL was mapped.

The start virtual address in the MDL being freed has changed since the MDL was mapped.

The MDL being freed was never (or is currently not) mapped.

(Windows 2000 only) The mapping range is being double-allocated.

(Windows 2000 only) The caller is asking to free an incorrect number of mappings.

(Windows 2000 only) The caller is asking to free several mappings, but at least one of them
is not allocated.
(Windows 2000 only) The caller is asking to allocate zero mappings.

0: The driver did not

request "bug check on
failure" in the MDL.
0x0B

0x0C

0x0D

0x0E

0x0F

0x10

0x11

The corrupt mapping The number of

mappings that the caller
is allocating
The corrupt mapping The number of
mappings that the caller
is allocating
The initial mapping The number of
mappings that the caller
is freeing
The initial mapping The number of
mappings that the caller
is freeing
The non-existent
The number of
mapping
mappings that the caller
is trying to free
The non-existent
The number of
mapping
mappings the caller is
trying to free
The non-existent
The number of
mapping
mappings that the caller
is trying to free

The type of mapping (Windows 2000 only) The mapping list was already corrupt at the time of this allocation.
pool requested
The corrupt mapping is located below the lowest possible mapping address.
The type of mapping (Windows 2000 only) The mapping list was already corrupt at the time of this allocation.
pool requested
The corrupt mapping is located above the lowest possible mapping address.
The type of mapping (Windows 2000 only) The caller is trying to free zero mappings.
pool
The type of mapping (Windows 2000 only) The caller is trying to free mappings, but the guard mapping has been
pool
overwritten.
The type of mapping (Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent
pool being freed
mapping is located below the lowest possible mapping address.
The type of mapping (Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent
pool being freed
mapping is located above the highest possible mapping address.
The type of mapping (Windows 2000 only) The caller is trying to free a non-existent mapping. The non-existent
pool being freed
mapping is at the base of the mapping address space.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 885 of 1651

0x100

The number of
mappings being
requested

0x101

The first mapping

address
The first mapping
address
The address of the
invalid mapping

0x102
0x103

0x104
0x105
0x107

0x108
0x109
0x10A

0x10B
0x10C
0x200
0x201
0x202
0x300
0x301
0x303
0x304
0x305

0x306
0x400

mapping that has
already been reserved
0

The last mapping

address

The number of
mappings to unmap

(Windows XP and later only) The caller requested 0 mappings.

(Windows XP and later only) A caller is trying to free a mapping address range that it does
not own.
(Windows XP and later only) The mapping address space that the caller is trying to free is
apparently empty.
(Windows XP and later only) The mapping address space that the caller is trying to free is
still reserved. MmUnmapReservedMapping
must be called before MmFreeMappingAddress.
(Windows XP and later only) The caller is attempting to map an MDL to a mapping
address space that it does not own.
(Windows XP and later only) The caller is attempting to map an MDL to an invalid
mapping address space. The caller has mostly likely specified an invalid address.
(Windows XP and later only) The caller is attempting to map an MDL to a mapping
address space that has not been properly reserved. The caller should have called
MmUnmapReservedMapping prior to calling
MmMapLockedPagesWithReservedMapping
(Windows XP and later only) The caller is attempting to unmap a locked mapping address
space that it does not own.
(Windows XP and later only) The caller is attempting to unmap a locked virtual address
space that is apparently empty.
(Windows XP and later only) The caller is attempting to unmap more mappings than
actually exist in the locked mapping address space.

(Windows XP and later only) The caller is attempting to unmap a portion of a locked
virtual address space that is not currently mapped.
(Windows XP and later only) The caller is not unmapping the entirety of the locked
mapping address space.
(Windows XP and later only) The caller is attempting to reserve a mapping address space
that contains no mappings.
The number of
(Windows XP and later only) One of the mappings that the caller is attempting to reserve
mappings to reserve has already been reserved.
The number of
mappings to unmap
The number of
mappings to unmap
0

(Windows XP and later only) The caller is attempting to release a mapping address space
that contains no mappings.
0
0
(Windows XP and later only) The caller is attempting to release a mapping that it is not
permitted to release.
The number of
0
(Windows XP and later only) The caller is attempting to release a mapping address range
mappings to release
that was not reserved.
The number of
0
(Windows XP and later only) The caller is attempting to release a mapping address range
mappings to release
that begins in the middle of a different allocation.
The number of
The number of
(Windows XP and later only) The caller is attempting to release the wrong number of
mappings that the caller mappings that should mappings.
is trying to release
be released
The free mapping
The number of
(Windows XP and later only) One of the mappings that the caller is attempting to release is
address
mappings to release already free.
The number of pages to 0
(Windows XP and later only) The caller is trying to free an I/O space mapping that the
be freed
system is unaware of.
0

Cause
The error is indicated by the value of Parameter 1.
A stack trace will identify the driver that caused the error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDB: DRIVER_CORRUPTED_SYSPTES

The DRIVER_CORRUPTED_SYSPTES bug check has a value of 0x000000DB. This indicates that an attempt was made to touch memory at an invalid IRQL, probably due
to corruption of system PTEs.
Parameters
The following parameters are displayed on the blue screen.
Parameter

Description

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

1
2
3

Page 886 of 1651

Memory referenced
IRQL
0: Read
1: Write

Address in code which referenced memory

Cause
A driver tried to access pageable (or completely invalid) memory at too high of an IRQL. This bug check is almost always caused by drivers that have corrupted system PTEs.
Resolving the Problem
If this bug check occurs, the culprit can be detected by editing the registry. In the
\\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management registry key, create or edit the TrackPtes value, and set
it equal to DWORD 3. Then reboot. The system will then save stack traces, and if the driver commits the same error, the system will issue bug check 0xDA
(SYSTEM_PTE_MISUSE). Then the stack trace will identify the driver that caused the error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDC: DRIVER_INVALID_STACK_ACCESS

The DRIVER_INVALID_STACK_ACCESS bug check has a value of 0x000000DC. This indicates that a driver accessed a stack address that lies below the stack pointer of
the stack's thread.
Parameters
None
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDE: POOL_CORRUPTION_IN_FILE_AREA

The POOL_CORRUPTION_IN_FILE_AREA bug check has a value of 0x000000DE. This indicates that a driver has corrupted pool memory that is used for holding pages
destined for disk.
Parameters
None
Cause
When the Memory Manager dereferenced the file, it discovered this corruption in pool memory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDF: IMPERSONATING_WORKER_THREAD

The IMPERSONATING_WORKER_THREAD bug check has a value of 0x000000DF. This indicates that a workitem did not disable impersonation before it completed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The worker routine that caused this error
2
The parameter passed to this worker routine
3
A pointer to the work item
4
Reserved

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

0x20
0x21

The performance counter has decreased. The old and new values of the counter are displayed.
The performance counter has increased too fast. The counter value is displayed in the debugger.
The driver freed too many DMA common buffers. Usually this means it freed the same buffer two times.
The driver freed too many DMA adapter channels. Usually this means it freed the same adapter channel two times.
The driver freed too many DMA map registers. Usually this means it freed the same map register two times. The number of active map registers is displayed.
The driver freed too many DMA scatter/gather lists. Usually this means it freed the same scatter/gather list two times. The number of lists allocated and the
number of lists freed is displayed.
The driver tried to release the adapter without first freeing all its common buffers. The adapter address and the number of remaining buffers is displayed.
The driver tried to release the adapter without first freeing all adapter channels, common buffers, or scatter/gather lists. The adapter address and the number of
remaining items is displayed.
The driver tried to release the adapter without first freeing all map registers. The adapter address and the number of remaining map registers is displayed.
The driver tried to release the adapter without first freeing all its scatter/gather lists. The adapter address and the number of remaining scatter/gather lists is
displayed.
HV_TOO_MANY_ADAPTER_CHANNELSThe driver has allocated too many adapter channels at the same time. . (Only one adapter channel is permitted per
adapter.)
The driver tried to allocate too many map registers at the same time. The number requested and the number allowed are displayed.
The driver did not flush its adapter buffers. The number of bytes that the driver tried to map and the maximum number of bytes allowed are displayed.
The driver tried a DMA transfer without locking the buffer. The buffer in question was in paged memory. The address of the MDL is displayed.
The driver or the hardware wrote outside its allocated DMA buffer. The nature of the error (overrun or underrun) is displayed, as well as the relevant addresses.
The driver tried to free its map registers while some were still mapped. The number of map registers still mapped is displayed.
The driver has too many outstanding reference counts for the adapter. The number of reference counts and the adapter address are displayed.
The driver called a DMA routine at an improper IRQL. The required IRQL and the actual IRQL are displayed.
The driver called a DMA routine at an improper IRQL. The required IRQL and the actual IRQL are displayed.
The driver tried to allocate too many map registers. The number requested and the number allowed are displayed.
The driver tried to flush a buffer that is not mapped. The address of the buffer is displayed.
The driver tried a DMA operation by using an adapter that was already released and no longer exists. The adapter address is displayed.
The driver passed a null DMA_ADAPTER value to a HAL routine.
The driver passed an address and MDL to a HAL routine. However, this address is not within the bounds of this MDL. The address passed and the address of
the MDL are displayed.
The driver tried to map an address range that was already mapped. The address range and the current mapping for that range are displayed.
The driver called HalGetAdapter. This function is obsolete you must use IoGetDmaAdapter instead.
HV_BAD_MDLThe driver referenced an invalid system address either before the first MDL, or after the end of the first MDL, or by using a transfer length
that is longer than the MDL buffer and crosses a page boundary within the MDL. . Either the invalid address and the first MDL address, or the MDL address
and the extra transfer length are displayed.
The driver tried to flush a map register that hasn't been mapped. The map register base, flushing address, and MDL are displayed.
The driver tried to map a zero-length buffer for transfer.

Cause
See the description of each code in the Parameters section for a description of the cause.
Resolving the Problem
This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it.
You might also consider removing the driver that caused this problem.
If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code.
The Driver Verifier DMA Verification option is only available in Windows XP and later versions. For full details on Driver Verifier, see the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xE7: INVALID_FLOATING_POINT_STATE

The INVALID_FLOATING_POINT_STATE bug check has a value of 0x000000E7. This indicates that a thread's saved floating-point state is invalid.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates which validity check failed. Parameter 4 is not used. The meaning of the other parameters
depends on the value of Parameter 1.
Parameter
1

Parameter 2

Parameter 3

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Cause of Error

9/18/2010

Introduction

Page 890 of 1651

0x0

The flags field

0x1

The saved IRQL

0x2

The saved address of the thread that owns this

floating-point context

The current
IRQL
The current
thread

The saved context flags field is invalid. Either FLOAT_SAVE_VALID is not set, or some
reserved bits are nonzero.
The current processor's IRQL is not the same as when the floating-point context was
saved.
The saved context does not belong to the current thread.

Cause
While restoring the previously-saved floating-point state for a thread, the state was found to be invalid.
Parameter 1 indicates which validity check failed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xE8: INVALID_CANCEL_OF_FILE_OPEN

The INVALID_CANCEL_OF_FILE_OPEN bug check has a value of 0x000000E8. This indicates that an invalid file object was passed to IoCancelFileOpen.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The file object passed to IoCancelFileOpen
2
The device object passed to IoCancelFileOpen
3
Reserved
4
Reserved
Cause
The file object passed to IoCancelFileOpen is invalid. It should have reference of one. The driver that called IoCancelFileOpen is at fault.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xE9: ACTIVE_EX_WORKER_THREAD_TERMINATION

The ACTIVE_EX_WORKER_THREAD_TERMINATION bug check has a value of 0x000000E9. This indicates that an active executive worker thread is being terminated.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The exiting ETHREAD
2
Reserved
3
Reserved
4
Reserved
Cause
An executive worker thread is being terminated without having gone through the worker thread rundown code. This is forbidden; work items queued to the ExWorkerQueue
must not terminate their threads.
A stack trace should indicate the cause.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xEA: THREAD_STUCK_IN_DEVICE_DRIVER

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 891 of 1651

The THREAD_STUCK_IN_DEVICE_DRIVER bug check has a value of 0x000000EA. This indicates that a thread in a device driver is endlessly spinning.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
A pointer to the stuck thread object
2
A pointer to the DEFERRED_WATCHDOG object
3
A pointer to the offending driver name
4
In the kernel debugger: The number of times the "intercepted" bug check 0xEA was hit
On the blue screen: 1

Cause
A device driver is spinning in an infinite loop, most likely waiting for hardware to become idle.
This usually indicates problem with the hardware itself, or with the device driver programming the hardware incorrectly. Frequently, this is the result of a bad video card or a
bad display driver.
Resolving the Problem
Use the .thread (Set Register Context) command together with Parameter 1. Then use kb (Display Stack Backtrace) to find the location where the thread is stuck.
If the kernel debugger is already connected and running when Windows detects a time-out condition. Then DbgBreakPoint will be called instead of KeBugCheckEx. A
detailed message will be printed to the debugger. See Sending Output to the Debuggefor more information.
This message will include what would have been the bug check parameters. Because no actual bug check was issued, the .bugcheck (Display Bug Check Data) command
will not be useful. The four parameters can also be retrieved from Watchdog's global variables by using dd watchdog!g_WdBugCheckData L5" on a 32-bit system, or
dq watchdog!g_WdBugCheckData L5" on a 64-bit system.
Debugging this error in an interactive manner such as this will enable you to find an offending thread, set breakpoints in it, and then use g (Go) to return to the spinning code
to debug it further.
On multiprocessor machines (OS build 3790 or earlier), you can hit a time out if the spinning thread is interrupted by a hardware interrupt and an ISR or DPC routine is
running at the time of the bug check. This is because the time out's work item can be delivered and handled on the second CPU and the same time. If this occurs, you must
look deeper at the offending thread's stack to determine the spinning code which caused the time out to occur. Use the dds (Display Words and Symbols) command to do
this.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xEB: DIRTY_MAPPED_PAGES_CONGESTION

The DIRTY_MAPPED_PAGES_CONGESTION bug check has a value of 0x000000EB. This indicates that no free pages are available to continue operations.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The total number of dirty pages
2
The number of dirty pages destined for the page file
3
Windows Server 2003 only: The size of the nonpaged pool available at the time of the bug check (in pages)
Windows Vista and later versions: Reserved
Windows Server 2003 only: The number of transition pages that are currently stranded

Windows Vista and later versions: The most recent modified write error status

Cause
The file system driver stack has deadlocked and most of the modified pages are destined for the file system. Because the file system is non-operational, the system has crashed
because none of the modified pages can be reused without losing data. Any file system or filter driver in the stack may be at fault.
To see general memory statistics, use the !vm 3 extension.
This bug check can occur for any of the following reasons:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 892 of 1651

If Parameter 1 or Parameter 2 is large, this is a possibility. Use !vm 3.

A storage driver is not processing requests. Examples of this are stranded queues and unresponsive drives. This indicates a driver bug.
If Parameter 1 or Parameter 2 is large, this is a possibility. Use !process 0 7.

Windows Server 2003 only: Not enough pool is available for the storage stack to write out modified pages. This indicates a driver bug.
If Parameter 3 is small, this is a possibility. Use !vm and !poolused 2.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xEC: SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT

The SESSION_HAS_VALID_SPECIAL_POOL_ON_EXIT bug check has a value of 0x000000EC. This indicates that a session unload occurred while a session driver still
held memory.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The session ID
2
The number of special pool pages that are leaking
3
Reserved
4
Reserved
Cause
This error is caused by a session driver not freeing its special pool allocations prior to a session unload. This indicates a bug in win32k.sys, atmfd.dll, rdpdd.dll, or a video
driver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xED: UNMOUNTABLE_BOOT_VOLUME

The UNMOUNTABLE_BOOT_VOLUME bug check has a value of 0x000000ED. This indicates that the I/O subsystem attempted to mount the boot volume and it failed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The device object of the boot volume
2
The status code from the file system that describes why it failed to mount the volume
3
Reserved
4
Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xEF: CRITICAL_PROCESS_DIED

The CRITICAL_PROCESS_DIED bug check has a value of 0x000000EF. This indicates that a critical system process died.
Parameters
The following parameters are displayed on the blue screen.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 893 of 1651

Parameter
Description
1
The process object
2
Reserved
3
Reserved
4
Reserved

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF1: SCSI_VERIFIER_DETECTED_VIOLATION

The SCSI_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000F1. This is the bug check code for all Driver Verifier SCSI Verification violations.
Parameters
The four bug check parameters are displayed on the blue screen. Parameter 1 identifies the type of violation.
Parameter
Parameter 2
1
0x1000
First argument passed

Second argument passed

Reserved

0x1001

Delay, in microseconds

Reserved

0x1002

Address of routine that took too

long

Address of miniport's
HW_DEVICE_EXTENSION

Duration of the
routine, in
microseconds

Parameter 3

Parameter 4

Cause of Error
The miniport driver passed bad arguments to
ScsiPortInitialize.
The miniport driver called ScsiPortStallExecution and
specified a delay greater than 0.1 second, stalling the
processor too long.
A miniport routine called by the port driver took longer than
0.5 second to execute.
(0.5 seconds is the limit for most routines. However, the
HwInitialize routine is allowed 5 seconds, and the
FindAdapter routine is exempt.)

0x1003
0x1004
0x1005
0x1006

Address of miniport's
HW_DEVICE_EXTENSION
Address of the SRB
Address of miniport's
HW_DEVICE_EXTENSION
Address of miniport's
HW_DEVICE_EXTENSION

Address of the SRB

Reserved

The miniport driver completed a request more than once.

Address of miniport's
HW_DEVICE_EXTENSION
Address of
LOGICAL_UNIT_EXTENSION
Invalid virtual address

Reserved

The miniport driver completed a request with an invalid SRB

status.
The miniport driver called ScsiPortNotification to ask for
NextLuRequest, but an untagged request is still active.
The miniport driver passed an invalid virtual address to
ScsiPortGetPhysicalAddress.

Reserved
Reserved

(This usually means the address supplied doesn't map to the

common buffer area.)
0x1007

Address of
ADAPTER_EXTENSION

Address of miniport's
HW_DEVICE_EXTENSION

Reserved

The reset hold period for the bus ended, but the miniport
driver still has outstanding requests.

Cause
See the description of each code in the Parameters section for an explanation of the cause.
Resolving the Problem
This bug check can only occur when Driver Verifier has been instructed to monitor one or more drivers. If you did not intend to use Driver Verifier, you should deactivate it.
You might consider removing the driver which caused this problem as well.
If you are the driver writer, use the information obtained through this bug check to fix the bugs in your code.
The Driver Verifier SCSI Verification option is only available in Windows XP and later. For full details on Driver Verifier, see the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF3: DISORDERLY_SHUTDOWN

The DISORDERLY_SHUTDOWN bug check has a value of 0x000000F3. This indicates that Windows was unable to shut down due to lack of memory.
Parameters
The following parameters are displayed on the blue screen.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 894 of 1651

Parameter
Description
1
The total number of dirty pages
2
The number of dirty pages destined for the page file
3
Windows Server 2003 only: The size of the nonpaged pool available at the time of the bug check (in pages)
Windows Vista and later: Reserved
4

Windows Server 2003 only: The current shut down stage

Windows Vista and later: The most recent modified write error status

Cause
Windows attempted to shut down, but there were no free pages available to continue operations.
Because applications were not terminated and drivers were not unloaded, they continued to access pages even after the modified writer had terminated. This causes the system
to run out of pages, since the page files could be used.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF4: CRITICAL_OBJECT_TERMINATION

The CRITICAL_OBJECT_TERMINATION bug check has a value of 0x000000F4. This indicates that a process or thread crucial to system operation has unexpectedly exited
or been terminated.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The terminating object type:
0x3: Process
0x6: Thread
2
3
4

The terminating object

The process image file name
Pointer to an ASCII string containing an explanatory message

Cause
Several processes and threads are necessary for the operation of the system. When they are terminated for any reason, the system can no longer function.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF5: FLTMGR_FILE_SYSTEM

The FLTMGR_FILE_SYSTEM bug check has a value of 0x000000F5. This indicates that an unrecoverable failure occurred in the Filter Manager.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the type of violation. The meaning of the other parameters depends on the value of
Parameter 1.
Parameter
Parameter 2
1
0x66
Pointer to the
callback data
structure for the
operation.
0x67
Pointer to the
callback data
structure for the
operation.

Parameter 3

Parameter 4

Cause of error

The minifilter returned FLT_PREOP_SUCCESS_WITH_CALLBACK or

FLT_PREOP_SYNCHRONIZE from a preoperation callback, but did not
register a corresponding postoperation callback.

Error NTSTATUS code for the

operation

An internal object ran out of space, and the system is unable to allocate new
space.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x68
0x6A
0x6B
0x6C
0x6D

0x6E

Handle for the

object.
File object pointer
for the file.
Frame ID
Frame ID
Address of the
minifilter's context
structure

Page 895 of 1651

NTSTATUS code returned by

ObReferenceObjectByHandle
0

0
0
BackPocket List
Address of the
CONTEXT_NODE
structure

Address of the
Address of the
minifilter's context CONTEXT_NODE
structure
structure

Unexpected failure referencing an object.

Thread
Thread
0

The file-open or file-create request could not be canceled, because one or

more handles have been created for the file.
Invalid BACKPOCKET IRPCTRL state.
Too many nested PageFaults for BACKPOCKETED IRPCTR.
The context structure was dereferenced too many times. This means that the
reference count on the Filter Manager's CONTEXT_NODE structure went to
zero while it was still attached to its associated object.

The context structure was referenced after being freed.

Cause
The cause of the problem is indicated by the value of Parameter 1. See the table in the Parameters section.
Resolving the Problem
If Parameter 1 equals 0x66, you can debug this problem by verifying that your minifilter driver has registered a post-operation callback for this operation. The current
operation can be found in the callback data structure. (See Parameter 2.) Use the !fltkd.cbd debugger extension.
If Parameter 1 equals 0x67, you should verify that you do not have a nonpaged pool leak somewhere in the system.
If Parameter 1 equals 0x6A, make sure that your minifilter driver does not reference this file object (see Parameter 2) to get a handle at any point during your minifilter's
processing of this operation.
If Parameter 1 equals 0x6B or 0x6C, then a non-recoverable internal state error has occurred which will cause the operating system to bug check.
If Parameter 1 equals 0x6D, make sure that your minifilter driver does not call FltReleaseContext too many times for the given context (see Parameter 2).
If Parameter 1 equals 0x6E, make sure that your minifilter driver does not call FltReferenceContext after the given context has been deleted (see Parameter 2).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF6: PCI_VERIFIER_DETECTED_VIOLATION

The PCI_VERIFIER_DETECTED_VIOLATION bug check has a value of 0x000000F6. This indicates that an error occurred in the BIOS or another device being verified by
the PCI driver.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 is the only parameter of interest; this identifies the nature of the failure detected.
Parameter 1
Cause of Error
0x01
An active bridge was reprogrammed by the BIOS during a docking event.
0x02
The PMCSR register was not updated within the spec-mandated time.
0x03
A driver has written to Windows-controlled portions of a PCI device's configuration space.
Cause
The PCI driver detected an error in a device or BIOS being verified.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF7: DRIVER_OVERRAN_STACK_BUFFER

The DRIVER_OVERRAN_STACK_BUFFER bug check has a value of 0x000000F7. This indicates that a driver has overrun a stack-based buffer.
Parameters
The following parameters are displayed on the blue screen.
Parameter

Description

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

1
2
3
4

Page 896 of 1651

The actual security check cookie from the stack

The expected security check cookie
The bit-complement of the expected security check cookie
0

Cause
A driver overran a stack-based buffer (or local variable) in a way that would have overwritten the function's return address and jumped back to an arbitrary address when the
function returned.
This is the classic "buffer overrun" hacking attack. The system has been brought down to prevent a malicious user from gaining complete control of it.
Resolving the Problem
Use the kb (Display Stack Backtrace) command to get a stack trace.
The last routine on the stack before the buffer overrun handlers and bug check call is the one that overran its local variable.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF8: RAMDISK_BOOT_INITIALIZATION_FAILED

The RAMDISK_BOOT_INITIALIZATION_FAILED bug check has a value of 0x000000F8. This indicates that an initialization failure occurred while attempting to boot
from the RAM disk.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Indicates the cause of the failure.
1: No LoaderXIPRom descriptor was found in the loader memory list.
2: Unable to open the RAM disk driver (ramdisk.sys or \Device\Ramdisk).
3: FSCTL_CREATE_RAM_DISK failed.
4: Unable to create GUID string from binary GUID.
5: Unable to create symbolic link pointing to the RAM disk device.
2
3
4

NTSTATUS code
0
0

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xF9:

DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN
The DRIVER_RETURNED_STATUS_REPARSE_FOR_VOLUME_OPEN bug check has a value of 0x000000F9. This indicates that a driver returned STATUS_REPARSE
to an IRP_MJ_CREATE request with no trailing names.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The device object that was opened
2
The device object to which the IRP_MJ_CREATE request was issued
3
Address of the Unicode string containing the new name of the file (to be reparsed)
4
Information returned by the driver for the IRP_MJ_CREATE request
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 897 of 1651

STATUS_REPARSE should be returned only for IRP_MJ_CREATE requests with trailing names, as that indicates the driver is supporting name spaces.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xFA: HTTP_DRIVER_CORRUPTED

The HTTP_DRIVER_CORRUPTED bug check has a value of 0x000000FA. This indicates that the HTTP kernel driver (Http.sys) has reached a corrupted state and cannot
recover.
Parameters
The four bug check parameters are displayed on the blue screen. Parameter 1 identifies the exact state of the HTTP kernel driver.
Parameter Parameter 2
Parameter 3
1
0x1
Address of work Name of the file that contains the
item
work item check

Parameter 4

Cause of Error

Line number of the work item check A work item is invalid. This will eventually result in thread pool
within the file
corruption and an access violation.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xFC: ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY

The ATTEMPTED_EXECUTE_OF_NOEXECUTE_MEMORY bug check has a value of 0x000000FC. This indicates that an attempt was made to execute non-executable
memory.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The virtual address whose execution was attempted
2
The contents of the page table entry (PTE)
3
Reserved
4
Reserved
Resolving the Problem
When possible, the Unicode string of the driver name that attempted to execute non-executable memory is printed on the bug check screen and is also saved in
KiBugCheckDriver. Otherwise, the driver in question can often be found by running a stack trace and then reviewing the current instruction pointer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xFD: DIRTY_NOWRITE_PAGES_CONGESTION

The DIRTY_NOWRITE_PAGES_CONGESTION bug check has a value of 0x000000FD. This indicates that there are no free pages available to continue basic system
operations.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Total number of dirty pages
2
Number of non-writeable dirty pages
3
Reserved
4
Most recently modified write-error status
Cause

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 898 of 1651

This bug check usually occurs because the component that owns the modified non-writeable pages failed to write out these pages after marking the relevant files as "do not
write" to memory management. This indicates a driver bug.
Resolving the Problem
For more information about which driver is causing the problem, use the !vm 3 extension, followed by !memusage 1 .
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xFE: BUGCODE_USB_DRIVER

The BUGCODE_USB_DRIVER bug check has a value of 0x000000FE. This indicates that an error has occurred in a Universal Serial Bus (USB) driver.
Parameters
The four bug check parameters are displayed on the blue screen. Parameter 1 identifies the type of violation.
Parameter
Parameter 2
Parameter 3
1
0x1
Reserved
Reserved
0x2
Address of the pending IRP Address of the IRP that
was passed in
0x3
Reserved
Reserved

Reserved
Address of the USB request block
(URB) that caused the error
Reserved

0x4

Address of the IRP

Reserved

0x5

Device extension pointer of PCI vendor, product id

the host controller
for the controller
Object address
Signature that was
expected
Pointer to usbport.sys debug Message string
log
Reserved Type
Reserved

Ox6
0x7
0x8

Address of the URB

Parameter 4

Cause of Error

Reserved

An internal error has occurred in the USB stack.

The USB client driver has submitted a URB that is still attached to
another IRP that is pending in the bus driver.
The USB miniport driver has generated a bug check. This usually
happens in response to a catastrophic hardware failure.
The caller has submitted an IRP that is already pending in the USB
bus driver.
A hardware failure has occurred due to a bad physical address found
in a hardware data structure. This is not due to a driver bug.
An Internal data structure (object) has been corrupted.

File name

Please consult the provided message string for details.

Reserved

Pointer to endpoint data structure

Cause
See the description of each code in the Parameters section for an explanation of the cause.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xFF: RESERVE_QUEUE_OVERFLOW

The RESERVE_QUEUE_OVERFLOW bug check has a value of 0x000000FF. This indicates that an attempt was made to insert a new item into a reserve queue, causing the
queue to overflow.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the reserve queue
2
The size of the reserve queue
3
0
4
0

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x100: LOADER_BLOCK_MISMATCH

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 899 of 1651

The LOADER_BLOCK_MISMATCH bug check has a value of 0x00000100. This indicates that either the loader block is invalid, or it does not match the system that is
being loaded.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
3
2
The size of the loader black extension
3
The major version of the loader block
4
The minor version of the loader block

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x101: CLOCK_WATCHDOG_TIMEOUT

The CLOCK_WATCHDOG_TIMEOUT bug check has a value of 0x00000101. This indicates that an expected clock interrupt on a secondary processor, in a multi-processor
system, was not received within the allocated interval.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Clock interrupt time-out interval, in nominal clock ticks
2
0
3
The address of the processor control block (PRCB) for the unresponsive processor
4
0
Cause
The specified processor is not processing interrupts. Typically, this occurs when the processor is nonresponsive or is deadlocked.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x103: MUP_FILE_SYSTEM

[This is preliminary documentation and subject to change.]
The MUP_FILE_SYSTEM bug check has a value of 0x00000103. This bug check indicates that the multiple UNC provider (MUP) has encountered invalid or unexpected
data. As a result, the MUP cannot channel a remote file system request to a network redirector, the Universal Naming Convention (UNC) provider.
Parameters
These bug check parameters are displayed on the blue screen. Parameter 1 identifies the type of violation.
Parameter Parameter 2
Parameter 3
Parameter 4
1
0x1
The address of The address of the
The address of the
the pending
file object whose file device object.
IRP.
context could not be
found.

Cause of error
The MUP could not locate the file context that corresponds to a file object. This typically
indicates that the MUP is seeing an I/O request for a file object for which MUP did not see a
corresponding IRP_MJ_CREATE request. The likely cause of this bug check is a filter driver
error.

0x2

The address of The address that was Reserved

the expected file actually retrieved
context.
from the file object.

A file context is known to exist for the file object, but was not what was expected (for example,
it might be NULL).

0x3

The address of The IRP completion The driver object of the The IRP completion status was unexpected or invalid.
the IRP context. status code.
UNC provider that
This bug check occurs only when you are using a Checked Build of Windows and should only
completed the IRP
be caused by file system filter drivers that are attached to legacy network redirectors. Legacy

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 900 of 1651

(might be NULL).

0x4

Address of the
IRP

Address of the file

object

redirectors use FsRtlRegisterUncProvider to register with MUP. This bug check detects filter
drivers that return an NTSTATUS that is not STATUS_SUCCESS in IRP_MJ_CLEANUP or
IRP_MJ_CLOSE requests.

The file context for the An I/O operation was started on a file object before the create request for the file object was
file object
completed.

Comments
The MUP maintains context information on a per-file object basis for all file objects it handles.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x104: AGP_INVALID_ACCESS

The AGP_INVALID_ACCESS bug check has a value of 0x00000104. This indicates that the GPU wrote to a range of Accelerated Graphics Port (AGP) memory that had not
previously been committed.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
Offset (in ULONG) within the AGP verifier page to the first ULONG data that is corrupted
1
2
0
3
0
4
0
Cause
Typically, this bug check is caused by an unsigned or improperly tested video driver. It can also be caused by an old BIOS.
Resolving the Problem
Check for display driver and computer BIOS updates.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x105: AGP_GART_CORRUPTION

The AGP_GART_CORRUPTION bug check has a value of 0x00000105. This indicates that the Graphics Aperture Remapping Table (GART) is corrupt.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The base address (virtual) of the GART
2
The offset into the GART where the corruption occurred
3
The base address (virtual) of the GART cache (a copy of the GART)
4
0
Cause
This bug check is typically caused by improper direct memory access (DMA) by a driver.
Resolving the Problem

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 901 of 1651

Enable Driver Verifier for any unsigned drivers. Remove them or disable them one by one until the erring driver is identified.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x106: AGP_ILLEGALLY_REPROGRAMMED

The AGP_ILLEGALLY_REPROGRAMMED bug check has a value of 0x00000106. This indicates that the Accelerated Graphics Port (AGP) hardware has been
reprogrammed by an unauthorized agent.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The originally programmed AGP command register value
2
The current command register value
3
0
4
0
Cause
This bug check is typically caused by an unsigned, or improperly tested, video driver.
Resolving the Problem
Check the video manufacturer's Web site for updated display drivers or use VGA mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x108: THIRD_PARTY_FILE_SYSTEM_FAILURE

The THIRD_PARTY_FILE_SYSTEM_FAILURE bug check has a value of 0x00000108. This indicates that an unrecoverable problem has occurred in a third-party file
system or file system filter.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Identifies the file system that failed. Possible values include:
1: Polyserve (Psfs.sys)
2
3
4

The address of the exception record.

The address of the context record.
Reserved.

Cause
One possible cause of this bug check is disk corruption. Corruption in the third-party file system or bad blocks (sectors) on the hard disk can induce this error. Corrupted SCSI
and IDE drivers can also adversely affect the Windows operating systems ability to read and write to disk, thus causing the error.
Another possible cause is depletion of nonpaged pool memory. If the nonpaged pool is completely depleted, this error can stop the system.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command with Parameter 3, and then use kb (Display Stack Backtrace).
To resolve a disk corruption problem: Check Event Viewer for error messages from SCSI, IDE, or other disk controllers in the system that might help pinpoint the device or
driver that is causing the error. Try disabling any virus scanners, backup programs, or disk defragmenter tools that continually monitor the system. You should also run
hardware diagnostics supplied by the file system or the file system filter manufacturer.
To resolve a nonpaged pool memory depletion problem: Add new physical memory to the computer. This will increase the quantity of nonpaged pool memory available to the
kernel.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 902 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x109: CRITICAL_STRUCTURE_CORRUPTION

The CRITICAL_STRUCTURE_CORRUPTION bug check has a value of 0x00000109. This indicates that the kernel has detected critical kernel code or data corruption.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Reserved
2
Reserved
3
Reserved
4
The type of the corrupted region. (See the following table later on this page.)
The value of Parameter 4 indicates the type of corrupted region.
Parameter 4 Type of Corrupted Region, Type of Corruption, or Type of Action Taken That Caused the Corruption
0x0
A generic data region
0x1
A function modification or the Itanium-based function location
0x2
A processor interrupt dispatch table (IDT)
0x3
A processor global descriptor table (GDT)
0x4
A type-1 process list corruption
0x5
A type-2 process list corruption
0x6
A debug routine modification
0x7
A critical MSR modification
Cause
There are generally three different causes for this bug check:
1. A driver has inadvertently, or deliberately, modified critical kernel code or data. Microsoft Windows Server 2003 with Service Pack 1 (SP1) and later versions of
Windows for x64-based computers do not allow the kernel to be patched except through authorized Microsoft-originated hot patches. For more information, see
Patching Policy for x64-based Systems.
2. A developer attempted to set a normal kernel breakpoint using a kernel debugger that was not attached when the system was started. Normal breakpoints (bp) can only
be set if the debugger is attached at start time. Processor breakpoints (ba) can be set at any time.
3. A hardware corruption occurred. For example, the kernel code or data could have been stored in memory that failed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10A: APP_TAGGING_INITIALIZATION_FAILED

The APP_TAGGING_INITIALIZATION_FAILED bug check has a value of 0x0000010A.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10C: FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION

The FSRTL_EXTRA_CREATE_PARAMETER_VIOLATION bug check has a value of 0x0000010C. This indicates that a violation was detected in the File system Runtime library (FsRtl) Extra Create Parameter (ECP) package.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The type of violation. (See the following table later on this page for more details).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

2
3
4

Page 903 of 1651

0
The address of the ECP.
The starting address of the ECP list.

The value of Parameter 1 indicates the type of violation.

Parameter 1
Type of Violation
0x1
The ECP signature is invalid, due to either a bad pointer or memory corruption.
0x2
The ECP has undefined flags set.
0x3
The ECP was not allocated by the FsRtl.
0x4
The ECP has flags set that are illegal for a parameter passed by a create caller.
0x5
The ECP is corrupted; its size is smaller than the header size.
0x6
The ECP that is being freed has non-empty list pointers; it might still be part of an ECP list.
0x11
The ECP list signature is invalid, due to either a bad pointer or memory corruption.
0x12
The ECP list has undefined flags set.
0x13
The ECP list was not allocated by the FsRtl.
0x14
The ECP list has flags set that are illegal for a parameter list passed by a create caller.
0x15
The ECP list passed by the create caller is empty.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10D: WDF_VIOLATION

The WDF_VIOLATION bug check has a value of 0x0000010D. This indicates that Kernel-Mode Driver Framework (KMDF) detected that Windows found an error in a
framework-based driver.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 indicates the specific error code of the bug check. Parameter 4 is reserved.
Parameter 2
Parameter
1
0x1
Pointer to a
WDF_POINTER_ROUTINE_TIMED_OUT_DATA
structure
0x2
0x3

0x4
0x5
0x6
0x7
0x8
0x9
0xA

Parameter 3
Reserved

Reserved
WDFREQUEST handle

Cause of Error
A framework-based driver has timed out during a power operation. This typically
means that the device stack did not set the DO_POWER_PAGABLE bit and a
driver attempted a pageable operation after the paging device stack was powered
down.
An attempt is being made to acquire a lock that is currently being held.
Windows Driver Framework Verifier has encountered a fatal error. In particular,
an I/O request was completed, but a framework request object cannot be deleted
because there are outstanding references to the input buffer, the output buffer, or
both.

Reserved
The number of
outstanding
references that
remain on both
buffers
Reserved
The caller's address A NULL parameter was passed to a function that required a non-NULL value.
The handle value passed in
Reserved
A framework object handle of the incorrect type was passed to a framework
object method.
See table below.
The handle of the framework object
Reserved
A driver attempted to delete a framework object incorrectly by calling
WdfObjectDereference to delete a handle instead of calling WdfObjectDelete.
The handle of the DMA transaction object
Reserved
An operation occurred on a DMA transaction object while it was not in the
correct state.
Currently unused.
A pointer to a WDF_QUEUE_FATAL_ERROR_DATA Reserved
A fatal error has occurred while processing a request that is currently in the
structure
queue.

0xB
0xC

WDFDEVICE handle

0xD

WDFDEVICE handle

0xE

IRQL at which the event callback function was called.

IRQL at which the

event callback
function returned.

0xF

Address of an event callback function.

Reserved

Pointer to new PnP

IRP
Pointer to power
IRP

See table below.

A new state-changing PnP IRP arrived while the driver was processing another
state-changing PnP IRP.
A device's power policy owner received a power IRP that it did not request. There
might be multiple power policy owners, but only one is allowed. A KMDF driver
can change power policy ownership by calling
WdfDeviceInitSetPowerPolicyOwnership.
An event callback function did not return at the same IRQL at which it was
called. The callback function changed the IRQL directly or indirectly (for
example, by acquiring a spinlock, which raises IRQL to DISPATCH_LEVEL, but
not releasing the spinlock).
An event callback function entered a critical region, but it did not leave the
critical region before returning.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 904 of 1651

If Parameter 1 is equal to 0x6, then a fatal error was made in handling a WDF request. In this case, Parameter 2 further specifies the type of fatal error that has been made, as
defined by the enumeration WDF_REQUEST_FATAL_ERROR.
Parameter
2
0x1
The address of the IRP

Parameter 3

0x2

The WDF request handle value

0x3

The WDF request handle value

0x4

A pointer to a WDR_REQUEST_FATAL_ERROR_INFORMATION_LENGTH_MISMATCH_DATA structure that

contains a pointer to the IRP, a WDF request handle value, an IRP major function, and the number of bytes attempted to be
written

Cause of Error
No more I/O stack locations are
available to format the underlying
IRP.
An attempt was made to format a
framework request object that did
not contain an IRP.
The driver attempted to send a
framework request that has already
been sent to an I/O target.
The driver has completed a
framework request, but has written
more bytes to the output buffer
than are specified in the IRP.

If Parameter 1 is equal to 0xB, then an attempt to acquire or release a lock was invalid. In this case, Parameter 3 further specifies the error that has been made.
Parameter 2
The handle value
A WDF spin lock
handle

Parameter
Cause of Error
3
0x0
A handle passed to WdfObjectAcquireLock or WdfObjectReleaseLock represents an object that does not support synchronization
locks.
0x1
The spin lock is being released by a thread that did not acquire it.

Cause
See the description of each code in the Parameters section for an explanation of the cause.
Resolving the Problem
Typically, the dump file will yield further information on the driver that caused this bug check.
If Parameter 1 is equal to 0x2, examine the callers stack to determine the lock in question.
If Parameter 1 is equal to 0x3, the driver's Kernel-Mode Driver Framework error log will include details about the outstanding references.
If Parameter 1 is equal to 0x4, use the ln debugger command with the value of Parameter 3 as its argument to determine which function requires a non-NULL parameter.
If Parameter 1 is equal to 0x7, use the !wdfkd.wdfhandle Parameter 2 extension command to determine the handle type.
If Parameter 1 is equal to 0xA, then the WDF_QUEUE_FATAL_ERROR_DATA structure will indicate either the problematic request or the queue handle. It will also
indicate the NTSTATUS, if not STATUS_SUCCESS, when available.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10E: VIDEO_MEMORY_MANAGEMENT_INTERNAL

The VIDEO_MEMORY_MANAGEMENT_INTERNAL bug check has a value of 0x0000010E. This indicates that the video memory manager has encountered a condition
that it is unable to recover from.
Parameters
The following parameters are displayed on the blue screen. Parameter 1 is the only parameter of interest; this identifies the exact violation. Values for Parameter 1 that do not
appear in this table must be individually examined.
Parameter 1
Cause of Error
0x1
An attempt was made to rotate a non-rotate range.
0x2
An attempt was made to destroy a non-empty process heap.
0x3
An attempt to unmap from an aperture segment failed.
0x4
A rotation in a must-succeed path failed.
0x5
A deferred command failed.
An attempt was made to reallocate resources for an allocation that was having its eviction canceled.
0x6
0x7
An invalid attempt was made to defer free usage.
0x8
The split direct memory access (DMA) buffer contains an invalid reference.
0x9
An attempt to evict an allocation failed.
0xA
An invalid attempt to use a pinned allocation was made.
0xB
A driver returned an invalid error code from BuildPagingBuffer.
0xC
A resource leak was detected in a segment.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0xD
0xE
0xF
0x10
0x11
0x12
0x13
0x14
0x15
0x16
0x17
0x18
0x19
0x1A
0x1B

Page 905 of 1651

A segment is being used improperly.

An attempt to map an allocation into an aperture segment failed.
A driver returned an invalid error code from AcquireSwizzlingRange.
A driver returned an invalid error code from ReleaseSwizzlingRange.
An invalid attempt to use an aperture segment was made.
A driver overflowed the provided DMA buffer.
A driver overflowed the provided private data buffer.
An attempt to purge all segments failed.
An attempt was made to free a virtual address descriptor (VAD) that was still in the rotated state
A driver broke the guaranteed DMA buffer model contract.
An unexpected system command failure occurred.
An attempt to release a pinned allocation's resource failed.
A driver failed to patch a DMA buffer.
The owner of a shared allocation was freed.
An attempt was made to release an aperture range that is still in use.

Cause
This bug check is usually caused by a video driver behaving improperly.
Resolving the Problem
If the problem persists, check Windows Update for an updated video driver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x10F: RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED

The RESOURCE_MANAGER_EXCEPTION_NOT_HANDLED bug check has a value of 0x0000010F. This indicates that the kernel transaction manager detected that a
kernel-mode resource manager has raised an exception in response to a direct call-back. The resource manager is in an unexpected and unrecoverable state.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the exception record
2
The address of the context record
3
The address of the exception code
4
The address of the resource manager

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x111: RECURSIVE_NMI

[This is preliminary documentation and subject to change.]
The RECURSIVE_NMI bug check has a value of 0x00000111. This bug check indicates that a non-maskable-interrupt (NMI) occurred while a previous NMI was in
progress.
Comments
This bug check occurs when there is an error in the system management interrupt (SMI) code, and an SMI interrupts an NMI and enables interrupts. Execution then continues
with NMIs enabled, and another NMI interrupts the NMI in progress.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x112: MSRPC_STATE_VIOLATION

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 906 of 1651

The MSRPC_STATE_VIOLATION bug check has a value of 0x00000112. This indicates that the Msrpc.sys driver has initiated a bug check.
Parameters
The following parameters are displayed on the blue screen. Parameters 1 and 2 are the only parameters of interest. Parameter 1 indicates the state violation type; the value for
Parameter 2 is determined by the value of Parameter 1.
Parameter
Parameter 2
1
0x01
The exception code
0x02
The error
0x03
The session to the server
0x04
and
0x05
0x06
0x07
0x08
0x09
0x0A
0x0B
0x0C
and
0x0E
0x0F
0x15
0x16
0x17
0x18

Cause of Error

The session to the server

A non-continuable exception was continued by the caller.

The advanced local procedure call (ALPC) returned an invalid error.
The caller unloaded the Microsoft remote procedure call (MSRPC) driver while it was still in use. It is likely that open binding
handles remain.
An invalid close command was received from the ALPC.

The binding handle

The binding handle
The binding handle
The binding handle
The call object
The call object
The pipe object

An attempt was made to bind a remote procedure call (RPC) handle a second time.
An attempt was made to perform an operation on a binding handle that was not bound.
An attempt was made to set security information on a binding handle that was already bound.
An attempt was made to set an option on a binding handle that was already bound.
An attempt was made to cancel an invalid asynchronous remote procedure call.
An attempt was made to push on an asynchronous pipe call when it was not expected.
An attempt was made to push on an asynchronous pipe without waiting for notification.

The pipe object

The object closest to the
error
Reserved
The call object
The async handle

An attempt was made to synchronously terminate a pipe a second time.

An RPC internal error occurred.
Two causally ordered calls were issued in an order that cannot be enforced by the RPC.
A server manager routine did not unsubscribe from notifications prior to completing the call.
An invalid operation on the asynchronous handle occurred.

Cause
The most common cause of this bug check is that the caller of the Msrpc.sys driver violated the state semantics for such a call.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x113: VIDEO_DXGKRNL_FATAL_ERROR

The VIDEO_DXGKRNL_FATAL_ERROR bug check has a value of 0x00000113. This indicates that the dxg kernel has detected a violation.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x114: VIDEO_SHADOW_DRIVER_FATAL_ERROR

The VIDEO_SHADOW_DRIVER_FATAL_ERROR bug check has a value of 0x00000114. This indicates that the shadow driver has detected a violation.
This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x115: AGP_INTERNAL

The AGP_INTERNAL bug check has a value of 0x00000115. This indicates that the accelerated graphics port (AGP) driver has detected a violation.
This bug check appears very infrequently.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 907 of 1651

9/18/2010

Introduction

Page 908 of 1651

The EM_INITIALIZATION_FAILURE bug check has a value of 0x0000011A.

This bug check appears very infrequently.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x11B: DRIVER_RETURNED_HOLDING_CANCEL_LOCK

[This is preliminary documentation and subject to change.]
The DRIVER_RETURNED_HOLDING_CANCEL_LOCK bug check has a value of 0x0000011B. This bug check indicates that a driver has returned from a cancel routine
that holds the global cancel lock. This causes all later cancellation calls to fail, and results in either a deadlock or another bug check.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
The address of the IRP that was canceled (might not be valid).
2
The address of the cancel routine.
Comments
The cancel spin lock should have been released by the cancel routine.
The driver calls the IoCancelIrpIoCancelIrp function to cancel an individual I/O request packet (IRP). This function acquires the cancel spin lock, sets the cancel flag in the
IRP, and then calls the cancel routine specified by the appropriate field in the IRP, if a routine was specified. The cancel routine is expected to release the cancel spin lock. If
there is no cancel routine, the cancel spin lock is released.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x11C: ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE

[This is preliminary documentation and subject to change.]
The ATTEMPTED_WRITE_TO_CM_PROTECTED_STORAGE bug check has a value of 0x0000011C. This bug check indicates that an attempt was made to write to the
read-only protected storage of the configuration manager.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Virtual address for the attempted write
2
PTE contents
3
Reserved
4
Reserved
Comments
When it is possible, the name of the driver that is attempting the write operation is printed as a Unicode string on the bug check screen and then saved in KiBugCheckDriver.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x11D: EVENT_TRACING_FATAL_ERROR

[This is preliminary documentation and subject to change.]
The EVENT_TRACING_FATAL_ERROR bug check has a value of 0x0000011D. This bug check indicates that the Event Tracing subsystem has encountered an unexpected
fatal error.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 909 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x121: DRIVER_VIOLATION

[This is preliminary documentation and subject to change.]
The DRIVER_VIOLATION bug check has a value of 0x00000121. This bug check indicates that a driver has caused a violation.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Describes the type of violation
2
Reserved
3
Reserved
Comments
Use a kernel debugger and view the call stack to determine the name of the driver that caused the violation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x122: WHEA_INTERNAL_ERROR

[This is preliminary documentation and subject to change.]
The WHEA_INTERNAL_ERROR bug check has a value of 0x00000122. This bug check indicates that an internal error in the Windows Hardware Error Architecture
(WHEA) has occurred.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x124: WHEA_UNCORRECTABLE_ERROR

[This is preliminary documentation and subject to change.]
The WHEA_UNCORRECTABLE_ERROR bug check has a value of 0x00000124. This bug check indicates that a fatal hardware error has occurred. This bug check uses the
error data that is provided by the Windows Hardware Error Architecture (WHEA).
Parameters
Parameter
Parameter 2
1
0x0
Address of
WHEA_ERROR_RECORD
structure.

0x1

0x2

0x3

0x4

Address of
WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure.
Address of

Parameter 3

Parameter 4

Cause of error

High 32 bits of MCi_STATUS Low 32 bits of MCi_STATUS A machine check exception occurred.
MSR for the MCA bank that MSR for the MCA bank that
had the error.
had the error.
These parameter descriptions apply if the processor is based on
the x64 architecture, or the x86 architecture that has the MCA
feature available (for example, Intel Pentium Pro, Pentium IV,
or Xeon).
Reserved.

Reserved.

A corrected machine check exception occurred.

Reserved.

A corrected platform error occurred.

Reserved.

A nonmaskable Interrupt (NMI) error occurred.

Reserved

Reserved.

An uncorrectable PCI Express error occurred.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0x5

0x6

0x7

0x8

0x9

0xA

0xB

Page 910 of 1651

WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure
Address of
WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure
Address of
WHEA_ERROR_RECORD
structure.
Address of
WHEA_ERROR_RECORD
structure
Address of
WHEA_ERROR_RECORD
structure.

Reserved.

A generic hardware error occurred.

Reserved.

An IA64 INIT error occurred.

Reserved.

A BOOT error occurred.

Reserved.

A Scalable Coherent Interface (SCI) generic error occurred.

Length, in bytes, of the SAL

log.

Address of the SAL log.

An uncorrectable IA-64 machine check abort error occurred.

Reserved.

A corrected IA-64 machine check error occurred.

Reserved.

A corrected IA-64 platform error occurred.

Comments
Parameter 1 identifies the type of error source that reported the error. Parameter 2 holds the address of the WHEA_ERROR_RECORD structure that describes the error
condition.
For information about WHEA, see Windows Hardware Error Architecture Design Guide within the WDK documentation .
Note This bug check is not supported in Windows versions prior to Windows Vista. Instead, machine check exceptions are reported through bug check 0x9C.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x127: PAGE_NOT_ZERO

[This is preliminary documentation and subject to change.]
The PAGE_NOT_ZERO bug check has a value of 0x00000127. This bug check indicates that a page that should have been filled with zeros was not. This bug check might
occur because of a hardware error or because a privileged component of the operating system modified a page after freeing it.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Virtual address that maps the corrupted page
2
Physical page number
3
Zero (Reserved)
4
Zero (Reserved)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x12B: FAULTY_HARDWARE_CORRUPTED_PAGE

[This is preliminary documentation and subject to change.]
The FAULTY_HARDWARE_CORRUPTED_PAGE bug check has a value of 0x00000128. This bug check indicates that a single-bit error was found in this page. This is a
hardware memory error.
Parameters
The following parameters are displayed on the blue screen.
Parameter

Description

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

1
2
3
4

Page 911 of 1651

Virtual address maps to the corrupted page

Physical page number
Zero (Reserved)
Zero (Reserved)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x12C: EXFAT_FILE_SYSTEM

[This is preliminary documentation and subject to change.]
The EXFAT_FILE_SYSTEM bug check has a value of 0x0000012C. This bug check indicates that a problem occurred in the Extended File Allocation Table (exFAT) file
system.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
1
Specifies source file and line number information. The high 16 bits (the first four hexadecimal digits after the "0x") determine the source file by its identifier
number. The low 16 bits determine the source line in the file where the bug check occurred.
2
If FppExceptionFilter is on the stack, this parameter specifies the address of the exception record.
3
If FppExceptionFilter is on the stack, this parameter specifies the address of the context record.
4
Reserved.
Cause
This bug check is caused by the file system as a last resort when its internal accounting is in an unsupportable state and to continue poses a large risk of data loss. The file
system never causes this bug check when the on disk structures are corrupted, the disk sectors go bad, or a memory allocation fails. Bad sectors could lead to a bug check, for
example, when a page fault occurs in kernel code or data and the memory manager cannot read the pages. However, for this bug check, the file system is not the cause.
Resolving the Problem
To debug this problem: Use the .cxr (Display Context Record) command together with Parameter 3, and then use kb (Display Stack Backtrace).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1000007E:

SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M
The SYSTEM_THREAD_EXCEPTION_NOT_HANDLED_M bug check has a value of 0x1000007E. This indicates that a system thread generated an exception which the
error handler did not catch.
Bug check 0x1000007E has the same meaning and parameters as bug check 0x7E (SYSTEM_THREAD_EXCEPTION_NOT_HANDLED).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x1000007F: UNEXPECTED_KERNEL_MODE_TRAP_M

The UNEXPECTED_KERNEL_MODE_TRAP_M bug check has a value of 0x1000007F. This indicates that a trap was generated by the Intel CPU and the kernel failed to
catch this trap.
Bug check 0x1000007F has the same meaning and parameters as bug check 0x7F (UNEXPECTED_KERNEL_MODE_TRAP).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 912 of 1651

Debugging Tools for Windows

Bug Check 0x1000008E: KERNEL_MODE_EXCEPTION_NOT_HANDLED_M

The KERNEL_MODE_EXCEPTION_NOT_HANDLED_M bug check has a value of 0x1000008E. This indicates that a kernel-mode program generated an exception which
the error handler did not catch.
Bug check 0x1000008E has the same meaning and parameters as bug check 0x8E (KERNEL_MODE_EXCEPTION_NOT_HANDLED).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0x100000EA: THREAD_STUCK_IN_DEVICE_DRIVER_M

The THREAD_STUCK_IN_DEVICE_DRIVER_M bug check has a value of 0x100000EA. This indicates that a thread in a device driver is endlessly spinning.
Bug check 0x100000EA has the same meaning and parameters as bug check 0xEA (THREAD_STUCK_IN_DEVICE_DRIVER).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC0000218: STATUS_CANNOT_LOAD_REGISTRY_FILE

The STATUS_CANNOT_LOAD_REGISTRY_FILE bug check has a value of 0xC0000218. This indicates that a registry file could not be loaded.
Parameters
This bug check will display a descriptive text message. The name of the damaged file is displayed as part of the message.
Cause
This error occurs if a necessary registry hive file cannot be loaded. Usually this means the file is corrupt or is missing.
In rare instances, this error can be caused by a driver that has corrupted the registry image in memory, or by a memory error in this region.
Resolving the Problem
Try running the Emergency Recovery Disk (ERD) and allow the system to repair any errors that it detects. If the problem is a missing or corrupt registry file, this will usually
fix the problem.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC000021A: STATUS_SYSTEM_PROCESS_TERMINATED

The STATUS_SYSTEM_PROCESS_TERMINATED bug check has a value of 0xC000021A. This means that an error has occurred in a crucial user-mode subsystem.
Parameters
The following parameters are displayed on the blue screen.
Parameter
Description
A string that identifies the problem
1
2
The error code
3
Reserved
4
Reserved
Cause
This error occurs when a user-mode subsystem, such as WinLogon or the Client Server Run-Time Subsystem (CSRSS), has been fatally compromised and security can no
longer be guaranteed. In response, the operating system switches to kernel mode. Microsoft Windows cannot run without WinLogon or CSRSS. Therefore, this is one of the
few cases where the failure of a user-mode service can shut down the system.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 913 of 1651

Mismatched system files can also cause this error. This can occur if you have restored your hard disk from a backup. Some backup programs might skip restoring system files
that they determine are in use.
Resolving the Problem
Running the kernel debugger is not useful in this situation because the actual error occurred in a user-mode process.
Resolving an error in a user-mode device driver, system service, or third-party application: Because bug check 0xC000021A occurs in a user-mode process, the most
common culprits are third-party applications. If the error occurred after the installation of a new or updated device driver, system service, or third-party application, the new
software should be removed or disabled. Contact the manufacturer of the software about a possible update.
If the error occurs during system startup, restart your computer, and press F8 at the character-based menu that displays the operating system choices. At the resulting Windows
Advanced Options menu, choose the Last Known Good Configuration option. This option is most effective when only one driver or service is added at a time. If this does
not resolve the error, try manually removing the offending software. If the system partition is formatted with file allocation table (FAT), use an MS-DOS startup disk to gain
access to the computer's hard disk. If the system partition is formatted with NTFS file system, you might be able to use Safe Mode to rename or delete the faulty software. If
the faulty software is used as part of the system startup process in Safe Mode, you need to start the computer using the Recovery Console in order to access the file. If a newly
installed piece if hardware is suspected, remove it to see if this resolves the issue.
Try running the Emergency Recovery Disk (ERD) and allow the system to repair any errors that it detects.
Resolving a mismatched system file problem: If you have recently restored your hard disk from a backup, check if there is an updated version of the Backup/Restore program
available from the manufacturer. Make sure the latest Windows Service Pack is installed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xC0000221: STATUS_IMAGE_CHECKSUM_MISMATCH

The STATUS_IMAGE_CHECKSUM_MISMATCH bug check has a value of 0xC0000221. This indicates that a driver or a system DLL has been corrupted.
Parameters
This bug check will display a descriptive text message. The name of the damaged file is displayed as part of the message.
Cause
This bug check results from a serious error in a driver or other system file. The file header checksum does not match the expected checksum.
This can also be caused by faulty hardware in the I/O path to the file (a disk error, faulty RAM, or a corrupted page file).
Resolving the Problem
To remedy this error, run the Emergency Recovery Disk (ERD) and allow the system to repair or replace the missing or damaged driver file on the system partition.
You can also run an in-place upgrade over the existing copy of Windows. This preserves all registry settings and configuration information, but replaces all system files. If
any Service Packs and/or hotfixes had previously been applied, you need to reinstall them afterward in the appropriate order (latest Service Pack, then any post-Service Pack
hotfixes in the order in which they were originally installed, if applicable).
If a specific file was identified in the bug check message as being corrupted, you can try replacing that individual file manually. If the system partition is formatted with FAT,
you can start from an MS-DOS startup disk and copy the file from the original source onto the hard disk. If you have a dual-boot machine, you can boot to your other
operating system and replace the file.
If you want to replace the file on a single-boot system with an NTFS partition, you need to restart the system, press F8 at the operating system Loader menu, and choose Safe
Mode with Command Prompt. From there, copy a fresh version of the file from the original source onto the hard disk. If the file is used as part of the system startup process
in Safe Mode, you need to start the computer using the Recovery Console in order to access the file. If these methods fail, try reinstalling Windows and then restoring the
system from a backup.
Note If the original file from the product CD has a filename extension ending in an _ (underscore), the file needs to be uncompressed before it can be used. The Recovery
Console's Copy command automatically detects compressed files and expands them as they are copied to the target location. If you are using Safe Mode to access a drive, use
the Expand command to uncompress and copy the file to the target folder. You can use the Expand command in the command line environment of Safe Mode.
Resolving a disk error problem: Disk errors can be a source of file corruption. Run Chkdsk /f /r to detect and resolve any file system structural corruption. You must restart
the system before the disk scan begins on a system partition.
Resolving a RAM problem: If the error occurred immediately after RAM was added to the system, the paging file might be corrupted or the new RAM itself might be either
faulty or incompatible.
To determine if newly added RAM is causing a bug check
1.
2.
3.
4.
5.
6.

Return the system to the original RAM configuration.

Use the Recovery Console to access the partition containing the paging file and delete the file pagefile.sys.
While still in the Recovery Console, run Chkdsk /r on the partition that contained the paging file.
Restart the system.
Set the paging file to an optimal level for the amount of RAM added.
Shutdown the system and add your RAM.
The new RAM must meet the system manufacturer's specifications for speed, parity, and type (that is, fast page-mode (FPM) versus extended data out (EDO) versus
synchronous dynamic random access memory (SDRAM)). Try to match the new RAM to the existing installed RAM as closely as possible. RAM can come in many

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 914 of 1651

different capacities, and more importantly, in different formats (single inline memory modules SIMM or dual inline memory modules DIMM). The electrical
contacts can be either gold or tin and it is not wise to mix these contact types.
If you experience the same error message after reinstalling the new RAM, run hardware diagnostics supplied by the system manufacturer, especially the memory scanner. For
details on these procedures, see the owner's manual for your computer.
When you can log on to the system again, check the System Log in Event Viewer for additional error messages that might help pinpoint the device or driver that is causing the
error.
Disabling memory caching of the BIOS might also resolve this error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Check 0xDEADDEAD: MANUALLY_INITIATED_CRASH1

The MANUALLY_INITIATED_CRASH1 bug check has a value of 0xDEADDEAD. This indicates that the user deliberately initiated a crash dump from either the kernel
debugger or the keyboard.
Parameters
None
Comments
For details on manually-initiated crash dumps, see Forcing a System Crash.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Processor Architecture
This section includes:
The x86 Processor
The x64 Processor
The Itanium Processor
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The x86 Processor

This section includes:
x86 Architecture
x86 Instructions
Annotated x86 Disassembly
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

x86 Architecture
The Intel x86 processor uses complex instruction set computer (CISC) architecture, which means there is a modest number of special-purpose registers instead of large

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 915 of 1651

quantities of general-purpose registers. It also means that complicated special-purpose instructions will predominate.
The x86 processor traces its heritage at least as far back as the 8-bit Intel 8080 processor. Many peculiarities in the x86 instruction are due to the backward compatibility with
that processor (and with its Zilog Z-80 variant).
Microsoft Win32 uses the x86 processor in 32-bit flat mode. This documentation will focus only on the flat mode.

Registers
The x86 architecture consists of the following unprivileged integer registers:
eax Accumulator
ebx Base register
ecx Count register
edx Double-precision register
esi Source index register
edi Destination index register
ebp Base pointer register
esp Stack pointer
All integer registers are 32 bit. However, many of them have 16-bit or 8-bit subregisters.
ax Low 16 bits of eax
bx Low 16 bits of ebx
cx Low 16 bits of ecx
dx Low 16 bits of edx
si Low 16 bits of esi
di Low 16 bits of edi
bp Low 16 bits of ebp
sp Low 16 bits of esp
al Low 8 bits of eax
ah High 8 bits of ax
bl Low 8 bits of ebx
bh High 8 bits of bx
cl Low 8 bits of ecx
ch High 8 bits of cx
dl Low 8 bits of edx
dh High 8 bits of dx
Operating on a subregister affects only the subregister and none of the parts outside the subregister. For example, storing to the ax register leaves the high 16 bits of the eax
register unchanged.
When using the ? (Evaluate Expression) command, registers should be prefixed with an "at" sign ( @ ). For example, you should use ? @ax rather than ? ax. This ensures
that the debugger recognizes ax as a register rather than a symbol.
However, the (@) is not required in the r (Registers) command. For instance, r ax=5 will always be interpreted correctly.
Two other registers are important for the processor's current state.
eip instruction pointer
flags flags
The instruction pointer is the address of the instruction being executed.
The flags register is a collection of single-bit flags. Many instructions alter the flags to describe the result of the instruction. These flags can then be tested by conditional jump
instructions. See x86 Flags for details.

Calling Conventions
The x86 architecture has several different calling conventions. Fortunately, they all follow the same register preservation and function return rules:

Functions must preserve all registers, except for eax, ecx, and edx, which can be changed across a function call, and esp, which must be updated according to the
calling convention.
The eax register receives function return values if the result is 32 bits or smaller. If the result is 64 bits, then the result is stored in the edx:eax pair.

The following is a list of calling conventions used on the x86 architecture:

Win32 (__stdcall)
Function parameters are passed on the stack, pushed right to left, and the callee cleans the stack.

Native C++ method call (also known as thiscall)

Function parameters are passed on the stack, pushed right to left, the "this" pointer is passed in the ecx register, and the callee cleans the stack.

COM (__stdcall for C++ method calls)

Function parameters are passed on the stack, pushed right to left, then the "this" pointer is pushed on the stack, and then the function is called. The callee cleans the

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 916 of 1651

stack.

__fastcall
The first two DWORD-or-smaller arguments are passed in the ecx and edx registers. The remaining parameters are passed on the stack, pushed right to left. The callee
cleans the stack.

__cdecl
Function parameters are passed on the stack, pushed right to left, and the caller cleans the stack. The __cdecl calling convention is used for all functions with variablelength parameters.

Debugger Display of Registers and Flags

Here is a sample debugger register display:
eax=00000000 ebx=008b6f00 ecx=01010101 edx=ffffffff esi=00000000 edi=00465000
eip=77f9d022 esp=05cffc48 ebp=05cffc54 iopl=0
nv up ei ng nz na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000
efl=00000286
In user-mode debugging, you can ignore the iopl and the entire last line of the debugger display.

x86 Flags
In the preceding example, the two-letter codes at the end of the second line are flags. These are single-bit registers and have a variety of uses.
The following table lists the x86 flags:
Flag Flag Name
Code
of
Overflow Flag

Value

Flag
Status

Status Description

0
nv
No overflow
1
ov
Overflow
df
Direction Flag 0
up
Direction up
1
dn
Direction down
if
Interrupt Flag 0
di
Interrupts disabled
1
ei
Interrupts enabled
sf
Sign Flag
0
pl
Positive (or zero)
1
ng
Negative
zf
Zero Flag
0
nz
Nonzero
1
zr
Zero
af
Auxiliary Carry 0
na
No auxiliary carry
Flag
1
ac
Auxiliary carry
pf
Parity Flag
0
pe
Parity even
1
po
Parity odd
cf
Carry Flag
0
nc
No carry
1
cy
Carry
tf
Trap Flag
If tf equals 1, the processor will raise a STATUS_SINGLE_STEP exception after the execution of one instruction. This flag is used by a debugger to
implement single-step tracing. It should not be used by other applications.
iopl I/O Privilege
This is a two-bit integer, with values between zero and 3. It is used by the operating system to control access to hardware. It should not be used by
Level
applications.
When registers are displayed as a result of some command in the Debugger Command window, it is the flag status that is displayed. However, if you want to change a flag
using the r (Registers) command, you should refer to it by the flag code.
In the Registers window of WinDbg, the flag code is used to view or alter flags. The flag status is not supported.
Here is an example. In the preceding register display, the flag status ng appears. This means that the sign flag is currently set to 1. To change this, use the following command:
r sf=0
This sets the sign flag to zero. If you do another register display, the ng status code will not appear. Instead, the pl status code will be displayed.
The Sign Flag, Zero Flag, and Carry Flag are the most commonly-used flags.

Conditions
A condition describes the state of one or more flags. All conditional operations on the x86 are expressed in terms of conditions.
The assembler uses a one or two letter abbreviation to represent a condition. A condition can be represented by multiple abbreviations. For example, AE ("above or equal") is
the same condition as NB ("not below"). The following table lists some common conditions and their meaning.
Condition Name Flags
Meaning
Z
ZF=1 Result of last operation was zero.
NZ
ZF=0 Result of last operation was not zero.
C
CF=1 Last operation required a carry or borrow. (For unsigned integers, this indicates overflow.)
NC
CF=0 Last operation did not require a carry or borrow. (For unsigned integers, this indicates overflow.)
S
SF=1 Result of last operation has its high bit set.
NS
SF=0 Result of last operation has its high bit clear.
O
OF=1 When treated as a signed integer operation, the last operation caused an overflow or underflow.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 917 of 1651

OF=0 When treated as signed integer operation, the last operation did not cause an overflow or underflow.

Conditions can also be used to compare two values. The cmp instruction compares its two operands, and then sets flags as if subtracted one operand from the other. The
following conditions can be used to check the result of cmp value1, value2.
Condition Name
Flags
Meaning after a CMP operation.
E
ZF=1
value1 == value2.
NE
ZF=0
value1 != value2.
GE
SF=OF
value1 >= value2.
NL
Values are treated as signed integers.
LE
ZF=1 or SF!=OF value1 <= value2. Values are treated as signed integers.
NG
G
ZF=0 and SF=OF value1 > value2. Values are treated as signed integers.
NLE
L
SF!=OF
value1 < value2. Values are treated as signed integers.
NGE
AE
CF=0
value1 >= value2. Values are treated as unsigned integers.
NB
BE
CF=1 or ZF=1
value1 <= value2. Values are treated as unsigned integers.
NA
A
CF=0 and ZF=0 value1 > value2. Values are treated as unsigned integers.
NBE
B
CF=1
value1 < value2. Values are treated as unsigned integers.
NAE
Conditions are typically used to act on the result of a cmp or test instruction. For example,
cmp eax, 5
jz equal
compares the eax register against the number 5 by computing the expression (eax - 5) and setting flags according to the result. If the result of the subtraction is zero, then the
zr flag will be set, and the jz condition will be true so the jump will be taken.

Data Types

byte: 8 bits
word: 16 bits
dword: 32 bits
qword: 64 bits (includes floating-point doubles)
tword: 80 bits (includes floating-point extended doubles)
oword: 128 bits

Notation
The following table indicates the notation used to describe assembly language instructions.
Notation
Meaning
r, r1, r2... Registers
m
Memory address (see the succeeding Addressing Modes section for more information.)
#n
Immediate constant
r/m
Register or memory
r/#n
Register or immediate constant
r/m/#n
Register, memory, or immediate constant
cc
A condition code listed in the preceding Conditions section.
T
"B", "W", or "D" (byte, word or dword)
accT
Size T accumulator: al if T = "B", ax if T = "W", or eax if T = "D"

Addressing Modes
There are several different addressing modes, but they all take the form T ptr [expr], where T is some data type (see the preceding Data Types section) and expr is some
expression involving constants and registers.
The notation for most modes can be deduced without much difficulty. For example, BYTE PTR [esi+edx*8+3] means "take the value of the esi register, add to it eight times
the value of the edx register, add three, then access the byte at the resulting address."

Pipelining
The Pentium is dual-issue, which means that it can perform up to two actions in one clock tick. However, the rules on when it is capable of doing two actions at once (known
as pairing) are very complicated.
Because x86 is a CISC processor, you do not have to worry about jump delay slots.

Synchronized Memory Access

Load, modify, and store instructions can receive a lock prefix, which modifies the instruction as follows:
1. Before issuing the instruction, the CPU will flush all pending memory operations to ensure coherency. All data prefetches are abandoned.
2. While issuing the instruction, the CPU will have exclusive access to the bus. This ensures the atomicity of the load/modify/store operation.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 918 of 1651

The xchg instruction automatically obeys the previous rules whenever it exchanges a value with memory.
All other instructions default to nonlocking.

Jump Prediction
Unconditional jumps are predicted to be taken.
Conditional jumps are predicted to be taken or not taken, depending on whether they were taken the last time they were executed. The cache for recording jump history is
limited in size.
If the CPU does not have a record of whether the conditional jump was taken or not taken the last time it was executed, it predicts backward conditional jumps as taken and
forward conditional jumps as not taken.

Alignment
The x86 processor will automatically correct unaligned memory access, at a performance penalty. No exception is raised.
A memory access is considered aligned if the address is an integer multiple of the object size. For example, all BYTE accesses are aligned (everything is an integer multiple of
1), WORD accesses to even addresses are aligned, and DWORD addresses must be a multiple of 4 in order to be aligned.
The lock prefix should not be used for unaligned memory accesses.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

x86 Instructions
In the lists in this section, instructions marked with an asterisk (*) are particularly important. Instructions not so marked are not critical.
On the x86 processor, instructions are variable-sized, so disassembling backward is an exercise in pattern matching. To disassemble backward from an address, you should
start disassembling at a point further back than you really want to go, then look forward until the instructions start making sense. The first few instructions may not make any
sense because you may have started disassembling in the middle of an instruction. There is a possibility, unfortunately, that the disassembly will never synchronize with the
instruction stream and you will have to try disassembling at a different starting point until you find a starting point that works.
For well-packed switch statements, the compiler emits data directly into the code stream, so disassembling through a switch statement will usually stumble across instructions
that make no sense (because they are really data). Find the end of the data and continue disassembling there.

Instruction Notation
The general notation for instructions is to put the destination register on the left and the source on the right. However, there can be some exceptions to this rule.
Arithmetic instructions are typically two-register with the source and destination registers combining. The result is stored into the destination.
Some of the instructions have both 16-bit and 32-bit versions, but only the 32-bit versions are listed here. Not listed here are floating-point instructions, privileged
instructions, and instructions that are used only in segmented models (which Microsoft Win32 does not use).
To save space, many of the instructions are expressed in combined form, as shown in the following example.
* MOV r1, r/m/#n r1 = r/m/#n
means that the first parameter must be a register, but the second can be a register, a memory reference, or an immediate value.
To save even more space, instructions can also be expressed as shown in the following.
* MOV r1/m, r/m/#n r1/m = r/m/#n
which means that the first parameter can be a register or a memory reference, and the second can be a register, memory reference, or immediate value.
Unless otherwise noted, when this abbreviation is used, you cannot choose memory for both source and destination.
Furthermore, a bit-size suffix (8, 16, 32) can be appended to the source or destination to indicate that the parameter must be of that size. For example, r8 means an 8-bit
register.

Memory, Data Transfer, and Data Conversion

Memory and data transfer instructions do not affect flags.

Effective Address
* LEA r, m Load effective address.
(r = address of m)

For example, LEA eax, [esi+4] means eax = esi + 4. This instruction is often used to perform arithmetic.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 919 of 1651

Data Transfer
* MOV r1/m, r2/m/#n r1/m = r/m/#n
* MOV r1, r/m
Move with sign extension.
* MOV r1, r/m
Move with zero extension.
MOVSX and MOVZX are special versions of the mov instruction that perform sign extension or zero extension from the source to the destination. This is the only instruction
that allows the source and destination to be different sizes. (And in fact, they must be different sizes.

Stack Manipulation
The stack is pointed to by the esp register. The value at esp is the top of the stack (most recently pushed, first to be popped); older stack elements reside at higher addresses.
* PUSH
r/m/#n Push value onto stack.
* POP
r/m
Pop value from stack.
PUSHFD
Push flags onto stack.
POPFD
Pop flags from stack.
PUSHAD
Push all integer registers.
POPAD
Pop all integer registers.
ENTER #n, #n Build stack frame.
* LEAVE
Tear down stack frame
The C/C++ compiler does not use the enter instruction. (The enter instruction is used to implement nested procedures in languages like Algol or Pascal.)
The leave instruction is equivalent to:
mov esp, ebp
pop ebp

Data Conversion
CBW Convert byte (al) to word (ax).
CWD Convert word (ax) to dword (dx:ax).
CWDE Convert word (ax) to dword (eax).
CDQ convert dword (eax) to qword (edx:eax).
All conversions perform sign extension.

Arithmetic and Bit Manipulation

All arithmetic and bit manipulation instructions modify flags.

Arithmetic
* ADD r1/m, r2/m/#n r1/m += r2/m/#n
ADC r1/m, r2/m/#n r1/m += r2/m/#n + carry
* SUB r1/m, r2/m/#n r1/m -= r2/m/#n
SBB r1/m, r2/m/#n r1/m -= r2/m/#n + carry
* NEG r1/m
r1/m = -r1/m
* INC r/m
r/m += 1
* DEC r/m
r/m -= 1
* CMP r1/m, r2/m/#n Compute r1/m - r2/m/#n
The cmp instruction computes the subtraction and sets flags according to the result, but throws the result away. It is typically followed by a conditional jump instruction that
tests the result of the subtraction.
MUL r/m8
ax = al * r/m8
MUL r/m16
dx:ax = ax * r/m16
* MUL r/m32
edx:eax = eax * r/m32
IMUL r/m8
ax = al * r/m8
IMUL r/m16
dx:ax = ax * r/m16
* IMUL r/m32
edx:eax = eax * r/m32
* IMUL r1, r2/m
r1 *= r2/m
* IMUL r1, r2/m, #n r1 = r2/m * #n
Unsigned and signed multiplication. The state of flags after multiplication is undefined.
DIV r/m8 (ah, al) = (ax % r/m8, ax r/m8)
DIV r/m16 (dx, ax) = dx:ax r/m16
* DIV r/m32 (edx, eax) = edx:eax r/m32
IDIV r/m8 (ah, al) = ax r/m8
IDIV r/m16 (dx, ax) = dx:ax r/m16
* IDIV r/m32 (edx, eax) = edx:eax r/m32

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 920 of 1651

Unsigned and signed division. The first register in the pseudocode explanation receives the remainder and the second receives the quotient. If the result overflows the
destination, a division overflow exception is generated.
The state of flags after division is undefined.
* SETcc r/m8 Set r/m8 to 0 or 1
If the condition cc is true, then the 8-bit value is set to 1. Otherwise, the 8-bit value is set to zero.

Binary-coded Decimal
You will not see these instructions unless you are debugging code written in COBOL.
DAA Decimal adjust after addition.
DAS Decimal adjust after subtraction.
These instructions adjust the al register after performing a packed binary-coded decimal operation.
AAA ASCII adjust after addition.
AAS ASCII adjust after subtraction.
These instructions adjust the al register after performing an unpacked binary-coded decimal operation.
AAM ASCII adjust after multiplication.
AAD ASCII adjust after division.
These instructions adjust the al and ah registers after performing an unpacked binary-coded decimal operation.

Bits
* AND r1/m, r2/m/#n r1/m = r1/m and r2/m/#n
* OR r1/m, r2/m/#n r1/m = r1/m or r2/m/#n
* XOR r1/m, r2/m/#n r1/m = r1/m xor r2/m/#n
* NOT r1/m
r1/m = bitwise not r1/m
* TEST r1/m, r2/m/#n Compute r1/m and r2/m/#n
The test instruction computes the logical AND operator and sets flags according to the result, but throws the result away. It is typically followed by a conditional jump
instruction that tests the result of the logical AND.
* SHL r1/m, cl/#n r1/m <<= cl/#n
* SHR r1/m, cl/#n r1/m >>= cl/#n zero-fill
* SAR r1/m, cl/#n r1/m >>= cl/#n sign-fill
The last bit shifted out is placed in the carry.
SHLD r1, r2/m, cl/#n Shift left double.
Shift r1 left by cl/#n, filling with the top bits of r2/m. The last bit shifted out is placed in the carry.
SHRD r1, r2/m, cl/#n Shift right double.
Shift r1 right by cl/#n, filling with the bottom bits of r2/m. The last bit shifted out is placed in the carry.
ROL r1, cl/#n Rotate r1 left by cl/#n.
ROR r1, cl/#n Rotate r1 right by cl/#n.
RCL r1, cl/#n Rotate r1/C left by cl/#n.
RCR r1, cl/#n Rotate r1/C right by cl/#n.
Rotation is like shifting, except that the bits that are shifted out reappear as the incoming fill bits. The C-language version of the rotation instructions incorporate the carry bit
into the rotation.
BT r1, r2/#n Copy bit r2/#n of r1 into carry.
BTS r1, r2/#n Set bit r2/#n of r1, copy previous value into carry.
BTC r1, r2/#n Clear bit r2/#n of r1, copy previous value into carry.

Control Flow
* Jcc
dest Branch conditional.
* JMP dest Jump direct.
* JMP r/m Jump indirect.
* CALL dest Call direct.
* CALL r/m Call indirect.
The call instruction pushes the return address onto the stack then jumps to the destination.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 921 of 1651

* RET #n Return
The ret instruction pops and jumps to the return address on the stack. A nonzero #n in the RET instruction indicates that after popping the return address, the value #n should
be added to the stack pointer.
LOOP
Decrement ecx and jump if result is nonzero.
LOOPZ Decrement ecx and jump if result is nonzero and zr was set.
LOOPNZ Decrement ecx and jump if result is nonzero and zr was clear.
JECXZ Jump if ecx is zero.
These instructions are remnants of the x86's CISC heritage and in recent processors are actually slower than the equivalent instructions written out the long way.

String Manipulation
* MOVST
CMPST
SCAST
LODST
* STOST

Move T from esi to edi.

Compare T from esi with edi.
Scan T from edi for accT.
Load T from esi into accT.
Store T to edi from accT.

After performing the operation, the source and destination register are incremented or decremented by sizeof(T), according to the setting of the direction flag (up or down).
The instruction can be prefixed by REP to repeat the operation the number of times specified by the ecx register.
The rep mov instruction is used to copy blocks of memory.
The rep stos instruction is used to fill a block of memory with accT.

Flags
LAHF Load ah from flags.
SAHF Store ah to flags.
STC Set carry.
CLC Clear carry.
CMC Complement carry.
STD Set direction to down.
CLD Set direction to up.
STI Enable interrupts.
CLI Disable interrupts.

Interlocked Instructions
XCHG
r1, r/m Swap r1 and r/m.
XADD
r1, r/m Add r1 to r/m, put original value in r1.
CMPXCHG r1, r/m Compare and exchange conditional.
The cmpxchg instruction is the atomic version of the following:
cmp
jz
mov
jmp
match:
mov
done:

accT, r/m
match
accT, r/m
done
r/m, r1

Miscellaneous
INT
#n Trap to kernel.
BOUND r, m Trap if r not in range.
* NOP
No operation.
XLATB
al = [ebx + al]
BSWAP r
Swap byte order in register.
Here is a special case of the int instruction.
INT 3 Debugger breakpoint trap.
The opcode for INT 3 is 0xCC. The opcode for NOP is 0x90.
When debugging code, you may need to patch out some code. You can do this by replacing the offending bytes with 0x90.

Idioms
* XOR r, r r = 0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 922 of 1651

* TEST r, r Check if r = 0.
* ADD r, r Shift r left by 1.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Annotated x86 Disassembly

The following section will walk you through a disassembly example.

Source Code
The following is the code for the function that will be analyzed.
HRESULT CUserView::CloseView(void)
{
if (m_fDestroyed) return S_OK;
BOOL fViewObjectChanged = FALSE;
ReleaseAndNull(&m_pdtgt);
if (m_psv) {
m_psb->EnableModelessSB(FALSE);
if(m_pws) m_pws->ViewReleased();
IShellView* psv;
HWND hwndCapture = GetCapture();
if (hwndCapture && hwndCapture == m_hwnd) {
SendMessage(m_hwnd, WM_CANCELMODE, 0, 0);
}
m_fHandsOff = TRUE;
m_fRecursing = TRUE;
NotifyClients(m_psv, NOTIFY_CLOSING);
m_fRecursing = FALSE;
m_psv->UIActivate(SVUIA_DEACTIVATE);
psv = m_psv;
m_psv = NULL;
ReleaseAndNull(&_pctView);
if (m_pvo) {
IAdviseSink *pSink;
if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) && pSink) {
if (pSink == (IAdviseSink *)this)
m_pvo->SetAdvise(0, 0, NULL);
pSink->Release();
}
fViewObjectChanged = TRUE;
ReleaseAndNull(&m_pvo);
}
if (psv) {
psv->SaveViewState();
psv->DestroyViewWindow();
psv->Release();
}
m_hwndView = NULL;
m_fHandsOff = FALSE;
if (m_pcache) {
GlobalFree(m_pcache);
m_pcache = NULL;
}
m_psb->EnableModelessSB(TRUE);
CancelPendingActions();
}
ReleaseAndNull(&_psf);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 923 of 1651

if (fViewObjectChanged)
NotifyViewClients(DVASPECT_CONTENT, -1);
if (m_pszTitle) {
LocalFree(m_pszTitle);
m_pszTitle = NULL;
}
SetRect(&m_rcBounds, 0, 0, 0, 0);
return S_OK;
}

Assembly Code
This section contains the annotated disassembly example.
Functions which use the ebp register as a frame pointer start out as follows:
HRESULT CUserView::CloseView(void)
SAMPLE!CUserView__CloseView:
71517134 55
push
ebp
71517135 8bec
mov
ebp,esp
This sets up the frame so the function can access its parameters as positive offsets from ebp, and local variables as negative offsets.
This is a method on a private COM interface, so the calling convention is __stdcall. This means that parameters are pushed right to left (in this case, there are none), the "this"
pointer is pushed, and then the function is called. Thus, upon entry into the function, the stack looks like this:
[esp+0] = return address
[esp+4] = this
After the two preceding instructions, the parameters are accessible as:
[ebp+0] = previous ebp pushed on stack
[ebp+4] = return address
[ebp+8] = this
For a function that uses ebp as a frame pointer, the first pushed parameter is accessible at [ebp+8]; subsequent parameters are accessible at consecutive higher DWORD
addresses.
71517137 51
71517138 51

push
push

ecx
ecx

This function requires only two local stack variables, so a sub esp, 8 instruction. The pushed values are then available as [ebp-4] and [ebp-8].
For a function that uses ebp as a frame pointer, stack local variables are accessible at negative offsets from the ebp register.
71517139 56

push

esi

Now the compiler saves the registers that are required to be preserved across function calls. Actually, it saves them in bits and pieces, interleaved with the first line of actual
code.
7151713a 8b7508
7151713d 57

mov
push

esi,[ebp+0x8]
edi

; esi = this
; save another registers

It so happens that CloseView is a method on ViewState, which is at offset 12 in the underlying object. Consequently, this is a pointer to a ViewState class, although when
there is possible confusion with another base class, it will be more carefully specified as (ViewState*)this.
if (m_fDestroyed)
7151713e 33ff

xor

edi,edi

; edi = 0

XORing a register with itself is a standard way of zeroing it out.

71517140 39beac000000
71517146 7407

cmp
jz

[esi+0xac],edi
; this->m_fDestroyed == 0?
NotDestroyed (7151714f) ; jump if equal

The cmp instruction compares two values (by subtracting them). The jz instruction checks if the result is zero, indicating that the two compared values are equal.
The cmp instruction compares two values; a subsequent j instruction jumps based on the result of the comparison.
return S_OK;
71517148 33c0
7151714a e972010000

xor
jmp

eax,eax
; eax = 0 = S_OK
ReturnNoEBX (715172c1) ; return, do not pop EBX

The compiler delayed saving the EBX register until later in the function, so if the program is going to "early-out" on this test, then the exit path needs to be the one that does
not restore EBX.
BOOL fViewObjectChanged = FALSE;
ReleaseAndNull(&m_pdtgt);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 924 of 1651

The execution of these two lines of code is interleaved, so pay attention.

NotDestroyed:
7151714f 8d86c0000000

lea

eax,[esi+0xc0]

; eax = &m_pdtgt

The lea instruction computes the effect address of a memory access and stores it in the destination. The actual memory address is not dereferenced.
The lea instruction takes the address of a variable.
71517155 53

push

ebx

You should save that EBX register before it is damaged.

71517156 8b1d10195071

mov ebx,[_imp__ReleaseAndNull]

Because you will be calling ReleaseAndNull frequently, it is a good idea to cache its address in EBX.
7151715c 50
7151715d 897dfc
71517160 ffd3
if (m_psv) {
71517162 397e74
71517165 0f8411010000

push
mov
call

eax
[ebp-0x4],edi
ebx

; parameter to ReleaseAndNull
; fViewObjectChanged = FALSE
; call ReleaseAndNull

cmp
je

[esi+0x74],edi
; this->m_psv == 0?
No_Psv (7151727c) ; jump if zero

Remember that you zeroed out the EDI register a while back and that EDI is a register preserved across function calls (so the call to ReleaseAndNull did not change it).
Therefore, it still holds the value zero and you can use it to quickly test for zero.

7151716b
7151716e
7151716f
71517170
71517172

m_psb->EnableModelessSB(FALSE);
8b4638
mov
eax,[esi+0x38]
57
push
edi
50
push
eax
8b08
mov
ecx,[eax]
ff5124
call
[ecx+0x24]

;
;
;
;
;

eax = this->m_psb
FALSE
"this" for callee
ecx = m_psb->lpVtbl
__stdcall EnableModelessSB

The above pattern is a telltale sign of a COM method call.

COM method calls are pretty popular, so it is a good idea to learn to recognize them. In particular, you should be able to recognize the three IUnknown methods directly from
their Vtable offsets: QueryInterface=0, AddRef=4, and Release=8.

71517175
7151717b
7151717d
7151717f
71517181
71517182
NoWS:

if(m_pws) m_pws->ViewReleased();
8b8614010000
mov
eax,[esi+0x114]
; eax = this->m_pws
3bc7
cmp
eax,edi
; eax == 0?
7406
jz
NoWS (71517185) ; if so, then jump
8b08
mov
ecx,[eax]
; ecx = m_pws->lpVtbl
50
push
eax
; "this" for callee
ff510c
call
[ecx+0xc]
; __stdcall ViewReleased

HWND hwndCapture = GetCapture();

71517185 ff15e01a5071
call [_imp__GetCapture]

; call GetCapture

Indirect calls through globals is how function imports are implemented in Microsoft Win32. The loader fixes up the globals to point to the actual address of the target. This is
a handy way to get your bearings when you are investigating a crashed machine. Look for the calls to imported functions and in the target. You will usually have the name of
some imported function, which you can use to determine where you are in the source code.
if (hwndCapture && hwndCapture == m_hwnd) {
SendMessage(m_hwnd, WM_CANCELMODE, 0, 0);
}
7151718b 3bc7
cmp
eax,edi
; hwndCapture == 0?
7151718d 7412
jz
No_Capture (715171a1) ; jump if zero
The function return value is placed in the EAX register.
7151718f 8b4e44
71517192 3bc1
71517194 750b

mov
cmp
jnz

71517196 57
push
71517197 57
push
71517198 6a1f
push
7151719a 51
push
7151719b ff1518195071
call
No_Capture:
m_fHandsOff = TRUE;
m_fRecursing = TRUE;
715171a1 66818e0c0100000180 or

ecx,[esi+0x44]
; ecx = this->m_hwnd
eax,ecx
; hwndCapture = ecx?
No_Capture (715171a1) ; jump if not
edi
; 0
edi
; 0
0x1f
; WM_CANCELMODE
ecx
; hwndCapture
[_imp__SendMessageW] ; SendMessage

word ptr [esi+0x10c],0x8001 ; set both flags at once

NotifyClients(m_psv, NOTIFY_CLOSING);
715171aa 8b4e20
mov
ecx,[esi+0x20]
715171ad 6a04
push
0x4
715171af 8d4620
lea
eax,[esi+0x20]

; ecx = (CNotifySource*)this.vtbl
; NOTIFY_CLOSING
; eax = (CNotifySource*)this

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 925 of 1651

715171b2 ff7674
715171b5 50
715171b6 ff510c

push
push
call

[esi+0x74]
eax
[ecx+0xc]

; m_psv
; "this" for callee
; __stdcall NotifyClients

Notice how you had to change your "this" pointer when calling a method on a different base class from your own.
m_fRecursing = FALSE;
715171b9 80a60d0100007f
and
byte ptr [esi+0x10d],0x7f
m_psv->UIActivate(SVUIA_DEACTIVATE);
715171c0 8b4674
mov
eax,[esi+0x74]
; eax = m_psv
715171c3 57
push
edi
; SVUIA_DEACTIVATE = 0
715171c4 50
push
eax
; "this" for callee
715171c5 8b08
mov
ecx,[eax]
; ecx = vtbl
715171c7 ff511c
call
[ecx+0x1c]
; __stdcall UIActivate
psv = m_psv;
m_psv = NULL;
715171ca 8b4674
mov
eax,[esi+0x74]
; eax = m_psv
715171cd 897e74
mov
[esi+0x74],edi
; m_psv = NULL
715171d0 8945f8
mov
[ebp-0x8],eax
; psv = eax
The first local variable is psv.
ReleaseAndNull(&_pctView);
715171d3 8d466c
lea
eax,[esi+0x6c]
715171d6 50
push
eax
715171d7 ffd3
call
ebx
if (m_pvo) {
715171d9 8b86a8000000
mov
eax,[esi+0xa8]
715171df 8dbea8000000
lea
edi,[esi+0xa8]
715171e5 85c0
test
eax,eax
715171e7 7448
jz
No_Pvo (71517231)

; eax = &_pctView
; parameter
; call ReleaseAndNull
;
;
;
;

eax = m_pvo
edi = &m_pvo
eax == 0?
jump if zero

Note that the compiler speculatively prepared the address of the m_pvo member, because you are going to use it frequently for a while. Thus, having the address handy will
result in smaller code.

715171e9
715171eb
715171ee
715171ef
715171f1
715171f3
715171f4
715171f7
715171f9
715171fb
715171fd
71517200

if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) && pSink) {

8b08
mov
ecx,[eax]
; ecx = m_pvo->lpVtbl
8d5508
lea
edx,[ebp+0x8]
; edx = &pSink
52
push
edx
; parameter
6a00
push
0x0
; NULL
6a00
push
0x0
; NULL
50
push
eax
; "this" for callee
ff5120
call
[ecx+0x20]
; __stdcall GetAdvise
85c0
test
eax,eax
; test bits of eax
7c2c
jl
No_Advise (71517227) ; jump if less than zero
33c9
xor
ecx,ecx
; ecx = 0
394d08
cmp
[ebp+0x8],ecx
; _pSink == ecx?
7425
jz
No_Advise (71517227)

Notice that the compiler concluded that the incoming "this" parameter was not required (because it long ago stashed that into the ESI register). Thus, it reused the memory as
the local variable pSink.
If the function uses an EBP frame, then incoming parameters arrive at positive offsets from EBP and local variables are placed at negative offsets. But, as in this case, the
compiler is free to reuse that memory for any purpose.
If you are paying close attention, you will see that the compiler could have optimized this code a little better. It could have delayed the lea edi, [esi+0xa8] instruction until
after the two push 0x0 instructions, replacing them with push edi. This would have saved 2 bytes.
if (pSink == (IAdviseSink *)this)
These next several lines are to compensate for the fact that in C++, (IAdviseSink *)NULL must still be NULL. So if your "this" is really "(ViewState*)NULL", then the result
of the cast should be NULL and not the distance between IAdviseSink and IBrowserService.
71517202
71517205
71517208
7151720a
7151720c

8d46ec
8d5614
f7d8
1bc0
23c2

lea
lea
neg
sbb
and

eax,[esi-0x14]
edx,[esi+0x14]
eax
eax,eax
eax,edx

;
;
;
;
;

eax
edx
eax
eax
eax

=
=
=
=
=

-(IAdviseSink*)this
(IAdviseSink*)this
-eax (sets carry if != 0)
eax - eax - carry
NULL or edx

Although the Pentium has a conditional move instruction, the base i386 architecture does not, so the compiler uses specific techniques to simulate a conditional move
instruction without taking any jumps.
The general pattern for a conditional evaluation is the following:
neg
sbb
and
add

r
r, r
r, (val1 - val2)
r, val2

The neg r sets the carry flag if r is nonzero, because neg negates the value by subtracting from zero. And, subtracting from zero will generate a borrow (set the carry) if you
subtract a nonzero value. It also damages the value in the r register, but that is acceptable because you are about to overwrite it anyway.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 926 of 1651

Next, the sbb r, r instruction subtracts a value from itself, which always results in zero. However, it also subtracts the carry (borrow) bit, so the net result is to set r to zero or 1, depending on whether the carry was clear or set, respectively.
Therefore, sbb r, r sets r to zero if the original value of r was zero, or to -1 if the original value was nonzero.
The third instruction performs a mask. Because the r register is zero or -1, "this" serves either to leave r zero or to change r from -1 to (val1 - val1), in that ANDing any value
with -1 leaves the original value.
Therefore, the result of "and r, (val1 - val1)" is to set r to zero if the original value of r was zero, or to "(val1 - val2)" if the original value of r was nonzero.
Finally, you add val2 to r, resulting in val2 or (val1 - val2) + val2 = val1.
Thus, the ultimate result of this series of instructions is to set r to val2 if it was originally zero or to val1 if it was nonzero. This is the assembly equivalent of r = r ? val1 :
val2.
In this particular instance, you can see that val2 = 0 and val1 = (IAdviseSink*)this. (Notice that the compiler elided the final add eax, 0 instruction because it has no effect.)
7151720e 394508
71517211 750b

cmp
jnz

[ebp+0x8],eax ; pSink == (IAdviseSink*)this?

No_SetAdvise (7151721e) ; jump if not equal

Earlier in this section, you set EDI to the address of the m_pvo member. You are going to be using it now. You also zeroed out the ECX register earlier.

71517213 8b07
71517215 51
71517216 51
71517217 51
71517218 8b10
7151721a 50
7151721b ff521c
No_SetAdvise:
7151721e 8b4508
71517221 50
71517222 8b08
71517224 ff5108
No_Advise:

m_pvo->SetAdvise(0, 0, NULL);
mov
eax,[edi]
push
ecx
push
ecx
push
ecx
mov
edx,[eax]
push
eax
call
[edx+0x1c]
pSink->Release();
mov
push
mov
call

eax,[ebp+0x8]
eax
ecx,[eax]
[ecx+0x8]

;
;
;
;
;
;
;

eax = m_pvo
NULL
0
0
edx = m_pvo->lpVtbl
"this" for callee
__stdcall SetAdvise

;
;
;
;

eax = pSink
"this" for callee
ecx = pSink->lpVtbl
__stdcall Release

All these COM method calls should look very familiar.

The evaluation of the next two statements is interleaved. Do not forget that EBX contains the address of ReleaseAndNull.
fViewObjectChanged = TRUE;
ReleaseAndNull(&m_pvo);
71517227 57
push
edi
; &m_pvo
71517228 c745fc01000000
mov
dword ptr [ebp-0x4],0x1 ; fViewObjectChanged = TRUE
7151722f ffd3
call
ebx
; call ReleaseAndNull
No_Pvo:
if (psv) {
71517231 8b7df8
mov
edi,[ebp-0x8]
; edi = psv
71517234 85ff
test
edi,edi
; edi == 0?
71517236 7412
jz
No_Psv2 (7151724a) ; jump if zero
psv->SaveViewState();
71517238 8b07
mov
eax,[edi]
; eax = psv->lpVtbl
7151723a 57
push
edi
; "this" for callee
7151723b ff5034
call
[eax+0x34]
; __stdcall SaveViewState
Here are more COM method calls.
psv->DestroyViewWindow();
7151723e 8b07
mov
eax,[edi]
; eax = psv->lpVtbl
71517240 57
push
edi
; "this" for callee
71517241 ff5028
call
[eax+0x28]
; __stdcall DestroyViewWindow
psv->Release();
71517244 8b07
mov
eax,[edi]
; eax = psv->lpVtbl
71517246 57
push
edi
; "this" for callee
71517247 ff5008
call
[eax+0x8]
; __stdcall Release
No_Psv2:
m_hwndView = NULL;
7151724a 83667c00
and
dword ptr [esi+0x7c],0x0 ; m_hwndView = 0
ANDing a memory location with zero is the same as setting it to zero, because anything AND zero is zero. The compiler uses this form because, even though it is slower, it is
much shorter than the equivalent mov instruction. (This code was optimized for size, not speed.)
m_fHandsOff = FALSE;
7151724e 83a60c010000fe
and
if (m_pcache) {
71517255 8b4670
mov
71517258 85c0
test
7151725a 740b
jz
GlobalFree(m_pcache);
7151725c 50
push

dword ptr [esi+0x10c],0xfe

eax,[esi+0x70]
; eax = m_pcache
eax,eax
; eax == 0?
No_Cache (71517267) ; jump if zero
eax

; m_pcache

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 927 of 1651

7151725d ff15b4135071
call
[_imp__GlobalFree]
; call GlobalFree
m_pcache = NULL;
71517263 83667000
and
dword ptr [esi+0x70],0x0 ; m_pcache = 0
No_Cache:
m_psb->EnableModelessSB(TRUE);
71517267 8b4638
mov
eax,[esi+0x38]
; eax = this->m_psb
7151726a 6a01
push
0x1
; TRUE
7151726c 50
push
eax
; "this" for callee
7151726d 8b08
mov
ecx,[eax]
; ecx = m_psb->lpVtbl
7151726f ff5124
call
[ecx+0x24]
; __stdcall EnableModelessSB
CancelPendingActions();
In order to call CancelPendingActions, you have to move from (ViewState*)this to (CUserView*)this. Note also that CancelPendingActions uses the __thiscall calling
convention instead of __stdcall. According to __thiscall, the "this" pointer is passed in the ECX register instead of being passed on the stack.
71517272 8d4eec
lea
ecx,[esi-0x14]
; ecx = (CUserView*)this
71517275 e832fbffff
call CUserView::CancelPendingActions (71516dac) ; __thiscall
ReleaseAndNull(&_psf);
7151727a 33ff
xor
edi,edi
; edi = 0 (for later)
No_Psv:
7151727c 8d4678
lea
eax,[esi+0x78]
; eax = &_psf
7151727f 50
push
eax
; parameter
71517280 ffd3
call
ebx
; call ReleaseAndNull
if (fViewObjectChanged)
71517282 397dfc
cmp
[ebp-0x4],edi
; fViewObjectChanged == 0?
71517285 740d
jz
NoNotifyViewClients (71517294) ; jump if zero
NotifyViewClients(DVASPECT_CONTENT, -1);
71517287 8b46ec
mov
eax,[esi-0x14]
; eax = ((CUserView*)this)->lpVtbl
7151728a 8d4eec
lea
ecx,[esi-0x14]
; ecx = (CUserView*)this
7151728d 6aff
push
0xff
; -1
7151728f 6a01
push
0x1
; DVASPECT_CONTENT = 1
71517291 ff5024
call
[eax+0x24]
; __thiscall NotifyViewClients
NoNotifyViewClients:
if (m_pszTitle)
71517294 8b8680000000
mov
eax,[esi+0x80]
; eax = m_pszTitle
7151729a 8d9e80000000
lea
ebx,[esi+0x80]
; ebx = &m_pszTitle (for later)
715172a0 3bc7
cmp
eax,edi
; eax == 0?
715172a2 7409
jz
No_Title (715172ad) ; jump if zero
LocalFree(m_pszTitle);
715172a4 50
push
eax
; m_pszTitle
715172a5 ff1538125071
call
[_imp__LocalFree]
m_pszTitle = NULL;
Remember that EDI is still zero and EBX is still &m_pszTitle, because those registers are preserved by function calls.
715172ab 893b
mov
[ebx],edi
No_Title:
SetRect(&m_rcBounds, 0, 0, 0, 0);
715172ad 57
push
edi
715172ae 57
push
edi
715172af 57
push
edi
715172b0 81c6fc000000
add
esi,0xfc
715172b6 57
push
edi
715172b7 56
push
esi
715172b8 ff15e41a5071
call
[_imp__SetRect]

; m_pszTitle = 0

;
;
;
;
;
;

0
0
0
esi = &this->m_rcBounds
0
&m_rcBounds

Notice that you do not need the value of "this" any more, so the compiler uses the add instruction to modify it in place instead of using up another register to hold the address.
This is actually a performance win due to the Pentium u/v pipelining, because the v pipe can do arithmetic, but not address computations.
return S_OK;
715172be 33c0

xor

eax,eax

; eax = S_OK

Finally, you restore the registers you are required to preserve, clean up the stack, and return to your caller, removing the incoming parameters.
715172c0 5b
ReturnNoEBX:
715172c1 5f
715172c2 5e
715172c3 c9
715172c4 c20400

pop

ebx

; restore

pop
pop
leave
ret

edi
esi

;
;
;
;

0x4

restore
restore
restores EBP and ESP simultaneously
return and clear parameters

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The x64 Processor

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 928 of 1651

This section includes:

x64 Architecture
x64 Instructions
Annotated x64 Disassembly
Note The x64 processor architecture is sometimes referred to as "AMD64", "x86-64", "AMD x86-64" or "Intel64".
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

x64 Architecture
The x64 architecture is a backwards-compatible extension of x86. It provides a legacy 32-bit mode, which is identical to x86, and a new 64-bit mode.
The term "x64" includes both AMD 64 and Intel64. The instruction sets are close to identical.

Registers
x64 extends x64's 8 general-purpose registers to be 64-bit, and adds 8 new 64-bit registers. The 64-bit registers have names beginning with "r", so for example the 64-bit
extension of eax is called rax. The new registers are named r8 through r15.
The lower 32 bits, 16 bits, and 8 bits of each register are directly addressable in operands. This includes registers, like esi, whose lower 8 bits were not previously addressable.
The following table specifies the assembly-language names for the lower portions of 64-bit registers.
64-bit register Lower 32 bits Lower 16 bits Lower 8 bits
rax
eax
ax
al
rbx
ebx
bx
bl
rcx
ecx
cx
cl
rdx
edx
dx
dl
rsi
esi
si
sil
rdi
edi
di
dil
rbp
ebp
bp
bpl
rsp
esp
sp
spl
r8
r8d
r8w
r8b
r9
r9d
r9w
r9b
r10
r10d
r10w
r10b
r11
r11d
r11w
r11b
r12
r12d
r12w
r12b
r13
r13d
r13w
r13b
r14
r14d
r14w
r14b
r15
r15d
r15w
r15b
Operations that output to a 32-bit subregister are automatically zero-extended to the entire 64-bit register. Operations that output to 8-bit or 16-bit subregisters are not zeroextended (this is compatible x86 behavior).
The high 8 bits of ax, bx, cx, and dx are still addressable as ah, bh, ch, dh, but cannot be used with all types of operands.
The instruction pointer, eip, and flags register have been extended to 64 bits (rip and rflags, respectively) as well.
The x64 processor also provides several sets of floating-point registers:

Eight 80-bit x87 registers.

Eight 64-bit MMX registers. (These overlap with the x87 registers.)
The original set of eight 128-bit SSE registers is increased to sixteen.

Calling Conventions
Unlike the x86, the C/C++ compiler only supports one calling convention on x64. This calling convention takes advantage of the increased number of registers available on
x64:

The first four integer or pointer parameters are passed in the rcx, rdx, r8, and r9 registers.
The first four floating-point parameters are passed in the first four SSE registers, xmm0-xmm3.
The caller reserves space on the stack for arguments passed in registers. The called function can use this space to spill the contents of registers to the stack.
Any additional arguments are passed on the stack.
An integer or pointer return value is returned in the rax register, while a floating-point return value is returned in xmm0.
rax, rcx, rdx, r8-r11 are volatile.
rbx, rbp, rdi, rsi, r12-r15 are nonvolatile.

The calling convention for C++ is very similar: the this pointer is passed as an implicit first parameter. The next three parameters are passed in registers, while the rest are
passed on the stack.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 929 of 1651

Addressing Modes
The addressing modes in 64-bit mode are similar to, but not identical to, x86.

Instructions that refer to 64-bit registers are automatically performed with 64-bit precision. (For example mov rax, [rbx] moves 8 bytes beginning at rbx into rax.)
A special form of the mov instruction has been added for 64-bit immediate constants or constant addresses. For all other instructions, immediate constants or constant
addresses are still 32 bits.
x64 provides a new rip-relative addressing mode. Instructions that refer to a single constant address are encoded as offsets from rip. For example, the mov rax, [addr]
instruction moves 8 bytes beginning at addr + rip to rax.

Instructions, such as jmp, call, push, and pop, that implicitly refer to the instruction pointer and the stack pointer treat them as 64 bits registers on x64.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

x64 Instructions
Most x86 instructions continue to be valid for x64 in 64-bit mode. Some rarely-used operations are no longer supported in 64-bit mode, such as:

binary-coded decimal arithmetic instructions: AAA, AAD, AAM, AAS, DAA, DAS
BOUND
PUSHAD and POPAD
most operations that dealt with segment registers, such as PUSH DS and POP DS. (Operations that use the FS or GS segment registers are still valid.)

The x64 instruction set includes recent additions to the x86, such as SSE 2. Programs compiled for x64 can freely use these instructions.

Data Transfer
The x64 provides new variants of the MOV instruction that can handle 64-bit immediate constants or memory addresses.
MOV r,#n r = #n
MOV rax, m Move contents at 64-bit address to rax.
MOV m, rax Move contents of rax to 64-bit address.
The x64 also provides a new instruction to sign-extend 32-bit operands to 64 bits.
MOVSXD r1, r/m Move DWORD with sign extension to QWORD.
Ordinary MOV operations into 32-bit subregisters automatically zero extend to 64 bits, so there is no MOVZXD instruction.
Two SSE instructions can be used to move 128-bit values (such as GUIDs) from memory to an xmmn register or vice versa.
MOVDQA r1/m, r2/m Move 128-bit aligned value to xmmn register, or vice versa.
MOVDQU r1/m, r2/m Move 128-bit value (not necessarily aligned) to register, or vice versa.

Data Conversion
CDQE Convert dword (eax) to qword (rax).
CQO convert qword (rax) to oword (rdx:rax).

String Manipulation
MOVSQ Move qword from rsi to rdi.
CMPSQ Compare qword at rsi with rdi.
SCASQ Scan qword at rdi. Compares qword at rdi to rax.
LODSQ Load qword from rsi into rax.
STOSQ Store qword to rdi from rax.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Annotated x64 Disassembly

The following very simple function illustrates the x64 calling convention.
int Simple(int i, int j)
{

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 930 of 1651

return i*5 + j + 3;
}
This compiles to code like this:
01001080 lea
01001083 lea
01001087 ret

eax,[rdx+rcx*4]
eax,[rcx+rax+0x3]

; eax = rdx+rcx*4
; eax = rcx+rax+3

The i and j parameters are passed in the ecx and edx registers, respectively. Since there are only two parameters, the routine does not use the stack at all.
The particular code generated exploits three tricks, one of which is specific to the x64:
1. The lea operation can be used to perform a series of simple arithmetic operations as a single operation. The first instruction stores j+i*4 in eax, and the second
instruction adds i+3 to the result, for a total of j+i*5+3.
2. Many operations, such as addition and multiplication, can be done with extra precision, and then truncated to the correct precision. In this instance, the code uses 64-bit
addition and multiplication. We can safely truncate the result to 32 bits.
3. On the x64, any operation that outputs to a 32-bit register automatically zero-extends the result. In this case, outputting to eax has the effect of truncating the result to 32
bits.
Return values are passed in the rax register. In this case, the result is already in the rax register, so the function returns.
Next we consider a more complicated function to demonstrate typical x64 disassembly:
HRESULT Meaningless(IDispatch *pdisp, DISPID dispid, BOOL fUnique, LPCWSTR pszExe)
{
IQueryAssociations *pqa;
HRESULT hr = AssocCreate(CLSID_QueryAssociations, IID_IQueryAssociations, (void**)&pqa);
if (SUCCEEDED(hr)) {
hr = pqa->Init(ASSOCF_INIT_BYEXENAME, pszExe, NULL, NULL);
if (SUCCEEDED(hr)) {
WCHAR wszName[MAX_PATH];
DWORD cchName = MAX_PATH;
hr = pqa->GetString(0, ASSOCSTR_FRIENDLYAPPNAME, NULL, wszName, &cchName);
if (SUCCEEDED(hr)) {
VARIANTARG rgvarg[2] = { 0 };
V_VT(&rgvarg[0]) = VT_BSTR;
V_BSTR(&rgvarg[0]) = SysAllocString(wszName);
if (V_BSTR(&rgvarg[0])) {
DISPPARAMS dp;
LONG lUnique = InterlockedIncrement(&lCounter);
V_VT(&rgvarg[1]) = VT_I4;
V_I4(&rgvarg[1]) = fUnique ? lUnique : 0;
dp.rgvarg = rgvarg;
dp.cArgs = 2;
dp.rgdispidNamedArgs = NULL;
dp.cNamedArgs = 0;
hr = pdisp->Invoke(dispid, IID_NULL, 0, DISPATCH_METHOD, &dp, NULL, NULL, NULL);
VariantClear(&rgvarg[0]);
VariantClear(&rgvarg[1]);
} else {
hr = E_OUTOFMEMORY;
}
}
}
pqa->Release();
}
return hr;
}
We'll go through this function and the equivalent assembly line by line.
When entered, the function's parameters are stored as follows:

rcx = pdisp.
rdx = dispid.
r8 = fUnique.
r9 = pszExe.

Recall that the first four parameters are passed in registers. Since this function has only four registers, none are passed on the stack.
The assembly begins as follows:
Meaningless:
010010e0 push
010010e1 push
010010e2 push
010010e3 push
010010e5 push
010010e7 push
010010e9 push
010010eb sub
010010f2 mov

rbx
rsi
rdi
r12d
r13d
r14d
r15d
rsp,0x2c0
rbx,r9

;
;
;
;
;
;
;
;
;

save
save
save
save
save
save
save
reserve stack
rbx = pszExe

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

010010f5 mov
010010f8 mov
010010fb mov

Page 931 of 1651

r12d,r8d
r13d,edx
rsi,rcx

; r12 = fUnique (zero-extend)

; r13 = dispid (zero-extend)
; rsi = pdisp

The function begins by saving nonvolatile registers, and then reserving stack space for local variables. It then saves parameters in nonvolatile registers. Note that the
destination of the middle two mov instructions is a 32-bit register, so they are implicitly zero-extended to 64 bits.
IQueryAssociations *pqa;
HRESULT hr = AssocCreate(CLSID_QueryAssociations, IID_IQueryAssociations, (void**)&pqa);
The first parameter to AssocCreate is a 128-bit CLSID passed by value. Since this doesn't fit in a 64-bit register, the CLSID is copied to the stack, and a pointer to the stack
location is passed instead.
010010fe
01001106
0100110c
01001111
01001118
0100111d

movdqu xmm0,oword ptr [CLSID_QueryAssociations (01001060)]

movdqu oword ptr [rsp+0x60],xmm0 ; temp buffer for first parameter
lea
r8,[rsp+0x58]
; arg3 = &pqa
lea rdx,[IID_IQueryAssociations (01001070)] ; arg2 = &IID_IQueryAssociations
lea
rcx,[rsp+0x60]
; arg1 = &temporary
call qword ptr [_imp_AssocCreate (01001028)] ; call

The movdqu instruction transfers 128-bits values to and from xmmn registers. In this instance, the assembly code uses it to copy the CLSID to the stack. The pointer to the
CLSID is passed in r8. The other two arguments are passed in rcx and rdx.
if (SUCCEEDED(hr)) {
01001123 test
01001125 jl

eax,eax
ReturnEAX (01001281)

The code checks to see if the return value is a success.

hr = pqa->Init(ASSOCF_INIT_BYEXENAME, pszExe, NULL, NULL);
0100112b
01001130
01001133
01001136
0100113b
0100113e
01001141
01001147
0100114a

mov
mov
xor
mov
xor
mov
mov
mov
call

rcx,[rsp+0x58]
rax,[rcx]
r14d,r14d
[rsp+0x20],r14
r9d,r9d
r8,rbx
r15d,0x2
edx,r15d
qword ptr [rax+0x18]

;
;
;
;
;
;
;
;
;

arg1 = pqa
rax = pqa.vtbl
r14 = 0
arg5 = 0
arg4 = 0
arg3 = pszExe
r15 = 2 (for later)
arg2 = 2 (ASSOCF_INIT_BY_EXENAME)
call Init method

This is an indirect function call using a C++ vtable. The this pointer is passed in rcx as the first parameter. The first three parameters are passed in registers, while the final
parameter is passed on the stack. The function reserves 16 bytes for the parameters passed in registers, so the fifth parameter begins at rsp+0x20.
if (SUCCEEDED(hr)) {
0100114d mov
0100114f test
01001151 jl

ebx,eax
ebx,ebx
ReleasePQA (01001274)

; ebx = hr
; FAILED?
; jump if so

The assembly-language code saves the result in ebx, and checks to see if it's a success code.
WCHAR wszName[MAX_PATH];
DWORD cchName = MAX_PATH;
hr = pqa->GetString(0, ASSOCSTR_FRIENDLYAPPNAME, NULL, wszName, &cchName);
if (SUCCEEDED(hr)) {
01001157
0100115f
01001164
01001167
0100116c
01001171
01001179
0100117e
01001181
01001187
01001189
0100118c
0100118e
01001190

mov
mov
mov
lea
mov
lea
mov
xor
mov
xor
call
mov
test
jl

dword ptr [rsp+0x50],0x104 ; cchName = MAX_PATH

rcx,[rsp+0x58]
; arg1 = pqa
rax,[rcx]
; rax = pqa.vtbl
rdx,[rsp+0x50]
; rdx = &cchName
[rsp+0x28],rdx
; arg6 = cchName
rdx,[rsp+0xb0]
; rdx = &wszName[0]
[rsp+0x20],rdx
; arg5 = &wszName[0]
r9d,r9d
; arg4 = 0
r8d,0x4
; arg3 = 4 (ASSOCSTR_FRIENDLYNAME)
edx,edx
; arg2 = 0
qword ptr [rax+0x20]
; call GetString method
ebx,eax
; ebx = hr
ebx,ebx
; FAILED?
ReleasePQA (01001274) ; jump if so

Once again, we set up the parameters and call a function, then test the return value for success.
VARIANTARG rgvarg[2] = { 0 };
01001196
0100119e
010011a0
010011a5

lea
xor
mov
rep

rdi,[rsp+0x82]
eax,eax
ecx,0x2e
stosb

;
;
;
;

rdi = &rgvarg
rax = 0
rcx = sizeof(rgvarg)
Zero it out

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 932 of 1651

The idiomatic method for zeroing out a buffer on x64 is the same as x86.
V_VT(&rgvarg[0]) = VT_BSTR;
V_BSTR(&rgvarg[0]) = SysAllocString(wszName);
if (V_BSTR(&rgvarg[0])) {
010011a7
010011b1
010011b9
010011bf
010011c7
010011ca

mov
lea
call
mov
test
je

word ptr [rsp+0x80],0x8 ; V_VT(&rgvarg[0]) = VT_BSTR

rcx,[rsp+0xb0]
; arg1 = &wszName[0]
qword ptr [_imp_SysAllocString (01001010)] ; call
[rsp+0x88],rax
; V_BSTR(&rgvarg[0]) = result
rax,rax
; anything allocated?
OutOfMemory (0100126f) ; jump if failed
DISPPARAMS dp;
LONG lUnique = InterlockedIncrement(&lCounter);

010011d0
010011d7
010011dc
010011e0

lea
mov
lock
add

rax,[lCounter (01002000)]
ecx,0x1
xadd [rax],ecx
ecx,0x1

; interlocked exchange and add

InterlockedIncrement compiles directly to machine code. The lock xadd instruction performs an atomic exchange and add. The final result is stored in ecx.
V_VT(&rgvarg[1]) = VT_I4;
V_I4(&rgvarg[1]) = fUnique ? lUnique : 0;
010011e3
010011ed
010011f0
010011f3
010011f6

mov
mov
test
cmovne
mov

word ptr [rsp+0x98],0x3

eax,r14d
r12d,r12d
eax,ecx
[rsp+0xa0],eax

;
;
;
;
;

V_VT(&rgvarg[1]) = VT_I4;
rax = 0 (r14d is still zero)
fUnique set?
if so, then set rax=lCounter
V_I4(&rgvarg[1]) = ...

Since x64 supports the cmov instruction, the ?: construct can be compiled without using a jump.
dp.rgvarg = rgvarg;
dp.cArgs = 2;
dp.rgdispidNamedArgs = NULL;
dp.cNamedArgs = 0;
010011fd
01001205
0100120a
0100120f
01001214

lea
mov
mov
mov
mov

rax,[rsp+0x80]
[rsp+0x60],rax
[rsp+0x70],r15d
[rsp+0x68],r14
[rsp+0x74],r14d

;
;
;
;
;

rax = &rgvarg[0]
dp.rgvarg = rgvarg
dp.cArgs = 2 (r15 is still 2)
dp.rgdispidNamedArgs = NULL
dp.cNamedArgs = 0

This code initializes the rest of the members of DISPPARAMS. Note that the compiler reuses the space on the stack previously used by the CLSID.
hr = pdisp->Invoke(dispid, IID_NULL, 0, DISPATCH_METHOD, &dp, NULL, NULL, NULL);
01001219
0100121c
01001221
01001226
0100122b
01001230
01001235
0100123c
0100123f
01001246
01001249
0100124c
0100124f

mov
mov
mov
mov
lea
mov
mov
xor
lea
mov
mov
call
mov

rax,[rsi]
[rsp+0x40],r14
[rsp+0x38],r14
[rsp+0x30],r14
rcx,[rsp+0x60]
[rsp+0x28],rcx
word ptr [rsp+0x20],0x1
r9d,r9d
r8,[GUID_NULL (01001080)]
edx,r13d
rcx,rsi
qword ptr [rax+0x30]
ebx,eax

;
;
;
;
;
;
;
;
;
;
;
;
;

rax = pdisp.vtbl
arg9 = 0
arg8 = 0
arg7 = 0
rcx = &dp
arg6 = &dp
arg5 = 1 (DISPATCH_METHOD)
arg4 = 0
arg3 = &IID_NULL
arg2 = dispid
arg1 = pdisp
call Invoke method
hr = result

The code then sets up the parameters and calls the Invoke method.
VariantClear(&rgvarg[0]);
VariantClear(&rgvarg[1]);
01001251
01001259
0100125f
01001267
0100126d

lea
call
lea
call
jmp

rcx,[rsp+0x80]
;
qword ptr [_imp_VariantClear
rcx,[rsp+0x98]
;
qword ptr [_imp_VariantClear
ReleasePQA (01001274)

arg1 = &rgvarg[0]
(01001018)]
arg1 = &rgvarg[1]
(01001018)]

The code finishes up the current branch of the conditional, and skips over the else branch.
} else {
hr = E_OUTOFMEMORY;
}
}

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 933 of 1651

OutOfMemory:
0100126f mov
ebx,0x8007000e
pqa->Release();
ReleasePQA:
01001274 mov
rcx,[rsp+0x58]
01001279 mov
rax,[rcx]
0100127c call
qword ptr [rax+0x10]

; hr = E_OUTOFMEMORY

; arg1 = pqa
; rax = pqa.vtbl
; release

The else branch.

return hr;
}
0100127f mov
ReturnEAX:
01001281 add
01001288 pop
0100128a pop
0100128c pop
0100128e pop
01001290 pop
01001291 pop
01001292 pop
01001293 ret

eax,ebx

; rax = hr (for return value)

rsp,0x2c0
r15d
r14d
r13d
r12d
rdi
rsi
rbx

;
;
;
;
;
;
;
;
;

clean up the stack

restore
restore
restore
restore
restore
restore
restore
return (do not pop arguments)

The return value is stored in rax, and then the non-volatile registers are restored before returning.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The Itanium Processor

This section includes:
Itanium Architecture
Itanium Instructions
Annotated Itanium Disassembly
Note In certain Windows environment variables and debugger output, the Intel Itanium processor is referred to as "the IA-64 processor."
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Itanium Architecture
The Intel Itanium processor has several features that do not appear on the x86 processor:

Explicit Parallel Instruction Computation (EPIC).

A large number of registers. (Doing as much as possible in registers gets you better performance.)
Dedicated register usage (integer registers, branch registers, floating-point registers).
Conditional execution (predication) on almost all instructions.
Modulo scheduling for software pipelining.

Registers
The Itanium has a large number of registers.

128 integer registers, each with a NaT bit (r0 - r127)

128 floating-point registers (f0 - f127)
64 predicate registers (p0 - p63)
8 branch registers (b0 - b7)
An instruction pointer (the debugger calls this iip)
128 other special-purpose registers (not all of which have yet been given meanings). These are called the "application register set," or "ar" registers. (They are not
covered in this documentation.)
A number of miscellaneous registers, not covered in this documentation.

Many of the registers are further subdivided into categories such as static, stacked, and rotating.
When discussing register preservation conventions, the term preserved refers to a register whose value must be preserved by a function, and scratch refers to a register whose

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 934 of 1651

value can be modified by a function.

When using the ? (Evaluate Expression) command, registers should be prefixed with an "at" sign ( @ ). For example, you should use ? @f0 rather than ? f0. This ensures
that the debugger recognizes f0 as a register, rather than as a hexadecimal number or a symbol.
However, the "at" sign is not required in the r (Registers) command. For instance, r r32 = 5 will always be interpreted correctly.

Integer Registers
The 128 integer registers are named r0 through r127 and break down as follows:
r0 r31 Static general registers
r32 r127 Stacked general registers
Some of the registers have special meaning, most of which are assigned by convention rather than hardware requirement. (The only one that is a hardware requirement is r0.)
r0
Reads as zero (writing will AV)
gp
Global pointer (r1)
ret0 ret3 Function return values go here (r8 through r11).
sp
Stack pointer (r12)
r13
TEB
By convention, registers r4 through r7 are preserved. You also should not change the TEB pointer.
The gp register points to your global variables. To access a global variable, you have to indirect OFF the gp register. The gp register is kept up-to-date when you jump from
one DLL to another (by means described later).
The other static registers are scratch.
All integer registers are 64 bits, with a magic NaT bit attached to each one. NaT stands for "not a thing" and is used by speculative execution to indicate that the register
values are undefined.
The static integer registers do not participate in register stacking. The behavior of the stacked registers (including their preservation rules) will be described in Procedure Calls
and the Register Stack subsection of this section.
The return value registers hold function return values and therefore can be destroyed across a function call. Notice that there are four integer return value registers at 64 bits
each, for a total of 256 bits or 32 bytes of data that can be returned from a function (twice the size of a GUID).

Floating-Point Registers
f0
Reads as 0.0 (writing to it will cause an access violation).
f1
Reads as 1.0 (writing to it will cause an access violation).
f2 f31 Static floating-point registers.
f32 f127 Rotating floating-point registers
This document does not discuss floating-point code.
By convention, floating-point registers f2 through f5 and f16 through f31 are preserved across calls; the rest are scratch.

Predicate Registers
pr0
Reads as TRUE (writes are ignored).
pr1 pr15 Static predicate registers.
pr16 pr63 Rotating predicate registers.
Predicate registers act as flags. They record the result of comparison instructions, and you can test them later to perform some sort of conditional action (called "predication").
You can predicate almost any instruction, not just jump instructions. For example,
(p1)

add

ret0 = r32, r33

instruction means "set register ret0 equal to register r32 plus register r33 if register p1 is TRUE; otherwise, do nothing." Allowing arbitrary predication helps performance
significantly: You have fewer jump instructions and therefore less misprediction You can also pack your instructions more compactly, because jump targets must begin on a
bundle boundary, but predicated instructions can go anywhere.
The parenthesized predicate register is called the qualifying predicate (abbreviated as "qp"). Because predicate register zero is always TRUE, unconditional instructions are
internally encoded as conditional on p0.
By convention, predicate registers pr6 through pr15 are scratch; the rest are preserved.
There is a special pseudo-register called pr (called preds by the debugger) that consists of the 64 predicate registers combined to form a single 64-bit value. This lets you read
and write all the predicate registers so you can preserve them across a call.

Branch Registers
The branch registers b0 through b7 are used for computed jump instructions. These are dedicated to computed jumps so the processor can optimize more efficiently for them.
By convention, the following meanings are assigned to the branch registers.
br

Return address (b0)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 935 of 1651

b1 b5 Preserved across procedure calls

b6 b7 Scratch

Application Registers
Of the application registers, ar.unat and ar.lc must be preserved across calls.

Procedure Calls and the Register Stack

Each procedure declares how many parameters it has (input registers), how many private registers it needs (local registers), and the maximum number of parameters of any
function it calls (output registers). The input registers plus the local registers together are called the "local region." The input registers plus the local registers plus the output
registers together are called the "register stack frame".
For example, this function
int sampleFunction(int a, int b)
{
int c;
c = someFunction(0) + otherFunction(a, b);
return c;
}
would specify two input registers, some number of local registers, and two output registers.
When control enters a procedure, the alloc instruction shuffles the registers around.
Suppose the calling function uses five local registers (r32 through r36) and it wants to execute a sampleFunction(3,4).
Before calling the function, the registers would be arranged like this:
static
local rgn
output
r0
...
r31 r32
r36 r37 r38 r39 ...
+--------------+-----------+-------+------------| 0
...
aaa|bbb ... ccc| 3
4|??? ...
+--------------+-----------+-------+------------Registers r37 and r38 are the output registers and contain the parameters to the function.
When sampleFunction gets control, it executes an alloc instruction.
alloc

r34 = ar.pfs, 2, 2, 2, 0

Essentially, this means: Set up the register stack frame as follows: 2 input registers, 2 local register, 2 output registers, and zero rotating registers. Save the previous register
frame state (pfs) in register r34 so it can be restored later.
This instruction shuffles the registers like this:
static
local rgn
output
r0
...
r31 r32 r33 r34 r35 r36 r37 ...
+--------------+---------------+-------+---------| 0
...
aaa| 3
4 pfs ???|??? ???|...
+--------------+---------------+-------+---------The static registers did not change. What used to be the output registers are now the input registers; the local registers are uninitialized (except for register r34, which was
explicitly set to ar.pfs by the first parameter of the alloc instruction). What used to be in the local variables got pushed onto the register stack; they are not accessible to the
called function.
Note The distinction between input and local registers is purely semantic. It makes no difference for the processor. The only important thing to the encoding of the instruction
is the size of the local region, so when you read the instruction in disassembly, the first number is the size of the local region and the second number is always zero. Thus, the
preceding alloc instruction will be disassembled as
alloc r34 = ar.pfs, 4, 0, 2, 0
Note In reality, this register shuffling process happens in two stages. The br.call instruction is the one that renumbers the registers. The alloc instruction is the one that
describes the layout of the registers on the receiving side. However,in simple cases, you can act as if the alloc instruction does it all. In complicated situations, you may want
to execute multiple alloc instructions to reinterpret all your registers.
The called function now performs its operation, maybe calls some other functions, and then when it is ready to return, the registers look like this:
static
local rgn
output
r0...ret0..r31 r32 r33 r34 r35 r36 r37 ...
+--------------+---------------+-------+---------| 0...rrr...aaa|xxx yyy zzz www|??? ???|...
+--------------+---------------+-------+---------It has placed the function return value (rrr) into the ret0 register. All the registers in the local region contain whatever values are left over from the computation.
When control returns to the calling function, the register stack is popped and the registers look like this:
static
local rgn
output
r0...ret0..r31 r32
r36 r37 r38 r39 ...

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 936 of 1651

+--------------+-----------+-------+------------| 0...rrr...aaa|bbb ... ccc|??? ???|??? ...

+--------------+-----------+-------+------------All the old registers in the local region are restored from the register stack, and the return value is now available in the ret0 register. Note that the values in the output registers
have returned to garbage. You cannot rely on the values of output registers being preserved across a call.
The hardware supports any number of output registers, but by convention, only the first eight are used to contain function parameters. Parameters beyond eight are passed on
the stack.
The register stack is itself limited in size. If you push too many registers onto the register stack, it spills into regular memory.

The gp Register
The gp register is used to access global variables in your module. The rules for its management are complicated:

On entry to a function, gp is assumed to be properly initialized.

When you call a function within your module, gp must be properly initialized.
When you call a function outside your module, the gp register can be destroyed on return.
When you return from a function, gp must contain the value it did when your function started.

These rules allow for the following procedure call paradigms:

Call to function in same module: Simply call it, there is no need to use gp. The gp register will still be valid on return.
Call to function in other module: Set up gp appropriate for the module you are calling, then restore it after the function returns.

So how do you set up gp for the target? A function pointer on the Itanium is really a pointer to a block of data that describes the target function. One of the items in that block
of data is the value of gp that the target function expects.
Return to the sampleFunction example. Assume this is an exported function. In this case, the code to call it would be:
mov
mov
addl
ld8
ld8
ld8
mov
br.call
mov

r37 = 3
r38 = 4
r31 = 0x108, gp;;
r30 = [r31];;
r41 = [r30], 8;;
gp = [r30]
b6 = r41
rp = b6;;
gp = ...

// set up the function parameters

//
//
//
//
//
//
//

r31 -> import table entry

r30 -> sampleFunction descriptor
r41 = actual address of function
set up gp for sampleFunction
set up the branch register
call the function
restore gp to original value

This means that if you try to disassemble at sampleFunction, you will end up just looking at the function descriptor rather than the function itself. The function itself begins
with a dot, so if you want to see the code for sampleFunction you have to type u .sampleFunction.

Debugger Register Dump

dbi0
dbi2
dbi4
dbi6
dbd0
dbd2
dbd4
dbd6

=
=
=
=
=
=
=
=

0
0
0
0
0
0
0
0

gp
r3
r5
r7
r9
r11
r13
r15
r17
r19
r21
r23
r25
r27
r29
r31

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

77560000
c000000000000309
1010aa0
0
ffffffffffffffff
ffffffff
6fbfffdc000
0
e0000165e11ae910
0
e000000086b8ee20
1
2f
6
6fbff
0

preds =

8941

dbi1
dbi3
dbi5
dbi7
dbd1
dbd3
dbd5
dbd7
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

r2
r4
r6
r8
r10
sp
r14
r16
r18
r20
r22
r24
r26
r28
r30
intnats

=
=
=
=
=
=
=
=

0
0
0
0
0
0
0
0

=
6fbffc90bf0 0
=
78190000 0
=
6fbfffde000 0
=
6fbffe8d948 0
=
0 0
=
6fbffe8d520 0
=
6fbffc90be8 0
= e0000165e11ae7f0 0
=
6fbffc90bec 0
=
9804c8a70033f 0
= e000000086b96040 0
=
7f05 0
=
14e 0
=
6fb000006fb 0
=
103 0
=
0

b0
b2
b4
b6

=
=
=
=

772b43b0
766e9e88
0
772ba2e0

b1
b3
b5
b7

= e0000000ffa005c0
=
0
=
0
=
0

unat
ec
dcr
bsp

=
=
=
=

0
0
7f05
6fbffe90cc8

lc
ccv
pfs
bspstore

=
0
= e000000086c577b0
= c000000000000309
=
6fbffe90cc8

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

rsc
ipsr
ifs
eflag
ssd
fsr
fdr

Page 937 of 1651

=
f
=
1013082a6018
= 8000000000000204
=
202
= cf3fffff00000000
=
0
=
0

r32 =
r34 =

rnat
iip
fcr
csd
cflag
fir

6fbffe8d948 0
104 0

=
0
=
772b4310
=
40
= cfbfffff00000000
=
111
=
0

r33 =
r35 =

6fb000006fb 0
8941 0

At the top of this display are eight instruction debug registers (dbi) and eight data debug registers (dbd).
Next come the static integer registers, followed by intnats, which consists of all the NaT bits combined to form a 32-bit integer.
Then preds, which is all the predicate registers combined into a 64-bit integer.
Next are all the branch registers.
Then there are several special-purpose registers. Of these, the following two are probably the only ones you will need to deal with:

ar.pfs describes the stack frame of the previous function.

ar.ccv is an implicit parameter for the cmpxchg instruction.

Finally shown are the registers for the current register stack frame. You happen to be in a function that has four registers in its frame, so the debugger showed the first four
stacked registers, r32 through r35. If the function used more registers, this part would have been larger.

Notation
x
1 (byte), 2 (word), 4 (long) or 8 (quad)
Ra, Rb, Rc... Registers
Signed n-bit constant
immn
Rb/immn

Ba/addr
cc
Rb<n1, n2>
f

Branch register or an address

Condition (such as eq or ne)
n2 bits from Rb starting at position n1.
Floating-point type (s, d, e)

For example, Rb<5, 4> means "extract 4 bits from Rb starting at position 5," which is the value (Rb >> 5) & 0x0F.
Many instructions can be modified by suffixes called completers.

Addressing Modes
Unlike the x86 instruction set, which has a significant number of addressing modes, the Itanium instruction set has only one addressing mode: Register indirect. The notation
for register indirect is "[r]" which means "the value stored at memory location r." The thing inside the brackets is always a register.

Instruction Format and Pipelining

Instructions are packaged into groups of three called bundles. If you execute an .asm verbose command, the instructions that belong to a bundle will be surrounded by curly
brackets. Bundles always start on 16-byte boundaries (in other words, the last digit of the hexadecimal address is zero).
You cannot jump into the middle of a bundle.
There are restrictions on what type of instruction can be put into a particular slot in a bundle. For example, one valid bundle type is MII, which means that slot 0 (zero) is a
memory access, slot 1 is an integer instruction, and slot 2 is another integer instruction.
Valid instruction types are:

M - Memory/Move instruction
I - Complex Integer/Multimedia instruction
A - Simple Integer/Logic/Multimedia instruction
F - Floating-Point instruction (Normal/SIMD)
B - Branch instruction

Many instructions can be used in multiple slot types, in which case a completer is specified to disambiguate them. For example, there are five different nop instructions
(nop.m, nop.i, nop.f, nop.b, nop.x) depending on which type of slot it was placed into.
Each valid combination of instruction categories is called a template. There are 32 different templates. Some of the templates differ only in the placement of stops.
A stop is used to indicate that instructions after the stop depend on instructions before the stop. For example, if you have the following series of instructions
mov r3 = r2
add r1 = r2,r4 ;;
add r2 = r1,r3
there is no dependency between the first two instructions, but the third instruction cannot execute until after the first two have completed. Therefore, the compiler inserts a
stop, represented by a double semicolon, after the second instruction.
Note that a stop does not have to go at the end of a bundle. There are some bundle templates that have stops in the middle and some that have more than one stop. For

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 938 of 1651

example, template 11 is an M|MI| instruction. Slot 0 (zero) is a memory access, then there is a stop after slot 0 (zero), then slot 1 is another memory access, then slot 2 is an
integer instruction, then there is another stop after slot 2.
An instruction group is a sequence of instructions up to the next stop, taken branch, interrupt, or exception. The instructions within an instruction group cannot have
dependencies among them. This allows the processor to execute them in parallel.
There are some exceptions to the no dependencies rule.

A branch instruction is allowed to depend on a predicate register and branch register set elsewhere in the group.
You can use the result of a successful ld.c without an intervening stop.
Instructions after a branch will implicitly depend on whether the branch was taken; this is acceptable. However, instructions after a branch cannot interfere with
instructions before the branch.
Comparison instructions .and, .andcm, .or and .orcm are allowed to combine with others of the same type into the same target registers. (This means you cannot
combine an .and with an .or.)
You are allowed to write to a register after a previous instruction reads it, with rare exceptions.
Two instructions in the group cannot both write to the same register, with the exception of combined comparison instructions as already noted.

This description omits a number of details that are important only to compiler-writers or people hand-writing Itanium assembly. When reading disassembly, you can assume
that the compiler or author generated correct code, unless you are tracking a compiler bug.

Speculative Execution
The ld instruction (load from memory) supports an .s completer, which means that execution of the instruction is speculated. (You cannot speculatively write to memory.)
An instruction that can be speculated is called a speculative instruction, rather than a speculatable instruction. Consequently, this documentation will use the word
"speculated" to refer to the .s variant of the ld instruction.
A speculated load is just like a regular load, except that if an exception occurs, the processor sets the NaT bit in the destination register instead of raising the exception.
If any input to an integer computation instruction has the NaT bit set, then the result of the computation will also have the NaT bit set. If any input to a comparison instruction
has the NaT bit set, then the result of the comparison is always FALSE.
You can also speculate floating-point instructions, but instead of setting the NaT bit, the entire floating-point register is set to a special NaT-like value called NaTVal. As with
the integer case, NaTVal infects all subsequent computations.
Perhaps you realize that the speculated execution was not necessary. (Maybe you started going down the TRUE branch of an IF statement, only to discover that the value is
FALSE.) In which case, you just ignore the registers that you changed with the speculated execution and continue on your way. (Don't look at them, of course, because they
might be NaT.)
If you decide that the speculated execution was worthwhile, execute a chk.s instruction, which means "verify that this register contains an actual value. If it is a NaT, then
jump to the recovery code." The recovery code typically just consists of all the speculated instructions re-executed normally, so the exception can be raised.
Aside from the instructions previously mentioned, which can handle NaTs and a few other special instructions, attempting to use the value of a NaT register will cause an
exception. This is not useful in general because you cannot tell which speculated instruction caused the exception.

Advanced Loads
The Itanium contains special techniques to optimize in the face of aliased pointers. For example, consider this code snippet:
int MyNewFcn(int *p1, int *p2)
{
*p1 = 1;
*p2 = 2;
return *p1;
}
This function usually returns 1, but if p1 and p2 both point to the same address, then it will return 2.
The advanced load instruction ld.a means "load this value from memory and remember the access as successful." If there is a subsequent write to that address, it is removed
from the list, rendering the advance load unsucessful. (Other events can remove an entry from the list; for example, if you ask it to remember too many advanced loads, it
starts forgetting the older ones.)
Later on, you can check whether the advance load is still valid. If it is not, it means that the value was modified and you have to reload it.
There are two types of checks. The simplest check is ld.c.nc or ld.c.clr. This says, "Check if that advanced load is still valid. If not, then reload the value." The .clr completer
means that this advanced load is not important anymore, so the processor can free up the entry for recording new advanced loads; the .nc completer means that this advanced
load is still valuable, so do not clear it from the table.
Here is an example that uses ld.c.clr.
ld8.a
r6 = [r8]
...
ld8.c.clr r6 = [r8]
...

;;

//
//
//
//

read memory at r8, remember the address

perform operation that might modify memory...
reload r6 from [r8] if necessary
perform operations with the value in r6

In order to avoid a stall, the compiler requested that register r6 be loaded from the memory address specified by register r8 in advance of when it actually needed the result.
Then, the compiler wanted to use the value in r6, but had not determined if, in the meantime, some pointer dereference had modified the value, thus rendering the prefetched
value in r6 useless.
The ld8.c.clr instruction checks if anything has written to that address (even on another processor). If not, then the instruction does nothing. However, if something has indeed
written to the address, then the instruction refetches the value (taking the memory stall).
The second type of check is if you need more complicated recovery than just reloading the value.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 939 of 1651

Here is an example that uses chk.a.clr.

ld8.a
r6 = [r8]
add
r5 = r6, r7
...
chk.a.clr r6, failed
continue:
...
failed:
ld8
add
br

r6 = [r8]
r5 = r6, r7
continue

;;
;;

//
//
//
//

read memory at r8, remember the address

precompute based on advanced read
perform operations that might modify memory...
memory was modified

// perform operations with the value in r5

;;

// load the correct value

// redo the precomputation
// and then continue as if nothing was wrong

After doing some precomputation with the value you read from r8, you execute a chk.a.clr instruction, which checks if your advanced load is still valid. If not, you jump to
failed, where you reload the value and redo the precomputation, then jump back to continue normal execution.

Speculated Advanced Loads

You can combine the preceding two techniques. The ld.sa instruction performs a speculated advance load.

Register Rotation
Register rotation is an advanced technique where the registers renumber themselves each time they go through a loop. It is not covered in this documentation.

Control Flow
The types of control flow you will see most of the time are jump (br.cond), call (br.call), and return (br.ret). (Conditional jumps are just regular jump instructions with a
qualifying predicate attached in front.)
The jump and call instructions also have long versions (brl) if the target of the jump is really far away.
The brl instruction is actually emulated on Itanium, so do not expect it to be fast.

Branch Prediction
Each of the standard jump instructions also includes a group of completers. The first completer determines whether the jump should be predicted taken or not taken.

.spnt: Static predict not taken. Always predict not taken.

.sptk: Static predict taken. Always predict taken.
.dpnt: Dynamic predict not taken. Use the prediction hardware. If prediction hardware cannot tell, then predict not taken.
.dptk: Dynamic predict taken. Use the prediction hardware. If prediction hardware cannot tell, then predict taken.

Prediction hardware might not be able to tell, because this instruction was never encountered before, or it was last encountered so long ago that it fell out of the cache.
The second completer specifies how aggressively you should prefetch after the cache. In other words, how sure are you that the prediction is correct.

.few: Prefetch a few instructions. Your prediction could be wrong, or it is not worth prefetching.
.many: Prefetch several instructions. You are confident that your prediction is correct.

Most jumps within a procedure will be marked .few, whereas unconditional subroutine calls and unconditional return instructions are usually marked .many.
Finally, there is an optional completer.

.clr: Clear this entry.

If you clear the entry, the processor will wipe out any knowledge of this jump instruction. Do this if you know the instruction will not be encountered again for a long time.
There is also a bonus instruction brp whose sole purpose is to indicate to the processor: "That computed jump instruction ahead is going to jump to here."

Comparisons
In its simplest form, the comparison instruction compares two values and stores the result into two predicate registers; one gets the the result of the comparison, and the other
gets the opposite of the result. For example,
cmp.eq

p1, p2 = r32, r33

compares the two registers for equality and stores the result into p1. Meanwhile, the p2 register gets the opposite value. For example, if they were equal, then p1 would be
TRUE and p2 would be FALSE.
The next most complicated comparison instruction is called the unconditional comparison and it is always used with a qualifying predicate. Here is a sample unconditional
comparison:
(p3)

cmp.eq.unc p1, p2 = r32, r33

If the qualifying predicate p3 is TRUE, then this acts just like a regular comparison instruction. However, if the qualifying predicate is FALSE, then both the p1 and p2
registers are set to FALSE. This is a rare case where a qualifying predicate has an effect even though it is FALSE. (Normally, if a qualifying predicate is FALSE, the entire
instruction is ignored.)
The next most complicated comparisons are the parallel comparisons. These are used when you have a chain of "a && b && c" or "a || b || c" results. Here is a sample AND
parallel comparison:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 940 of 1651

cmp.eq.and p1, p2 = r32, r33

This is expressible in C as
p1 = p1 && (r32 == r33)
p2 = p2 && (r32 == r33)
In other words, if the comparison is false, then both predicate registers are set to FALSE; otherwise, they are left alone.
The other variations of parallel comparisons are:
cmp.eq.andcm p1, p2 = r32, r33
p1 = p1 && !(r32 == r33)
p2 = p2 && !(r32 == r33)
cmp.eq.or p1, p2 = r32, r33
p1 = p1 || (r32 == r33)
p2 = p2 || (r32 == r33)
cmp.eq.orcm p1, p2 = r32, r33
p1 = p1 || !(r32 == r33)
p2 = p2 || !(r32 == r33)
and the DeMorgan operators...
cmp.eq.or.andcm p1, p2 = r32, r33
p1 = p1 || (r32 == r33)
p2 = p2 && !(r32 == r33)
cmp.eq.and.orcm p1, p2 = r32, r33
p1 = p1 && (r32 == r33)
p2 = p2 || !(r32 == r33)
For example, the expression p5 = (r4 == 0) || (r5 == r6) can be computed as follows (assuming that p5 is preinitialized to FALSE):
cmp.eq.or
cmp.eq.or

p5, p0 = r0, r4
p5, p0 = r5, r6

Notice that because these are both OR type comparisons, they can be combined into a single instruction group and, therefore, executed in parallel.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Itanium Instructions
Only the instructions most likely to be encountered in user-mode code are detailed here. Instructions marked with an asterisk (*) are particularly important.
The general notation for instructions is:
(qp)

op...

dest = src1, src2, ...

where (qp) is the optional qualifying predicate, the ellipses (...) after the opcode are optional completers, dest is the destination (or destinations, for comparison operators),
and src is the source.

Memory Access (Aligned)

* ldx Ra = [Rb]
Load from memory (zero-extended).
* ldx Ra = [Rb], Rc/imm9 Load with postincrement.
An optional parameter after the comma performs a postincrement of the Rb register. For example, ld8 r1 = [r2], 8 loads a 64-bit value from the address in r2 and then
increments the r2 register by 8.
An optional .nt# completer spcifies that the memory will not be accessed again for a while. Higher values of # indicate longer-term abandonment. (.nta is the most aggressive
level.)
* stx [Ra] = Rb
Store to memory.
* stx [Ra] = Rb, imm9 Store with postincrement.
Again, an optional parameter after the comma performs a postincrement of the address register.
* ldff Ra = [Rb]

Load from memory (zero-extended).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 941 of 1651

* ldff Ra = [Rb], Rc/imm9 Load with postincrement.

* stff [Ra] = Rb
* stff [Ra] = Rb, imm9

Store to memory.
Store with postincrement.

And again for floating-point registers.

Memory Access (Advanced/Speculated)

ldx.s Ra = [Rb] Load speculated.
ldx.a Ra = [Rb] Load advanced.
ldx.sa Ra = [Rb] Load speculated advanced.
These were previously discussed.
st.spill... [Rb] = Ra Save a speculated value.
ld.fill... Ra = [Rb] Restore a speculated value.
Read and write a value that might have the NaT bit set. The numerical value is written as usual, and the NaT bit is saved/restored in the ar.unat special register. These allow
you to speculate across procedure calls.
lfetch... ... Cache line prefetch.

Verifying Speculated/Advanced Instructions

ldx.c.clr Ra = [Rb] Check (or reload) and clear.
ldx.c.nc Ra = [Rb] Check (or reload), no clear.
chk.a.clr Ra = [Rb] Check (or jump) and clear.
chk.a.nc Ra = [Rb] Check (or jump), no clear.
Clearing an advanced load means that you have no plans to check the load again.

Special Registers
mov Ra = S Read from special register.
mov S = Ra Write to special register.
Special registers, in general, can only be read from and written to. They do not take part in arithmetic computations and cannot be compared against directly.
mov pr = Ra, mask Write to predicate registers.
The mask specifies which predicate registers should be loaded from register Ra. The bottom bit of the mask corresponds to predicate register p1, through bit 14 of the mask
corresponding to predicate register p15. Bit 15 of the mask represents all the predicate registers p16 through p63. (Recall that predicate register zero is hard-wired to TRUE.)
Recall that the predicate register preservation rules are established by convention, so the only masks you are likely to see are -1 (restore all registers) and 0x801F (preserve all
the usual registers).

Interlocked Instructions
xchgx... Ra = [Rb], Rc Interlocked exchange
Store Rc to [Rb] and return the original value in Ra.
cmpxchgx... Ra = [Rb], Rc, ar.ccv Conditional exchange
Check if the value in [Rb] is equal to the special ar.ccv register. If so, store Rc to [Rb]; otherwise, leave it unchanged. In either case, return the original value of [Rb] in Ra.
fetchaddx... Ra = [Rb], Rc/n Interlocked add
Atomically adds Rc/n to [Rb], returning the previous value in Ra.

Control Flow
* br.cond... Ba/addr Branch
* br.call... Ba/addr Call
* br.ret... Ba/addr Return
See the Control Flow section in Itanium Architecture for a description of the various completers.
There are other types of branch instructions as well, but these are not used as much.

Arithmetic
* add Ra = Rb,Rc
Ra = Rb + Rc
* add Ra = Rb,Rc,1 Ra = Rb + Rc + 1
* adds Ra = imm14,Rb Ra = imm14 + Rb

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 942 of 1651

* addl Ra = imm22,Rb Ra = imm22 + Rb

* subx Ra = Rb/n,Rc Ra = Rb/n - Rc
* subx Ra = Rb,Rc,1 Ra = Rb - Rc - 1
shladd Ra = Rb,n,Rc Ra = (Rb SHL n) + Rc
This shifts the first addend left by up to four positions before adding.
Note There is no integer division or multiplication. See the Multiplication subsection in this section for a multiplication workaround. For division, you will have to convert to
floating point.

Multiplication
There is a special floating-point format for handling integer multiplication.
* setf.sig Fa = Rb
Fa = Rb (special form)
* getf.sig Ra = Fb
Ra = Fb (special form)
* xma... Fa = Fb, Fc, Fd Fa = Fb * Fc + Fd (special form)
The setf.sig and getf.sig instructions transfer between integer registers and floating-point registers (in the special form).
The xma instruction performs the operation on numbers in special form, and the result is also in special form.
There are four variations on the xma instruction. The .l version saves the low 64 bits of the result, the .h version saves the high 64 bits of the result, and the .u version
performs an unsigned multiplication, rather than a signed multiplication.
For example, xma.lu performs the multiplication as two unsigned integers and saves the low 64 bits of the result.

Bits
* and

Ra = Rb/imm8,Rc Ra = Rb/imm8 and Rc

* or

Ra = Rb/imm8,Rc Ra = Rb/imm8 or Rc

* andcm Ra = Rb/imm8,Rc Ra = Rb/imm8 and not Rc

* xor

Ra = Rb/imm8,Rc Ra = Rb/imm8 xor Rc

The andcm instruction clears the bits specified by the last parameter.
* shl Ra = Rb,Rc/n Ra = Rb SHL Rc/n
* shr Ra = Rb,Rc/n Ra = Rb SAR Rc/n
* shr.u Ra = Rb,Rc/n Ra = Rb SHR Rc/n
The shx instructions do shifting. A more general form of shifting is performed by the extr and dep instructions.
* extr Ra = Rb, n1, n2 Ra = Rb<n1, n2>
* extr.u Ra = Rb, n1, n2 Ra = Rb<n1, n2>
The regular version of the extr (extract) instruction sign-extends the result, whereas the extr.u form zero-extends the result. The bit extraction instructions are also used to
handle unaligned data.
* dep Ra = Rb, Rc, n1, n2 Ra<n1, n2> = Rb;
other bits come from Rc
The dep (deposit) instruction builds its output by taking the <n1, n2> part from Rb and the rest of Rc. Think of it as a masked blt.
* shrp Ra = Rb, Rc, n Ra = (Rb:Rc)<n, 64>
The shrp (shift right pair) instruction treats Rb and Rc as a huge 128-bit value and extracts 64 bits of it into the Ra register.

Constants
* movl Ra = n Load 64-bit number.
Small numbers (up to 22 bits) can be loaded using add Ra = n, r0 instruction. Larger numbers require the movl instruction. This is one of the few instructions that takes up
two slots.

Comparisons
* cmp.cc p1, p2 = Ra, Rb Compare 64-bit values.
* cmp4.cc p1, p2 = Ra, Rb Compare 32-bit values.
See Comparisons section in Itanium Architecture for a detailed explanation.
* tbit p1, p2 = Ra, n Test bit
The tbit instruction tests bit n in register Ra, setting both p1 and p2 accordingly.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 943 of 1651

Bit and Bytes

popcnt Ra = Rb Ra = number of set bits in Rb
czx1.l Ra = Rb Ra = position of lowest zero byte
czx2.l Ra = Rb Ra = position of lowest zero word
czx1.r Ra = Rb Ra = position of highest zero byte
czx2.r Ra = Rb Ra = position of highest zero word
If there is no zero byte or word, the czx instruction sets the Ra register to 8 (czx1) or 4 (czx2).

Conversion
* sxtx Ra = Rb sign-extend Rb to Ra
* zxtx Ra = Rb zero-extend Rb to Ra

Idioms
* add
* add
* add
* sub
* subx
* xor
shrp

Ra = r0, n
mov Ra = n
Ra = r0, Rb
mov Ra = Rb
Ra = Rb, r0, 1 inc Ra = Rb
Ra = Rb, r0, 1 dec Ra = Rb
Ra = r0, Rb
negx Ra = Rb
Ra = -1, Rb
not Ra = Rb
Ra = Rb, Rb, n rotl Ra = Rb, n

You can rotate by doing a paired shift where the two input registers are the same.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Annotated Itanium Disassembly

Source Code
The following is the code for the function that will be analyzed.
HRESULT CUserView::CloseView(void)
{
if (m_fDestroyed) return S_OK;
BOOL fViewObjectChanged = FALSE;
ReleaseAndNull(&m_pdtgt);
if (m_psv) {
m_psb->EnableModelessSB(FALSE);
if (m_pws) m_pws->ViewReleased();
IShellView* psv;
HWND hwndCapture = GetCapture();
if (hwndCapture && hwndCapture == m_hwnd) {
SendMessage(m_hwnd, WM_CANCELMODE, 0, 0);
}
m_fHandsOff = TRUE;
m_fRecursing = TRUE;
NotifyClients(m_psv, NOTIFY_CLOSING);
m_fRecursing = FALSE;
m_psv->UIActivate(SVUIA_DEACTIVATE);
psv = m_psv;
m_psv = NULL;
ReleaseAndNull(&_pctView);
if (m_pvo) {
IAdviseSink *pSink;
if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) && pSink) {
if (pSink == (IAdviseSink *)this)
m_pvo->SetAdvise(0, 0, NULL);
pSink->Release();
}

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 944 of 1651

fViewObjectChanged = TRUE;
ReleaseAndNull(&m_pvo);
}
if (psv) {
psv->SaveViewState();
psv->DestroyViewWindow();
psv->Release();
}
m_hwndView = NULL;
m_fHandsOff = FALSE;
if (m_pcache) {
GlobalFree(m_pcache);
m_pcache = NULL;
}
m_psb->EnableModelessSB(TRUE);
CancelPendingActions();
}
ReleaseAndNull(&_psf);
if (fViewObjectChanged)
NotifyViewClients(DVASPECT_CONTENT, -1);
if (m_pszTitle) {
LocalFree(m_pszTitle);
m_pszTitle = NULL;
}
SetRect(&m_rcBounds, 0, 0, 0, 0);
return S_OK;
}

Assembly Code
This section contains the annotated disassembly.
HRESULT CUserView::CloseView(void)
On entry to a function, the parameters are passed in registers r32 through r39. Remember that for C++ functions, the first parameter is the secret "this" pointer. Therefore, on
entry to CUserView::CloseView, the registers are:
r32 = this
br = return address
Parameters are passed in r32 through r39.
The br variable contains the function return address.
The Itanium separates its registers into several categories. The ones you will see most are r (regular integer registers), b (branch registers, used for branching), and p
(predicate registers, which can hold the value TRUE or FALSE).
It so happens that CloseView is a method on ViewState, which is at offset 12 in the underlying object. This method will be referred to as "this," although when there is
possible confusion with another base class, it will be more carefully specified as "(ViewState*)this".
sample!.CUserView__CloseView:
Notice that the symbol name is preceded by a dot. Recall that function pointers on the Itanium are not pointers to code. Instead, they point to a descriptor block (Intel calls it
the PLABEL), which contains information about the function (including the address of its first instruction). The symbol without a leading dot represents the function
descriptor. The symbol with a leading dot is the first line of code.
{
717796c0
717796c4

alloc
mov

r39 = ar.pfs, 0ah, 00h, 05h, 00h

r40 = pr

The alloc instruction builds a stack frame. In this case, the stack frame has the local region with 10 (0ah) registers and it needs 5 output registers. Recall that in disassembly,
the input registers and local registers are combined to form the local region. Because you know that you have only one parameter ("this"), there must be 9 local registers.
Every function begins with an alloc instruction.
Because you have a total of 10 registers in your local region, and the local region begins with register r32, the local region registers must be r32 through r41, leaving r42
through r46 as the 5 output registers.
The second instruction saves the predicate registers (pr) into register r40. This allows the predicate registers to be restored before the function returns.
if (m_fDestroyed) return S_OK;
717796c8
adds
r31 = 0180h, r32

}// r31 = &this->m_fDestroyed

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 945 of 1651

This is equivalent to "r31 = 0180h + r32". The adds instruction adds a small integer to a register. There is a corresponding addl instruction that adds a large integer, but it can
only add to registers r0, gp, r2, and r3.
Arithmetic operations are of the form "op dst = src, src, src".
Before proceeding with the computations, you need to finish the function prologue.
717796d0
717796d4
717796d8
717796e0

adds
ld8.nta
mov
or

sp = -32, sp ;;
// local stack space
r3 = [sp]
// stack probe
r38 = rp
} // save return address
r41 = gp, r0 ;;
// save gp

Notice that the integer argument to the adds sp instruction is disassembled in decimal rather than hexadecimal. However, the debugger default is to assume hexadecimal for
all inputs, so the command ?sp-32 will typically display as "sp-0x32". You can use the n (Set Number Base) command to change the default radix to 10. (The default radix
can be overridden with the 0x hexadecimal prefix or the 0n decimal prefix.)
The next adds instruction allocates some space on the stack. It is followed by a load instruction that appears unusual.
The ld instruction loads a register from memory.
The "nta" suffix means "this memory location will not be accessed for a long time" and is an indication to the processor to allow it to better optimize its L2 cache. The only
place you will see it in regular code is at the top of a function to perform a stack probe.
The third instruction saves the return address into register r38 so you know where to go when this function is finished.
The fourth instruction says, "r41 = gp | r0".
The r0 register is hard-wired to the value zero.
Therefore, ORing something with zero and storing the result is the same as copying the value.
"or dest = src, r0" copies a register.
The gp register, by convention, always points to the current module's global variables.
Because you are calling functions that might belong to other DLLs, you need to save the gp register so you can access your global variables after calling those functions. This
will require the gp register to point to their global variables.
717796e4
717796e8

ld4
nop.i

r31 = [r31]
00h ;;

// r31 = m_fDestroyed
}

The ld4 instruction is another memory fetch, but this time you load only 32 bits (4 bytes) from memory instead of a full 64 bits.
The ld4 instruction zero-extends the loaded value to 64 bits.
The next instruction is a NOP. The suffix indicates that this is actually an integer NOP However, this is not important, because the instruction does nothing.
717796f0
717796f4
717796f8

{
(p15)

cmp4.eq p14, p15 = r0, r31

nop.f
00h
br.cond.dpnt.few $+07c0h ;;

// if m_fDestroyed
}// jump if not to ReturnSOK

The cmp4.eq instruction compares the bottom 32 bits of the two registers r0 and r31. The result of the comparison is saved into the p14 register, and the opposite result is
saved to p15.
The cmp instruction compares two registers. The result of the comparison is saved in the first destination register; the opposite is saved in the second destination register.
The cmp4.eq instruction compares the r31 register (which you just loaded) with r0 (which is zero). If the registers are equal, then p14 is set to TRUE; otherwise, p14 is set to
FALSE. The p15 register is set to the opposite of p14 (that is, FALSE or TRUE, respectively).
After another NOP, check the result of the comparison.
A parenthesized register in the left margin indicates that the instruction is executed only if that register is TRUE.
In this case, you execute the branch instruction only if the p15 register is TRUE, which happens when the previous comparison is FALSE, because p15 was the second
destination of the comparison.
The suffixes on the br.cond instruction are hints to the processor for optimization and do not affect the execution semantics.
The target of the branch instruction is not quite right. The target is disassembled as $+07c0h, but the actual target address is 07b8h bytes away. That is because the branch
target is computed relative to the beginning of the instruction bundle (in other words, relative to the preceding open brace). Thus, when you are disassembling through code
and trying to follow the flow of the code, be careful how you compute your jump targets.
Jump instructions are relative to the start of the bundle, not to the start of the instruction.
Now you can see how that gp register gets used. The compiler has interleaved some instructions for performance, so the next step it does is actually the initial step for calling
an imported function.
ReleaseAndNull(&m_pdtgt);
71779700
{
addl
71779704
adds

r31 = -2025856, gp
r42 = 0198h, r32

// r31 = &__imp__ReleaseAndNull
// r42 = &this->m_pdtgt

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 946 of 1651

Because the gp register points to your global variables, the addl instruction against the gp register is computing the address of a global variable. In this case, it is the import
table entry for the ReleaseAndNull function.
As you computed at the beginning of the function, the output registers start at r42, and here you see the first output register being loaded with the address of the m_pdtgt
member. This is the first, and in this case, the only parameter of ReleaseAndNull.
if (m_psv)
71779708

adds

r33 = 0110h, r32

}// r33 = &this->m_psv

The compiler has aggressively started emitting instructions for the line two ahead of where you are.
BOOL fViewObjectChanged = FALSE;
71779710
{
or
r37 = r0, r0 ;;

; r37 = 0

The compiler used the r37 register to represent the local variable fViewObjectChanged. Because the r0 register is hard-wired to zero, the OR instruction zeroes out the r37
register.
ReleaseAndNull(&m_pdtgt);
71779714
ld8
r31 = [r31]
71779718
nop.i
00h ;;
71779720
{
ld8
r30 = [r31], 08h ;;
71779724
ld8
gp = [r31]
71779728
mov
b6 = r30, $+0x0
71779730
{
nop.m
00h
71779734
nop.f
00h
71779738
br.call.dptk.many rp = b6 ;;

// r31 = &ReleaseAndNull
}
// r30 = .ReleaseAndNull
// gp = gp.ReleaseAndNull
}// b6 = .ReleaseAndNull

}// call .ReleaseAndNull

Here is the remainder of the function call. Recall that a function pointer is really a pointer to a descriptor. Thus, after getting the address of the descriptor, you read the actual
code address and the gp of the target function.
The following diagram outlines this concept.
__imp__Function
+--------------+
| Function
--->
+--------------+

Function
+---------------+
| code pointer --->
+---------------+
| gp
|
+---------------+

Remember, a function name without a period in front of it refers to the function descriptor. The function with a period represents the first line of code.
"ld dest = [src], n" is a post-incremented load.
In this case, "ld8 r30 = [r31], 08h" means "load the r30 register from the 8 bytes pointed to by r31, and then increment r31 by 8."
After you load the code address into r30, you move it into the b6 register so you can branch to it. You cannot move from memory directly into a branch register; you have to
go through a regular integer register.
Finally, execute a br.call instruction to call the target function. (Again, the other suffixes are optimization indications.)
You will see this pattern repeatedly; it is the template for calling an imported function.
To call an imported function
1.
2.
3.
4.
5.
6.

Load the address of the import table

Load from the import table to get the descriptor
Load the code address from the descriptor, with postincrement +8
Load the gp register from the descriptor
Move the code address into a branch register
Call through the branch register

if (m_psv)
71779740
{
71779744
71779748
71779750
{
71779754
71779758
(p14)

ld8
r29 = [r33]
or
gp = r41, r0 ;;
cmp.eq
p14, p15 = r0, r29
nop.m
00h
nop.f
00h
br.cond.dpnt.few $+0620h ;;

// r29 = m_psv
// restore gp
}// m_psv == 0?

}// Y: jump to NoPSV

After control returns, dereference the r33 register, which you set up before calling ReleaseAndNull. The processor automatically preserves the local region across calls, so
the r33 register still contains the value you set up earlier.
After returning from the imported function call, restore the gp register to point to your own global registers so you can access them once again. (Though theoretically this
often is not necessary because you do not access any global variables before the next call that discards it anyway.)
The following is again a comparison followed by a predicated branch instruction. Check if the value you loaded is zero and branch it if it is.

71779760
71779764
71779768
71779770

m_psb->EnableModelessSB(FALSE);
{
adds
r36 = 0a0h, r32
addl
r43 = 00h, r0
nop.b
00h ;;
{
ld8
r42 = [r36] ;;

// r36 = &this->m_psb
// r43 = 0
}
// r42 = this->m_psb

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

71779774
71779778
71779780
71779784
71779788
71779790
71779794
71779798
717797a0
717797a4
717797a8

Page 947 of 1651

ld8
r31 = [r42]
nop.i
00h ;;
adds
r31 = 048h, r31 ;;
ld8
r30 = [r31]
nop.i
00h ;;
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;

// r31 = this->m_psb.vtbl
}
// r31 = &vtbl.EnableModelessSB
// r30 = &EnableModelessSB
}
// r29 = .EnableModelessSB
// gp = gp.EnableModelessSB
}// b6 = .EnableModelessSB

}// call .EnableModelessSB

Now you get to see how a virtual C++ method call gets compiled. As before, registers r42 and r43 receive the parameters to the function.
This time, instead of getting the function pointer from your gp, you load the vtbl out of m_psb, step forward to the method you want to call, then set up for another function
call.
The following diagram outlines this process.
object
+-------+
| vtbl --->
+-------+
| ...
|

object vtbl
+-----------------+
| QueryInterface |
+-----------------+
| AddRef
|
+-----------------+
| Release
|
+-----------------+
| ...
|
+-----------------+
| EnableModeless --->
+-----------------+
| ...
|

EnableModeless
+---------------+
| code pointer --->
+---------------+
| gp
|
+---------------+

The following is a pattern you should recognize.

How to compile a virtual C++ method
1.
2.
3.
4.
5.
6.
7.
8.

Load the object into an output register.

Load the vtbl from the object.
Add to the vtbl to get to the function you want to call.
Load from the vtbl to get the descriptor.
Load the code address from the descriptor, with postincrement +8.
Load the gp register from the descriptor.
Move the code address into a branch register.
Call through the branch register.

717797b0
717797b4
717797b8
717797c0
717797c4
717797c8
717797d0
717797d4
717797d8
717797e0
717797e4
717797e8
717797f0
717797f4
717797f8
71779800
71779804
71779808
71779810
71779814
71779818
NoWS:

if (m_pws) m_pws->ViewReleased();
{
adds
r28 = 0228h, r32
or
gp = r41, r0
nop.b
00h ;;
{
ld8
r42 = [r28] ;;
cmp.eq
p14, p15 = r0, r42
nop.i
00h
{
nop.m
00h
nop.f
00h
(p14)
br.cond.dpnt.few $+050h ;;
{
ld8
r31 = [r42] ;;
adds
r31 = 018h, r31
nop.i
00h ;;
{
ld8
r30 = [r31] ;;
ld8
r29 = [r30], 08h
nop.i
00h ;;
{
ld8
gp = [r30]
mov
b6 = r29, $+0x0
br.call.dptk.many rp = b6 ;;
{
or
gp = r41, r0
nop.f
00h
nop.b
00h ;;

// r28 = &this->m_pws
// restore gp after call
}
// r42 = this->m_pws
// equal to zero?
}

}//
//
//
}
//
//
}
//
//
}//
//

Y: Jump to NoWS
r31 = this->m_pws.vtbl
r31 = &vtbl.ViewReleased
r30 = &ViewReleased
r29 = .ViewReleased
gp = gp.ViewReleased
b6 = ViewReleased
call .ViewReleased
restore gp after call

You are now familiar enough to read the following entire code sequence, which consists of another variable test, conditional jump, and method call:

71779820
71779824
71779828
71779830
71779834
71779838
71779840
71779844
71779848

HWND hwndCapture = GetCapture();

{
addl
r31 = -2024992, gp ;;
ld8
r30 = [r31]
nop.i
00h ;;
{
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
{
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;

// r31 = &__imp__GetCapture
// r30 = &GetCapture
}
// r29 = .GetCapture
// gp = gp.GetCapture
}// b6 = .GetCapture

}// call .GetCapture

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

71779850

Page 948 of 1651

gp = r41, r0

// restore gp after call

Again, a pattern you already recognize, but this time it is a call to an imported function:

71779854
71779858
71779860
71779864
71779868
71779870
71779874
71779878

if (hwndCapture && hwndCapture == m_hwnd) {

cmp.eq
p14, p15 = r0, ret0
(p14)
br.cond.dpnt.few $+080h ;;
{
adds
r31 = 0b8h, r32 ;;
ld8
r42 = [r31]
nop.i
00h ;;
{
cmp.eq
p15, p14 = ret0, r42
nop.f
00h
(p14)
br.cond.dptk.few $+060h ;;

//
}//
//
//
}
//

hwndCapture == NULL?
Y: Jump to NoCapture
r31 = &this->m_hwnd
r42 = this->m_hwnd
hwndCapture == this->m_hwnd?

}// Y: Jump to NoCapture

Functions return their value in the ret0 register.

Check if hwndCapture is NULL or equal to m_hwnd, and jump if either condition is met.
SendMessage(m_hwnd, WM_CANCELMODE, 0, 0);
}
71779880
71779884
71779888
71779890
71779894
71779898
717798a0
717798a4
717798a8
717798b0
717798b4
717798b8
717798c0
717798c4
717798c8
NoCapture:

addl
r31 = -2025920, gp
addl
r45 = 00h, r0
addl
r44 = 00h, r0
addl
r43 = 01fh, r0 ;;
ld8
r30 = [r31]
nop.i
00h ;;
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;
or
gp = r41, r0
nop.f
00h
nop.b
00h

//
//
}//
//
//
}
//
//
}//

r31
r45
r44
r43
r30

=
=
=
=
=

&__imp__SendMessage
0 (lParam)
0 (wParam)
WM_CANCELMODE (uMsg)
&SendMessage

r29 = .SendMessage
gp = gp.SendMessage
b6 = .SendMessage

}// call .SendMessage

// restore gp after call
}

This time, you have to call a function that takes four parameters, so you fill the output registers r42 through r45 with the parameters. Note that you set up r42 ahead of time
while you were still deciding whether to call SendMessage.
m_fHandsOff = TRUE;
m_fRecursing = TRUE;
NotifyClients(m_psv, NOTIFY_CLOSING);
717798d0
{
ld8
r43 = [r33]
717798d4
adds
r42 = 040h, r32
717798d8
adds
r35 = 0218h, r32
717798e0
{
addl
r31 = 08001h, r0 ;;
717798e4
addl
r44 = 04h, r0
717798e8
nop.i
00h ;;
717798f0
{
ld8
r29 = [r42]
717798f4
ld4
r30 = [r35]
717798f8
nop.b
00h ;;
71779900
{
or
r31 = r31, r30 ;;
71779904
st4
[r35] = r31

//
//
}//
//
//
}
//
//
}
//
//

r43
r42
r35
r31
r44

=
=
=
=
=

m_psv
(CNotifySource*)this
&this->bitfield
0x8001
4

r29 = (CNotifySource*)this->vtbl
r30 = bitfield
set the two bits in r30
store the result

Now you get to see how bitfields get compiled, with some instructions from the upcoming method call interleaved. Recall that you set up the r33 register to point to the
m_psv member, so all you have to do is dereference it to fetch the value.
The other instructions prepare for the method call by setting up the output registers (r42 through r44) and loading the vtbl of m_psv.
Meanwhile, the two bits in the bitfield are set by loading the full bitfield, ORing the values, then storing the result.

71779908
71779910
71779914
71779918
71779920
71779924
71779928

NotifyClients(m_psv, NOTIFY_CLOSING);
adds
r29 = 018h, r29 ;;
{
ld8
r30 = [r29] ;;
ld8
r31 = [r30], 08h
nop.i
00h ;;
{
ld8
gp = [r30]
mov
b6 = r31, $+0x0
br.call.dptk.many rp = b6 ;;

}//
//
//
}
//
//
}//

r29 = &vtbl.NotifyClients
r30 = NotifyClients
r31 = .NotifyClients

//
//
}//
//
//
}//
//

r28 = bitfield
r42 = m_psv
r29 = ~0x8000
r29 = bitfield & ~0x8000
restore gp after call
r43 = 0 (SVUIA_DEACTIVATE)
store updated bitfield

gp = gp.NotifyClients
b6 = .NotifyClients
call .NotifyClients

Here is the rest of the method call:

71779930
71779934
71779938
71779940
71779944
71779948
71779950

m_fRecursing = FALSE;
{
ld4
ld8
addl
{
and
or
addl
{
st4

r28 = [r35]
r42 = [r33]
r29 = -32769, r0 ;;
r29 = r29, r28
gp = r41, r0
r43 = 00h, r0 ;;
[r35] = r29

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 949 of 1651

Here is how to clear a bit in a bitfield:

71779954
71779958
71779960
71779964
71779968
71779970
71779974
71779978
71779980
71779984
71779988

m_psv->UIActivate(SVUIA_DEACTIVATE);
ld8
r31 = [r42]
nop.b
00h ;;
{
adds
r31 = 038h, r31 ;;
ld8
r30 = [r31]
nop.i
00h ;;
{
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
{
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;

// r31 = m_psv.vtbl
}
// r31 = &vtbl.UIActivate
// r30 = &UIActivate
}
// r29 = .UIActivate
// gp = gp.UIActivate
}// b6 = .UIActivate

}// call .UIActivate

These method calls are becoming routine.

psv = m_psv;
m_psv = NULL;
ReleaseAndNull(&_pctView);
71779990
{
ld8
r34 = [r33]
71779994
or
gp = r41, r0
71779998
adds
r42 = 0100h, r32
717799a0
{
st8
[r33] = r0 ;;
717799a4
addl
r31 = -2025856, gp
717799a8
nop.i
00h ;;
717799b0
{
ld8
r30 = [r31] ;;
717799b4
ld8
r29 = [r30], 08h
717799b8
nop.i
00h ;;
717799c0
{
ld8
gp = [r30]
717799c4
mov
b6 = r29, $+0x0
717799c8
br.call.dptk.many rp = b6 ;;

//
//
}//
//
//
}
//
//
}
//
//
}//

r34 (psv) = m_psv

restore gp after call
r42 = &this->_bbt._pctView
m_psv = 0
r31 = &__imp__ReleaseAndNull
r30 = &ReleaseAndNull
r29 = .ReleaseAndNull
gp = gp.ReleaseAndNull
b6 = .ReleaseAndNull
call .ReleaseAndNull

Another method call, with some variable rearranging in it:

717799d0
717799d4
717799d8
717799e0
717799e4
717799e8
717799f0
717799f4
717799f8

if (m_pvo) {
{

{
(p14)

adds
r33 = 0178h, r32
or
gp = r41, r0
nop.b
00h ;;
ld8
r42 = [r33] ;;
cmp.eq
p14, p15 = r0, r42
nop.i
00h
nop.m
00h
nop.f
00h
br.cond.dpnt.few $+01a0h ;;

// r33 = &this->m_pvo
// restore gp after call
}
// r42 = this->m_pvo
// m_pvo == NULL?
}

}// Y: Jump to NoPVO

Simply checking a variable:

71779a00
71779a04
71779a08
71779a10
71779a14
71779a18
71779a20
71779a24
71779a28
71779a30
71779a34
71779a38
71779a40
71779a44
71779a48

IAdviseSink *pSink;
if (SUCCEEDED(m_pvo->GetAdvise(NULL, NULL, &pSink)) ...
{
ld8
r31 = [r42]
// r31 = this->m_pvo->vtbl
adds
r45 = 010h, sp
// r45 = &pSink
addl
r44 = 00h, r0
}// r44 = NULL
{
addl
r43 = 00h, r0 ;;
// r43 = NULL
adds
r37 = 010h, sp
// r37 = &pSink
nop.i
00h ;;
}
{
adds
r31 = 040h, r31 ;;
// r31 = &vtbl.GetAdvise
ld8
r30 = [r31]
// r30 = &GetAdvise
nop.i
00h ;;
}
{
ld8
r29 = [r30], 08h ;;
// r29 = .GetAdvise
ld8
gp = [r30]
// gp = gp.GetAdvise
mov
b6 = r29, $+0x0
}// b6 = .GetAdvise
{
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;
}// call .GetAdvise

Now call the GetAdvise method, and check the return value.

71779a50
71779a54
71779a58
71779a60
71779a64
71779a68

if (SUCCEEDED(...) && pSink) {

ld8
r42 = [r37]
// r42 = pSink
cmp4.eq p14, p15 = 01h, r0
// p14 = FALSE, p15 = TRUE
or
gp = r41, r0 ;;
}// restore gp after call
{
cmp4.gt.or.andcm p14, p15 = r0, ret0 // if (0 > ret0) { p14 = TRUE; p15 = FALSE }
cmp.eq.or.andcm p14, p15 = r0, r42 // if (0 == pSink) { p14 = TRUE; p15 = FALSE }
(p14)
br.cond.dpnt.few $+0f0h ;;
}// if FAILED or NULL, jump to NoSink
{

Now you see the unusual conditional instructions in action.

The first comparison instruction seems pointless in that it compares one against zero. It does this to initialize the predicate registers p14 to FALSE and p15 to TRUE.
The next two comparison instructions execute in parallel. The first one checks if 0 > ret0; that is, if the return value is negative. The next two suffixes indicate that the result is
ORed into the first destination and complemented and ANDed (andcm) with the second destination.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 950 of 1651

After doing the combination testing, you jump if p14 is TRUE, which happens if one of the combination tests was true.
There are two interesting points to note about this sequence. First, the two combination comparisons were executed in parallel. (Notice that they execute as part of the same
instruction group.) Second, you only executed a single conditional jump. Furthermore, that conditional jump was part of the same instruction group, so it all executes in a
single cycle.
A traditional CPU would have had to test the return value, jump conditionally, then test pSink, and jump conditionally again.Those four operations are dependent on each
other, so it would take four cycles to perform the combination test instead of the one cycle that the Itanium required.
if (pSink == (IAdviseSink *)this)
adds
r31 = -40, r32 ;;
cmp.eq
p14, p15 = r0, r31
adds
r31 = 028h, r32
{
nop.m
00h
nop.f
00h
(p15)
br.cond.dpnt.few $+020h ;;
{
or
r31 = r0, r0
nop.f
00h
nop.b
00h ;;

71779a70
71779a74
71779a78
71779a80
71779a84
71779a88
71779a90
71779a94
71779a98
NotNULL:

// r31 = (CUserView*)this
// r31 == NULL?
}// r31 = (IAdviseSink*)this

}// N: Jump to NotNULL

// r31 = NULL
}

This is a quirk of the C++ specification, namely that if p is a NULL pointer, then (T*)p must be equal to NULL for all types T. This means that changing from one base class
to another requires the compiler to stick in special checks for NULL.
At the end of the following sequence, the r31 register contains the result of the cast (IAdviseSink*).
if (pSink == (IAdviseSink *)this)
m_pvo->SetAdvise(0, 0, NULL);
cmp.eq
p15, p14 = r42, r31
nop.f
00h
(p14)
br.cond.dptk.few $+070h ;;
ld8
r42 = [r33]
addl
r45 = 00h, r0
addl
r44 = 00h, r0
addl
r43 = 00h, r0 ;;
ld8
r31 = [r42]
nop.i
00h ;;
adds
r31 = 038h, r31 ;;
ld8
r30 = [r31]
nop.i
00h ;;
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;
ld8
r42 = [r37]
or
gp = r41, r0
nop.b
00h ;;

71779aa0
{
71779aa4
71779aa8
71779ab0
{
71779ab4
71779ab8
71779ac0
{
71779ac4
71779ac8
71779ad0
{
71779ad4
71779ad8
71779ae0
{
71779ae4
71779ae8
71779af0
{
71779af4
71779af8
71779b00
{
71779b04
71779b08
NotSameSink:

// r31 == pSink?
}//
//
//
}//
//
//
}
//
//
}
//
//
}//

N: Jump to NotSameSink
r42 = this->m_pvo
r45 = 0
r44 = 0
r43 = NULL
r31 = this->m_pvo->vtbl
r31 = &vtbl.SetAdvise
r30 = SetAdvise
r29 = .SetAdvise
gp = gp.SetAdvise
b6 = .SetAdvise

}// call .SetAdvise

//r42 = pSink (restore register variable)
// restore gp after call
}

Notice that the compiler had to reload the r42 register after the call, because r42 is an output register, and output registers can be modified across a call. (That is not important
in this case, because you also explicitly destroyed the r42 register.)
pSink->Release();
}
71779b10
71779b14
71779b18
71779b20
71779b24
71779b28
71779b30
71779b34
71779b38
71779b40
71779b44
71779b48
NoSink:

ld8
r31 = [r42] ;;
adds
r31 = 010h, r31
nop.i
00h ;;
ld8
r30 = [r31] ;;
ld8
r29 = [r30], 08h
nop.i
00h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
br.call.dptk.many rp = b6 ;;
or
gp = r41, r0
nop.f
00h
nop.b
00h ;;

// r31 = pSink->vtbl
// r31 = &vtbl.Release
}
// r30 = &Release
// r29 = .Release
}
//
//
}//
//

gp = gp.Release
b6 = .Release
call .Release
restore gp after call

Another method call:

fViewObjectChanged = TRUE;
ReleaseAndNull(&m_pvo);
}
71779b50
71779b54
71779b58
71779b60
71779b64
71779b68
71779b70

addl
or
addl
ld8
ld8
nop.i
ld8

r31 = -2025856, gp
r42 = r33, r0
r37 = 01h, r0 ;;
r30 = [r31] ;;
r29 = [r30], 08h
00h ;;
gp = [r30]

//
//
}//
//
//
}
//

r31
r42
r37
r30
r29

= &__imp__ReleaseAndNull
= r33 = &this->m_pvo
(fViewObjectChanged) = 1 = TRUE
= &ReleaseAndNull
= .ReleaseAndNull

= gp.ReleaseAndNull

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

71779b74
71779b78
71779b80
71779b84
71779b88

Page 951 of 1651

mov
b6 = r29, $+0x0
br.call.dptk.many rp = b6 ;;
or
gp = r41, r0
nop.f
00h
nop.b
00h

// b6 = .ReleaseAndNull
}// call .ReleaseAndNull
// restore gp after call
}

Recall that the fViewObjectChanged local variable is being kept in the r37 register.
if (psv) {
psv->SaveViewState();
psv->DestroyViewWindow();
psv->Release();
}
71779b90
{
cmp.eq
p14, p15 = r0, r34
71779b94
nop.f
00h
71779b98
(p14)
br.cond.dptk.few $+0d0h ;;
71779ba0
{
ld8
r31 = [r34]
71779ba4
or
r42 = r34, r0 ;;
71779ba8
adds
r31 = 068h, r31 ;;
71779bb0
{
ld8
r30 = [r31] ;;
71779bb4
ld8
r29 = [r30], 08h
71779bb8
nop.i
00h ;;
71779bc0
{
ld8
gp = [r30]
71779bc4
mov
b6 = r29, $+0x0
71779bc8
br.call.dptk.many rp = b6 ;;
71779bd0
71779bd4
71779bd8
71779be0
71779be4
71779be8
71779bf0
71779bf4
71779bf8
71779c00
71779c04
71779c08

71779c10
71779c14
71779c18
71779c20
71779c24
71779c28
71779c30
71779c34
71779c38
71779c40
71779c44
71779c48
71779c50
71779c54
71779c58
NoPSV2:

// r34 (psv) == NULL?

}//
//
//
}//
//
//
}
//
//
}//

Y: Jump to NoPSV2
r31 = psv->vtbl
r42 = psv
r31 = &vtbl.SaveViewState
r30 = &SaveViewState
r29 = .SaveViewState

ld8
r28 = [r34]
or
gp = r41, r0
or
r42 = r34, r0 ;;
adds
r31 = 050h, r28 ;;
ld8
r29 = [r31]
nop.i
00h ;;
ld8
r27 = [r29], 08h ;;
ld8
gp = [r29]
mov
b6 = r27, $+0x0
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;

//
//
}//
//
//
}
//
//
}//

r28 = psv->vtbl
restore gp after call (pointless)
r42 = psv
r31 = &vtbl.DestroyViewWindow
r29 = &DestroyViewWindow

ld8
r30 = [r34]
or
gp = r41, r0
or
r42 = r34, r0 ;;
adds
r31 = 010h, r30 ;;
ld8
r28 = [r31]
nop.i
00h ;;
ld8
r29 = [r28], 08h ;;
ld8
gp = [r28]
mov
b6 = r29, $+0x0
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;
or
gp = r41, r0
nop.f
00h
nop.b
00h

//
//
}//
//
//
}
//
//
}//

gp = gp.SaveViewState
b6 = .SaveViewState
call .SaveViewState

r27 = .DestroyViewWindow
gp = gp.DestroyViewWindow
b6 = .DestroyViewWindow

}// call .DestroyViewWindow

r30 = psv->vtbl
restore gp after call (pointless)
r42 = psv
r31 = &vtbl.Release
r28 = &Release
r29 = .Release
gp = gp.Release
b6 = .Release

}// call .Release

// restore gp after call
}

The restores of gp after the function call are pointless, because the next function call is going to destroy it anyway. This is an actual compiler error; its optimizer should have
noticed that gp is not read before it is rewritten.
m_hwndView = NULL;
m_fHandsOff = FALSE;
71779c60
{
ld4
71779c64
adds
71779c68
adds
71779c70
{
ld8
71779c74
st4
71779c78
and
71779c80
{
st4
71779c84
st4

r30 =
r31 =
r33 =
r42 =
[r31]
r30 =
[r31]
[r35]

[r35]
0120h, r32
0108h, r32 ;;
[r33]
= r0, 04h
-2, r30 ;;
= r0
= r30

//
//
}//
//
//
}//
//
//

r30 = this->bitfield
r31 = &m_hwndView
r33 = &m_pcache
r42 = m_pcache
[r31] = NULL, r31 += 4
r30 = r30 & ~-2 (clear bit)
[r31] = NULL (other half)
bitfield = r30

The compiler is making additional errors. It splits the m_hwndView into two parts, storing the NULL two DWORDs at a time instead of as a single 64-bit store. The compiler
thinks that the m_hwndView member is unaligned so it has to split the store. So you now get to see a postincremented store.
"st [dest] = src, n" is a post-incremented store.
The "and r30 = -2, r30" clears the bottom bit.

71779c88
71779c90
71779c94
71779c98

if (m_pcache) {
cmp.eq
p14, p15 = r0, r42
{
nop.b
00h
nop.b
00h
(p14)
br.cond.dpnt.few $+090h ;;

}// m_pcache == NULL?

}// Y: Jump to NoCache

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 952 of 1651

The r42 register was set up while you were clearing bits in the previous block of code.
GlobalFree(m_pcache);
addl
r31 = -2029288, gp ;;
ld8
r30 = [r31]
nop.i
00h ;;
{
ld8
r29 = [r30], 08h ;;
ld8
gp = [r30]
mov
b6 = r29, $+0x0
{
nop.m
00h
nop.f
00h
br.call.dptk.many rp = b6 ;;

71779ca0
71779ca4
71779ca8
71779cb0
71779cb4
71779cb8
71779cc0
71779cc4
71779cc8

// r31 = &__imp__GlobalFree
// r30 = &GlobalFree
}
// r29 = .GlobalFree
// gp = gp.GlobalFree
}// b6 = .GlobalFree

}// call .GlobalFree

Recall that r42 already contains the value of m_pcache.

m_pcache = NULL;
}
71779cd0
71779cd4
71779cd8
71779ce0
71779ce4
71779ce8
71779cf0
71779cf4
71779cf8
71779d00
71779d04
71779d08
71779d10
71779d14
71779d18
NoCache:

st1
or
nop.b
st1
st1
nop.i
st1
st1
nop.i
st1
st1
nop.i
st1
nop.f
nop.b

[r33] = r0, 01h

gp = r41, r0
00h ;;
[r33] = r0, 01h ;;
[r33] = r0, 01h
00h ;;
[r33] = r0, 01h ;;
[r33] = r0, 01h
00h ;;
[r33] = r0, 01h ;;
[r33] = r0, 01h
00h ;;
[r33] = r0
00h
00h

// [r33] = 0, r33++
// restore gp after call
}
// [r33] = 0, r33++
// [r33] = 0, r33++
}
// [r33] = 0, r33++
// [r33] = 0, r33++
}
// [r33] = 0, r33++
// [r33] = 0, r33++
}
// [r33] = 0
}

More compiler errors. The compiler assumes that m_pcache is unaligned so it has to zero it out by writing 8 bytes, one at a time, even though it loaded the value at address
71779c70, assuming the address was aligned.

71779d20
71779d24
71779d28
71779d30
71779d34
71779d38
71779d40
71779d44
71779d48
71779d50
71779d54
71779d58
71779d60
}
71779d64
71779d68
NoPSV:

m_psb->EnableModelessSB(TRUE);
{
ld8
r42 = [r36]
addl
r43 = 01h, r0
nop.b
00h ;;
{
ld8
r31 = [r42] ;;
adds
r31 = 048h, r31
nop.i
00h ;;
{
ld8
r30 = [r31] ;;
ld8
r29 = [r30], 08h
nop.i
00h ;;
{
ld8
gp = [r30]
mov
b6 = r29, $+0x0
br.call.dptk.many rp = b6 ;;
{
or
gp = r41, r0
CancelPendingActions();

// r42 = this->m_psb
// r43 = TRUE
}
// r31 = this->m_psb.vtbl
// r31 = &vtl.EnableModeless
}
// r30 = &EnableModeless
// r29 = .EnableModeless
}
//
//
}//
//

gp = gp.EnableModeless
b6 = .EnableModeless
call .EnableModeless
restore gp after call

adds
r42 = -40, r32
// r42 = (CUserView*)this
br.call.sptk.many rp = $-15424 ;; } // call .CancelPendingActions

This is a direct call rather than an imported function or a virtual method call. Notice that you did not have to set up the gp register, because CancelPendingActions was not a
virtual method. Thus, you know that it resides in your own DLL and, therefore, its gp is equal to your gp. It also means that you do not need to restore gp after the call.
ReleaseAndNull(&_psf);
71779d70
{
addl
r31 = -2025856, gp
71779d74
adds
r42 = 0118h, r32
71779d78
nop.b
00h ;;
71779d80
{
ld8
r30 = [r31] ;;
71779d84
ld8
r29 = [r30], 08h
71779d88
nop.i
00h ;;
71779d90
{
ld8
gp = [r30]
71779d94
mov
b6 = r29, $+0x0
71779d98
br.call.dptk.many rp = b6 ;;
71779da0
{
or
gp = r41, r0
if (fViewObjectChanged)
NotifyViewClients(DVASPECT_CONTENT, -1);
71779da4
cmp4.eq p14, p15 = r0, r37
71779da8
(p14)
br.cond.dpnt.few $+060h ;;
71779db0
{
adds
r42 = -40, r32
71779db4
addl
r44 = -1, r0
71779db8
addl
r43 = 01h, r0 ;;
71779dc0
{
ld8
r31 = [r42] ;;
71779dc4
adds
r31 = 048h, r31
71779dc8
nop.i
00h ;;

// r31 = &__imp__ReleaseAndNull
// r42 = &this->_psf
}
// r30 = &ReleaseAndNull
// r29 = .ReleaseAndNull
}
//
//
}//
//

gp = gp.ReleaseAndNull
b6 = .ReleaseAndNull
call .ReleaseAndNull
restore gp after call

//
}//
//
//
}//
//
//
}

r36 (fViewObjectChanged) == FALSE?

Y: Jump to NoChange
r42 = (CBaseBrowser*)this
r44 = -1
r43 = 1 = DVASPECT_CONTENT
r31 = this.vtbl
r31 = &vtbl.NotifyViewClients

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 953 of 1651

71779dd0
{
ld8
r30 = [r31] ;;
71779dd4
ld8
r29 = [r30], 08h
71779dd8
nop.i
00h ;;
71779de0
{
ld8
gp = [r30]
71779de4
mov
b6 = r29, $+0x0
71779de8
br.call.dptk.many rp = b6 ;;
71779df0
{
or
gp = r41, r0
71779df4
nop.f
00h
71779df8
nop.b
00h
NoChange:
if (m_pszTitle) {
LocalFree(m_pszTitle);
m_pszTitle = NULL;
}
71779e00
{
adds
r33 = 0128h, r32 ;;
71779e04
ld8
r42 = [r33]
71779e08
nop.i
00h ;;
71779e10
{
cmp.eq
p14, p15 = r0, r42
71779e14
nop.f
00h
71779e18
(p14)
br.cond.dpnt.few $+050h ;;
71779e20
{
addl
r31 = -2029752, gp ;;
71779e24
ld8
r30 = [r31]
71779e28
nop.i
00h ;;
71779e30
{
ld8
r29 = [r30], 08h ;;
71779e34
ld8
gp = [r30]
71779e38
mov
b6 = r29, $+0x0
71779e40
{
nop.m
00h
71779e44
nop.f
00h
71779e48
br.call.dptk.many rp = b6 ;;
71779e50
{
st8
[r33] = r0
71779e54
or
gp = r41, r0
71779e58
nop.b
00h ;;
NoTitle:

// r30 = &NotifyViewClients
// r29 = .NotifyViewClients
}
//
//
}//
//

gp = gp.NotifyViewClients
b6 = .NotifyViewClients
call .NotifyViewClients
restore gp after call

// r33 = &this->m_pszTitle
// r42 = this->m_pszTitle
}
// r42 == NULL?
}//
//
//
}
//
//
}//

Y: Jump to NoTitle
r31 = &__imp__LocalFree
r30 = &LocalFree
r29 = .LocalFree
gp = gp.LocalFree
b6 = .LocalFree

}// call .LocalFree

// this->m_pszTitle = 0
// restore gp after call
}

Nothing new in the following.

SetRect(&m_rcBounds, 0, 0, 0, 0);
71779e60
{
addl
r31 = -2024936, gp
71779e64
addl
r46 = 00h, r0
71779e68
addl
r45 = 00h, r0
71779e70
{
addl
r44 = 00h, r0 ;;
71779e74
ld8
r30 = [r31]
71779e78
addl
r43 = 00h, r0
71779e80
{
adds
r42 = 0208h, r32 ;;
71779e84
ld8
r29 = [r30], 08h
71779e88
nop.i
00h ;;
71779e90
{
ld8
gp = [r30]
71779e94
mov
b6 = r29, $+0x0
71779e98
br.call.dptk.many rp = b6 ;;
71779ea0
{
or
gp = r41, r0
71779ea4
nop.f
00h
71779ea8
nop.b
00h
return S_OK;
ReturnSOK:
71779eb0
{
or
ret0 = r0, r0

//
//
}//
//
//
}//
//
//
}
//
//
}//
//

r31
r46
r45
r44
r30
r43
r42
r29

=
=
=
=
=
=
=
=

&__imp__SetRect
0
0
0
&SetRect
0
&this->m_rcBounds
.SetRect

gp = gp.SetRect
b6 = .SetRect
call .SetRect
restore gp after call

Finally, you get to set the return value:

}
71779eb4
71779eb8
71779ec0
71779ec4
71779ec8
71779ed0
71779ed4
71779ed8

mov
rp = r38, $+0x0
adds
sp = 020h, sp ;;
nop.m
00h
mov
pr = r40, -2 ;;
mov.i
ar.pfs = r39
nop.m
00h
nop.f
00h
br.ret.sptk.many rp ;;

// restore return address

}// clean up stack
// restore predicate registers
}// clean up stack frame

Using the DbgRpc Tool

The DbgRpc tool (Dbgrpc.exe) is located in the root directory of the Debugging Tools for Windows installation and must be started in a Command Prompt window. Doubleclicking the icon will not start this tool.
The Command Prompt window must be running under an account with administrative privileges on the local computer, or with domain administrative privileges.
DbgRpc makes no calls to any system services (such as LSASS). This makes it useful for debugging even if a system service has crashed, as long as the kernel is still running.
Using DbgRpc on a Remote Computer
DbgRpc can also be used to examine information from a remote machine. For this to work, the remote machine must be able to accept remote connections and authenticate
remote users. If the remote machine's RPCSS (RPC Endpoint Mapper) service has crashed, DbgRpc will not be able to work. Administrative or domain administrative
privileges on the remote machine are required.
The -s command-line option is used to specify the server name, and the -p parameter is used to specify the transport protocol. Both TCP and named pipe protocols are
available. TCP is the recommended protocol; it should work in almost every situation.
Here is an example:
G:\>dbgrpc -s MyServer -p ncacn_ip_tcp -l -P 1e8 -L 0.1
Getting remote cell info ...
Endpoint
Status: Active
Protocol Sequence: LRPC
Endpoint name: OLE18
DbgRpc Command Line
For a description of the the full command syntax, see DbgRpc Command-Line Options.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Get RPC Cell Information

Detailed cell information is displayed by the !rpcexts.getdbgcell extension, or by DbgRpc when the -l switch is used.
The process ID of the process that contains the preferred cell must be specified, as well as the cell number.
In the following example, the process ID is 0x278, and the cell number is 0000.0002:
D:\wmsg>dbgrpc -l -P 278 -L 0.2
Getting cell info ...
Thread
Status: Dispatched
Thread ID: 0x1A4 (420)
Last update time (in seconds since boot):470.25 (0x1D6.19)
For details on the optional parameters, see DbgRpc Command-Line Options.
For a similar example using the RPC debugger extensions, see !rpcexts.getdbgcell.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Get RPC Endpoint Information

Endpoint information is displayed by the !rpcexts.getendpointinfo extension, or by DbgRpc when the -e switch is used.
If an endpoint number is specified, information about that endpoint is shown. If it is omitted, the endpoints for all processes on the system are displayed.
The following example displays all endpoints. This is often a useful way to obtain process IDs and cell numbers that can be used as arguments for additional commands:
D:\wmsg>dbgrpc -e
Searching for endpoint info ...
PID CELL ID
ST PROTSEQ
ENDPOINT
------------------------------------------------------00a8 0000.0001 01
NMP \PIPE\InitShutdown

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

00a8
00a8
00a8
00a8
00c4
00c4
00c4
00d0
00d0
00d0
00d0
0170
0170
0170
0170
0170
0170
01b8
01b8
01b8
00ec
00ec
00ec
00ec
00ec
00ec
0214
022c
022c
022c
022c
02a8
0370
0278
030c

0000.0003
0000.0004
0000.0007
0000.0008
0000.0001
0000.0003
0000.0008
0000.0001
0000.0004
0000.000b
0000.000c
0000.0001
0000.0003
0000.0005
0000.0006
0000.0007
0000.000b
0000.0001
0000.0003
0000.0007
0000.0001
0000.0003
0000.0007
0000.0008
0000.000c
0000.0010
0000.0001
0000.0001
0000.0003
0000.0005
0000.0006
0000.0001
0000.0001
0000.0001
0000.0001

Page 957 of 1651

01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01
01

NMP
NMP
NMP
LRPC
LRPC
NMP
NMP
NMP
NMP
NMP
LRPC
LRPC
TCP
SPX
NB
NB
NMP
NMP
LRPC
LRPC
LRPC
LRPC
NMP
LRPC
NMP
NMP
NMP
LRPC
TCP
SPX
NMP
LRPC
LRPC
TCP
LRPC

\PIPE\SfcApi
\PIPE\ProfMapApi
\pipe\winlogonrpc
OLE5
ntsvcs
\PIPE\ntsvcs
\PIPE\scerpc
\PIPE\lsass
\pipe\WMIEP_d0
\PIPE\POLICYAGENT
policyagent
epmapper
135
34280
135
135
\pipe\epmapper
\pipe\spoolss
spoolss
OLE7
OLE2
senssvc
\pipe\tapsrv
tapsrvlpc
\PIPE\ROUTER
\pipe\WMIEP_ec
\PIPE\winreg
LRPC0000022c.00000001
1058
24576
\PIPE\atsvc
OLE3
OLE9
1120
OLE12

For details on the optional parameters, see DbgRpc Command-Line Options.

For a similar example using the RPC debugger extensions, see !rpcexts.getendpointinfo.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Get RPC Thread Information

Thread information is displayed by the !rpcexts.getthreadinfo extension, or by DbgRpc when the -t switch is used.
The PID of a process must be specified. You may specify a thread within that process as well. If the thread is omitted, all threads within that process will be displayed.
In the following example, the process ID is 0x278 and the thread ID is omitted:
D:\wmsg>dbgrpc -t -P 278
Searching for thread info ...
PID CELL ID
ST TID
LASTTIME
----------------------------------0278 0000.0002 01 000001a4 00072c09
0278 0000.0005 03 0000031c 00072bf5
For details on the optional parameters, see DbgRpc Command-Line Options.
For a similar example using the RPC debugger extensions, see !rpcexts.getthreadinfo.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Get RPC Call Information

Server-side call (SCALL) information is displayed by the !rpcexts.getcallinfo extension, or by DbgRpc when the -c switch is used.
Four optional parameters are permitted. Three of these CallID, IfStart, and ProcNum are identifying information used by RPC to keep track of its calls. The fourth
parameter, ProcessID, is the PID of the server process that owns the call. You should supply whatever parameters you know to narrow down the search.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 958 of 1651

If no parameters are supplied, all known SCALLs in the system will be displayed. The following is an example of this long display:
D:\wmsg>dbgrpc -c
Searching for call info ...
PID CELL ID
ST PNO IFSTART TIDNUMBER CALLFLAG CALLID
LASTTIME CONN/CLN
---------------------------------------------------------------------------00c4 0000.0002 00 00f 82273fdc 0000.0007 00000001 00000002 0003595d 0000.0010
00c4 0000.0006 00 009 367abb81 0000.0015 00000001 0000004d 000185bd 0000.0005
00c4 0000.000a 00 007 367abb81 0000.002d 00000001 0000009f 00014672 0000.0009
00c4 0000.000c 00 007 367abb81 0000.002d 00000001 00000083 000122e3 0000.000b
00c4 0000.000d 00 03b 8d9f4e40 0000.002d 00000001 000000f7 0001aba5 0000.0020
00c4 0000.000e 00 03b 8d9f4e40 0000.0026 00000001 00000002 00023056 0000.0021
00c4 0000.000f 00 008 82273fdc 0000.001e 00000009 baadf00d 000366b4 00ec.03bc
00c4 0000.0012 00 00d 8d9f4e40 0000.0004 00000001 00000051 0000a334 0000.0011
00c4 0000.0014 00 000 367abb81 0000.0015 00000001 0000004c 0002db53 0000.0013
00c4 0000.0017 00 007 367abb81 0000.0015 00000001 00000006 0000d102 0000.0016
00c4 0000.0019 00 007 367abb81 0000.0004 00000001 00000006 0000f09e 0000.0018
00c4 0000.001b 00 009 65a93890 0000.0007 00000001 0000012e 00630f65 0000.001a
00c4 0000.001e 00 026 8d9f4e40 0000.0015 00000001 0000037d 0005e579 0000.002c
00c4 0000.001f 00 008 82273fdc 0000.0033 00000009 baadf00d 000145b3 00c4.02f8
00c4 0000.0023 00 000 367abb81 0000.0004 00000001 0000007e 000372f3 0000.0022
00c4 0000.0025 00 03b 8d9f4e40 0000.0026 00000001 0000000b 000122e3 0000.0024
00c4 0000.0027 00 000 367abb81 0000.002d 00000001 0000000b 00012e27 0000.0028
00c4 0000.002a 00 008 82273fdc 0000.0033 00000009 baadf00d 0001245f 022c.0290
00c4 0000.002f 00 007 367abb81 0000.0026 00000001 0000000a 0002983c 0000.002e
00c4 0000.0031 00 004 3ba0ffc0 0000.0026 00000001 00000007 0005c439 0000.001c
00c4 0000.0032 00 00b 82273fdc 0000.0039 00000009 baadf00d 00687db6 00d0.01d4
00c4 0000.0036 00 007 367abb81 0000.0030 00000001 00000065 0003a5e1 0000.0035
00c4 0000.0037 00 00d 8d9f4e40 0000.0015 00000001 0000033f 000376fa 0000.002b
00c4 0000.0038 00 008 8d9f4e40 0000.0015 00000001 00000803 0018485c 0000.003b
00c4 0000.003c 00 00b 82273fdc 0000.0034 00000009 baadf00d 0001f956 00a8.0244
00c4 0000.003d 00 008 82273fdc 0000.0034 00000009 baadf00d 0001ff02 01b8.037c
0170 0000.0009 00 002 e60c73e6 0000.0013 00000009 baadf00d 0005a371 00ec.031c
0170 0000.000a 00 002 0b0a6584 0000.0002 00000009 baadf00d 000126ae 00c4.0130
0170 0000.000c 00 002 0b0a6584 0000.0010 00000009 baadf00d 00012bc4 022c.0290
0170 0000.000d 00 003 00000136 0000.001b 00000009 baadf00d 0005ba71 00ec.0310
0170 0000.000e 00 000 412f241e 0000.0002 00000009 baadf00d 00012f21 02a8.029c
0170 0000.0010 00 003 00000136 0000.0013 00000009 00000003 000341da 0370.0060
0170 0000.0011 00 006 e60c73e6 0000.001b 00000009 baadf00d 000f1d00 0370.0328
0170 0000.0017 00 002 0b0a6584 0000.001b 00000009 baadf00d 0006c803 0278.0184
0170 0000.001a 00 004 00000136 0000.0012 00000001 baadf00d 00038e9b 00ec.0348
00ec 0000.0006 00 009 00000134 0000.0011 00000009 baadf00d 000b233f 0170.0244
00ec 0000.000b 00 001 2f5f6520 0000.001c 00000009 baadf00d 00035510 00ec.0334
00ec 0000.000e 00 001 629b9f66 0000.0014 00000009 baadf00d 00035813 00ec.01c4
00ec 0000.0012 00 000 629b9f66 0000.0014 00000009 baadf00d 00026cc6 00a8.0164
00ec 0000.001b 00 001 2f5f6520 0000.0004 00000001 baadf00d 000352c1 00ec.03a8
02a8 0000.0004 00 009 00000134 0000.0002 00000009 baadf00d 0009a540 0170.0244
0370 0000.0006 00 003 00000134 0000.0005 0000000b baadf00d 0002e7cd 00ec.0350
0370 0000.0008 00 009 00000134 0000.0007 0000000b 01cee9e4 000838fa 0170.0244
0278 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 00072c09 0000.0003
For details on the optional parameters, see DbgRpc Command-Line Options.
For a similar example using the RPC debugger extensions, see !rpcexts.getcallinfo.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Get RPC Client Call Information

Client call (CCALL) call information is displayed by the !rpcexts.getclientcallinfo extension, or by DbgRpc when the -a switch is used.
Four optional parameters are permitted. Three of these CallID, IfStart, and ProcNum are identifying information used by RPC to keep track of its calls. The fourth
parameter, ProcessID, is the PID of the process that owns the call. You should supply whatever parameters you know to narrow down the search.
If no parameters are supplied, all known CCALLs in the system will be displayed. The following is an example of this (potentially long) display:
D:\wmsg>dbgrpc -a
Searching for call info ...
PID CELL ID
PNO IFSTART TIDNUMBER CALLID
LASTTIME PS CLTNUMBER ENDPOINT
-----------------------------------------------------------------------------0390 0000.0001 0000 19bb5061 0000.0000 00000001 00072bff 07 0000.0002 1120
For details on the optional parameters, see DbgRpc Command-Line Options.
For a similar example using the RPC debugger extensions, see !rpcexts.getclientcallinfo.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 959 of 1651

Note Information about Client Call objects is only gathered if the Full state information is being gathered. See Enabling RPC State Information for details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Common RPC Debugging Techniques

This section describes four common RPC-related problems. RPC state information can be used to troubleshoot these problems.
Either the DbgRpc tool or the RPC debugger extensions can be used in any of these four situations.
Analyzing a Stuck Call Problem
Tracking Contention in the Server Process
Checking for Stuck Threads
Identifying the Caller From the Server Thread
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Stuck Call Problem

A common problem occurs when a process makes an RPC call, directly or indirectly, while holding a critical section or a resource. In this case, the RPC call goes to another
process or machine and dispatches to the manager routine (server routine), which then hangs or takes too long. This causes the original caller to encounter a critical section
time-out.
When examined through the debugger, RPC is on top of the stack of the thread owning the critical section, but it is not clear what it is waiting for.
Here is one example of such a stack. Many variations are possible.
0:002> ~1k
ChildEBP RetAddr
0068fba0 77e9e8eb
0068fbc8 4efeff73
0068fbe8 4eff0012
0068fc0c 4efe6e2b
0068fc44 4ef973bf
0068fc68 4ef98d5a
0068fce4 4ef9b682
0068fd38 4ef9a5a8
0068fd88 4ef9a9cb
0068fda8 4ef9a7f8
0068fdd4 4ef946a7
0068fdf0 4efd56b3
0068fe08 01002850
0068ff40 01001f32
0068ffb4 77e92ca8
0068ffec 00000000

ntdll!ZwWaitForSingleObject+0xb
KERNEL32!WaitForSingleObjectEx+0x5a
RPCRT4!UTIL_WaitForSyncIO+0x21
RPCRT4!UTIL_GetOverlappedResultEx+0x44
RPCRT4!WS_SyncRecv+0x12a
RPCRT4!OSF_CCONNECTION__TransSendReceive+0xcb
RPCRT4!OSF_CCONNECTION__SendFragment+0x297
RPCRT4!OSF_CCALL__SendNextFragment+0x272
RPCRT4!OSF_CCALL__FastSendReceive+0x165
RPCRT4!OSF_CCALL__SendReceiveHelper+0xed
RPCRT4!OSF_CCALL__SendReceive+0x37
RPCRT4!I_RpcSendReceive+0xc4
RPCRT4!NdrSendReceive+0x4f
rtclnt+0x2850
rtclnt+0x1f32
KERNEL32!CreateFileA+0x11b

Here's how to troubleshoot this problem.

Troubleshooting a stuck call problem
1. Make sure the debugger is debugging the process that owns the stuck cell. (This is the process containing the client thread that is suspected of hanging in RPC.)
2. Get the stack pointer of this thread. The stack will look like the one shown in the preceding example. In this example, the stack pointer is 0x0068FBA0.
3. Get the call information for this thread. In order to do that, use the !rpcexts.rpcreadstack extension with the thread stack pointer as its parameter, as follows:
0:001> !rpcexts.rpcreadstack 68fba0
CallID: 1
IfStart: 19bb5061
ProcNum: 0
Protocol Sequence:
"ncacn_ip_tcp" (Address: 00692ED8)
NetworkAddress: ""
(Address: 00692F38)
Endpoint:
"1120" (Address: 00693988)
The information displayed here will allow you to trace the call.
4. The network address is empty, which indicates the local machine. The endpoint is 1120. You need to determine which process hosts this endpoint. This can be done by
passing this endpoint number to the !rpcexts.getendpointinfo extension, as follows:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 960 of 1651

0:001> !rpcexts.getendpointinfo 1120

Searching for endpoint info ...
PID CELL ID
ST PROTSEQ
ENDPOINT
-------------------------------------------0278 0000.0001 01
TCP 1120
5. From the preceding information, you can see that process 0x278 contains this endpoint. You can determine if this process knows anything about this call by using the !
rpcexts.getcallinfo extension. This extension needs four parameters: CallID, IfStart, and ProcNum (which were found in step 3), and the ProcessID of 0x278:
0:001> !rpcexts.getcallinfo 1 19bb5061 0 278
Searching for call info ...
PID CELL ID
ST PNO IFSTART TIDNUMBER CALLFLAG CALLID
LASTTIME CONN/CLN
---------------------------------------------------------------------------0278 0000.0004 02 000 19bb5061 0000.0002 00000001 00000001 00072c09 0000.0003
6. The information in step 5 is useful, but somewhat abbreviated. The cell ID is given in the second column as 0000.0004. If you pass the process ID and this cell number
to the !rpcexts.getdbgcell extension, you will see a more readable display of this cell:
0:001> !rpcexts.getdbgcell 278 0.4
Getting cell info ...
Call
Status: Dispatched
Procedure Number: 0
Interface UUID start (first DWORD only): 19BB5061
Call ID: 0x1 (1)
Servicing thread identifier: 0x0.2
Call Flags: cached
Last update time (in seconds since boot):470.25 (0x1D6.19)
Owning connection identifier: 0x0.3
This shows that the call is in state "dispatched", which means is has left the RPC Run-Time. The last update time is 470.25. You can learn the current time by using
the !rpcexts.rpctime extension:
0:001> !rpcexts.rpctime
Current time is: 6003, 422
This shows that the last contact with this call was approximately 5533 seconds ago, which is about 92 minutes. Thus, this must be a stuck call.
7. As a last step before you attach a debugger to the server process, you can isolate the thread that should currently service the call by using the Servicing thread identifier.
This is another cell number; it appeared in step 6 as "0x0.2". You can use it as follows:
0:001> !rpcexts.getdbgcell 278 0.2
Getting cell info ...
Thread
Status: Dispatched
Thread ID: 0x1A4 (420)
Last update time (in seconds since boot):470.25 (0x1D6.19)
Now you know that you are looking for thread 0x1A4 in process 0x278.
It is possible that the thread was making another RPC call. If necessary, you can trace this call by repeating this procedure.
Note This procedure shows how to find the server thread if you know the client thread. For an example of the reverse technique, see Identifying the Caller From the Server
Thread.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Tracking Contention in the Server Process

In order to service incoming requests, RPC will maintain a set of worker threads. Ideally, the number of threads will be small. However, this ideal situation has only been seen
in lab environments, where the server manager routines are carefully tuned. In a real situation, the number of threads will vary depending on server workload, but it can be
anywhere from 1 to 50.
If the number of worker threads is above 50, you may have excessive contention in the server process. Common causes of this are indiscriminate use of the heap, memory
pressure, or serializing most activities in a server through a single critical section.
To see the number of threads in a given server process, use the !rpcexts.getthreadinfo extension, or use DbgRpc with the -t switch. Supply the process ID (in the following
example, 0xC4):
D:\wmsg>dbgrpc -t -P c4
Searching for thread info ...
PID CELL ID
ST TID
LASTTIME
----------------------------------00c4 0000.0004 03 0000011c 000f164f
00c4 0000.0007 03 00000120 008a6290

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

00c4
00c4
00c4
00c4
00c4

0000.0015
0000.0026
0000.002d
0000.0030
0000.0034

Page 961 of 1651

03
03
03
03
03

0000018c
00000264
00000268
0000026c
00000388

008a6236
0005c443
000265bb
000f1d32
007251e9

In this case, there are only seven worker threads, which is reasonable.
If there are over 100 threads, a debugger should be attached to this process and the cause investigated.
Note Running queries such as dbgrpc -t remotely is expensive to the server and the network. If you use this query in a script, you should make sure this command is not run
too often.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Checking for Stuck Threads

RPC needs its worker threads available in order to perform normally. A common problem is that some component in the same process will deadlock while holding one of the
global critical sections (for example, loader lock or heap lock). This will cause many threads to hang very possibly including some RPC worker threads.
If this occurs, the RPC server will not respond to the outside world. RPC calls to it will return RPC_S_SERVER_UNAVAILABLE or RPC_S_SERVER_TOO_BUSY.
A similar problem can result if a faulty driver prevents IRPs from completing and reaching the RPC server.
If you suspect that one of these problems may be occurring, use DbgRpc with the -t switch (or use the !rpcexts.getthreadinfo extension). The process ID should be used as a
parameter. In the following example, assume the process ID is 0xC4:
D:\wmsg>dbgrpc -t -P c4
Searching for thread info ...
PID CELL ID
ST TID
LASTTIME
----------------------------------00c4 0000.0004 03 0000011c 000f164f
00c4 0000.0007 03 00000120 008a6290
00c4 0000.0015 03 0000018c 008a6236
00c4 0000.0026 03 00000264 0005c443
00c4 0000.002d 03 00000268 000265bb
00c4 0000.0030 03 0000026c 000f1d32
00c4 0000.0034 03 00000388 007251e9
The TID column gives the thread ID for each thread. The LASTTIME column contains the time stamp of the last change in state for each thread.
Whenever the server receives a request, at least one thread will change state, and its time stamp will be updated. Therefore, if an RPC request is made to the server and the
request fails but none of the time stamps change, this indicates that the request is not actually reaching the RPC Run-Time. You should investigate the cause of this.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Identifying the Caller From the Server Thread

It is possible to determine what made a given RPC call, even if the only information you have is the server thread that serviced the call.
This can be very useful for example, to find out who passed invalid parameters to an RPC call.
Depending on which protocol sequence is used by this particular call, you can get varying degrees of detail. Some protocols (such as NetBios) do not have this information at
all.
Identifying the caller from the server thread
1. Start a user-mode debugger with the server thread as the target.
2. Get the process ID by using the | (Process Status) command:
0:001> |
0
id: 3d4 name: rtsvr.exe
3. Get the active calls in this process by using the !rpcexts.getcallinfo extension. (See the reference page for an explanation of the syntax.) You need to supply the process
ID of 0x3D4:
0:001> !rpcexts.getcallinfo 0 0 FFFF 3d4
Searching for call info ...

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

ACPI Debugging
This section includes:
The AMLI Debugger
Other ACPI Debugging Extensions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The AMLI Debugger

This section includes:
Introduction to the AMLI Debugger
Setting Up an AML Debugging Session
Basic AML Debugging
Using AMLI Debugger Extensions
Using AMLI Debugger Commands
AML Debugging Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Introduction to the AMLI Debugger

There are significant differences between debugging standard kernel-mode code and debugging an ACPI (Advanced Configuration and Power Interface) BIOS.
Whereas Windows and its drivers are composed of binary machine code compiled for a specific processor, the core of an ACPI BIOS is not in machine code. Rather, it is
stored as ACPI Machine Language (AML) and is processed by the Microsoft AML interpreter as it is run.
The Microsoft AMLI Debugger is a special debugging tool that can debug AML code. The AMLI Debugger is not actually a free-standing program. Rather, it consists of two
components. One component is the checked build of the Microsoft Windows ACPI driver (Acpi.sys). The other component is located in certain debugger extensions included
in the Debugging Tools for Windows package.
On Windows XP and later versions of Windows, the AMLI Debugger is completely 64-bit aware. No matter what processor is being used by the target computer or the host
computer, the AMLI Debugger will function correctly.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Up an AML Debugging Session

The AMLI Debugger resides within the checked build of Acpi.sys. In order to fully perform AML debugging, this driver must be installed on your target computer. The free
build of Acpi.sys does not contain the AMLI Debugger itself, although it does support some of the AMLI Debugger extensions.
If you are running the checked build of Windows on your target computer, then the checked driver is already installed.
If you are running the free build, you must either install the entire checked build of Windows, or simply install the checked version of Acpi.sys.
For instructions on how to install a full checked build or individual checked files, see the Windows Driver Kit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 965 of 1651

Debugging Tools for Windows

Basic AML Debugging

The AMLI Debugger supports two types of specialized commands: AMLI Debugger extensions and AMLI Debugger commands.
When you are performing AML debugging, you should carefully distinguish between two different kinds of prompts that will appear in the Debugger Command window:

When you see the kd> prompt, you are controlling the kernel debugger. All the standard kernel debugger commands and extensions are available. In addition, the
AMLI Debugger extensions are also available. In Windows 2000, these extensions have a syntax of !acpikd.amli command. In Windows XP and later versions of
Windows, these extensions have a syntax of !amli command. The AMLI Debugger commands are not available in this mode.
When you see the AMLI(? for help)-> prompt, you are controlling the AMLI Debugger. (When you are using WinDbg, this prompt will appear in the top pane of the
Debugger Command window, and an Input> prompt will appear in the bottom pane.) From this prompt, you can enter any AMLI Debugger command. You can also
enter any AMLI Debugger extension; these extensions should not be prefixed with !amli. The standard kernel debugging commands are not available in this mode.
When you see no prompt at all, the target computer is running.

At the beginning of any debugging session, you should set your AMLI Debugger options with the !amli set extension. The verboseon, traceon, and errbrkon options are
also very useful. When your target computer is running Windows XP or later, you should always activate the spewon option. See the extension reference page for details.
There are several ways for the AMLI Debugger to become active:

If a breakpoint in AML code is encountered, ACPI will break into the AMLI Debugger.
If a serious error or exception occurs within AML code (such as an int 3), ACPI will break into the AMLI Debugger.
If the errbrkon option has been set, any AML error will cause ACPI to break into the AMLI Debugger.
If you want to deliberately break into the AMLI Debugger, use the !amli debugger extension and then the g (Go) command. The next time any AML code is executed
by the interpreter, the AMLI Debugger will take over.

When you are at the AMLI Debugger prompt, you can type q to return to the kernel debugger, or type g to resume normal execution.
The following extensions are especially useful for AML debugging:

The !amli dns extension displays the ACPI namespace for a particular object, the namespace tree subordinate to that object, or even the entire namespace tree. This
command is especially useful in determining what a particular namespace object is whether it is a method, a fieldunit, a device, or another type of object.
The !amli find extension takes the name of any namespace object and returns its full path.
The !amli u extension unassembles AML code.
The !amli lc extension displays brief information about all active ACPI contexts.
The !amli r extension displays detailed information about the current context of the interpreter. This is useful when the AMLI Debugger prompt appears after an error is
detected.
Breakpoints can be set and controlled within AML code. Use !amli bp to set a breakpoint, !amli bc to clear a breakpoint, !amli bd to disable a breakpoint, !amli be to
re-enable a breakpoint, and !amli bl to list all breakpoints.
The AMLI Debugger is able to run, step, and trace through AML code. Use the run, p, and t commands to perform these actions.

For a full list of extensions and commands, see Using AMLI Debugger Extensions and Using AMLI Debugger Commands .
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using AMLI Debugger Extensions

In Windows XP and later versions of Windows, AMLI Debugger extension commands are contained in the extension module Kdexts.dll and use the following syntax:
kd> !amli command [parameters]
In Windows 2000, these extension commands are contained in Acpikd.dll and use the following syntax:
kd> !acpikd.amli command [parameters]
As with any extension module, after it has been loaded you can omit the acpikd prefix.
If you are at the AMLI Debugger prompt, you can execute any of these extension commands by simply entering the command name without the !amli prefix:
AMLI(? for help)-> command [parameters]
When you are at this prompt, the !amli debugger command is not available (because it would be meaningless). Also, the help command ( ? ) at this prompt shows all AMLI
Debugger extensions and commands, while the !amli ? extension only displays help on actual extensions.
Action
Display Help
Set AML Breakpoint
List AML Breakpoints
Disable AML Breakpoint
Enable AML Breakpoint
Clear AML Breakpoint
Enter AMLI Debugger

Extension Command
!amli ?
!amli bp
!amli bl
!amli bd
!amli be
!amli bc
!amli debugger

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 966 of 1651

Display Event Log

!amli dl
Clear Event Log
!amli cl
Display Heap
!amli dh
Display Data Object
!amli do
!amli ds
Display Stack
Display Namespace Object !amli dns
!amli find
Find Namespace Object
Display Nearest Method
!amli ln
!amli lc
List All Contexts
Display Context Information !amli r
!amli u
Unassemble AML Code
Set AMLI Debugger Options !amli set

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using AMLI Debugger Commands

The following commands can be issued from the AMLI Debugger prompt.
General Category

Specific Action

AMLI Debugger
Commands
Controlling the Debugger
Continue Execution
g
Break to Kernel Debugger q
Controlling AML Execution
Run Method
run
Step Over AML Code
p
Trace Into AML Code
t
Controlling Trace Mode Settings Configure Trace Mode
trace
Notifying a Namespace Object
Notify Namespace Object notify
Displaying the Object Count Table Display Object Count Table dc
Accessing Memory
Display Data
d
Display Data Bytes
db
Display Data Words
dw
Display Data DWORDs
dd
Display Data String
da
Edit Memory
e
Accessing Ports
Read Byte from Port
i
Read Word from Port
iw
Read DWORD from Port id
Write Byte to Port
o
Write Word to Port
ow
Write DWORD to Port
od
Displaying Help
Display Help
?

Controlling the Debugger

These commands exit the AMLI Debugger. The g command will resume normal execution of the target computer, and the q command will freeze the target computer and
break into the kernel debugger.
g
q

Controlling AML Execution

These commands allow you to run or step through AML methods. The run command begins execution at a specified point. The p and t commands allow you to step through
one instruction at a time. If a function call is encountered, the p command treats the function as a single step, while the t command traces into the new function one instruction
at a time.
run MethodName [ArgumentList]
run CodeAddress [ArgumentList]
p
t
MethodName
Specifies the full path and name of a method. Execution will start at the beginning of this method's memory location.
CodeAddress
Specifies the address where execution is to begin.
ArgumentList

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 967 of 1651

Specifies a list of arguments to be passed to the method. Each argument must be an integer. Multiple arguments should be separated with spaces.

Controlling Trace Mode Settings

The trace command controls the AML interpreter's trace mode settings. If this command is used with no parameters, the current trace mode settings are displayed.
trace [trigon|trigoff] [level=Level] [add=TPStrings] [zap=TPNumbers]
trigon
Activates trace trigger mode.
trigoff
Deactivates trace trigger mode.
Level
Specifies the new setting for the trace level.
TPStrings
Specifies one or more trigger points to be added. Each trigger point is specified by name. Multiple trigger point strings should be separated by commas.
TPNumbers
Specifies one or more trigger points to be deleted. Each trigger point is specified by number. Multiple trigger point numbers should be separated by commas. To see a list
of trigger point numbers, use the trace command with no parameters.

Notifying a Namespace Object

The notify command sends a notification to an ACPI namespace object. The notification will be placed in the specified object's queue.
notify ObjectName Value
notify ObjectAddress Value
ObjectName
Specifies the full namespace path of the object to be notified.
ObjectAddress
Specifies the address of the object to be notified.
Value
Specifies the notification value.

Displaying the Object Count Table

The dc command displays the memory object count table.
dc

Accessing Memory
The memory access commands allow you to read and write to memory. When reading memory, you can choose the size of the memory units with the db, dw, dd, or da
command. A simple d command displays memory in the most recently-chosen units. If this is the first display command used, byte units are used.
If no address or method is specified, display will begin where the previous display command ended.
These commands have the same effect as the standard kernel debugger memory commands; they are duplicated within the AMLI Debugger for easy access.
d[b|w|d|a] [ [l=Length] [ Method | [%%]Address ] ]
e [%%]Address DataList
b
Specifies that the data should be displayed in byte units.
w
Specifies that the data should be displayed in word (16-bit) units.
d
Specifies that the data should be displayed in DWORD (32-bit) units.
a
Specifies that the data should be displayed as a string. The data is displayed as ASCII characters. The display terminates when a NULL character is read, or when Length
characters have been displayed.
Length
Specifies the number of bytes to be displayed. Length must be a hexadecimal number (without an 0x prefix). If Length is omitted, the default display size is 0x80 bytes.
Method
Specifies the full path and name of a method. The display will start at the beginning of this method's memory location.
Address
Specifies the memory address where reading or writing will begin. If the address is prefixed with two percent signs (%%), it is interpreted as a physical address.
Otherwise, it is interpreted as a virtual address.
DataList
Specifies the data to be written to memory. Each item in the list can be either a hexadecimal byte or a string. When a string is used, it must be enclosed in quotation
marks. Multiple items should be separated by spaces.

Accessing Ports
The port commands allow you to send output or receive input from a data port. The i and o commands transfer single bytes, the iw and ow commands transfer words (16 bits),
and the id and od commands transfer DWORDS (32 bits).
These commands have the same effect as the standard kernel debugger port commands; they are duplicated within the AMLI Debugger for easy access.
i Port

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 968 of 1651

iw Port
id Port
o Port DataForPort
ow Port DataForPort
od Port DataForPort
Port
Specifies the address of the port to be accessed. The port size must match the command chosen.
DataForPort
Specifies the data to be written to the port. The size of this data must match the command chosen.

Displaying Help
This command displays help text for the AMLI Debugger commands.
? [Command]
Command
Specifies the command for which to display help. If this is omitted, a list of all AMLI Debugger commands and AMLI Debugger extensions is displayed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

AML Debugging Examples

Here are examples that illustrate how to get started with AML debugging.
Investigating a Frozen Computer
If the target computer has frozen and you suspect it may be an ACPI problem, begin by using the !amli lc extension to display all the active contexts:
kd> !amli lc
*Ctxt=ffffffff8128d000, ThID=ffffffff81277880, Flgs=----R----, pbOp=ffffffff8124206c, Obj=\_SB.PCI0.ISA0.FDC0._CRS
If no contexts are displayed, the error is probably not ACPI-related.
If there are contexts shown, look for the one marked with an asterisk. This is the current context (the one that is being executed by the interpreter at the present moment).
In this example, the target computer is running Windows XP or Windows Server 2003 on a 32-bit processor. Therefore all addresses are cast to 64 bits, producing a gratuitous
FFFFFFFF in the high 32 bits. The abbreviation pbOp indicates the instruction pointer ("pointer to binary op codes"). The Obj field gives the full path and name of the
method as it appears in the ACPI tables. For a description of the flags, see !amli lc.
You can use the !amli u command to disassemble the _CRS method as follows:
kd> !amli u \_SB.PCI0.ISA0.FDC0._CRS
ffffffff80e4a535
ffffffff80e4a540
ffffffff80e4a54b
ffffffff80e4a559
ffffffff80e4a567

:
:
:
:
:

CreateDWordFieldCRES, 0x76, RAMT)

CreateDWordField(CRES, 0x82, PCIT)
Add(MLEN(), 0x100000, RAMT)
Subtract(0xffe00000, RAMT, PCIT)
Return(CRES)

Breaking Into the AMLI Debugger

The !amli debugger command causes the AML interpreter to break into the AMLI Debugger the next time any AML code is executed.
After the AMLI Debugger prompt appears, you can use any of the AMLI Debugger commands. You can also use !amli extension commands without prefixing them with "!
amli":
kd> !amli debugger
kd> g
AMLI(? for help)-> find _crs
\_SB.LNKA._CRS
\_SB.LNKB._CRS
\_SB.LNKC._CRS
\_SB.LNKD._CRS
\_SB.PCI0._CRS
\_SB.PCI0.LPC.NCP._CRS
\_SB.PCI0.LPC.PIC._CRS
\_SB.PCI0.LPC.TIME._CRS

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 969 of 1651

\_SB.PCI0.LPC.IDMA._CRS
\_SB.PCI0.LPC.RTC._CRS
\_SB.PCI0.LPC.SPKR._CRS
\_SB.PCI0.LPC.FHUB._CRS
\_SB.PCI0.SBD1._CRS
\_SB.PCI0.SBD2._CRS
\_SB.MBRD._CRS
AMLI(? for help)-> u \_SB.PCI0._CRS
ffffffff80e4a535
ffffffff80e4a540
ffffffff80e4a54b
ffffffff80e4a559
ffffffff80e4a567

:
:
:
:
:

CreateDWordFieldCRES, 0x76, RAMT)

CreateDWordField(CRES, 0x82, PCIT)
Add(MLEN(), 0x100000, RAMT)
Subtract(0xffe00000, RAMT, PCIT)
Return(CRES)

Using Breakpoints
In the following example, you will break into the AMLI Debugger before the method _BST is executed.
Even if you have located a _BST object, you should verify that it is indeed a method. You can use the !amli dns extension to do this.
kd> !amli dns /s \_sb.pci0.isa.bat1._bst
ACPI Name Space: \_SB.PCI0.ISA.BAT1._BST (c29c2044)
Method(_BST:Flags=0x0,CodeBuff=c29c20a5,Len=103)
Now you can use the !amli bp command to place the breakpoint:
kd> !amli bp \_sb.pci0.isa.bat1._bst
You may also want to place breakpoints within the method. You could use the !amli u command to disassemble _BST and then place a breakpoint on one of its steps:
kd> !amli u _sb.pci0.isa.bat1._bst
ffffffffc29c20a5:
ffffffffc29c20c0:
ffffffffc29c20d7:
ffffffffc29c20ee:
ffffffffc29c2107:

Acquire(\_SB_.PCI0.ISA_.EC0_.MUT1, 0xffff)
Store("CMBatt - _BST.BAT1", Debug)
\_SB_.PCI0.ISA_.EC0_.CPOL()
Release(\_SB_.PCI0.ISA_.EC0_.MUT1)
Return(PBST)

kd> !amli bp c29c20ee

Responding to a Triggered Breakpoint
In the following example, the method _WAK is running and then encounters a breakpoint:
Running \_WAK method
Hit Breakpoint 0.
Use the !amli ln extension to see the nearest method to the current program counter. The following example is taken from a Windows 2000 system, so the addresses are
shown in 32-bit form:
kd> !amli ln
c29accf5: \_WAK
The !amli lc extension displays all the active contexts:
kd> !amli lc
Ctxt=c18b6000, ThID=00000000, Flgs=A-QC-W----, pbOp=c29bf8fe, Obj=\_SB.PCI0.ISA.EC0._Q09
*Ctxt=c18b4000, ThID=c15a6618, Flgs=----R-----, pbOp=c29accf5, Obj=\_WAK
This shows that the active contexts are associated with the methods _Q09 and _WAK. The current context is _WAK.
Now you can use the !amli r command to display more details about the current context. From this you can see useful thread and stack information, as well as arguments
passed to _WAK and the local data objects.
kd> !amli r
Context=c18b4000*, Queue=00000000, ResList=00000000
ThreadID=c15a6618, Flags=00000010
StackTop=c18b5eec, UsedStackSize=276 bytes, FreeStackSize=7636 bytes
LocalHeap=c18b40c0, CurrentHeap=c18b40c0, UsedHeapSize=88 bytes
Object=\_WAK, Scope=\_WAK, ObjectOwner=c18b4108, SyncLevel=0
AsyncCallBack=ff06b5d0, CallBackData=0, CallBackContext=c99efddc
MethodObject=\_WAK
c18b40e4: Arg0=Integer(:Value=0x00000001[1])
c18b5f3c: Local0=Unknown()
c18b5f54: Local1=Unknown()
c18b5f6c: Local2=Unknown()
c18b5f84: Local3=Unknown()

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

c18b5f9c:
c18b5fb4:
c18b5fcc:
c18b5fe4:
c18b4040:

Page 970 of 1651

Local4=Unknown()
Local5=Unknown()
Local6=Unknown()
Local7=Unknown()
RetObj=Unknown()

Tracing, Stepping, and Running AML Code

If you want to trace through the code, you can turn on full tracing information by using the !amli set extension as follows:
kd> !amli set spewon verboseon traceon
Now you can step through the AML code, watching the code execute line by line. The p command steps over any function calls. The t command will step into function calls.
AMLI(? for help)-> p
c29bfcb7: Store(\_SB_.PCI0.ISA_.ACAD.CHAC(SEL0=0x10e1)
c29c17b1: {
c29c17b1: | Store(LGreater(And(Arg0=0x10e1,0xf0,)=0xe0,0x80)=0xffffffff,Local0)=0xffffffff
AMLI(? for help)-> p
c29c17bb:
c29c17ce:
c29c17ce:
c29c17d0:
c29c17d0:

| If(LNot(LEqual(Local0=0xffffffff,ACP_=0xffffffff)=0xffffffff)=0x0)
| {
| | Return(Zero)
| }
},Local1)=0x0

AMLI(? for help)-> t

c29bfcd4: Store(\_SB_.PCI0.ISA_.BAT1.CHBP(SEL0=0x10e1)
c29c293d: {
c29c293d: | Store("CMBatt - CHBP.BAT1",Debug)String(:Str="CMBatt - CHBP.BAT1")="CMBatt - CHBP.BAT1"
You may also run methods from within the AMLI Debugger if you choose. For example, you might evaluate the status of the LNKA device by running its control method
_STA:
AMLI(? for help)-> run \_sb.lnka._sta
PCI OpRegion Access on region c29b2268 device c29b2120
\_SB.LNKA._STA completed successfully with object data:
Integer(:Value=0x0000000b[11])

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Other ACPI Debugging Extensions

The following extension commands are useful for debugging problems with an Advanced Configuration and Power Interface (ACPI) BIOS:

!acpicache displays all of the ACPI tables cached by the hardware application layer (HAL)
!acpiinf displays information on the configuration of the ACPI
!acpiirqarb displays the contents of the ACPI IRQ arbiter structure
!facs displays a Firmware ACPI Control Structure
!fadt displays a Fixed ACPI Description Table
!mapic displays an ACPI Multiple APIC Table
!nsobj displays an ACPI namespace object
!nstree displays a section of the ACPI namespace tree
!rsdt displays the ACPI Root System Description Table

For a complete list of ACPI-related extensions, see !acpikd.help.

For details on the !amli xxx extensions, see The AMLI Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

NDIS Debugging
This section includes:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 971 of 1651

Overview of NDIS Debugging

Preparing for NDIS Debugging
Enabling NDIS Debug Tracing
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Overview of NDIS Debugging

The two primary tools for debugging a network driver are debug tracing and the Network Driver Interface Specification (NDIS) extensions. For more information on debug
tracing, see Enabling NDIS Debug Tracing. For more information on the NDIS debugging extensions, see NDIS Extensions, which provides a complete list of the extension
commands found in the extension module Ndiskd.dll. The Windows 2000 version of this extension module appears in the w2kfre and w2kchk directories. The Windows XP
and later version of this extension module appear in the winxp directory.
An additional tool for debugging a network driver is the collection of regular debugging extensions, which are useful for obtaining debugging information. For example,
entering !stacks 2 ndis! displays all threads in the stack beginning with ndis!. This information can be useful for debugging hangs and stalls.
There is also an NDIS-specific bug check code, bug check 0x7C (BUGCODE_NDIS_DRIVER). For a complete list of its parameters, see Bug Check 0x7C.
Another useful tool for testing an NDIS driver is NDIS Verifier. For more information, consult the NDIS Verifier topic in the Windows Driver Kit (WDK) documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Preparing for NDIS Debugging

To debug NDIS components, a checked version of Ndis.sys is required on the target computer. However, instead of installing an entire checked-build operating system, you
can copy the checked version of Ndis.sys onto an otherwise free-build operating system. Before you copy the checked version of Ndis.sys to the target computer, you must
disable Windows File Protection (WFP). To ensure that WFP is disabled, start the operating system in safe mode.
The NDIS symbols are publicly available on the Microsoft symbol store. For details on how to access this, see Microsoft Public Symbols.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enabling NDIS Debug Tracing

NDIS debug tracing is the primary method for debugging NDIS drivers. When you set up NDIS debug tracing, you are actually enabling one or more levels of DbgPrint
statements with NDIS. The resulting information is sufficient for debugging most network driver problems.
Debug tracing can be enabled in two ways: from a debugger, or by editing the registry. To enable debug tracing from the debugger, use the two NDIS extensions !
ndiskd.dbglevel and !ndiskd.dbgsystems. For each extension you must provide appropriate arguments. To enable debug tracing by editing the registry, you must set the
appropriate registry values; for details, see Enabling NDIS Debug Tracing By Setting Registry Values.
The registry method works even if the host computer does not have the checked version of the Ndis.sys symbols installed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enabling NDIS Debug Tracing By Setting Registry Values

You can enable different levels of debug tracing in various NDIS components by editing the registry. Typically, you should add the following entries and values to the
HKLM\SYSTEM\CurrentControlSet\Services\NDIS\Parameters registry key:
"DebugLevel"=dword:00000000
"DebugSystems"=dword:000030F3
"DebugBreakPoint"=dword:00000001

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 972 of 1651

The following values are acceptable for DebugBreakPoint, DebugLevel and DebugSystems:
DebugBreakPoint
Controls whether an NDIS driver will automatically break into the debugger. If this value is set to 1, NDIS will break into the debugger when a driver enters Ndis.sys's
DriverEntry function.
DebugLevel
Selects the level or amount of debug tracing in the NDIS components that you select with the DebugSystems value. This corresponds to using the !ndiskd.dbglevel
extension. The following values specify levels that you can select:
Level
Description
Value
DBG_LEVEL_INFO All available debug information. This is the highest level of trace.
0x00000000
DBG_LEVEL_LOG Log information.
0x00000800
DBG_LEVEL_WARN Warnings.
0x00001000
DBG_LEVEL_ERR
Errors.
0x00002000
DBG_LEVEL_FATAL Fatal errors, which can cause the operating system to crash. This is the lowest level of trace. 0x00003000
DebugSystems
Enables debug tracing for specified NDIS components. This corresponds to using the !ndiskd.dbgsystems extension. The following values specify the NDIS components
that you can select:
Component
Description
Value
DBG_COMP_INIT
Handles adapter initialization.
0x00000001
DBG_COMP_CONFIG
Handles adapter configuration.
0x00000002
DBG_COMP_SEND
Handles sending data over the network.
0x00000004
DBG_COMP_RECV
Handles receiving data from the network.
0x00000008
DBG_COMP_PROTOCOL Handles protocol operations.
0x00000010
DBG_COMP_BIND
Handles binding operations.
0x00000020
DBG_COMP_BUSINFO
Handles bus queries.
0x00000040
DBG_COMP_REG
Handles registry operations.
0x00000080
DBG_COMP_MEMORY
Handles memory management.
0x00000100
DBG_COMP_FILTER
Handles filter operations.
0x00000200
DBG_COMP_REQUEST
Handles requests.
0x00000400
DBG_COMP_WORK_ITEM Handles work-item operations.
0x00000800
DBG_COMP_PNP
Handles Plug and Play operations.
0x00001000
DBG_COMP_PM
Handles power management operations.
0x00002000
DBG_COMP_OPENREF
Handles operations that open reference objects.
0x00004000
DBG_COMP_LOCKS
Handles locking operations.
0x00008000
DBG_COMP_RESET
Handles resetting operations.
0x00010000
DBG_COMP_WMI
Handles Windows Management Instrumentation operations. 0x00020000
DBG_COMP_CO
Handles Connection-Oriented NDIS.
0x00040000
DBG_COMP_REF
Handles reference operations.
0x00080000
DBG_COMP_ALL
Handles all NDIS components.
0xFFFFFFFF
You can select more than one NDIS component. If more than one component is selected, combine the data values with an OR operator. For example, to select
DBG_COMP_PNP, DBG_COMP_PM, DBG_COMP_INIT and DBG_COMP_CONFIG, you would combine the corresponding values (0x1000, 0x2000, 0x1, and 0x2)
to obtain the value 0x3003, and then set it in the registry thus:
"DebugSystems"=dword:00003003
Whenever you change registry values for debug tracing, you must restart your computer for the new settings to take effect.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel Streaming Debugging

This section includes:
Overview of Kernel Streaming Debugging
Analyzing a Video Stream Stall
Analyzing a Capture Stall
Live Local Debugging
Graph Analysis with Unloadable Modules
Using !ks.graph
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 973 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Overview of Kernel Streaming Debugging

Kernel streaming debugging extensions can be found in the extension module Ks.dll.
You can use Ks.dll to help debug KS, AVStream, port class and stream class drivers.
For a complete list of the extension commands in Ks.dll, see Kernel Streaming Extensions (Ks.dll).
If you wish to use these extensions with Windows 2000, you must copy Ks.dll from the kdexts directory to the w2kfre directory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Video Stream Stall

This section shows how to analyze a video stream stall. All sample output is generated from an AVStream minidriver after an independent hardware vendor (IHV) driver bug
has been introduced.
Determining the Cause
Debugging a Processing Stall
Using Logging to Track Important Events
Interpreting Bug Check 0xCB
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Determining the Cause of a Video Stream Stall

There are two basic causes for a video stream stall:

A hang. Either a user-mode thread or a kernel-mode thread is not being released by the driver.
A stall. This is the result of a problem with a component in the streaming path. Some possibilities include:
The capture driver is not completing packets. In this case, either a driver component or the hardware might be the source of the stall.
The capture driver has no packets to complete. In this case, the buffers might be stalled in a codec or other downstream component.

If you can reproduce the problem, attach a debugger at this point to determine which is the actual cause.
To determine if the problem is a hang
1. Attach a user-mode debugger to the application and look for blocked user-mode threads.
2. Determine whether the application is responsive. Can the graph be paused? Can the graph be stopped? Does streaming restart if the graph is stopped and restarted?
3. If the application is non-responsive, attempt to end the task by using Task Manager. If this fails, there is a kernel-mode hang.
To determine if the problem is a stall
1. Determine where the samples are in the graph. This can be done locally or in a kernel-mode debugging session.
2. Determine whether samples are flowing downstream. If you can reproduce the bug in GraphEdit, place an intermediate filter in the graph to display samples.
3. Determine if the processing routine is being called. This can be done by attaching a kernel-mode debugger and setting a breakpoint in this routine.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Processing Stall

Begin by finding the relevant pin. In a hypothetical case, the relevant video capture pin has address 8160DDE0, so we use the !ks.dump extension command on this address to
get more details:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 974 of 1651

kd> !ks.dump 8160DDE0 7

Pin object 8160DDE0 [CKsPin = 8160DD50]
DeviceState
KSSTATE_RUN
ClientState
KSSTATE_RUN
CKsPin object 8160DD50 [KSPIN = 8160DDE0]
State
KSSTATE_RUN
Processing Mutex
8160DFD0 is not held
And Gate &
8160DF88
And Gate Count
1
First, determine if the pin is in the appropriate state and whether the processing mutex is being held by another thread. In this case, the pin state is KSSTATE_RUN, as it
should be, and the processing mutex is not being held, so we next use the !ks.dumpqueue extension to determine if there are frames available:
kd> !ks.dumpqueue 8160DDE0 7
Queue 8172D5D8:
Frames Received : 763
Frames Waiting
: 5
...<this part of display not shown>...
Queue 8172D5D8:
Frame Header 81B77E60:
Irp = 816EE008
Refcount = 1
Frame Header 81A568D0:
Irp = 816DE008
Refcount = 0
Frame Header 81844ED8:
Irp = FFA0F650
Refcount = 0
Frame Header 8174B0B0:
Irp = FFABB460
Refcount = 0
Leading Edge:
Stream Pointer 8183EA58 [Public 8183EA90]:
Frame Header = 81B77E60
...<this part of display not shown>...
In the above partial display of the !ks.dumpqueue output, we see that there are five frames waiting, or available. Are these frames ahead of or behind the leading edge? In
the !ks.dumpqueue display, the frames are always listed from oldest to newest. The frame header of the leading edge matches that of the first frame listed, the oldest frame.
Thus all of the available frames are ahead of the leading edge.
If this were not the case, and instead all of the frames were behind the leading edge, and they had a reference count due to clone pointers, the problems most likely originate
with either the hardware or the driver's programming of hardware. Make sure that the hardware is signaling buffer completions (check interrupts and DPCs) and determine
that the driver is responding appropriately to those notifications (by deleting clones upon buffer completion, for example).
If, as in our example, all of the frames are ahead of the leading edge, the problem is almost certainly a software issue. Further information can be obtained by looking at the
pin's And gate.
Interpreting the And Gate
The pin's And gate controls processing. If the gate count is one, processing can occur. Obtain the current status of the And gate by using the !ks.dump extension:
kd> !ks.dump 8160DDE0 7
Pin object 8160DDE0 [CKsPin = 8160DD50]
DeviceState
KSSTATE_RUN
ClientState
KSSTATE_RUN
CKsPin object 8160DD50 [KSPIN = 8160DDE0]
State
KSSTATE_RUN
Processing Mutex
8160DFD0 is not held
And Gate &
8160DF88
And Gate Count
1
Because the gate count is one, the And gate is open. In this case, investigate the following potential causes for the processing stall:

The process dispatch incorrectly returned STATUS_PENDING.

The data availability case is missing a KsPinAttemptProcessing call.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Logging to Track Important Events

In general, data is moved downstream only by triggering events, the minidriver's processing, and buffer completions. To isolate the cause of a hang or stall:

Check for mismatched KsGateXxx calls.

Check for omitted KsXxxAttemptProcessing calls.
Look for problems in code related to triggering events, including code that either references the pin flags for the problem stream or that calls KsPinAttemptProcessing.
Look for problems in the code related to the processing dispatch, in particular where it queues to hardware and where clone pointers are created.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 975 of 1651

Look for problems in the code related to the driver's deferred procedure call (DPC), especially where buffers are completed or any calls are made to
KsStreamPointerDelete.
Look for problems in the startup code for the stream.

The most effective way to collect this information is by logging everything in the affected region, including processing, buffer acquisition (such as cloning and programming
hardware), buffer release (such as deleting clones), and any gate manipulations. Most of this information is highly timing dependent and requires memory-based logging or
ETW.
To maintain a rolling memory-based log, use the following code:
typedef struct _LOGENTRY {
ULONG Tag;
ULONG Arg[3];
} LOGENTRY, *PLOGENTRY;
#define LOGSIZE 2048
LONG g_LogCount;
LOGENTRY g_Log [LOGSIZE];
#define LOG(tag,arg1,arg2,arg3) do { \
LONG i = InterlockedIncrement (&g_LogCount) % LOGSIZE; \
g_Log [i].Tag = tag; \
g_Log [i].Arg [0] = (ULONG)(arg1); \
g_Log [i].Arg [1] = (ULONG)(arg2); \
g_Log [i].Arg [2] = (ULONG)(arg3); \
} while (0)
Then, use a simple "dc g_Log" to view the contents of the g_Log array in the debugger.
The following example uses the above memory-based scheme to determine the cause of a processing stall. Output is from an AVStream streaming scenario in graphedt. The
following minidriver events were logged:
Abbreviation Description
Strt
This event occurs when the minidriver first queues buffers for the device from within the minidriver's Start dispatch.
Prc<
This event occurs at the start of the minidriver's Process dispatch.
AddB
This event occurs when the minidriver queues buffers to the device from within its Process dispatch.
DPC<
This event occurs at the start of the minidriver's CallOnDPC. It indicates buffer completion.
Atmp
This event occurs when the minidriver calls from within the DPC to KsPinAttemptProcessing.
Dele
This event occurs when the minidriver calls from within the DPC to delete a clone stream pointer.
Log excerpts are as follows:
f9494b80
f9494b90
f9494ba0
f9494bb0
f9494bc0
f9494bd0
f9494be0
f9494bf0
f9494c00
f9494c10

3c435044
656c6544
706d7441
3c637250
42646441
3c435044
656c6544
706d7441
3c637250
42646441

816e2c90
816e2c90
816e2c90
819c1f00
819c1f00
816e2c90
816e2c90
816e2c90
819c1f00
819c1f00

00000000
81750260
ffa4d418
00000000
ffa2eb08
00000000
ffa80348
ffa4d418
00000000
ffa3d9b8

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000

DPC<.,n.........
Dele.,n.`.u.....
Atmp.,n.........
Prc<............
AddB............
DPC<.,n.........
Dele.,n.H.......
Atmp.,n.........
Prc<............
AddB............

This first log excerpt is representative of the normal streaming state. In the first line, the minidriver's CallOnDPC is called to complete a buffer (DPC<). The buffer is deleted
(Dele), and KsPinAttemptProcessing is called to move the leading edge forward, if there are any unprocessed buffers in the queue (Atmp). In this case, there were, as can be
seen by the call to the process dispatch (Prc<). More buffers are added to the queue (AddB), and the whole scenario repeats.
This next excerpt includes the last entries in the log right before the stall occurred.
f949b430
f949b440
f949b450
f949b460
f949b470
f949b480
f949b490
f949b4a0
f949b4b0
f949b4c0
f949b4d0
f949b4e0

3c435044
656c6544
706d7441
3c435044
656c6544
706d7441
3c435044
656c6544
706d7441
3c435044
656c6544
706d7441

816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90
816e2c90

00000000
ffac4de8
ffa4d418
00000000
816ffc80
ffa4d418
00000000
ffa80348
ffa4d418
00000000
8174e1c0
ffa4d418

00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000
00000000

DPC<.,n.........
Dele.,n..M......
Atmp.,n.........
DPC<.,n.........
Dele.,n...o.....
Atmp.,n.........
DPC<.,n.........
Dele.,n.H.......
Atmp.,n.........
DPC<.,n.........
Dele.,n...t.....
Atmp.,n.........

In this example, several buffers are being completed (indicated by the repeated instances of DPC<), but there are no unprocessed buffers in the queue, so the process dispatch
is not being called (indicated by the absence of Prc<). In fact, all of the processed buffers in the queue have been completed, apparently before any new unprocessed buffers
could be added. Because the application is already running (so that Start will not be called) and no calls are being made to CallOnDPC (because there are no processed
buffers ready to be completed), any new buffers are apparently accumulating ahead of the leading edge, waiting to be processed, with nothing initiating processing.
The problem is that the KSPIN_FLAG_DO_NOT_INITIATE_PROCESSING flag has been set. When this flag is set, processing occurs only through a call to Start or
CallOnDPC. If this flag is not set, processing will be initiated whenever new buffers are added to the queue.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 976 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Interpreting Bug Check 0xCB

The most common bug check code associated with debugging a video stream stall is Bug Check 0xCB (DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS). For a detailed
list of its parameters, see Bug Check 0xCB.
The message displayed when the bug check occurs will point to Ks.sys as the cause.
Use !analyze -v to get detailed debugging information.
BugCheck CB, {f90c6ae0, f9949215, 81861788, 26}
Probably caused by : ks.sys ( ks!KsProbeStreamIrp+333 )
As suggested, use !analyze v to get more detailed information.
kd> !analyze -v
DRIVER_LEFT_LOCKED_PAGES_IN_PROCESS (cb)
Caused by a driver not cleaning up completely after an I/O.
When possible, the guilty driver's name (Unicode string) is printed on
the bugcheck screen and saved in KiBugCheckDriver.
Arguments:
Arg3: 81861788, A pointer to the MDL containing the locked pages.
Now, use the !search extension to find the virtual addresses that are associated with the MDL pointer.
kd> !search 81861788
Searching PFNs in range 00000001 - 0000FF76 for [FFFFFFFF81861788 - FFFFFFFF81861788]
Pfn
Offset
- - - - - - - - 000008A7 00000B0C
00000A04 00000224

00001732 000009B4

Hit
Va
- - - - - - - - 81861788 808A7B0C
16000001 80A04224

Pte
- - - - - - - - C020229C
C0202810

81861788 817329B4 C0205CC8

For each virtual address (VA) found, look for an IRP signature. Do this by using the dd command with the VA minus one DWORD.
kd> dd 808A7B0C-4 l4
808a7b08 f9949215 81861788 00000026 00000000
kd> $ Not an Irp
kd> dd 80A04224-4 l4
80a04220 00000000 00000000 00000000 00000000
kd> $ Not an Irp
kd> dd 817329B4-4 l4
817329b0 01900006 81861788 00000070 ffa59220
kd> $ Matches signature
After a VA with an IRP signature has been found, use the !irp extension to find out what driver is pending on this IRP.
kd> !irp 817329b0 7
Irp is active with 2 stacks 2 is current (= 0x81732a44)
Mdl = 81861788 System buffer = ffa59220 Thread 00000000: Irp stack trace.
>[ e, 0]
1 1 81a883c8 81ae6158 00000000-00000000
pending
\Driver\TESTCAP
Args: 00000070 00000000 002f4017 00000000
In this case, \Driver\TESTCAP is the likely cause of the bug check.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyzing a Capture Stall

The following is an artificially created scenario that simulates a capture stall. This is a particularly valuable scenario since similar situations frequently occur in stress testing.
The scenario is as follows:
The Windows recording component Sndrec32 is recording from the primary capture device, in this case a Creative SBLive wave device. For a period of time, it records
normally; however, the graph stalls at 8.50 seconds because we have explicitly caused portcls not to complete capture IRPs for purposes of this test.
The application shows running, but the stream position is not advancing. Position is halted at 8.50 seconds.
Since the primary capture device on this machine is a PCI sound card, first use the !ks.pciaudio command to try and determine a starting point. Use a flag value of 1 to

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 977 of 1651

request a display of all running streams:

kd> !pciaudio 1
1 Audio FDOs found:
Functional Device 8121c030 [\Driver\emu10k]
Wave Cyclic Streams:
Pin 812567c0 RUN [emu10k1m!CMiniportWaveCyclicStreamSBLive ff9ec7f8]
In this case, there is only one PCI audio device and it is serviced by the Intel emu10k driver (\Driver\emu10k). This driver currently has a single running stream
(0x812567C0). Now you can use !ks.graph to view the kernel graph. Set Level and Flags both to 7 to obtain maximum detail on the stall:
kd> !graph 812567c0 7 7
Attempting a graph build on 812567c0... Please be patient...
Graph With Starting Point 812567c0:
"emu10k" Filter ff9ebb98, Child Factories 5
Output Factory 0:
Pin 812567c0 (File 811c6630, -> "splitter" 811df960) Irps(q/p) = 8, 0
Queued: 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98
The above shows the details for factory 0. The emu10k output pin 0x812567C0 is connected to the splitter input pin 0x811DF960. There are eight IRPs queued to emu10k's
output pin. The output from !ks.graph continues as follows:
"splitter" Filter ffb18890, Child Factories 2
Output Factory 0:
Pin 811df430 (File ffa55f90) Irps(q/p) = 10, 0
Queued: ffadd008 ffa73b00 ffa1e998 811de310 ffa54370 ffaaf008 811dee70 81250e70 811de580 811de8c0
There are ten IRPs queued to splitter's output pin.
Input Factory 1:
Pin 811df960 (File 81187820, <- "emu10k" 812567c0) Irps(q/p) = 0, 8
Pending: 81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98
Splitter's input pin has no queued IRPs; however, it is waiting for the eight from emu10k to enter the queue.
Analyzing a Hung Graph From 812567c0:
Suspect Filters (For a Hung Graph):
"emu10k" Filter ff9ebb98 or class "PortCls Wave Cyclic" is suspect.
Reasons For This Analysis:
- No critical pin has less than 8 queued Irps
- Downstream "splitter" pin 811df960 is starved
Irps to check:
81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98
From this information, the analyzer suggests that either emu10k or WaveCyclic may be at fault. It also provides a list of the suspect IRPs; these are the IRPs that are queued to
emu10k's input pin. If any of those IRPs were to complete, splitter would copy data and complete an IRP and the graph would progress. For some reason, emu10k is not
completing those capture Irps.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Live Local Debugging

In Microsoft Windows XP and later operating systems, it is possible to do local kernel debugging by starting the kernel debugger (KD) or WinDbg with the kl command line
option:
kd [-y SymbolPath] -kl
or
windbg [-y SymbolPath] -kl
Local debugging does not require the machine to be booted with the /debug option.
Live local debugging is extremely useful for debugging issues that are difficult to reproduce when the debugger is attached; however, anything that requires knowledge of
time sensitive information, including packet, IRP, and SRB data, is unlikely to work unless the problem is a hang or a stall.
When performing local debugging, consider the following variables:

Overall states. For example, is the stream running? Is the stream paused?
Packet counts. For example, are there IRPs queued to the stream?
Changes in packet counts. Is the stream moving?
Changes in packet lists.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 978 of 1651

Hung kernel threads.

Consider the last of these.

Examining a Hung Thread in LKD
First, use the !process 0 0 extension to identify the process containing the hung thread. Then, issue !process again for more information about that thread:
lkd> !process 816a550 7
THREAD 81705da8 Cid 0b5c.0b60 Teb: 7ffde000 Win32Thread: e1b2d890 WAIT: (Suspended)
IRP List:
816c9ad8: (0006,0190) Flags: 00000030 Mdl: 00000000
Start Address kernel32!BaseProcessStartThunk (0x77e5c650)
Win32 Start Address 0x0101c9be
Stack Init f50bf000 Current f50bea74 Base f50bf000 Limit f50b9000 Call 0
Priority 10 BasePriority 8 PriorityDecrement 0
The threads are not displayed, but the stack addresses are. Using the dds (or ddq) command on the current address on the stack yields a starting point for further investigation,
because it specifies which process is calling.
lkd> dds f50bea74
f50bea74 f50bebc4
f50bea78 00000000
f50bea7c 80805795
f50beab4 8080ece0
f50beabc f942afda
f50bead8 f94406c4
f50beb00 f943f6f1
f50beb24 f943fb1e

nt!KiSwapContext+0x25
nt!KeWaitForSingleObject
ks!CKsQueue::CancelAllIrps+0x14
ks!CKsQueue::SetDeviceState+0x170
ks!CKsPipeSection::DistributeDeviceStateChange+0x1d
ks!CKsPipeSection::SetDeviceState+0xb2

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Graph Analysis with Unloadable Modules

This section describes a scenario that may affect you if you are working with unloadable modules such as KMixer.
After loading, the extension module initializes at the first command usage. At initialization, the extension module checks whether every module is loaded and has correct
symbols. If any individual module is unloaded or has incorrect symbols loaded, the extension disables the library extension which handles identification, dumping, etc. for that
module. In this case, you need to manually re-enable the disabled module.
The above situation may occur if you load the extension at boot time. Specifically, you may encounter this scenario if you load Ks.dll and then issue a .reboot command. Or, it
could happen if you break into the debugger during boot and load Ks.dll at that point.
In the following example, we are capturing two streams (sndrec32) from a Telex USB microphone. Breaking on splitter!FilterProcess and running !ks.graph on splitter's
filter yields:
kd> !graph ffa0c6d4 7
Attempting a graph build on ffa0c6d4... Please be patient...
Graph With Starting Point ffa0c6d4:
"usbaudio" Filter ffaaa768, Child Factories 2
Output Factory 0:
Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p) = 7, 1
"splitter" Filter ffa0c660, Child Factories 2
Output Factory 0:
Pin 81250008 (File ffb10028) Irps(q/p) = 3, 0
Pin 811df9c0 (File ffaaf2f0) Irps(q/p) = 3, 0
Input Factory 1:
Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p) = 1, 7
In this example, KMixer has been loaded and connected to splitter, but Kmixer does not appear in the graph. There are IRPs queued to splitter's output pin, yet the !ks.graph
command is unable to backtrace and discover KMixer. Issue a !ks.libexts details command to investigate further:
kd> !libexts details
LibExt Details:
-------------------------------------------------LibExt "portcls!" :
Status : ACTIVE
This is the port class library extension to the KS DLL. It supports
dumping wave cyclic, wave pci, irp streams, and several other upper
level structures.
Commands Exported: pciaudio
Help : pchelp
Hooks : dump dumpqueue dumpcircuit conv(file) conv(device) graph
LibExt "STREAM!" :
Status : ACTIVE

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

This is the stream class library extension to the KS DLL.

dumping device extensions, filters, streams, and SRBs.
Hooks : dump enumdevobj graph
LibExt "kmixer!" :
Status : INACTIVE
This is the KMIXER extension to the KS DLL. It supports
virtually nothing at this point!
Hooks : dump graph

Page 979 of 1651

It supports

According to the above ouput, the KMixer section of the extension is currently disabled (Status : INACTIVE). Since the extension module was first used in a context in which
KMixer was not loaded, Ks.dll has disabled the KMixer section of the extension to prevent time-consuming references to an unloaded module.
To enable KMixer explicitly, you can use !ks.libexts with the enable parameter, as follows:
kd> !libexts enable kmixer
LibExt "kmixer" has been enabled.
kd> !graph ffa0c6d4 7
Attempting a graph build on ffa0c6d4... Please be patient...
Graph With Starting Point ffa0c6d4:
"usbaudio" Filter ffaaa768, Child Factories 2
Output Factory 0:
Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p)
"splitter" Filter ffa0c660, Child Factories 2
Output Factory 0:
Pin 81250008 (File ffb10028, -> "kmixer" 8123c000) Irps(q/p) =
Pin 811df9c0 (File ffaaf2f0, -> "kmixer" 81236000) Irps(q/p) =
Input Factory 1:
Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p)
"kmixer" Filter ffa65b70, Child Factories 4
Input Factory 2:
Pin 81236000 (File ffaaf7d0, <- "splitter" 811df9c0) Irps(q/p)
Output Factory 3:
Pin 81252d00 (File 811df1d8) Irps(q/p) = 10, 0
"kmixer" Filter ffb03808, Child Factories 4
Input Factory 2:
Pin 8123c000 (File ffb10130, <- "splitter" 81250008) Irps(q/p)
Output Factory 3:
Pin ffa1e9c0 (File 81253468) Irps(q/p) = 10, 0

= 7, 1

3, 0
3, 0
= 1, 7

= 0, 0

KMixer now appears as expected in the capture graph.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using !ks.graph
The !ks.graph command is one of most powerful extension commands in the kernel streaming extension module. This command displays a picture of an entire graph in kernel
mode from any given starting point.
Before running !ks.graph, you may want to enable all library extensions that are capable of being active. To do this, issue a !ks.libexts enableall command. The output of !
ks.graph will be a textual description of the kernel mode graph in topologically sorted order. Here is an example:
kd> !graph ffa0c6d4 7
Attempting a graph build on ffa0c6d4... Please be patient...
Graph With Starting Point ffa0c6d4:
"usbaudio" Filter ffaaa768, Child Factories 2
Output Factory 0:
Pin ffb1caf0 (File 811deeb8, -> "splitter" ffa8b008) Irps(q/p) = 7, 1
This example displays a capture graph in which two Sndrec32.exe's are capturing from a Telex USB Microphone. Each individual record begins with a name (usbaudio, in the
above section) and shows the filter address (0xFFAAA768) and quantity of child pin factories (2) on the filter.
Below each entry, each factory is enumerated and lists the address of each pin instance (0xFFB1CAF0), the file object (0x811DEEB8) corresponding to each instance, the
direction of the connection, the destination of that connection, and the address of the destination pin (0xFFA8B008). The number of queued (7) and pending IRPs (1) for each
pin is also displayed.
Connections which have forward direction symbols (->) indicate that the pin is an output pin and is connected to an input pin. Connections which have reverse direction
symbols (<-), on the other hand, are input pins and show the origination of the connection. The output continues as follows:
"splitter" Filter ffa0c660, Child Factories 2
Output Factory 0:
Pin 81250008 (File ffb10028, -> "kmixer" 8123c000) Irps(q/p) = 3, 0
Pin 811df9c0 (File ffaaf2f0, -> "kmixer" 81236000) Irps(q/p) = 3, 0
Input Factory 1:
Pin ffa8b008 (File ffb26d68, <- "usbaudio" ffb1caf0) Irps(q/p) = 1, 7

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 980 of 1651

"kmixer" Filter ffa65b70, Child Factories 4

Input Factory 2:
Pin 81236000 (File ffaaf7d0, <- "splitter" 811df9c0) Irps(q/p) = 0, 0
Output Factory 3:
Pin 81252d00 (File 811df1d8) Irps(q/p) = 10, 0
"kmixer" Filter ffb03808, Child Factories 4
Input Factory 2:
Pin 8123c000 (File ffb10130, <- "splitter" 81250008) Irps(q/p) = 0, 0
Output Factory 3:
Pin ffa1e9c0 (File 81253468) Irps(q/p) = 10, 0
In order to follow the graph, use the following procedure:
To follow this graph:
1. Find the pin of interest. Consider 0xFFB1CAF0, usbaudio's output pin (factory 0).
2. Find the connected pin. In this example, this is splitter pin 0xFFA8B008.
3. Look at the connection direction and visually move that way looking for the filter name. (Remember, the list is topologically sorted.) In this example, the right-pointing
arrow indicates that we need to look below this entry in the list to find the corresponding pin. The splitter filter 0xFFA0C660 is immediately below.
4. Find the destination pin address in the filter pin instance list. In this case, this address is 0xFFA8B008.
The !ks.graph command can also be used to analyze stalled graphs from any given starting point. To do this, specify 4 in the Flags parameter:
kd> !graph 812567c0 7 4
Attempting a graph build on 812567c0...

Please be patient...

Graph With Starting Point 812567c0:

"emu10k" Filter ff9ebb98, Child Factories 5
Output Factory 0:
Pin 812567c0 (File 811c6630, -> "splitter" 811df960) Irps(q/p) = 8, 0
"splitter" Filter ffb18890, Child Factories 2
Output Factory 0:
Pin 811df430 (File ffa55f90) Irps(q/p) = 10, 0
Input Factory 1:
Pin 811df960 (File 81187820, <- "emu10k" 812567c0) Irps(q/p) = 0, 8
Analyzing a Hung Graph From 812567c0:
Suspect Filters (For a Hung Graph):
"emu10k" Filter ff9ebb98 or class "PortCls Wave Cyclic" is suspect.
Reasons For This Analysis:
- No critical pin has less than 8 queued Irps
- Downstream "splitter" pin 811df960 is starved
Irps to check:
81255418 811df008 81252008 81255280 81250b30 ffa1fe70 81252e70 ffa01d98
NOTE: The above is based on heuristic analysis. It is not designed to be a
replacement for an actual developer looking at this particular hang! The
filters listed as suspects may or may not be the actual cause of the
stall!
For such output, look at the "suspects" list. These suspect filters are those that are in the critical path of progress being made in the graph. Begin debugging from that point
based on the reasons that the analyzer has produced for the stall.
Note This functionality should only be used on stalled graphs! The analyzer has no way of knowing how long the graph has been in this state. Breaking into the debugger and
analyzing a running graph as a stalled graph still displays a suspect filter.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SCSI Miniport Debugging

This section includes:
Overview of SCSI Miniport Debugging
Extensions for Debugging SCSI Miniport Drivers
Bug Checks for SCSI Miniport Debugging
Analyzing Stalled Drivers and Time-Outs
Important Breakpoints for Analyzing Reproducible Problems

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 981 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Overview of SCSI Miniport Debugging

Small computer system interface (SCSI) debugging extensions can be found in two extension modules: Scsikd.dll and Minipkd.dll. For an overview of the most important
extension commands in these modules, see Extensions for Debugging SCSI Miniport Drivers. For a complete list, see SCSI Miniport Extensions.
The SCSIkd.dll extension commands can be used in any version of Windows. The Minipkd.dll extension commands can only be used in Windows XP and later versions of
Windows. Commands in Minipkd.dll are only applicable to miniport drivers that work with the SCSI Port driver.
To test a SCSI miniport driver, use the SCSI Verification feature of Driver Verifier. For information about Driver Verifier, see
(WDK) documentation.

Driver Verifier in the Windows Driver Kit

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Extensions for Debugging SCSI Miniport Drivers

When you debug SCSI miniport drivers, you may find the following debugger extensions useful. General debugger extensions are listed first, followed by those specific to
SCSI miniport debugging.
!devobj
The !devobj extension displays detailed information about a DEVICE_OBJECT. If the Current Irp field is nonnull, this could be caused by the SCSI driver waiting for map
registers.
Here is an example:
0: kd> !devobj 8633da70
Device object (8633da70) is for:
adpu160m1 \Driver\adpu160m DriverObject 8633eeb8
Current Irp 860ef008 RefCount 0 Type 00000004 Flags 00000050
Dacl e129871c DevExt 8633db28 DevObjExt 8633dfd0
ExtensionFlags (0000000000)
AttachedTo (Lower) 863b2978 \Driver\PCI
Device queue is not busy.
!errlog
The !errlog extension displays the contents of any pending entries in the I/O system's error log.
!object
The !object extension displays information about a system object. This extension displays all SCSI devices.
For example:
0: kd> !object \device\scsi
Object: e12a2520 Type: (863d12c8) Directory
ObjectHeader: e12a2508
HandleCount: 0 PointerCount: 9
Directory Object: e1001100 Name: Scsi
Hash
---04
11
13
22
24
25
34

Address
------86352040
86353040
86334a70
862e6040
8633da70
86376040
862e5040

Type
---Device
Device
Device
Device
Device
Device
Device

Name
---adpu160m1Port3Path0Target6Lun0
adpu160m1Port3Path0Target1Lun0
lp6nds351
adpu160m1Port3Path0Target0Lun0
adpu160m1
adpu160m2
adpu160m1Port3Path0Target2Lun0

!pcr
The !pcr extension displays detailed information about the Processor Control Region (PCR) on a processor. The information includes the items in the DPC queue, which can
be useful. when you are debugging a stalled driver or a time-out.
!minipkd.help
The !minipkd.help extension displays a list of all of the Minipkd.dll extension commands.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 982 of 1651

If an error message similar to the following appears, it indicates that the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols.
minipkd error (0) <path> ... \minipkd\minipkd.c @ line 435
The .sympath (Set Symbol Path) command can be used to display the current path and to change the path. The .reload (Reload Module) command will reload symbols from
the current path.
!minipkd.adapter Adapter
The !minipkd.adapter extension displays detailed information about a specified adapter. The Adapter can be found by looking at the DevExt field in the !minipkd.adapters
display.
!minipkd.adapters
The !minipkd.adapters extension displays all the adapters that work with the SCSI Port driver that have been identified by Windows, and the individual devices associated
with each adapter.
Here is an example:
0: kd> !minipkd.adapters
Adapter \Driver\lp6nds35
Adapter \Driver\adpu160m
LUN 862e60f8 @(0,0,0) c
LUN 863530f8 @(0,1,0) c
LUN 862e50f8 @(0,2,0) c
LUN 863520f8 @(0,6,0)
Adapter \Driver\adpu160m

ev
ev
ev
ev

DO 86334a70
DO 8633da70
pnp(00/ff)
p d pnp(00/ff)
pnp(00/ff)
pnp(00/ff)
DO 86376040

DevExt 86334b28
DevExt 8633db28
pow(0,0) DevObj 862e6040
pow(0,0) DevObj 86353040
pow(0,0) DevObj 862e5040
pow(0,0) DevObj 86352040
DevExt 863760f8

An error message similar to the following indicates that either the symbol path is incorrect and does not point to the correct version of the Scsiport.sys symbols, or that
Windows has not identified any adapters that work with the SCSI Port driver:
minipkd error (0) <path> ... \minipkd\minipkd.c @ line 435
If the !minipkd.help extension command returns help information successfully, the SCSI Port symbols are correct.
!minipkd.exports Adapter
The !minipkd.exports extension displays the addresses of the miniport exports for the specified adapter.
!minipkd.lun {LUN | Device}
The !minipkd.lun extension displays detailed information about a specified Logical Unit Extension (LUN). The LUN can be specified either by its address (which can be
found by looking at the LUN field in the !minipkd.adapters display) or by its physical device object (which can be found in the DevObj field of the !minipkd.adapters
display).
!minipkd.portconfig PortConfig
The !minipkd.portconfig extension displays detailed information about a specified PORT_CONFIGURATION_DATA. The PortConfig can be found in the Port Config
Info field of the !minipkd.adapter display.
!minipkd.req {Adapter | Device}
The !minipkd.req extension displays information about all of the currently active requests on the specified adapter or LUN device.
!minipkd.srb SRB
The !minipkd.srb extension displays detailed information about a specified SCSI request block (SRB). The SRB is specified by address. The addresses of all currently active
requests can be found in the SRB fields of the output from the !minipkd.req command.
!scsikd.classext [Device [Level]]
The !scsikd.classext extension displays detailed information about a specified class Plug and Play (PnP) device or a list of all such devices. The Device is the device object or
device extension of the class PnP device. If Device is omitted, a list of all class PnP extensions is displayed.
Here is an example:
0: kd> !scsikd.classext
'
'
'
'

!scsikd.classext
!scsikd.classext
!scsikd.classext
!scsikd.classext

8633e3f0
86347b48
86347360
861d1898

'
'
'
'

(
) "IBM
" / "DDYS-T09170M
(paging device) "IBM
" / "DDYS-T09170M
(
) "UNISYS " / "003451ST34573WC
(
) "" / "MATSHITA CD-ROM CR-177"

"
"
"
/

/ "S93E"
/ "S80D"
/ "5786"
"7T03" /

/ "
XBY45906"
/ "
VDA60491"
/ "HN0220750000181300L6"
""

usage: !classext <class fdo> <level [0-2]>

!scsikd.scsiext Device
The !scsikd.scsiext extension displays detailed information about a specified SCSI port extension. The Device can be the device object or device extension of either the
adapter or the LUN.
Here are some examples:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 983 of 1651

0: kd> !scsikd.scsiext 86353040

Common Extension:
< ..omitted.. >
Logical Unit Extension:
Address (3, 0, 1, 0) Claimed Enumerated Visible
LuFlags (0x00000000):
Retry 0x00
Key 0x008889ff
Lock 0x00000000 Pause 0x00000000
CurrentLock: 0x00000000
HwLuExt 0x862e6f00 Adapter 0x8633db28 Timeout 0x0000000a
NextLun 0x00000000 ReadyLun 0x00000000
Pending 0x00000000 Busy 0x00000000
Untagged 0x00000000
< ..omitted.. >
Request list @0x86353200:
Tick count is 2526
SrbData 8615d700 Srb 8611f4fc Irp 8611f2b8
Key 60197
SrbData 85e72868 Srb 86100c3c Irp 861009f8
Key e29dc7

<1s
<1s

0: kd> !scsikd.scsiext 8633da70

Common Extension:
< ..omitted.. >
Adapter Extension:
Port 3
IsPnp VirtualSlot HasInterrupt
LowerPdo 0x84f9fb68
HwDevExt 0x84634004
Active Requests 0x00000000
MaxBus 0x03
MaxTarget 0x40
MaxLun 0x08
Port Flags (0x00001000): PD_DISCONNECT_RUNNING
NonCacheExt 0x850d4000 IoBase 0xd80f0000
Int 0x23 < ..omitted.. >
!scsikd.srbdata Address
The !scsikd.srbdata extension displays detailed information about a specified SRB_DATA tracking block.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Bug Checks for SCSI Miniport Debugging

There are primarily two bug checks that arise in the course of debugging a SCSI miniport driver: bug check 0x77 (KERNEL_STACK_INPAGE_ERROR) and bug check
0x7A (KERNEL_DATA_INPAGE_ERROR). For full details of their parameters, see Bug Check 0x77 and Bug Check 0x7A.
Each of these bug checks indicates that a paging error has occurred. There are three main causes for these bug checks:

Full bus reset due to a timeout on a particular device or no activity on an adapter

Selection time-out
Controller errors

To determine the precise cause of the failure, begin by using the !scsikd.classext extension, which displays information about recently failed requests, including the SRB
status, SCSI status, and sense data of the request.
kd> !scsikd.classext 816e96b0
Storage class device 816e96b0 with extension at 816e9768
Classpnp Internal Information at 817b4008
Failed requests:
Srb
Scsi
Opcode Status Status Sense Code Sector
Time Stamp
------ ------ ------ ---------- -------- -----------2a
0a
02
03 0c 00 0000abcd 23:01:07.453
28
0a
02
03 04 00 0000abcd 23:01:07.984

Retried
Retried

dt classpnp!_CLASS_PRIVATE_FDO_DATA 817b4008
...
In the previous example, opcode 0x2A indicates a write operation, and 0x28 indicates a read operation. The SCSI status in the example is 02, which indicates a check
condition. The sense codes provide more error information.
As always, miniport driver developers are responsible for associating error codes from their hardware to the SRB status codes. Typically, timeouts are associated with SRB
0x0A, the code for a selection timeout. SRB 0x0e is typically associated with a full bus reset, but it can also be associated with controller errors.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 984 of 1651

Debugging Tools for Windows

Analyzing Stalled Drivers and Time-Outs

When debugging a SCSI miniport driver, the three most common causes for hangs and time-outs are:

The SCSI miniport DPC is not running

The SCSI miniport fails to ask for the next request
A request is not being completed by the SCSI miniport, usually because it is waiting for map registers.

If you suspect that the SCSI miniport DPC is not running, use !pcr to display the DPC queue for the current processor. If the SCSI port DPC routine is in the DPC queue,
place a breakpoint on this routine to determine whether this routine is ever called. Otherwise, use !scsikd.scsiext on each device. Consider the following sample output from
the !scsikd.scsiext extension:
0: kd> !scsikd.scsiext 86353040
Common Extension:
< ..omitted.. >
Logical Unit Extension:
Address (3, 0, 1, 0) Claimed Enumerated Visible
LuFlags (0x00000000):
Retry 0x00
Key 0x008889ff
Lock 0x00000000 Pause 0x00000000
CurrentLock: 0x00000000
HwLuExt 0x862e6f00 Adapter 0x8633db28 Timeout 0x0000000a
NextLun 0x00000000 ReadyLun 0x00000000
Pending 0x00000000 Busy 0x00000000
Untagged 0x00000000
. . .
Request list @0x86353200:
Tick count is 2526
SrbData 8615d700 Srb 8611f4fc Irp 8611f2b8
SrbData 85e72868 Srb 86100c3c Irp 861009f8

Key 60197
Key e29dc7

<1s
<1s

If the timeout slot is -1 and the untagged slot is nonzero, or the time-out slot is nonzero and there are requests shown, the miniport has failed to ask for the next request.
Alternatively, if the retry slot and the busy slot are nonzero, a request may not be completed by the SCSI miniport because it is waiting for map registers. Similarly, if the
untagged and pending slots are nonzero, the SCSI miniport might be waiting for map registers. In either case, the address of the SCSI request block (SRB) is the address in the
busy slot and the address of the request that is not being completed. For more information about the SRB, use the !minipkd.srb extension with this address as input.
The !devobj extension determines whether the SCSI miniport is waiting for map registers. Use the device object address of the device that is issuing the request as input to !
devobj. If the current IRQ is nonzero, it is highly probable that the SCSI miniport is waiting for map registers.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Important Breakpoints for Analyzing Reproducible Problems

When debugging a SCSI miniport driver, there are three routines in which it is useful to set a breakpoint:

scsiport!scsiportnotification
scsiport!spstartiosynchronized
miniport!HwStartIo

The routine scsiport!scsiportnotification is called right after a request is sent to the miniport. Thus, if you set a breakpoint in scsiport!scsiportnotification and then run a
stack backtrace using kb 3, you can determine whether the miniport is receiving and completing requests. If the first parameter is zero, the request has been completed. If the
first parameter is nonzero, the third parameter is the address of the SCSI request block (SRB) that is not being completed, and you can use the !minipkd.srb extension to
further analyze the situation.
Placing a breakpoint in either scsiport!spstartiosynchronized or miniport!HwStartIo will cause a break just prior to sending a request to the miniport.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kernel-Mode Driver Framework Debugging

Debugging extensions for Kernel-Mode Driver Framework (KMDF) are contained in the Wdfkd.dll extension library.
You can use the extension commands that the Wdfkd.dll extension library contains to debug drivers that use KMDF.
For a description of the extension commands in Wdfkd.dll, see Kernel-Mode Driver Framework Extensions (Wdfkd.dll).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 985 of 1651

These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions; these restrictions are noted on the
individual reference pages.
To use this extension library, you must load the library into your debugger. For information about how to load extension libraries into a debugger, see Loading Debugger
Extension DLLs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

User-Mode Driver Framework Debugging

For an overview of how to debug User-Mode Driver Framework (UMDF) drivers, including information on how to start this kind of debugging session, see the
UMDF Drivers section of the Windows Driver Kit (WDK) documentation.

Debugging

UMDF Debugging Extensions

User-Mode Driver Framework (UMDF) debugging extensions are implemented in the extension module Wudfext.dll. You can use these extensions to debug drivers that use
UMDF.
For a complete description of the extension commands in Wudfext.dll, see User-Mode Driver Framework Extensions (Wudfext.dll).
These extensions can be used on Microsoft Windows XP and later operating systems. Some extensions have additional restrictions on the Windows version or UMDF version
that is required; these restrictions are noted on the individual reference pages.
To use this extension library, you must load the library into your debugger. For information about how to load extension libraries into a debugger, see Loading Debugger
Extension DLLs.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Plug and Play Debugging

This section includes:
Extensions for Debugging Plug and Play Drivers
Determining the Status of a Device
Device Node Status Flags
Device Manager Problem Codes
Checking for Resource Conflicts
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Extensions for Debugging Plug and Play Drivers

When you debug Plug and Play drivers, you may find the following debugger extensions useful.
!arbiter
Displays the current system resource arbiters. An arbiter is a piece of code that is exposed by the bus driver that arbitrates requests for resources, and attempts to solve the
resource conflicts among the devices connected on that bus.
!cmreslist
Displays the CM_RESOURCE_LIST for the specified device object.
You must know the address of the CM Resource List.
Here is an example:
kd> !cmreslist 0xe12576e8

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 986 of 1651

CmResourceList at 0xe12576e8 Version 0.0 Interface 0x1

Entry 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3f8 for 0x8 bytes
Entry 1 - Interrupt (0x2) Shared (0x3)
Flags (0x01) - LATCHED
Level 0x4, Vector 0x4, Affinity 0xffffffff

Bus #0

This shows that the device with this CM resource list is using I/O Range 3F8-3FF and IRQ 4.
!dcs
This extension is obsolete its functionality has been subsumed by !pci. See the !pci 100 example later in this section.
!devext
Displays bus-specific device extension information for a variety of devices.
!devnode
Displays information about a node in the device tree.
Device node 0 (zero) is the root of the device tree.
Here is an example:
kd> !devnode 0xff0d4a08
DevNode 0xff0d4a08 for PDO 0xff0d4af0 at level 0
Parent 0xff0daf48
Sibling 0xff0d4848
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xfffffff0
InstancePath is "Root\*PNP0501\PnPBIOS_2"
ServiceName is "Serial"
TargetDeviceNotify List - f 0xff0d4a6c b 0xff0d4a6c
Flags (0x6000122b) DNF_PROCESSED, DNF_STARTED,
DNF_ENUMERATED, DNF_MADEUP,
DNF_RESOURCE_ASSIGNED, DNF_ADDED,
DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
!devobj
Displays detailed information about a DEVICE_OBJECT.
Here is an example:
kd> !devobj 0xff0d4af0
Device object (ff0d4af0) is for:
00252d \Driver\PnpManager DriverObject ff0d9030
Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040AttachedDev ff0b59e0
DevExt ff0d4ba8 DevNode ff0d4a08
Device queue is not busy.
!drivers
The !drivers command is no longer supported. Please use the lm t n command instead.
!drvobj
Displays detailed information about a DRIVER_OBJECT.
Lists all the device objects created by the specified driver.
Here is an example:
kd> !drvobj serial
Driver object (ff0ba630) is for:
\Driver\Serial
Driver Extension List: (id , addr)
Device Object list:
ffba3040 ff0b4040 ff0b59e0

ff0b5040

!ecb, !ecd, !ecw

(x86 target computers only) Writes a sequence of values into the PCI configuration space.
ib, iw, id

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 987 of 1651

Reads data from an I/O port.

These three commands are useful for determining whether a certain I/O range is claimed by a device other than the driver being debugged. A byte value of 0xFF at a port
indicates that the port is not in use.
!ioreslist
Displays the specified IO_RESOURCE_REQUIREMENTS_LIST.
!irp
Displays information about an IRP.
!irpfind
Displays information about all IRPs currently allocated in the target system, or information about those IRPs whose fields match the specified search criteria.
!pci
(x86 target computers only) Displays the current status of the PCI buses and any devices attached to them. It can also display the PCI configuration space.
The following example displays the devices on the primary bus:
kd> !pci
PCI Bus 0
00:0 8086:1237.02
0d:0 8086:7000.01
0d:1 8086:7010.00
0e:0 1011:0021.01
bridge
10:0 5333:8811.43

Cmd[0106:.mb..s]
Cmd[0007:imb...]
Cmd[0005:i.b...]
Cmd[0107:imb..s]

Sts[2280:.....]
Sts[0280:.....]
Sts[0280:.....]
Sts[0280:.....]

Device Host bridge

Device ISA bridge
Device IDE controller
PciBridge 0->1-1 PCI-PCI

Cmd[0023:im.v..]

Sts[0200:.....]

Device

VGA compatible controller

The following example displays the devices for the secondary bus, with verbose output:
kd> !pci 1 1
PCI Bus 1
08:0 10b7:5900.00
cf8:80014000
IO[0]:fce1
09:0

9004:8178.00
cf8:80014800
IO[0]:f801

Cmd[0107:imb..s] Sts[0200:.....]
IntPin:1 IntLine:f Rom:fa000000

Device Ethernet
cis:0 cap:0

Cmd[0117:imb..s] Sts[0280:.....]
IntPin:1 IntLine:f Rom:fa000000
MEM[1]:f9fff000

Device SCSI controller

cis:0 cap:0

0b:0 9004:5800.10 Cmd[0116:.mb..s] Sts[0200:.....]

1394 host controller
cf8:80015800 IntPin:1 IntLine:e Rom:fa000000
MEM[0]:f9ffec00

Device
cis:0

SubID:9004:8940
cap:0

The following example displays the PCI configuration space for the SCSI controller (bus 1, device 9, function 0):
kd> !pci 100 1 9 0
00: 9004
;VendorID=9004
02: 8178
;DeviceID=8178
04: 0117
;Command=SERREnable,MemWriteEnable,BusInitiate,MemSpaceEnable,IOSpac
eEnable
06: 0280
;Status=FB2BCapable,DEVSELTiming:1
08: 00
;RevisionID=00
09: 00
;ProgIF=00 (SCSI bus controller)
0a: 00
;SubClass=00
0b: 01
;BaseClass=01 (Mass storage controller)
0c: 08
;CacheLineSize=Burst8DW
0d: 20
;LatencyTimer=20
0e: 00
;HeaderType=00
0f: 00
;BIST=00
10: 0000f801;BAR0=0000f801
14: f9fff000;BAR1=f9fff000
18: 00000000;BAR2=00000000
1c: 00000000;BAR3=00000000
20: 00000000;BAR4=00000000
24: 00000000;BAR5=00000000
28: 00000000;CBCISPtr=00000000
2c: 0000
;SubSysVenID=0000
2e: 0000
;SubSysID=0000
30: fa000000;ROMBAR=fa000000
34: 00000000;Reserved=00000000
38: 00000000;Reserved=00000000
3c: 0f
;IntLine=0f
3d: 01
;IntPin=01
3e: 08
;MinGnt=08
3f: 08
;MaxLat=08
40: 00001580,00001580,00000000,00000000,00000000,00000000,00000000,00000000

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

60:
80:
a0:
c0:
e0:

Page 988 of 1651

00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000
00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000
00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000
00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000
00000000,00000000,00000000,00000000,00000000,00000000,00000000,00000000

!pcitree
Displays information about PCI device objects, including child PCI buses and CardBus buses, as well as the devices attached to them.
!pnpevent
Displays the PnP device event queue.
!rellist
Displays a PnP relation list and any related CM_RESOURCE_LIST and IO_RESOURCE_LIST structures.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Determining the Status of a Device

To display the entire device tree, starting with the root, use !devnode 0 1:
kd> !devnode 0 1
Identify the devnode for which you are searching, either by examining the driver or the bus that exposed it.
The devnode status flags describe the status of the device. For details, see Device Node Status Flags.
In the example for the !devnode command in the Extensions for Debugging Plug and Play Drivers section, the on-board serial device was created by the PnP Manager, so the
DNF_MADEUP (0x00000020) flag is set.
The following example shows a device that was created by the PCI bus. This device does not have the DNF_MADEUP flag set.
kd> !devnode 0xff0d1588
DevNode 0xff0d1588 for PDO 0xff0d1030 at level 0x2
Parent 0xff0d2e28
Sibling 0xff0d14c8
Child 0xff0c8268
InterfaceType 0xffffffff Bus Number 0xfffffff0
InstancePath is "PCI\VEN_9004&DEV_6178\0&70"
ServiceName is "aic78xx"
TargetDeviceNotify List - f 0xff0d15ec b 0xff0d15ec
Flags (0x6000120b) DNF_PROCESSED, DNF_STARTED,
DNF_ENUMERATED, DNF_RESOURCE_ASSIGNED,
DNF_ADDED, DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
kd> !devobj 0xff0d1030
Device object (ff0d1030) is for:
NTPNP_PCI0002 \Driver\PCI DriverObject ff0d2830
Current Irp 00000000 RefCount 0 Type 00000022 Flags 00001040AttachedDev ff0ce710
DevExt ff0d10e8 DevNode ff0d1588
Device queue is not busy.
Examples
1. A devnode for a device with insufficient resources:
kd> !devnode 0xff0d06e8 6
DevNode 0xff0d06e8 for PDO 0xff0d07d0 at level 0x3
Parent 0xff0d1408
Sibling 0000000000
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xfffffff0
InstancePath is "ISAPNP\SUP2171\00000067"
ServiceName is "Modem"
TargetDeviceNotify List - f 0xff0d074c b 0xff0d074c
Flags (0x60001109) DNF_PROCESSED, DNF_ENUMERATED,
DNF_INSUFFICIENT_RESOURCES, DNF_ADDED,
DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
IoResList at 0xe133e7a8 : Interface 0x1
Alternative 0 (Version 1.1)

Bus 0

Slot 0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 989 of 1651

Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Shared (0x3)

Flags (0000) Data:
: 0x0 0x61004d 0x680063
Preferred Descriptor 1 - Port (0x1) Undetermined Sharing (0)
Flags (0x11) - PORT_IO 16_BIT_DECODE
0x000008 byte range with alignment 0x000001
2f8 - 0x2ff
Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3)
Flags (0x01) - LATCHED
0x3 - 0x3
Note that the devnode has no CM Resource List, because it is not started and is not using resources, although it has requested resources.
2. Note that there are no resources stored in this devnode for a legacy driver.
kd> !devnode 0xff0d1648 6
DevNode 0xff0d1648 for PDO 0xff0d22d0 at level 0x2
Parent 0xff0d2e28
Sibling 0xff0d1588
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
InstancePath is "PCI\VEN_102B&DEV_0519\0&60"
ServiceName is "mga_mil"
TargetDeviceNotify List - f 0xff0d16ac b 0xff0d16ac
Flags (0x6000500b) DNF_PROCESSED, DNF_STARTED,
DNF_ENUMERATED, DNF_ADDED,
DNF_LEGACY_DRIVER, DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
You can retrieve the device object list for the driver for the following types of devices:
kd> !drvobj mga_mil
Driver object (ff0bbc10) is for:
\Driver\mga_mil
Driver Extension List: (id , addr)
Device Object list:
ff0bb900
You can then dump the data for this device object:
kd> !devobj ff0bb900
Device object (ff0bb900) is for:
Video0 \Driver\mga_mil DriverObject ff0bbc10
Current Irp 00000000 RefCount 1 Type 00000023 Flags 0000204c
DevExt ff0bb9b8 DevNode ff0bb808
Device queue is not busy.
Finally, you can dump the devnode referred by the device object. This devnode is not linked in the device tree. It represents a "pseudo-devnode" used to claim resources for
the legacy device. Note the DNF_RESOURCE_REPORTED flag that indicates the device is a reported detected device.
kd> !devnode ff0bb808 6
DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff
Parent 0xff0daf48
Sibling 0000000000
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c
Flags (0x00000400) DNF_RESOURCE_REPORTED
CmResourceList at 0xe12474e8 Version 0.0 Interface 0x5 Bus #0
Entry 0 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3c0 for 0x10 bytes
Entry 1 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3d4 for 0x8 bytes
Entry 2 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3de for 0x2 bytes
Entry 3 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
Range starts at 0x0000000040000000 for 0x4000 bytes
Entry 4 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
Range starts at 0x0000000040800000 for 0x800000 bytes

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 990 of 1651

Debugging Tools for Windows

Device Node Status Flags

The Device Node Status flags describe the status of a device.
The most important flags are:
DNF_MADEUP (0x00000001)
The device was created and is owned by the PnP Manager. It was not created by a bus driver.
DNF_DUPLICATE (0x00000002)
The device node is a duplicate of another enumerated device node.
DNF_HAL_NODE (0x00000004)
The device node is the root node created by the hardware abstraction layer (HAL).
DNF_REENUMERATE (0x00000008)
The device needs to be re-enumerated.
DNF_ENUMERATED (0x00000010)
The PDO for the device was exposed by its parent.
DNF_IDS_QUERIED (0x00000020)
The operating system should send IRP_MN_QUERY_ID requests to the device driver.
DNF_HAS_BOOT_CONFIG (0x00000040)
The device has resources assigned by the BIOS. The device is considered pseudo-started and needs to participate in rebalancing.
DNF_BOOT_CONFIG_RESERVED (0x00000080)
The boot resources of the device are reserved.
DNF_NO_RESOURCE_REQUIRED (0x00000100)
The device does not require resources.
DNF_RESOURCE_REQUIREMENTS_NEED_FILTERED (0x00000200)
The device's resource requirements list is a filtered list.
DNF_RESOURCE_REQUIREMENTS_CHANGED (0x00000400)
The device's resource requirements list has changed.
DNF_NON_STOPPED_REBALANCE (0x00000800)
The device can be restarted with new resources without being stopped.
DNF_LEGACY_DRIVER (0x00001000)
The device's controlling driver is a non-PnP driver.
DNF_HAS_PROBLEM (0x00002000)
The device has a problem and will be removed.
DNF_HAS_PRIVATE_PROBLEM (0x00004000)
The device reported PNP_DEVICE_FAILED without also reporting PNP_DEVICE_RESOURCE_REQUIREMENTS_CHANGED.
DNF_HARDWARE_VERIFICATION (0x00008000)
The device node has hardware verification.
DNF_DEVICE_GONE (0x00010000)
The device's PDO is no longer returned in an IRP_QUERY_RELATIONS request.
DNF_LEGACY_RESOURCE_DEVICENODE (0x00020000)
The device node was created for legacy resource allocation.
DNF_NEEDS_REBALANCE (0x00040000)
The device node has triggered rebalancing.
DNF_LOCKED_FOR_EJECT (0x00080000)
The device is being ejected or is related to a device that is being ejected.
DNF_DRIVER_BLOCKED (0x00100000)
One or more of the drivers for the device node have been blocked from loading.
DNF_CHILD_WITH_INVALID_ID (0x00200000)
One or more children of the device node have invalid IDs.
DNF_ASYNC_START_NOT_SUPPORTED (0x00400000)
The device does not support asynchronous starts.
DNF_ASYNC_ENUMERATION_NOT_SUPPORTED (0x00800000)
The device does not support asynchronous enumeration.
DNF_LOCKED_FOR_REBALANCE (0x01000000)
The device is locked for rebalancing.
DNF_UNINSTALLED (0x02000000)
An IRP_MN_QUERY_REMOVE_DEVICE request is in progress for the device.
DNF_NO_LOWER_DEVICE_FILTERS (0x04000000)
There is no Registry entry of the lower-device-filters type for the device.
DNF_NO_LOWER_CLASS_FILTERS (0x08000000)
There is no Registry entry of the lower-class-filters type for the device.
DNF_NO_SERVICE (0x10000000)
There is no Registry entry of the service the for the device.
DNF_NO_UPPER_DEVICE_FILTERS (0x20000000)
There is no Registry entry of the upper-device-filters type for the device.
DNF_NO_UPPER_CLASS_FILTERS (0x40000000)
There is no Registry entry of the upper-class-filters type for the device.
DNF_WAITING_FOR_FDO (0x80000000)
Enumeration of the device is waiting until the driver attaches its FDO.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Device Manager Problem Codes

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 991 of 1651

The Device Manager marks a device with a yellow exclamation mark (!) when the device has a problem. The problem codes are in the form CM_PROB_XXX and are defined
in the header file cfg.h. The most important are explained here, together with their mapping to the Device Node Status Flags.
Code 1 (CM_PROB_NOT_CONFIGURED)
Indicates that the device is not installed and was not installed previously. (Corresponds to DNF_NOT_CONFIGURED.)
Code 10 (CM_PROB_FAILED_START)
Indicates that the device did not start for some reason, but the I/O Manager attempted to start it with a set of resources. (Corresponds to DNF_START_FAILED.)
Code 12 (CM_PROB_NORMAL_CONFLICT)
Indicates that there were not sufficient resources to start this device. (Corresponds to DNF_INSUFFICIENT_RESOURCES.)
Code 14 (CM_PROB_NEED_RESTART)
Indicates that user mode reconfigured the device and a reboot is required for the changes to take effect. (Corresponds to DNF_NEED_RESTART.)
Code 18 (CM_PROB_REINSTALL)
Indicates that the device needs to be installed and was installed previously. (Corresponds to DNF_REINSTALL.)
Code 21 (CM_PROB_WILL_BE_REMOVED)
Indicates that the user mode uninstalled this device. (Corresponds to DNF_WILL_BE_REMOVED.)
Code 22 (CM_PROB_DISABLED)
Indicates that the device is disabled. (Corresponds to DNF_DISABLED.)
Code 28 (CM_PROB_FAILED_INSTALL)
Indicates that the installation failed and there is no driver selected for this device, although the kernel did not report a problem (and there is no DNF_XXX match for this
the problem). This problem can be the result of an on-board system device (ISA timer, ISA RTC, RAM Memory, and so forth) that does not yet have an INF file.
Code 31 (CM_FAILED_ADD)
Indicates that the device was not added. Reasons for the failure may include: a driver's AddDevice routine returned an error, there is no service listed for the device in the
registry, there is more than one service listed, or the controlling driver could not be loaded. (Corresponds to DNF_ADD_FAILED.)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Checking for Resource Conflicts

This section discusses techniques that can be used to detect resource conflicts.
The first technique involves dumping the arbiter data. The following example examines the arbiter data for the I/O ranges:
kd> !arbiter 1
DEVNODE ff0daf48
Port Arbiter "RootPort" at 8045b920
Allocated ranges:
10 - 1f S
Owner ff0d6b30
22 - 3f S
Owner ff0d6b30
44 - 47 S
Owner ff0d6b30
4c - 6f S
Owner ff0d6b30
72 - 7f S
Owner ff0d6b30
90 - 91 S
Owner ff0d6b30
93 - 9f S
Owner ff0d6b30
a2 - bf S
Owner ff0d6b30
d0 - ef S
Owner ff0d6b30
100 - 2f7 S
Owner ff0d6b30
300 - cf7 S
Owner ff0d6b30
d00 - ffff S
Owner ff0d6b30
Possible allocation:
< none >
DEVNODE ff0d2e28 (PCI_HAL\PNP0A03\0)
Port Arbiter "PCI I/O Port (b=00)" at e122c2c8
Allocated ranges:
0 - f
Owner 00000000
20 - 21
Owner 00000000
40 - 43
Owner 00000000
48 - 4b
Owner 00000000
60 - 60
Owner ff0d4030
64 - 64
Owner ff0d4030
70 - 71
Owner 00000000
80 - 8f
Owner 00000000
92 - 92
Owner 00000000
a0 - a1
Owner 00000000
c0 - cf
Owner 00000000
f0 - ff
Owner 00000000
170 - 177
Owner ff0cf030
1ce - 1cf S
Owner ff040040
2f8 - 2ff
Owner 00000000
376 - 376
Owner ff0cf030
378 - 37f
Owner ff0d4e70
3b0 - 3bb S
Owner ff040040
3c0 - 3cf S
Owner ff0bb900
3c0 - 3df S
Owner ff040040
3d4 - 3db S
Owner ff0bb900
3de - 3df S
Owner ff0bb900

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 992 of 1651

3ec - 3ef
Owner ff0d0b50 (This device conflicts with another device, see below)
3f2 - 3f5
Owner ff0d4770
3f7 - 3f7 S
Owner ff0d4770
3f8 - 3ff
Owner ff0d4af0
778 - 77b
Owner ff0d4e70
cf8 - cff
Owner 00000000
1000 - 10ff
Owner ff0d1030
1400 - 140f
Owner ff0d1d30
1410 - 141f
Owner ff0d1890
10000 - ffffffffffffffff
Owner 00000000
Possible allocation:
< none >
Note that there are two arbiters: one located in the root of the device tree, and one in PCI_HAL. Also note that the PCI arbiter claims and preallocates ranges for the devices it
arbitrates (0xD000-0xFFFF, which is later suballocated by the PCI arbiter for its devices). The Owner field indicates the device object that owns the range. A value of zero for
Owner indicates that the range is not on the bus. In the case of a PCI bridge, for example, all the ranges it does not pass will be assigned to NULL.
In the following example, the PCI bridge passes I/O 0xD000-0xDFFFF so its arbiter will contain the following two ranges:
0-CFFFF
Owner 00000000
E0000-FFFFFFFFFFFFFFFF
Owner 00000000
The FFFFFFFFFFFFFFFF is because all arbitrated resources are treated as 64-bit ranges.
Examples:
kd> !devobj ff0bb900
Device object (ff0bb900) is for:
Video0 \Driver\mga_mil DriverObject ff0bbc10
Current Irp 00000000 RefCount 1 Type 00000023 Flags 0000204c
DevExt ff0bb9b8 DevNode ff0bb808
Device queue is not busy.
kd> !devnode ff0bb808
DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff
Parent 0xff0daf48
Sibling 0000000000
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c
Flags (0x00000400) DNF_RESOURCE_REPORTED
kd> !devnode ff0bb808 6
DevNode 0xff0bb808 for PDO 0xff0bb900 at level 0xffffffff
Parent 0xff0daf48
Sibling 0000000000
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
TargetDeviceNotify List - f 0xff0bb86c b 0xff0bb86c
Flags (0x00000400) DNF_RESOURCE_REPORTED
CmResourceList at 0xe12474e8 Version 0.0 Interface 0x5 Bus #0
Entry 0 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3c0 for 0x10 bytes
Entry 1 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3d4 for 0x8 bytes
Entry 2 - Port (0x1) Shared (0x3)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3de for 0x2 bytes
Entry 3 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
Range starts at 0x0000000040000000 for 0x4000 bytes
Entry 4 - Memory (0x3) Device Exclusive (0x1)
Flags (0000) - READ_WRITE
Range starts at 0x0000000040800000 for 0x800000 bytes
As shown in the example, this operation retrieved the legacy video card that owns the range 3c0-3cf. The same device object is listed near the other ranges it owns (3de-3df
and 3d4-3dc). Using the same tracking technique, the range of 3f8-3ff is determined to be that used by the serial port.
A similar technique is required to translate the interrupts:
kd> !arbiter 4
DEVNODE ff0daf48
Interrupt Arbiter "RootIRQ"
Allocated ranges:
31 - 31
Owner
34 - 34 S
Owner
36 - 36
Owner
3b - 3b S
Owner
3b - 3b S
Owner
3c - 3c
Owner
3f - 3f
Owner
Possible allocation:
< none >

at 8045bae0
ff0d4030
ff0d4af0
ff0d4770
ff0d1030
ff0d1d30
ff0d3c70
ff0cf030

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 993 of 1651

Note that there is a single arbiter for interrupts: the root arbiter.
For example, translate the interrupt 3F to an IRQ. First dump the device object, then the devnode:
kd> !devobj ff0cf030
Device object (ff0cf030) is for:
IdeFdoff0d0398Channel1 \Driver\IntelIde DriverObject ff0d0530
Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040AttachedDev ff0cd030
DevExt ff0cf0e8 DevNode ff0cfe88
Device queue is not busy.
kd> !devnode ff0cfe88 6
DevNode 0xff0cfe88 for PDO 0xff0cf030 at level 0x3
Parent 0xff0d1348
Sibling 0000000000
Child 0xff0c84a8
InterfaceType 0xffffffff Bus Number 0xfffffff0
InstancePath is "PCIIDE\IDEChannel\1&1"
ServiceName is "atapi"
TargetDeviceNotify List - f 0xff0cfeec b 0xff0cfeec
Flags (0x6000120b) DNF_PROCESSED, DNF_STARTED,
DNF_ENUMERATED, DNF_RESOURCE_ASSIGNED,
DNF_ADDED, DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
CmResourceList at 0xe12321c8 Version 0.0 Interface 0x1 Bus #0
Entry 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x170 for 0x8 bytes
Entry 1 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x376 for 0x1 bytes
Entry 2 - Interrupt (0x2) Device Exclusive (0x1)
Flags (0x01) - LATCHED
Level 0xf, Vector 0xf, Affinity 0xffffffff
IoResList at 0xe12363c8 : Interface 0x1 Bus 0 Slot 0
Reserved Values = {0x0002e0d0, 0x00920092, 0xe1235508}
Alternative 0 (Version 1.1)
Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80) Shared (0x3)
Flags (0000) Data:
: 0x1 0x61004d 0x680063
Preferred Descriptor 1 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000008 byte range with alignment 0x000001
170 - 0x177
Preferred Descriptor 2 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000001 byte range with alignment 0x000001
376 - 0x376
Preferred Descriptor 3 - Interrupt (0x2) Device Exclusive (0x1)
Flags (0x01) - LATCHED
0xf - 0xf
Alternative 1 (Version 1.1)
Preferred Descriptor 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000008 byte range with alignment 0x000001
170 - 0x177
Preferred Descriptor 1 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000001 byte range with alignment 0x000001
376 - 0x376
Preferred Descriptor 2 - Interrupt (0x2) Device Exclusive (0x1)
Flags (0x01) - LATCHED
0xf - 0xf
For example, try to determine if there is a resource conflict that caused this device not to start, starting with a devnode:
kd> !devnode 0xff0d4bc8 6
DevNode 0xff0d4bc8 for PDO 0xff0d4cb0 at level 0
Parent 0xff0daf48
Sibling 0xff0d4a08
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
InstancePath is "Root\*PNP0501\1_0_17_2_0_0"
ServiceName is "Serial"
TargetDeviceNotify List - f 0xff0d4c2c b 0xff0d4c2c
Flags (0x60001129) DNF_PROCESSED, DNF_ENUMERATED,
DNF_MADEUP, DNF_INSUFFICIENT_RESOURCES,
DNF_ADDED, DNF_HAS_BOOT_CONFIG
Unknown flags 0x40000000
IoResList at 0xe1251e28 : Interface 0x1 Bus 0 Slot 0
Reserved Values = {0x0043005c, 0x006e006f, 0x00720074}

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 994 of 1651

Alternative 0 (Version 1.1)

Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80)
ing (0)
Flags (0000) Data:
: 0xc000 0x0 0x0
Preferred Descriptor 1 - Port (0x1) Undetermined Sharing
Flags (0x05) - PORT_IO 10_BIT_DECODE
0x000008 byte range with alignment 0x000001
3e8 - 0x3ef
Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3)
Flags (0x01) - LATCHED
0x5 - 0x5
Alternative 1 (Version 1.1)
Preferred Descriptor 0 - NonArbitrated/ConfigData (0x80)
ing (0)
Flags (0000) Data:
: 0xc000 0x0 0x0
Preferred Descriptor 1 - Port (0x1) Undetermined Sharing
Flags (0x05) - PORT_IO 10_BIT_DECODE
0x000008 byte range with alignment 0x000008
3e8 - 0x3ef
Preferred Descriptor 2 - Interrupt (0x2) Shared (0x3)
Flags (0x01) - LATCHED
0x5 - 0x5

Undetermined Shar

(0)

Undetermined Shar

(0)

First, make the assumption that this is an I/O conflict and dump the arbiters (see the preceding example). The result shows that the range 0x3EC-0x3EF is owned by
0xFF0D0B50, which overlaps the serial device's resources request. Next, dump the device object for the owner of this range, and then dump the devnode for the owner:
kd> !devobj ff0d0b50
Device object (ff0d0b50) is for:
Resource00413e \Driver\isapnp DriverObject ff0d0e10
Current Irp 00000000 RefCount 0 Type 00000004 Flags 00001040
DevExt ff0d0c08 DevNode ff0d0a68
Device queue is not busy.
kd> !devnode ff0d0a68 6
DevNode 0xff0d0a68 for PDO 0xff0d0b50 at level 0xffffffff
Parent 0xff0daf48
Sibling 0000000000
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
Duplicate PDO 0xff0d0e10 TargetDeviceNotify List - f 0xff0d0acc b 0xff0d0acc
Flags (0x00000421) DNF_PROCESSED, DNF_MADEUP,
DNF_RESOURCE_REPORTED
CmResourceList at 0xe1233628 Version 0.0 Interface 0x1 Bus #0
Entry 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0x3ec for 0x4 bytes
This is a "pseudo-devnode" that corresponds to the range allocated by the ISAPNP driver for its read data port.
To determine the resources that the PnP Manager assigned to a particular device when it attempted to start the device:
1. Place a breakpoint on the routine that is called when the IRP_MN_START_DEVICE request is received by the driver. You can also place a breakpoint on the driver's
dispatch routine (if you know its name). In both cases, the driver and its symbols should be loaded. This may require you to set an initial breakpoint.
For example, for PCMCIA you can set a breakpoint on pcmcia!pcmciastartpccard. The advantage of using this particular routine is that its second parameter is a CM
Resource List that you can dump using !cmreslist (eliminating step 3). See the following PCMCIA example.
2. When you have determined which device is of interest, dump the device object (if you have not done so already), and then dump the devnode with the CM Resource
List. Check which resources were assigned to the device. You may also check whether the resources are a subset of the I/O Resource List. Then type g or single step
through the procedure, and determine whether the device was started and which resources were assigned. If a device was offered a set of resources to start but failed to
do so, the driver might not be behaving properly (for example, if it incorrectly declared that it can use a set of resources it cannot actually use).
Example:
ntoskrnl!IopStartDevice:
80420212 55
push
ebp
kd> kb
ChildEBP RetAddr Args to Child
f64138c0 8048b640 ff0ce870 ff0d7c08 ff0cde88
f64138f0 8048d8e7 ff0cde88 f6413978 ff0cddc8
+0x1a
f6413900 8048de7f ff0cde88 f6413978 ff0cf448
er+0x43
f6413910 8048d8d5 ff0cf448 8048d8a4 f6413978
0x1f
f6413924 8048de7f ff0cf448 f6413978 ff0d3f48
er+0x31
f6413934 8048d8d5 ff0d3f48 8048d8a4 f6413978
0x1f
f6413948 8048d893 ff0d3f48 f6413978 e12052e8
er+0x31
f641395c 804f6f1b ff0d7c08 f6413978 8045c520

ntoskrnl!IopStartDevice (!devobj ff0ce870)

ntoskrnl!IopStartAndEnumerateDevice
ntoskrnl!IopProcessStartDevicesWork
ntoskrnl!IopForAllChildDeviceNodes+
ntoskrnl!IopProcessStartDevicesWork
ntoskrnl!IopForAllChildDeviceNodes+
ntoskrnl!IopProcessStartDevicesWork
ntoskrnl!IopProcessStartDevices+0x1

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 995 of 1651

f
f64139d0 804f5cc1 80088000 f6413aec 8045bba0 ntoskrnl!IopInitializeBootDrivers+0
x2f9
f6413b24 804f4db3 80088000 00000001 00000000 ntoskrnl!IoInitSystem+0x3a6
f6413da8 80447610 80088000 00000000 00000000 ntoskrnl!Phase1Initialization+0x6a3
f6413ddc 8045375a 804f4710 80088000 00000000 ntoskrnl!PspSystemThreadStartup+0x5
4
00000000 00000000 00000000 00000000 00000000 ntoskrnl!KiThreadStartup+0x16
kd> !devobj ff0ce870
Device object (ff0ce870) is for:
NTPNP_PCI0002 \Driver\PCI DriverObject ff0ceef0
Current Irp 00000000 RefCount 0 Type 00000022 Flags 00001040AttachedDev ff0cb9e0
DevExt ff0ce928 DevNode ff0cde88
Device queue is not busy.
kd> !devnode ff0cde88 6
DevNode 0xff0cde88 for PDO 0xff0ce870 at level 0x2
Parent 0xff0cf448
Sibling 0xff0cddc8
Child 0000000000
InterfaceType 0xffffffff Bus Number 0xffffffff
InstancePath is "PCI\VEN_8086&DEV_7010\0&69"
ServiceName is "intelide"
TargetDeviceNotify List - f 0xff0cdeec b 0xff0cdeec
Flags (0x00001209) DNF_PROCESSED, DNF_ENUMERATED,
DNF_RESOURCE_ASSIGNED, DNF_ADDED
(note that the device is not yet started)
CmResourceList at 0xe120fce8 Version 0.0 Interface 0x5 Bus #0
Entry 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0xfff0 for 0x10 bytes (these are the resources used: 0xfff0-0xffff)
Entry 1 - DevicePrivate (0x81) Device Exclusive (0x1)
Flags (0000) Data - {0x00000001, 0x00000004, 0000000000}
IoResList at 0xe120df88 : Interface 0x5 Bus 0 Slot 0x2d
Alternative 0 (Version 1.1)
Descriptor 0 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_IO
0x000010 byte range with alignment 0x000010
0 - 0xffff
(it could have used any 16 bytes that are 16-byte aligned between 0 and 0xffff)
Descriptor 1 - DevicePrivate (0x81) Device Exclusive (0x1)
Flags (0000) Data:
: 0x1 0x4 0x0
Example for PCMCIA:
kd> bp pcmcia!pcmciastartpccard
Loading symbols for 0x8039d000
kd> kb
Loading symbols for 0x80241000
ChildEBP RetAddr Args to Child
f6413814 803a7cbd ff0d0c30 e11d8808
f6413838 803a3798 ff0d0c30 ff0d1500
f6413848 80418641 ff0d0c30 ff0d1588
f641385c 802455cf ff0d1614 ff0d1638
f641387c 802497cf ff0d1588 ff0d0c30
f64138ac 80418641 ff0c8210 ff0d161c
f64138c0 8048de68 ff0c3508 ff0d16a8
f64138d4 8041ff5e ff0c8210 f64138f8
f6413920 8048b4ae ff0d0c30 ff0e0a68
f6413950 8048d707 ff0d16a8 f64139fc
f6413960 8048dc9f ff0d16a8 f64139fc
f6413970 8048d6f5 ff0d1e88 8048d6c4
f6413984 8048dc9f ff0d1e88 f64139fc
f6413994 8048d6f5 ff0d3268 8048d6c4
f64139a8 8048dc9f ff0d3268 f64139fc
f64139b8 8048d6f5 ff0d7b28 8048d6c4
f64139cc 8048d6b3 ff0d7b28 f64139fc
f64139e0 804f6c97 ff0e0a68 f64139fc
f6413a30 804f5601 000001e0 80087000
f6413b7c 804f4820 80087000 00000001
kd> !cmreslist e11d8808

pcmcia.sys ->
ndis.sys ->
ff0d0c30
ff0d1588
00000000
00040000
ff0c8210
ff0d1640
00000000
ff0c3508
ff0d16a8
00000000
ff0d1e88
f64139fc
ff0d3268
f64139fc
ff0d7b28
f64139fc
80087000
8045c140
00000000
00000000

pcmcia.sys
ndis.sys

pcmcia!PcmciaStartPcCard
pcmcia!PcmciaPdoPnpDispatch+0x169
pcmcia!PcmciaDispatch+0x3a
ntoskrnl!IofCallDriver+0x35
NDIS!ndisPassIrpDownTheStack+0x3b
NDIS!ndisPnPDispatch+0x1f9
ntoskrnl!IofCallDriver+0x35
ntoskrnl!IopAsynchronousCall+0x90
ntoskrnl!IopStartDevice+0x76
ntoskrnl!IopStartAndEnumerateDevice+0x1a
ntoskrnl!IopProcessStartDevicesWorker+0x43
ntoskrnl!IopForAllChildDeviceNodes+0x1f
ntoskrnl!IopProcessStartDevicesWorker+0x31
ntoskrnl!IopForAllChildDeviceNodes+0x1f
ntoskrnl!IopProcessStartDevicesWorker+0x31
ntoskrnl!IopForAllChildDeviceNodes+0x1f
ntoskrnl!IopProcessStartDevicesWorker+0x31
ntoskrnl!IopProcessStartDevices+0x1f
ntoskrnl!IopInitializeSystemDrivers+0x5b
ntoskrnl!IoInitSystem+0x3fe

CmResourceList at 0xe11d8808 Version 0.0 Interface 0x1 Bus #0

Entry 0 - Interrupt (0x2) Device Exclusive (0x1)
Flags (0x01) - LATCHED
Level 0x9, Vector 0x9, Affinity 0xffffffff
Entry 1 - Port (0x1) Device Exclusive (0x1)
Flags (0x01) - PORT_MEMORY PORT_IO
Range starts at 0xdfe0 for 0x20 bytes (started with IRQ 9, IO dfe0-dfff)
Entry 2 - DevicePrivate (0x81) Device Exclusive (0x1)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 996 of 1651

Flags (0000) Data - {0x00010120, 0000000000, 0000000000}

kd> g

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Advanced Debugging Techniques

This section includes:
Finding a Memory Leak
Debugging a Stalled System
Debugging a Time Out
Debugging a Service Application
Getting a Stack Trace
Debugging a Stack Overflow
Debugging a Failed Driver Unload
Debugging a Deadlock
Debugging a Device Installation Co-Installer
Reading Bug Check Callback Data
Debugging an Itanium Firmware Failure
Debugging a Dual-Boot Machine
Debugging Windows Setup and the OS Loader
Debugging CSRSS
Debugging WinLogon
Debugging a User-Mode Failure with KD
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Finding a Memory Leak

A memory leak occurs when a process allocates memory from the paged or nonpaged pools, but does not free the memory. As a result, these limited pools of memory are
depleted over time, causing Windows to slow down. If memory is completely depleted, failures may result.
This section includes the following:

Determining Whether a Leak Exists describes a technique you can use if you are not sure whether there is a memory leak on your system.
Finding a Kernel-Mode Memory Leak describes how to find a leak that is caused by a kernel-mode driver or component.
Finding a User-Mode Memory Leak describes how to find a leak that is caused by a user-mode driver or application.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Determining Whether a Leak Exists

If Windows performance is degrading over time and you suspect that a memory leak may be involved, the technique described in this section can indicate whether there is a
memory leak. It will not tell you what the source of the leak is, nor whether it is user mode or kernel mode.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 997 of 1651

Begin by launching Performance Monitor. Add the following counters:

Memory>Pool Nonpaged Bytes

Memory>Pool Paged Bytes
Paging File>% Usage

Change the update time to 600 seconds to capture a graph of the leak over time. You might also want to log the data to a file for later examination.
Start the application or test that you believe is causing the leak. Allow the application or test to run undisturbed for some time; do not use the target computer during this time.
Leaks are usually slow and may take hours to detect. Wait for a few hours before deciding whether a leak has occurred.
Monitor the Performance Monitor counters. After the test has started, the counter values will change rapidly, and it may take some time for the memory pools values to reach
a steady state.
User-mode memory leaks are always located in pageable pool and cause both the Pool Paged Bytes counter and the page file Usage counter to increase steadily over time.
Kernel-mode memory leaks usually deplete nonpaged pool, causing the Pool Nonpaged Bytes counter to increase, although pageable memory can be affected as well.
Occasionally these counters may show false positives because an application is caching data.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Finding a Kernel-Mode Memory Leak

Use the following techniques to determine the cause of a kernel-mode memory leak:
Using PoolMon to Find a Kernel-Mode Memory Leak
Using the Kernel Debugger to Find a Kernel-Mode Memory Leak
Using Driver Verifier to Find a Kernel-Mode Memory Leak
If you do not know which kernel-mode driver or component is responsible for the leak, you should use the PoolMon technique first. This technique reveals the pool tag
associated with the memory leak; the driver or component that uses this pool tag is responsible for the leak.
If you have already identified the responsible driver or component, use the second and third techniques in the preceding list to determine the cause of the leak more
specifically.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using PoolMon to Find a Kernel-Mode Memory Leak

If you suspect there is a kernel-mode memory leak, the easiest way to determine which pool tag is associated with the leak is to use the PoolMon tool.
PoolMon (Poolmon.exe) monitors pool memory usage by pool tag name. This tool is included in the Windows Driver Kit (WDK). For a full description, see
WDK documentation.

PoolMon in the

Enable Pool Tagging (Windows 2000 and Windows XP)

On Windows 2000 and Windows XP you must first use GFlags to enable pool tagging. GFlags is included in Debugging Tools for Windows. Start GFlags, choose the System
Registry tab, check the Enable Pool Tagging box, and then click Apply. You must restart Windows for this setting to take effect. For more details, see GFlags.
On Windows Server 2003 and later versions of Windows, pool tagging is always enabled.
Using PoolMon
The PoolMon header displays the total paged and non-paged pool bytes. The columns show pool use for each pool tag. The display is updated automatically every few
seconds. For example:
Memory: 16224K Avail: 4564K PageFlts: 31 InRam Krnl: 684K P: 680K
Commit: 24140K Limit: 24952K Peak: 24932K Pool N: 744K P: 2180K
Tag
Type Allocs
Frees
Diff
Bytes
Per Alloc
----------------------------------------------------------------------CM
Strg
Fat
MmSt

Paged
Paged
Paged
Paged

1283 ( 0)
10385 ( 10)
6662 ( 8)
614 ( 0)

1002
6658
4971
441

(
(
(
(

0)
4)
6)
0)

281
3727
1691
173

1377312
( 0)
317952 ( 512)
174560 ( 128)
83456
( 0)

4901
85
103
482

PoolMon has command keys that sort the output according to various criteria. Press the letter associated with each command in order to re-sort the data. It takes a few seconds

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 998 of 1651

for each command to work.

The sort commands include:
Command Key Operation
P
Limits the tags shown to nonpaged pool, paged pool, or both. Repeatedly pressing P cycles through each of these options, in that order.
B
Sorts tags by maximum byte usage.
M
Sorts tags by maximum byte allocations.
T
Sorts tags alphabetically by tag name.
E
Causes the display to include the paged and non-paged totals across the bottom.
A
Sorts tags by allocation size.
F
Sorts tags by free operations.
S
Sorts tags by the difference between allocations and frees.
Q
Quits PoolMon.
Using the PoolMon Utility to Find a Memory Leak
To find a memory leak with the PoolMon utility, follow this procedure:
1. Start PoolMon.
2. If you have determined that the leak is occurring in non-paged pool, press P once; if you have determined that it is occurring in paged pool, press P twice. If you do not
know, do not press P and both kinds of pool are included.
3. Press B to sort the display by maximum byte use.
4. Start your test. Take a screen shot and copy it to Notepad.
5. Take a new screen shot every half hour. By comparing screen shots, determine which tag's bytes are increasing.
6. Stop your test and wait a few hours. How much of the tag was freed up in this time?
Typically, after an application reaches a stable running state, it allocates memory and free memory at roughly the same rate. If it tends to allocate memory faster than it frees
it, its memory use will grow over time. This often indicates a memory leak.
Addressing the Leak
After you have determined which pool tag is associated with the leak, this might reveal all you need to know about the leak. If you need to determine which specific instance
of the allocation routine is causing the leak, see Using the Kernel Debugger to Find Kernel-Mode Memory Leaks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the Kernel Debugger to Find a Kernel-Mode Memory Leak

The kernel debugger determines the precise location of a kernel-mode memory leak.
Enable Pool Tagging (Windows 2000 and Windows XP)
On Windows 2000 and Windows XP, you must first use GFlags to enable pool tagging. GFlags is included in Debugging Tools for Windows. Start GFlags, choose the
System Registry tab, check the Enable Pool Tagging box, and then click Apply. You must restart Windows for this setting to take effect.
On Windows Server 2003 and later versions of Windows, pool tagging is always enabled.
Determining the Pool Tag of the Leak
To determine which pool tag is associated with the leak, it is usually easiest to use the PoolMon tool for this step. For details, see Using PoolMon to Find Kernel-Mode
Memory Leaks.
Alternatively, you can use the kernel debugger to look for tags associated with large pool allocations. To do so, follow this procedure:
1. Reload all modules by using the .reload (Reload Module) command.
2. Use the !poolused extension. Include the flag "4" to sort the output by paged memory use:
kd> !poolused 4
Sorting by Paged Pool Consumed
Pool Used:
Tag
Abc
Tron
IoN7
Gla5
Ggb

NonPaged
Allocs
Used
0
0
0
0
0
0
1
128
0
0

Paged
Allocs
Used
36405 33930272
552 7863232
10939
998432
2222
924352
22
828384

3. Determine which pool tag is associated with the greatest usage of memory. In this example, the driver using the tag "Abc" is using the most memoryalmost 34 MB.
Therefore, the memory leak is most likely to be in this driver.
Finding the Leak

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 999 of 1651

After you have determined the pool tag associated with the leak, follow this procedure to locate the leak itself:
1. Use the ed (Enter Values) command to modify the value of the global system variable PoolHitTag. This global variable causes the debugger to break whenever a pool
tag matching its value is used.
2. Set PoolHitTag equal to the tag that you suspect to be the source of the memory leak. The module name "nt" should be specified for faster symbol resolution. The tag
value must be entered in little-endian format (that is, backward). Because pool tags are always four characters, this tag is actually A-b-c-space, not merely A-b-c. So use
the following command:
kd> ed nt!poolhittag ' cbA'
3. To verify the current value of PoolHitTag, use the db (Display Memory) command:
kd> db nt!poolhittag L4
820f2ba4 41 62 63 20

Abc

4. The debugger will break every time that pool is allocated or freed with the tag Abc. Each time the debugger breaks on one of these allocations or free operations, use
the kb (Display Stack Backtrace) debugger command to view the stack trace.
Using this procedure, you can determine which code resident in memory is overallocating pool with the tag Abc.
To clear the breakpoint, set PoolHitTag to zero:
kd> ed nt!poolhittag 0
If there are several different places where memory with this tag is being allocated and these are in an application or driver that you have written, you can alter your source
code to use unique tags for each of these allocations.
If you cannot recompile the program but you want to determine which one of several possible locations in the code is causing the leak, you can unassemble the code at each
location and use the debugger to edit this code resident in memory so that each instance uses a distinct (and previously unused) pool tag. Then allow the system to run for
several minutes or more. After some time has passed, break in again with the debugger and use the !poolfind extension to find all pool allocations associated with each of the
new tags.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Driver Verifier to Find a Kernel-Mode Memory Leak

Driver Verifier determines whether a kernel-mode driver is leaking memory.
The Pool Tracking feature of Driver Verifier monitors the memory allocations made by a specified driver. At the time that the driver is unloaded, Driver Verifier verifies that
all allocations made by the driver have been freed. If some of the driver's allocations have not been freed, a bug check is issued, and the parameters of the bug check indicate
the nature of the problem.
While this feature is active, use the Driver Verifier Manager graphical interface to monitor pool allocation statistics. If a kernel debugger is attached to the driver, use the !
verifier 0x3 extension to display allocation statistics.
If the driver uses Direct Memory Access (DMA), the DMA Verification feature of Driver Verifier is also helpful in finding memory leaks. DMA Verification tests for a
number of common misuses of DMA routines, including failure to free common buffers and other errors that can lead to memory leaks. If a kernel debugger is attached while
this option is active, use the !dma extension to show allocation statistics.
For information about Driver Verifier, see

Driver Verifier in the Windows Driver Kit (WDK) documentation.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Finding a User-Mode Memory Leak

Use the following techniques to determine the cause of a user-mode memory leak:
Using Performance Monitor to Find a User-Mode Memory Leak
Using UMDH to Find a User-Mode Memory Leak
The first technique determines which process is leaking memory. After you know which process is involved, the second technique can determine the specific routine that is at
fault.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1000 of 1651

Debugging Tools for Windows

Using Performance Monitor to Find a User-Mode Memory Leak

If you suspect there is a user-mode memory leak but are not sure which process is causing it, you can use Performance Monitor to measure the memory usage of individual
processes.
Launch Performance Monitor. Add the following counters:

Process>Private Bytes (for each process you want to examine)

Process>Virtual Bytes (for each process you wish to examine)

Change the update time to 600 seconds to capture a graph of the leak over time. You might also want to log the data to a file for later examination.
The Private Bytes counter indicates the total amount of memory that a process has allocated, not including memory shared with other processes. The Virtual Bytes counter
indicates the current size of the virtual address space that the process is using.
Some memory leaks appear in the data file as an increase in private bytes allocated. Other memory leaks show up as an increase in the virtual address space.
After you have determined which process is leaking memory, use the UMDH tool to determine the specific routine that is at fault. For details, see Using UMDH to Find UserMode Memory Leaks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using UMDH to Find a User-Mode Memory Leak

The user-mode dump heap (UMDH) utility works with the operating system to analyze Windows heap allocations for a specific process. UMDH locates which routine in a
specific process is leaking memory.
UMDH is included in Debugging Tools for Windows. For full details, see UMDH.
Preparing to Use UMDH
If you have not already determined which process is leaking memory, do that first. For details, see Using Performance Monitor to Find User-Mode Memory Leaks.
The most important data in the UMDH logs are the stack traces of the heap allocations. To determine whether a process is leaking heap memory, analyze these stack traces.
Before using UMDH to display the stack trace data, you must use GFlags to configure your system properly. GFlags is included in Debugging Tools for Windows.
The following GFlags settings enable UMDH stack traces:

In the GFlags graphical interface, choose the Image File tab, type the process name (including the file name extension), press the TAB key, select Create user mode
stack trace database, and then click Apply.
Or, equivalently, use the following GFlags command line, where ImageName is the process name (including the file name extension):
gflags /i ImageName +ust

Before using UMDH, you must have access to the proper symbols for your application. UMDH uses the symbol path specified by the environment variable
_NT_SYMBOL_PATH. Set this variable equal to a path containing the symbols for your application. If you also include a path to Windows symbols, the analysis may be
more complete. The syntax for this symbol path is the same as that used by the debugger; for details, see Symbol Path.
For example, if the symbols for your application are located at C:\MySymbols, and you want to use the public Microsoft symbol store for your Windows symbols, using
C:\MyCache as your downstream store, you would use the following command to set your symbol path:
set _NT_SYMBOL_PATH=c:\mysymbols;srv*c:\mycache*http://msdl.microsoft.com/download/symbols
In addition, to assure accurate results, you must disable BSTR caching. To do this, set the OANOCACHE environment variable equal to one (1). Make this setting before you
launch the application whose allocations are to be traced.
If you need to trace the allocations made by a service, you must set OANOCACHE as a system environment variable and then restart Windows for this setting to take effect.
On Windows 2000, in addition to setting OANOCACHE equal to 1, you must also install the hotfix available with
and later versions of Windows.

KB 139071. This hotfix is not needed on Windows XP

Detecting Increases in Heap Allocations with UMDH

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1001 of 1651

After making these preparations, you can use UMDH to capture information about the heap allocations of a process. To do so, follow this procedure:
1. Determine the process ID (PID) for the process you want to investigate.
2. Use UMDH to analyze the heap memory allocations for this process, and save it to a log file. Use the -p switch with the PID, and the -f switch with the name of the log
file. For example, if the PID is 124, and you want to name the log file Log1.txt, use the following command:
umdh p:124 f:log1.txt
3. Use Notepad or another program to open the log file. This file contains the call stack for each heap allocation, the number of allocations made through that call stack,
and the number of bytes consumed through that call stack.
4. Because you are looking for a memory leak, the contents of a single log file are not sufficient. You must compare log files recorded at different times to determine
which allocations are growing.
UMDH can compare two different log files and display the change in their respective allocation sizes. You can use the greater-than symbol (>) to redirect the results
into a third text file. You may also want to include the -d option, which converts the byte and allocation counts from hexadecimal to decimal. For example, to compare
Log1.txt and Log2.txt, saving the results of the comparison to the file LogCompare.txt, use the following command:
umdh log1.txt log2.txt > logcompare.txt
5. Open the LogCompare.txt file. Its contents resemble the following:
+ 5320 ( f110 - 9df0) 3a allocs BackTrace00B53
Total increase == 5320
For each call stack (labeled "BackTrace") in the UMDH log files, there is a comparison made between the two log files. In this example, the first log file (Log1.txt)
recorded 0x9DF0 bytes allocated for BackTrace00B53, while the second log file recorded 0xF110 bytes, which means that there were 0x5320 additional bytes allocated
between the time the two logs were captured. The bytes came from the call stack identified by BackTrace00B53.
6. To determine what is in that backtrace, open one of the original log files (for example, Log2.txt) and search for "BackTrace00B53." The results are similar to this data:
00005320 bytes in 0x14 allocations (@ 0x00000428) by: BackTrace00B53
ntdll!RtlDebugAllocateHeap+0x000000FD
ntdll!RtlAllocateHeapSlowly+0x0000005A
ntdll!RtlAllocateHeap+0x00000808
MyApp!_heap_alloc_base+0x00000069
MyApp!_heap_alloc_dbg+0x000001A2
MyApp!_nh_malloc_dbg+0x00000023
MyApp!_nh_malloc+0x00000016
MyApp!operator new+0x0000000E
MyApp!DisplayMyGraphics+0x0000001E
MyApp!main+0x0000002C
MyApp!mainCRTStartup+0x000000FC
KERNEL32!BaseProcessStart+0x0000003D
This UMDH output shows that there were 0x5320 (decimal 21280) total bytes allocated from the call stack. These bytes were allocated from 0x14 (decimal 20) separate
allocations of 0x428 (decimal 1064) bytes each.
The call stack is given an identifier of "BackTrace00B53," and the calls in this stack are displayed. In reviewing the call stack, you see that the DisplayMyGraphics
routine is allocating memory through the new operator, which calls the routine malloc, which uses the Visual C++ run-time library to obtain memory from the heap.
Determine which of these calls is the last one to explicitly appear in your source code. In this case, it is probably the new operator because the call to malloc occurred as
part of the implementation of new rather than as a separate allocation. So this instance of the new operator in the DisplayMyGraphics routine is repeatedly allocating
memory that is not being freed.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Stalled System

There are times when the computer can stop responding without actually initiating a bug check. This "freeze" can appear in a variety of forms:

The mouse pointer can be moved, but does not affect any windows on the screen.
The entire screen is still and the mouse pointer does not move, but paging continues between the memory and the disk.
The screen is still and the disk is silent.

If the mouse pointer moves or there is paging to the disk, this is usually due to a problem within the Client Server Run-Time Subsystem (CSRSS).
If NTSD is running on CSRSS, press F12 and dump out each thread to see if there is anything out of the ordinary. (See Debugging CSRSS for more details.)
If an examination of CSRSS reveals nothing, then the problem may be with the kernel after all.
If there is no mouse movement or paging, then it is almost certainly a kernel problem.
Analyzing a kernel crash of this sort is generally a difficult task. To begin, break into KD (with CTRL+C) or WinDbg (with CTRL+BREAK). You can now use the debugger
commands to examine the situation.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1002 of 1651

Some useful techniques in this case include:

Finding the Failed Process
Debugging an Interrupt Storm
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Finding the Failed Process

Before finding the failed process, make sure that you are in the context of the accepting processor. To determine the accepting processor, use the !pcr extension on each
processor and looking for the processor for which an exception handler has been loaded. The exception handler of the accepting processor has an address other than
0xFFFFFFFF.
For example, because the address of NtTib.ExceptionList on this processor, is 0xFFFFFFFF, this is not the processor with the failed process:
0: kd> !pcr
PCR Processor 0 @ffdff000
NtTib.ExceptionList:
NtTib.StackBase:
NtTib.StackLimit:
NtTib.SubSystemTib:
NtTib.Version:
NtTib.UserPointer:
NtTib.SelfTib:

ffffffff
80470650
8046d860
00000000
00000000
00000000
00000000

SelfPcr:
Prcb:
Irql:
IRR:
IDR:
InterruptMode:
IDT:
GDT:
TSS:

ffdff000
ffdff120
00000000
00000000
ffffffff
00000000
80036400
80036000
80257000

CurrentThread: 8046c610
NextThread: 00000000
IdleThread: 8046c610
DpcQueue:
However, the results for Processor 1 are quite different. In this case, the value of NtTib.ExceptionList is f0823cc0, not 0xFFFFFFFF, indicating that this is the processor on
which the exception occurred.
0: kd> ~1
1: kd> !pcr
PCR Processor 1 @81497000
NtTib.ExceptionList:
NtTib.StackBase:
NtTib.StackLimit:
NtTib.SubSystemTib:
NtTib.Version:
NtTib.UserPointer:
NtTib.SelfTib:

f0823cc0
f0823df0
f0821000
00000000
00000000
00000000
00000000

SelfPcr:
Prcb:
Irql:
IRR:
IDR:
InterruptMode:
IDT:
GDT:
TSS:

81497000
81497120
00000000
00000000
ffffffff
00000000
8149b0e8
8149b908
81498000

CurrentThread: 81496d28
NextThread: 00000000
IdleThread: 81496d28
DpcQueue:
When you are in the correct processor context, the !process extension displays the currently running process.
The most interesting parts of the process dump are:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1003 of 1651

The times (a high value indicates that process might be the culprit).
The handle count (this is the number in parentheses after ObjectTable in the first entry).
The thread status (many processes have multiple threads). If the current process is Idle, it is likely that either the machine is truly idle or it hung due to some unusual
problem.

Although using the !process 0 7 extension is the best way to find the problem on a hung system, it is sometimes too much information to filter. Instead, use a !process 0 0 and
then a !process on the process handle for CSRSS and any other suspicious processes.
When using a !process 0 7, many of the threads might be marked "kernel stack not resident" because those stacks are paged out. If those pages are still in the cache that is in
transition, you can get more information by using a .cache decodeptes before !process 0 7:
kd> .cache decodeptes
kd> !process 0 7
If you can identify the failing process, use !process <process> 7 to show the kernel stacks for each thread in the process. This output can identify the problem in kernel mode
and reveal what the suspect process is calling.
In addition to !process, the following extensions can help to determine the cause of an unresponsive computer:
Extension
Effect
!ready
Identifies the threads that are ready to run, in order of priority.
!kdext*.locks Identifies any held resource locks, in case there is a deadlock with retail time outs.
!vm
Checks the virtual memory usage.
!poolused
Determines whether one type of pool allocation is disproportionately large (pool tagging required).
!memusage Checks the physical memory status.
!heap
Checks the validity of the heap.
!irpfind
Searches nonpaged pool for active IRPs.
If the information provided does not indicate an unusual condition, try setting a breakpoint at ntoskrnl!KiSwapThread to determine whether the processor is stuck in one
process or if it is still scheduling other processes. If it is not stuck, set breakpoints in common functions, such as NtReadFile, to determine whether the computer is stuck in a
specific code path.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging an Interrupt Storm

One of the most common examples of a stalled system is an interrupt storm. An interrupt storm is a level-triggered interrupt signal that remains in the asserted state.
The following events can cause an interrupt storm:

A hardware device does not release its interrupt signal after being directed to do so by the device driver.
A device driver does not instruct its hardware to release the interrupt signal, because it does not detect that the interrupt was initiated from its hardware.
A device driver claims the interrupt even though the interrupt was not initiated from its hardware. This situation can only occur when multiple devices are sharing the
same IRQ.
The edge level control register (ELCR) is not set correctly.
Edge and level interrupt-triggered devices share an IRQ (for example, a COM port and a PCI SCSI controller).

This example demonstrates one method for detecting and debugging an interrupt storm.
When the machine hangs, use a kernel debugger to break in. Use the !irpfind extension command to look for pending IRPs. Then, use the !irp extension to obtain details
about any pending IRPs. For example:
kd> !irp 81183468
Irp is active with 2 stacks 2 is current (= 0x811834fc)
No Mdl Thread 00000000: Irp stack trace.
cmd flg cl Device
File
Completion-Context
[ 0, 0]
0 0 8145f470 00000000 00000000-00000000
\Driver\E100B
Args: 00000000 00000000 00000000 00000000
>[ 16, 2]
0 e1 8145f470 00000000 8047f744-814187a8 Success Error Cancel pending
\Driver\E100B
ntoskrnl!PopCompleteSystemPowerIrp
Args: 00000000 00000000 00000002 00000002
This example shows that \driver\e100b has not returned the IRP for ntoskrnl!PopCompleteSystemPowerIrp. It appears to be stuck and might be experiencing an interrupt
storm.
To investigate, use the kb command to request a stack trace. For example:
kd> kb
ChildEBP
f714ee68
f714ee68
f714eeec
f714eeec

RetAddr
8046355a
80067a4f
8046380b
80463c50

Args to Child
00000001 80068c10
00000001 80068c10
01001010 0000003b
01001010 0000003b

00000030
00000030
f714ef00
f714ef00

ntoskrnl!RtlpBreakWithStatusInstruction
ntoskrnl!KeUpdateSystemTime+0x13e
halacpi!HalBeginSystemInterrupt+0x83
ntoskrnl!KiChainedDispatch+0x1b

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1004 of 1651

f714ef78 80067cc2 00000000 00000240 8000017c ntoskrnl!KiDispatchInterrupt

f714ef78 80501cb5 00000000 00000240 8000017c halacpi!HalpDispatchInterrupt2ndEnt
Notice that the section in bold is an interrupt dispatch. If you use the g command and break in again, you will very likely see a different stack trace, but you will still see an
interrupt dispatch. To determine which interrupt is responsible for the system stall, look at the second parameter passed into HalBeginSystemInterrupt (in this case, 0x3B).
The standard rule is that the interrupt vector displayed (0x3B) is the IRQ line plus 0x30, so the interrupt is number 0xB. Running another stack trace may provide more
information about which device issued the interrupt service request (ISR). In this case, a second stack trace has the following result:
kd> kb
ChildEBP
f714ee24
f714ee24
f714eed8
f714eee0
f714eef8
f714eef8
f714ef78
f714ef78
f714f084
f714f084
f714f118
f714f184
f714f204
f714f220
f714f254
f714f268
f714f288
f714f2a8
f714f2bc
f714f2d4

RetAddr
8046355a
bfe854b9
f7051796
80463850
80463818
80463c50
80067cc2
80501cb5
8045f744
8042e487
804ab556
8041f75b
804965cd
bfee1eb9
bfedb416
bfed4ddb
bfed5146
8041c60f
8044cc52
8044cb89

Args to Child
00000001 00000010
00000001 00000010
00000000 80463850
8143ec88 81444038
00000202 0000003b
00000202 0000003b
00000000 00000240
00000000 00000240
f714f16c 00020019
f714f16c 00020019
f714f16c 00020019
f714f1e8 8000017c
8145f630 00000000
8145f630 00000000
00000004 00000800
bfed0660 811a2708
811a2708 00000004
81453a30 811a2708
80475b18 811a2708
811a279c 811a2708

00000030
00000030
8143ec88
8046380b
80450bb8
80450bb8
8000017c
8000017c
f714f148
f714f148
f714f148
f714f1d0
00000001
8145f5a0
0045f570
811a2708
8145f570
80475b18
811a279c
811a27c0

ntoskrnl!RtlpBreakWithStatusInstruction
ntoskrnl!KeUpdateSystemTime+0x13e
atimpab!AtiInterrupt+0x109
VIDEOPRT!pVideoPortInterrupt+0x16
ntoskrnl!KiChainedDispatch2ndLvl+0x28
ntoskrnl!KiChainedDispatch+0x28
ntoskrnl!KiDispatchInterrupt
halacpi!HalpDispatchInterrupt2ndEntry+0x1b
ntoskrnl!NtCreateKey+0x113
ntoskrnl!KiSystemService+0xc4
ntoskrnl!ZwCreateKey+0xb
ntoskrnl!IopCreateRegistryKeyEx+0x4e
ntoskrnl!IopProcessSetInterfaceState+0x93
ntoskrnl!IoSetDeviceInterfaceState+0x2b
NDIS!ndisMCommonHaltMiniport+0x1f
NDIS!ndisPmHaltMiniport+0x9a
NDIS!ndisSetPower+0x1d1
NDIS!ndisPowerDispatch+0x84
ntoskrnl!IopfCallDriver+0x35
ntoskrnl!PopPresentIrp+0x62

The system is currently running the ISR for the video card. The system will run the ISR for each of the devices sharing IRQ 0xB. If no process claims the interrupt, the
operating system will wait infinitely, requesting the driver ISRs to handle the interrupt. It is also possible that a process might handle the interrupt and stop it, but if the
hardware is broken the interrupt may simply be re-asserted.
Use the !arbiter 4 extension to determine which devices are on IRQ 0xB. If there is only one device on IRQ 0xB, you have found the cause of the problem.. If there is more
than one device sharing the interrupt (99% of the cases), you will need to isolate the device either by manually programming LNK nodes (which is destructive to the system
state), or by removing or disabling hardware.
kd> !arbiter 4
DEVNODE 8149a008 (HTREE\ROOT\0)
Interrupt Arbiter "RootIRQ" at 80472a20
Allocated ranges:
0000000000000000 - 0000000000000000
0000000000000001 - 0000000000000001
0000000000000002 - 0000000000000002
0000000000000003 - 0000000000000003
0000000000000004 - 0000000000000004
0000000000000005 - 0000000000000005
0000000000000006 - 0000000000000006
0000000000000007 - 0000000000000007
0000000000000008 - 0000000000000008
0000000000000009 - 0000000000000009
000000000000000a - 000000000000000a
000000000000000b - 000000000000000b
000000000000000c - 000000000000000c
000000000000000d - 000000000000000d
000000000000000e - 000000000000000e
000000000000000f - 000000000000000f
0000000000000010 - 0000000000000010
0000000000000011 - 0000000000000011
0000000000000012 - 0000000000000012
0000000000000013 - 0000000000000013
0000000000000014 - 0000000000000014
0000000000000015 - 0000000000000015
0000000000000016 - 0000000000000016
0000000000000017 - 0000000000000017
0000000000000018 - 0000000000000018
0000000000000019 - 0000000000000019
000000000000001a - 000000000000001a
000000000000001b - 000000000000001b
000000000000001c - 000000000000001c
000000000000001d - 000000000000001d
000000000000001e - 000000000000001e
000000000000001f - 000000000000001f
0000000000000020 - 0000000000000020
0000000000000021 - 0000000000000021
0000000000000022 - 0000000000000022
0000000000000023 - 0000000000000023
0000000000000024 - 0000000000000024
0000000000000025 - 0000000000000025
0000000000000026 - 0000000000000026
0000000000000027 - 0000000000000027

B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B
B

8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1005 of 1651

0000000000000028 0000000000000029 000000000000002a 000000000000002b 000000000000002c 000000000000002d 000000000000002e 000000000000002f 0000000000000032 0000000000000039 Possible allocation:
< none >

0000000000000028
0000000000000029
000000000000002a
000000000000002b
000000000000002c
000000000000002d
000000000000002e
000000000000002f
0000000000000032
0000000000000039 S

B
B
B
B
B
B
B
B
B

DEVNODE 81476f28 (ACPI_HAL\PNP0C08\0)

Interrupt Arbiter "ACPI_IRQ" at bfff10e0
Allocated ranges:
0000000000000000 - 0000000000000000
0000000000000001 - 0000000000000001
0000000000000003 - 0000000000000003 S
0000000000000004 - 0000000000000004
0000000000000006 - 0000000000000006
0000000000000008 - 0000000000000008
0000000000000009 - 0000000000000009 S
000000000000000b - 000000000000000b S
000000000000000b - 000000000000000b
000000000000000b - 000000000000000b
000000000000000b - 000000000000000b
000000000000000b - 000000000000000b
000000000000000c - 000000000000000c
000000000000000d - 000000000000000d
000000000000000e - 000000000000000e
000000000000000f - 000000000000000f
Possible allocation:
< none >

8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
8149acd0
814776d0

S
S
S
S
B

(ACPI)

81495bb0
814952b0
81495610
8149acd0
81495730
81495a90
814776d0

(i8042prt)
(Serial)
(fdc)
(ACPI)

81453c30 (ds1)
81453a30 (E100B)
81493c30 (uhcd)
8145c390 (atirage3)
814953d0 (i8042prt)
81495850
8145bb50 (atapi)
8145b970 (atapi)

In this case, the audio, Universal Serial Bus (USB), network interface card (NIC), and video are all using the same IRQ.
To find out which ISR claims ownership of the interrupt, examine the return value from the ISR. Simply disassemble the ISR using the U command with address given in
the !arbiter display, and set a breakpoint on the last instruction of the ISR (which will be a 'ret' instruction). Note that using the command g <address> is the equivalent of
setting a breakpoint on that address:
kd> g bfe33e7b
ds1wdm!AdapterIsr+ad:
bfe33e7b c20800

ret

0x8

Use the r command to examine the registers. In particular, look at the EAX register. If the portion of the register contents in bold (in the following code example) is anything
other then zero, this ISR claimed the interrupt. Otherwise, the interrupt was not claimed, and the operating system will call the next ISR. This example shows that the video
card is not claiming the interrupt:
kd> r
eax=00000000 ebx=813f4ff0 ecx=00000010 edx=ffdff848 esi=8145d168 edi=813f4fc8
eip=bfe33e7b esp=f714eec4 ebp=f714eee0 iopl=0
nv up ei pl zr na po nc
cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000
efl=00000246
ds1wdm!AdapterIsr+ad:
bfe33e7b c20800
ret
0x8
In fact, in this case, the interrupt is not claimed by any of the devices on IRQ 0xb. When you encounter this problem, you should also check to see if each piece of hardware
associated with the interrupt is actually enabled. For PCI, this is easy look at the CMD register displayed by the !pci extension output:
kd> !pci 0 0
PCI Bus 0
00:0 8086:7190.03
01:0 8086:7191.03
03:0 1073:000c.03
04:0 8086:1229.05
07:0 8086:7110.02
07:1 8086:7111.01
07:2 8086:7112.01
07:3 8086:7113.02

Cmd[0006:.mb...]
Cmd[0107:imb..s]
Cmd[0000:......]
Cmd[0007:imb...]
Cmd[000f:imb...]
Cmd[0005:i.b...]
Cmd[0005:i.b...]
Cmd[0003:im....]

Sts[2210:c....]
Sts[0220:.6...]
Sts[0210:c....]
Sts[0290:c....]
Sts[0280:.....]
Sts[0280:.....]
Sts[0280:.....]
Sts[0280:.....]

Device Host bridge

PciBridge 0->1-1 PCI-PCI bridge
Device SubID:1073:000c Audio device
Device SubID:8086:0008 Ethernet
Device ISA bridge
Device IDE controller
Device USB host controller
Device Class:6:80:0

Note that the audio chip's CMD register is zero. This means the audio chip is effectively disabled at this time. This also means that the audio chip will not be capable of
responding to accesses by the driver.
In this case, the audio chip needs to be manually re-enabled.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1006 of 1651

Debugging a Time Out

There are two main time outs that occur on Windows systems:
Resource Time Outs (kernel mode)
Critical Section Time Outs (user mode)
In many cases, these problems are simply a matter of a thread taking too long to release a resource or exit a section of code.
On a retail system, the time-out value is set high enough that you would not see the break (a true deadlock would simply hang). The time-out values are set in the registry
under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\SessionManager. The integer values specify the number of seconds in each time out.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Resource Time Outs

During a resource time out, the thread waiting for the resource will break into the kernel debugger with a message similar to the following:
Resource @ 800e99c0
ActiveCount = 0001 Flags = IsOwnedExclusive sharedWaiter
NumberOfExclusiveWaiters = 0000
Thread = 809cd2f0, Count = 01
Thread = 809ebc50, Count = 01
Thread = 00000000, Count = 00
Thread = 00000000, Count = 00
Thread = 00000000, Count = 00
NT!DbgBreakPoint+0x4:
800cee04: 000000ad callkd
The thread that holds the lock is the first thread listed (or multiple threads if it is a shared lock). To examine that thread, use a !thread extension on the thread ID (809cd2f0,
in the previous example). This will give a stack for the thread owning the resource. If it is also waiting for a resource to become available, either the
ExpWaitForResourceExclusive function or the ExpWaitForResourceShared function will be on the stack for that thread.
The first parameter to ExpWaitForResourceXxx is the lock that is being waited on. To find out about that resource, use a !locks <resource id> extension, which will give
you another thread to check.
If you get to a thread that is not waiting for another resource, that thread is probably the source of the problem. For a list of all held locks, use a !locks extension with no
parameter at the kd> prompt.
Example
Resource @ fc664ee0

// Here's the resource lock address

ActiveCount = 0001 Flags = IsOwnedExclusive ExclusiveWaiter

NumberOfExclusiveWaiters = 0001
Thread = ffaf5410, Count = 01
// Here's the owning thread
Thread = 00000000, Count = 00
ntoskrnl!_DbgBreakPoint:
80131400 cc
int
3
kd> kb
// Start with a stack
ChildEBP RetAddr Args to Child
fcd44980 801154c0 fc664ee0 ffab45d0 00110001 ntoskrnl!_DbgBreakPoint
fcd4499c 80102521 fc664ee0 ffb08ea8 fcd44a4c ntoskrnl!_ExpWaitForResource+0x114

// Lock being waited on...

fcd449e8 fc6509fa e12597c8 fef27c08 fee4fca8 ntoskrnl!_ExAcquireResourceExclusiveLite+0xa5

00380020 00000000 00000000 00000000 00000000 nwrdr!_CreateScb+0x2ff
kd> !locks fc664ee0
// !locks resource address gives lock info
Resource @ nwrdr!_NwScavengerSpinLock (0xfc664ee0)
Exclusively owned
Contention Count = 45
NumberOfExclusiveWaiters = 1
Threads: ffaf5410-01
// Owning thread again
1 total locks, 1 locks currently held
kd> !thread ffaf5410

// Check the owning thread

THREAD ffaf5410 Cid e7.e8 Teb: 7ffde000 WAIT: (Executive) KernelMode Non-Alertable
feecf698 SynchronizationEvent
IRP List:
fef29208: (0006,00b8) Flags: 00000884 Mdl: feed8328
Not impersonating
Owning Process ffaf5690
WaitTime (seconds)
2781250

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1007 of 1651

Context Switch Count

183175
UserTime
0:00:23.0153
KernelTime
0:01:01.0187
Start Address 0x77f04644
Initial Sp fec6c000 Current Sp fec6b938
Priority 11 BasePriority 7 PriorityDecrement 0 DecrementCount 8
ChildEBP
fec6b950
fec6b974
fec6ba5c
fec6ba28
fec6bac0
fec6bb6c

RetAddr
801044fc
fc655976
fc6509fa
fc6533e5
fc652f26
fc652b14

Args to Child
feecf668 feecf668
feecf698 00000000
e1263968 fef29208
feecf668 e125b3c8
feecf668 fec6bae4
feecf668 fef29208

00000080
00000000
feecf668
ffafae08
fef29208
fee50b60

ntoskrnl!KiSwapContext+0x25
ntoskrnl!_KeWaitForSingleObject+0x218
nwrdr!_ExchangeWithWait+0x38
nwrdr!_CreateScb+0x2ff
nwrdr!_CreateRemoteFile+0x2c9
nwrdr!_NwCommonCreate+0x3a2

fec6bbac
fec6bbc0
fec6bd10
fec6bd7c
fec6be5c
fec6bef4
fec6bef4

80107aea
80142792
80145403
80144c0c
80127803
801385c3
77f716ab

fee50b60
fef37700
fee50b60
00000000
0012dd64
0012dd64
0012dd64

804052ac
fee50b28
fec6bdbc
00000040
80127701
00000000
00000000

nwrdr!_NwFsdCreate+0x56
ntoskrnl!IofCallDriver+0x38
ntoskrnl!_IopParseDevice+0x6a0
ntoskrnl!_ObpLookupObjectName+0x479
ntoskrnl!_ObOpenObjectByName+0xa2
ntoskrnl!_NtQueryAttributesFile+0xc1
ntoskrnl!_KiSystemService+0x83

fef29208
fec6bdbc
00000000
fec6be34
00000000
0012dd3c
0012dd3c

0012dd20 00000000 00000000 00000000 00000000 ntdll!_ZwQueryAttributesFile+0xb

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Critical Section Time Outs

Critical section time outs can be identified by the stack trace that shows the routine RtlpWaitForCriticalSection near the top of the stack. Another variety of critical section
time out is a possible deadlock application error. To debug critical section time outs properly, CDB or WinDbg is necessary.
As with resource time outs, the !ntsdexts.locks extension will give a list of locks currently held and the threads that own them. Unlike resource time outs, the thread IDs given
are not immediately useful. These are system IDs that do not map directly to the thread numbers used by CDB.
Just as with ExpWaitForResourceXxx, the lock identifier is the first parameter to RtlpWaitForCriticalSection. Continue tracing the chain of waits until either a loop is
found or the final thread is not waiting for a critical section time out.
Example of Debugging a Critical Time Out
Start by displaying the stack:
0:024> kb
ChildEBP
0569fca4
0569fd04
0569fd0c
0569fd70
0569fd8c
0569fdc0

RetAddr
77f79c78
77f71048
5fef0b4b
5fedf83f
5fedfa5b
5fedf678

Args to Child
77f71000 002a6b88
5ffa9f9c 5fef0b4b
5ffa9f9c 002a6b88
002a6b88 0569fdc0
002a6b88 00190000
0569ff18 0031c200

7fffffff
5ffa9f9c
002a0019
0000003e
00000000
0335ee88

ntdll!_DbgBreakPoint
ntdll!_RtlpWaitForCriticalSection+0x89
ntdll!_RtlEnterCriticalSection+0x48
winsrv!_StreamScrollRegion+0x1f0
winsrv!_AdjustCursorPosition+0x8e
winsrv!_DoWriteConsole+0x104

0569fefc 5fe6311b 0569ff18 0569ffd0 00000005 winsrv!_SrvWriteConsole+0x96

0569fff4 00000000 00000000 00000024 00000024 csrsrv!_CsrApiRequestThread+0x4ff
Now use the !ntsdexts.locks extension to find the critical section:
0:024> !locks
CritSec winsrv!_ScrollBufferLock at 5ffa9f9c
5ffa9f9c is the first one
LockCount
5
RecursionCount
1
OwningThread
88
// here's the owning thread ID
EntryCount
11c
ContentionCount
135
*** Locked
CritSec winsrv!_gcsUserSrv+0 at 5ffa91b4
LockCount
RecursionCount
OwningThread
EntryCount
ContentionCount
*** Locked

8
1
6d
1d6c
1d47

//second critical section found below

// second owning thread

Now search for the thread that has the ID number 0x6D:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

0:024> ~
0 id:
1 id:
2 id:
3 id:
4 id:
5 id:
6 id:
7 id:
8 id:
9 id:
10 id:
11 id:
12 id:
13 id:
14 id:
15 id:
16 id:
17 id:
18 id:
19 id:
20 id:
21 id:
22 id:
23 id:
24 id:

16.15
16.13
16.30
16.2f
16.2e
16.6c
16.6d
16.2d
16.33
16.42
16.6f
16.6e
16.52
16.61
16.7e
16.43
16.89
16.95
16.90
16.71
16.bb
16.88
16.cd
16.c1
16.bd

Page 1008 of 1651

Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb
Teb

7ffdd000
7ffdb000
7ffda000
7ffd9000
7ffd8000
7ff6c000
7ff68000
7ffd7000
7ffd6000
7ff6f000
7ff6e000
7ffd5000
7ff6b000
7ff6a000
7ff69000
7ff67000
7ff50000
7ff65000
7ff64000
7ff63000
7ff62000
7ff61000
7ff5e000
7ff5f000
7ff5d000

Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen
Unfrozen

// this thread owns the second critical section

// this thread owns the first critical section

Thread 21 owns the first critical section. Make that the active thread and get a stack trace:
0:024> ~21s
ntdll!_ZwWaitForSingleObject+0xb:
77f71bfb c20c00
ret
0xc
0:021> kb
ChildEBP
0556fc44
0556fcb0
0556fcb8
0556fcf4
0556fd70
0556fd8c

RetAddr
77f79c20
77f71048
5feb4f7e
5fef0b76
5fedf83f
5fedfa5b

Args to Child
00000110 00000000
5ffa91b4 5feb4f7e
5ffa91b4 0556fd70
01302005 00000000
002bd880 0556fdc0
002bd880 00190000

77fa4700
5ffa91b4
77f71000
fffffff4
00000025
00000000

ntdll!_ZwWaitForSingleObject+0xb
ntdll!_RtlpWaitForCriticalSection+0x31
ntdll!_RtlEnterCriticalSection+0x48
winsrv!__ScrollDC+0x14
winsrv!_StreamScrollRegion+0x21b
winsrv!_AdjustCursorPosition+0x8e

0556fdc0 5fedf678 0556ff18 002bdf70 002a4d58 winsrv!_DoWriteConsole+0x104

0556fefc 5fe6311b 0556ff18 0556ffd0 00000005 winsrv!_SrvWriteConsole+0x96
0556fff4 00000000 00000000 00000024 00000024 csrsrv!_CsrApiRequestThread+0x4ff
Thread 6 owns the second critical section. Examine its stack as well:
0:021> ~6s
winsrv!_PtiFromThreadId+0xd:
5fe8429a 394858
cmp

[eax+0x58],ecx

ds:0023:7f504da8=000000f8

0:006> kb
ChildEBP
01ecfeb4
01ecfed0
01ecfefc
01ecfff4

RetAddr
5fecd0d7
5feccf62
5fe6311b
00000000

Args to Child
00000086 00000000
00000086 01ecfff4
01ecff18 01ecffd0
00000000 00000024

7f5738e0
00000113
00000005
00000024

winsrv!_PtiFromThreadId+0xd
winsrv!__GetThreadDesktop+0x12
winsrv!___GetThreadDesktop+0x8b
csrsrv!_CsrApiRequestThread+0x4ff

Thread 21 has RtlpWaitForCriticalSection near the top of its stack. Thread 6 does not. So thread 21 is the culprit.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Service Application

A service, also known as a Windows service, is a user-mode process designed to be started by Windows without human interaction. It is started automatically at system boot,
or by an application that uses the service functions included in the Win32 API. A service can also be started by a human user through the Services control panel utility. Every
service must conform to the interface rules of the service control manager (SCM).
Each service is composed of three elements: a service application, a service control program, and the service control manager itself. Although a service application is
sometimes (incorrectly) referred to as a "service," it is actually one of the three components that make up a service. The service application can contain almost any kind of
user-mode code. The service control program controls when the service application starts and stops. The service control manager is part of Windows.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1009 of 1651

The following sections describe how to debug a service application:

Choosing the Best Method
Preparing to Debug the Service Application
Debugging the Service Application Automatically
Debugging the Service Application Manually
For an overview of services, service applications, and the service control manager, see Microsoft Windows Internals: Microsoft Windows Server 2003, Windows XP, and
Windows 2000 by David A. Solomon and Mark E. Russinovich (4th edition, Microsoft Press, 2005).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Choosing the Best Method

There are several different ways to debug a service application. In order to choose the correct method, you must first make two choices: the time at which the debugger is
attached to the service application and what debugging configuration to use.
There are three stages at which the debugger can be attached to the service application:

The very beginning of the service startup. The debugger is automatically launched when the service begins. Choose this option if you want to debug the service's
initialization code.
The first time that the service encounters an exception. The debugger is automatically launched when an exception or crash occurs or if the service application calls the
DebugBreak function. Choose this option if you want the debugger to appear when a problem is encountered but not before.
After the service is running normally. You can manually attach a debugger to a service that is already running at any time. Choose this option if you do not want to
make advance preparations for debugging.

There are three debugging configurations you can choose:

Local debugging. A single debugger, running on the same computer as the service.
Remote debugging. A debugging server running on the same computer as the service, being controlled from a debugging client running on a second computer.
Kernel-controlled user-mode debugging. A user-mode debugger running on the same computer as the service, being controlled from a kernel debugger on a second
computer.

If your service is running on Windows 2000, Windows XP, or Windows Server 2003, you can combine any of these three attach options with any of these three debugging
configuration options.
If your service is running on Windows Vista or a later version of Windows, there is one restriction on how these choices can be combined. If you want to debug from the
beginning of the service startup, or from the time that an exception is encountered, you must use either remote debugging or kernel-controlled user-mode debugging.
In other words, on Windows Vista and later, you cannot use local debugging unless you plan to attach the debugger manually after the service is already running. This
restriction results from the fact that in these versions of Windows, services run in session 0, and any debugger that is automatically launched and attached to the service is also
in session 0, and does not have a user interface on the computer that the service is running on.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Preparing to Debug the Service Application

This topic lists all the preparatory steps that may be required prior to debugging a service application. Which steps are required in your scenario depends on which attach
option you have chosen and which debugging configuration you have chosen. For a list of these choices, see Choosing the Best Method.
Each of the preparatory steps described in this topic specifies the conditions under which it is required. These steps can be done in any order.
Enabling the Debugging of the Initialization Code
If you plan to debug the service application from the beginning of its execution, including its initialization code, this preparatory step is required.
Locate or create the following registry key, where ProgramName is the name of the service application's executable file:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ProgramName
ProgramName should include the file name extension, but not the path. For example, ProgramName might be Myservice.exe or Thisservice.dll.
Under this registry key, create a string data value entitled Debugger. The value of this string should be set to the full path and file name of a debugger to be attached to the
service application.

If you plan to debug locally, use a string such as the following:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1010 of 1651

c:\Debuggers\windbg.exe
Do not choose this option if you are running Windows Vista or a later version of Windows.

If you plan to use remote debugging, specify NTSD with the -noio option. This causes NTSD to run without any console of its own, accessible only through the remote
connection. For example:
c:\Debuggers\ntsd.exe -server ServerTransport -noio -y SymbolPath
If your debugging session begins before Windows is fully loaded, you may not be able to access symbols from a remote share; in such a case, you must use local
symbols. ServerTransport must specify a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or
NPIPE. For the syntax of ServerTransport, see Activating a Debugging Server.

If you plan to control the user-mode debugger from a kernel-mode debugger, specify NTSD with the -d option. For example:
c:\Debuggers\ntsd.exe -d -y SymbolPath
If you plan to use this method and your user-mode symbols will be accessed from a symbol server, you should combine this method with remote debugging. In this
case, specify NTSD with the -ddefer option. Choose a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such
as TCP or NPIPE. For example:
c:\Debuggers\ntsd.exe -server ServerTransport -ddefer -y SymbolPath
For details, see Controlling the User-Mode Debugger from the Kernel Debugger.

After this registry edit is complete, the debugger is launched whenever a service with this name is started or restarted.
Enabling the Service Application to Break Into the Debugger
If you want the service application to break into the debugger when it crashes or encounters an exception, this preparatory step is required. This step is also required if you
want the service application to break into the debugger by calling the DebugBreak function.
Note: If you have enabled debugging of the initialization code (the step described in the subsection Enabling the Debugging of the Initialization Code), you should skip
this step. When initialization code debugging is enabled, the debugger attaches to the service application when it starts, which causes all crashes, exceptions, and calls to
DebugBreak to be routed to the debugger without additional preparations being needed.
This preparatory step involves registering the chosen debugger as the postmortem debugger. This is done by using the -iae or -iaec options on the debugger command line.
We recommend the following commands, but if you want to vary them, see the syntax details in Enabling Postmortem Debugging.

If you plan to debug locally, use a command such as the following:

windbg -iae
Do not choose this option if you are running Windows Vista or a later version of Windows.

If you plan to use remote debugging, specify NTSD with the -noio option. This causes NTSD to run without any console of its own, accessible only through the remote
connection. To install a postmortem debugger that includes the -server parameter, you must manually edit the registry; for details, see Enabling Postmortem
Debugging. For example, the Debugger value of the AeDebug key could be the following:
ntsd -server npipe:pipe=myproc%x -noio -p %ld -e %ld -g -y SymbolPath
In the pipe specification, the %x token is replaced with the process ID of the process that launches the debugger. This guarantees that if more than one process launches
a postmortem debugger, each has a unique pipe name. If your debugging session begins before Windows is fully loaded, you may not be able to access symbols from a
remote share; in such a case, you must use local symbols. ServerTransport must specify a transport protocol that is implemented by the Windows kernel without
interfacing with a user-mode service, such as TCP or NPIPE. For the syntax of ServerTransport, see Activating a Debugging Server.

If you plan to control the user-mode debugger from a kernel-mode debugger, specify NTSD with the -d option. For example:
ntsd -iaec -d -y SymbolPath
If you choose this method and intend to access user-mode symbols from a symbol server, you should combine this method with remote debugging. In this case, specify
NTSD with the -ddefer option. Choose a transport protocol that is implemented by the Windows kernel without interfacing with a user-mode service, such as TCP or
NPIPE. To install a postmortem debugger that includes the -server parameter, you must manually edit the registry; for details, see Enabling Postmortem Debugging.
For example, the Debugger value of the AeDebug key could be the following:
ntsd -server npipe:pipe=myproc%x -ddefer -p %ld -e %ld -g -y SymbolPath
For details, see Controlling the User-Mode Debugger from the Kernel Debugger.

When you issue one of these commands, the postmortem debugger is registered. This debugger will be launched whenever any user-mode program, including a service
application, encounters an exception or runs a DebugBreak function.
Adjusting the Service Application Timeout
If you plan to launch the debugger automatically (either when the service starts or when it encounters an exception), this preparatory step is required.
Locate the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
Under this key, locate or create a DWORD data value called ServicesPipeTimeout. Set this entry to the amount of time in milliseconds that you want the service to wait

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1011 of 1651

before timing out. For example, a value of 60,000 is one minute, while a value of 86,400,000 is 24 hours. When this registry value is not set, the default timeout is about thirty
seconds.
The significance of this value is that a clock starts to run when each service is launched, and when the timeout value is reached, any debugger attached to the service is
terminated. Therefore, the value you choose should be longer than the total amount of time that elapses between the launching of the service and the completion of your
debugging session.
This setting applies to every service that is started or restarted after the registry edit is complete. If some service crashes or hangs and this setting is still in effect, the problem
is not detected by Windows. Therefore, you should use this setting only while you are debugging, and return the registry key to its original value after your debugging is
complete.
Isolating the Service
Sometimes, multiple services are combined in a single Service Host (Svchost) process. If you want to debug such a service, you must first isolate it into a separate Svchost
process.
There are three methods by which you can isolate a service. Microsoft recommends the Moving the Service to its Own Group method, as follows. The alternative methods
(Changing the Service Type and Duplicating the SvcHost Binary) can be used on a temporary basis for debugging, but because they alter the way the service runs, they are not
as reliable as the first method.
Preferred Method: Moving the Service to its Own Group
1. Issue the following Service Configuration tool (Sc.exe) command, where ServiceName is the name of the service:
sc qc ServiceName
This displays the current configuation values for the service. The value of interest is BINARY_PATH_NAME, which specifies the command line used to launch the
service control program. In this scenario, because your service is not yet isolated, this command line includes a directory path, Svchost.exe, and some SvcHost
parameters, including the -k switch, followed by a group name. For example, it may look something like this:
%SystemRoot%\System32\svchost.exe -k LocalServiceNoNetwork
Remember this path and the group name; they are used in steps 5 and 6.
2. Locate the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost
Create a new REG_MULTI_SZ value with a unique name (for example, TempGrp).
3. Set this new value equal to the name of the service that you want to isolate. Do not include any directory path or file name extension. For example, you might set the
new value TempGrp equal to MyService.
4. Under the same registry key, create a new key with the same name you used in step 2. For example:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\TempGrp
Now the SvcHost key contains a value with the new name and also has a subordinate key with this same name.
5. Look for another key subordinate to the SvcHost key that has the same name as the group you found in step 1. If such a key exists, examine all the values in it, and
create duplicates of them in the new key you created in step 4.
For example, the old key might be named this:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\LocalServiceNoNetwork
and it might contain values such as CoInitializeSecurityParam, AuthenticationCapabilities, and other values. You would go to the newly created key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\SvcHost\TempGrp
and create values in it that are identical in name, type, and data to those in the old key.
If the old key does not exist, you do not need to create a new key.
6. Use the following Service Configuration tool command to revise the path found in step 1:
sc config ServiceName binPath= "RevisedPath"
In this command, ServiceName is the name of the service, and RevisedPath is the new value you are supplying for BINARY_PATH_NAME. For RevisedPath, use the
exact same path as the one displayed in step 1, including all the options shown on that line, making only one change: replace the parameter following the -k switch with
the name of the new registry value you created in step 2. Enclose RevisedPath in quotation marks. The space after the equal sign is required.
For example, your command might look like this:
sc config MyService binPath= "%SystemRoot%\System32\svchost.exe -k TempGrp"
You may want to use the sc qc command again to review the change you have made.
These settings will take effect the next time the service is started. To clear the effects of the old service, we recommend that you restart Windows rather than just restarting the
service.
After you have completed your debugging, if you want to return this service to the shared service host, use the sc config command again to return the binary path to its

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1012 of 1651

original value, and delete the new registry keys and values you created..
Alternative Method: Changing the Service Type
1. Issue the following Service Configuration tool (Sc.exe) command, where ServiceName is the name of the service:
sc config ServiceName type= own
The space after the equal sign is required.
2. Restart the service, by using the following commands:
net stop ServiceName
net start ServiceName
This alternative is not the recommended method because it can alter the behavior of the service. If you do use this method, use the following command to revert to the normal
behavior after you have completed your debugging:
sc config ServiceName type= share
Alternative Method: Duplicating the SvcHost Binary
1. The Svchost.exe executable file is located in the system32 directory of Windows. Make a copy of this file, name it svhost2.exe, and place it in the system32 directory as
well.
2. Issue the following Service Configuration tool (Sc.exe) command, where ServiceName is the name of the service:
sc qc ServiceName
This command displays the current configuation values for the service. The value of interest is BINARY_PATH_NAME, which specifies the command line used to
launch the service control program. In this scenario, because your service is not yet isolated, this command line will include a directory path, Svchost.exe, and probably
some SvcHost parameters. For example, it may look something like this:
%SystemRoot%\System32\svchost.exe -k LocalServiceNoNetwork
3. To revise this path, issue the following command:
sc config ServiceName binPath= "RevisedPath"
In this command, ServiceName is the name of the service, and RevisedPath is the new value you are supplying for BINARY_PATH_NAME. For RevisedPath, use the
exact same path as the one displayed in step 2, including all the options shown on that line, making only one change: replace Svchost.exe with Svchost2.exe. Enclose
RevisedPath in quotation marks. The space after the equal sign is required.
For example, your command might look like this:
sc config MyService binPath= "%SystemRoot%\System32\svchost2.exe -k LocalServiceNoNetwork"
You can use the sc qc command again to review the change you have made.
4. Restart the service by using the following commands:
net stop ServiceName
net start ServiceName
This alternative is not the recommended method because it can alter the behavior of the service. If you do use this method, use the sc config command to change the path back
to its original value after you have completed your debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging the Service Application Automatically

A debugger can be launched automatically when the service application starts up. Alternatively, it can be launched automatically when the service application encounters an
exception or executes a DebugBreak command. If you have chosen one of these methods, this topic explains how to proceed. If you are not sure which method to choose, see
Choosing the Best Method.
Then use the following procedure:
1. Do one of the following preparatory steps:
If you plan to debug the service application from the very beginning, including its initialization code, follow the procedure described in Enabling the Debugging
of the Initialization Code. Alternatively, if you want the service application to break into the debugger when it crashes or encounters an exception, follow the
procedure described in Enabling the Service Application to Break Into the Debugger.
To assure that the service application will allow the debugger to run properly, perform the procedure described in Adjusting the Service Application Timeout.
If the service is combined with other services in a single SvcHost process, perform the procedure described in Isolating the Service.
2. If the service is already running, you must restart it for these changes to take effect. We recommend that you restart Windows itself, in order to remove any effects of
the running service. If you do not want to restart Windows, use the following commands, where ServiceName is the name of the service:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1013 of 1651

net stop ServiceName

net start ServiceName
3. If you have chosen to debug the service application's initialization code, when the the service starts, the debugger is launched and attaches to the service application.
If you have chosen to let the debugger be triggered by an exception, the service application executes normally until it encounters an exception or executes a
DebugBreak function. At this point, the debugger is launched and attaches to the service application.
4. The next step depends on the debugger command line you specified during step 1:
If you specified a debugger without any remoting options, this debugger is launched and its window becomes visible.
If you specified NTSD with the -server and -noio options, NTSD is launched without a console window. You can then connect to the debugging session from
another computer by starting any user-mode debugger with the -remote parameter. For instructions, see Activating a Debugging Client.
If you specified NTSD with the -d option, NTSD is launched without a console window. You can then connect to the debugging session by using kernel debugger
running on another computer. For instructions, see Controlling the User-Mode Debugger from the Kernel Debugger.
If you specified NTSD with the -ddefer and -server options, NTSD is launched without a console window. You can then connect to the debugging session by
using both a kernel debugger and a user-mode remote debugger, running on a different computer than the service (but possibly the same computer as each other).
For instructions, see Combining This Method with Remote Debugging.
5. When the debugger starts, the service pauses at the initial process breakpoint, the exception, or the DebugBreak command. This enables you to examine the current
state of the service application, set breakpoints, and make any other desired configuration choices.
6. Use g (Go) or another execution command to resume the execution of the service application. For other available commands, see Debugger Operation (User Mode) and
Debugger Operation (User Mode).
Additional Information
For information on the DebugBreak function, see

DebugBreak in the Microsoft Windows SDK.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging the Service Application Manually

Manually attaching to a service application after it has been started is much like debugging any running user-mode process.
Use the TList tool with the /s option to display the process ID (PID) of each running process and the services active in each process.
If the service application you want to debug is combined with other services in a single process, you must isolate it before debugging it. To do this, perform the procedure
described in Isolating the Service. At the end of this procedure, restart the service.
To determine the new PID of the service, issue the following Service Configuration tool (Sc.exe) command, where ServiceName is the name of the service:
sc queryex ServiceName
Now start WinDbg or CDB with this service application as the target. There are three ways to do this: by specifying the PID with the -p option, by specifying the executable
name with the -pn option (if the executable name is unique), or by specifying the service name with the -psn option.
For example, if the process SpoolSv.exe has a PID of 651 and contains the service named Spooler, the following three commands are equivalent:
windbg -p 651 [AdditionalOptions]
windbg -pn spoolsv.exe [AdditionalOptions]
windbg -psn spooler [AdditionalOptions]
After the debugger starts, proceed as you would in any other user-mode debugging session. For an overview of available options, see Debugger Operation (User Mode) and
Debugger Operation (User Mode).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Getting a Stack Trace

This section includes:
Anatomy of a Stack Trace
Manually Walking a Stack
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1014 of 1651

Debugging Tools for Windows

Anatomy of a Stack Trace

Basic stack information is stored in the registers. Use the r (Registers) command to display these:
kd> r [This command displays register values.]
eax=c0000018 ebx=80621828 ecx=00000000 edx=807da761 esi=e12e0e28 edi=e12df868
eip=f28343b3 esp=f2c132cc ebp=f2c132f0 iopl=0
nv up ei pl zr na po nc
cs=0008 ss=0010 ds=0023 es=0023 fs=0030 gs=0000
efl=00000246
VIDEOPRT!pVideoPortReportResourceList+0x263:
f28343b3 8db340010000
lea
esi,[ebx+0x140]
ds:0023:80621968=00000000
The registers are used as follows:

esp = stack pointer

ebp = base pointer
eip = instruction pointer
eax, ebx, ecx, edx = general-purpose registers for storing intermediate results
edi, esi = often used as general registers

A stack trace could be diagrammed in the following manner:

Arguments
Return Address
Caller's EBP
Local Variables

The stack trace displayed on a kernel debugger is written in assembly code. A simple set of instructions in assembly code could look like this:
push ebp
;Places the caller's base pointer (ebp) onto the stack
mov ebp,esp
;Sets the base pointer (ebp) equal to the stack pointer (esp)
mov eax, [ebp+8]
;Grab the value of the first argument off the stack and store it in eax
add eax, [ebp+c]
;Add the second argument's value to the value in eax
pop ebp
;Restore the caller's base pointer
ret 8
;Return to the calling function and remove 8 bytes from the stack
The compiler can optimize this code, simplifying it so it is shorter and more direct. An optimized routine might look like the following (note how the code omits references to
the base pointer):
mov eax, [esp+4]
add eax, [esp+8]
ret 8
Finally following is how it would look in C:
ULONG Add(ULONG a, ULONG b)
{
return a + b;
}

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Manually Walking a Stack

In some cases, the stack trace function will fail in the debugger. This can be caused by a call to an invalid address that caused the debugger to lose the location of the return
address; or you may have come across a stack pointer for which you cannot directly get a stack trace; or there could be some other debugger problem. In any case, being able
to manually walk a stack is often valuable.
The basic concept is fairly simple: dump out the stack pointer, find out where the modules are loaded, find possible function addresses, and verify by checking to see if each
possible stack entry makes a call to the next.
Before going through an example, it is important to note that the kb (Display Stack Backtrace) command has an additional feature on Intel systems. By doing a kb=[ebp]
[eip] [esp], the debugger will display the stack trace for the frame with the given values for base pointer, instruction pointer, and stack pointer, respectively.
For the example, a failure that actually gives a stack trace is used so the results can be checked at the end.
The first step is to find out what modules are loaded where. This is accomplished with the x (Examine Symbols) command (some symbols are edited out for reasons of
length):
kd> x *!
start
end
77f70000 77fb8000
80010000 80012320

module name
ntdll
(C:\debug\ntdll.dll, \\ntstress\symbols\dll\ntdll.DBG)
Aha154x
(load from Aha154x.sys deferred)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1015 of 1651

80013000 8001aa60
8001b000 8001fba0

SCSIPORT
Scsidisk

(load from SCSIPORT.SYS deferred)

(load from Scsidisk.sys deferred)

80100000
802f0000
80400000
fe4c0000
fe4d0000
fe4e0000
fe500000
fe510000

801b7b40
8033c000
8040c000
fe4c38c0
fe4d3e60
fe4f0e40
fe5057a0
fe519560

NT
Ntfs
hal
vga
VIDEOPRT
ati
Msfs
Npfs

(ntoskrnl.exe, \\ntstress\symbols\exe\ntoskrnl.DBG)
(load from Ntfs.sys deferred)
(load from hal.dll deferred)
(load from vga.sys deferred)
(load from VIDEOPRT.SYS deferred)
(load from ati.SYS deferred)
(load from Msfs.SYS deferred)
(load from Npfs.SYS deferred)

fe520000
fe530000
fe5603e0
fe580000
fe590000
fe5a0000
fe5c0000
fe5d0000

fe521f60
fe54ed20
fe575360
fe585920
fe59b8a0
fe5b7c40
fe5c1b40
fe5dd580

ndistapi
Fastfat
NDIS
elnkii
ndiswan
nbf
TDI
nwlnkipx

(load from ndistapi.sys deferred)

(load from Fastfat.SYS deferred)
(NDIS.SYS, \\ntstress\symbols\SYS\NDIS.DBG)
(elnkii.sys, \\ntstress\symbols\sys\elnkii.DBG)
(load from ndiswan.sys deferred)
(load from nbf.sys deferred)
(load from TDI.SYS deferred)
(load from nwlnkipx.sys deferred)

fe5e0000
fe5f0000
fe610000
fe630000
fe650000
fe660000
fe670000
fe680000

fe5ee220
fe5fb320
fe62bf00
fe648600
fe6572a0
fe660000
fe670000
fe6bcf20

nwlnknb
afd
tcpip
netbt
netbios
Parport
Parallel
rdr

(load from nwlnknb.sys deferred)

(load from afd.sys deferred)
(load from tcpip.sys deferred)
(load from netbt.sys deferred)
(load from netbios.sys deferred)
(load from Parport.SYS deferred)
(load from Parallel.SYS deferred)
(rdr.sys, \\ntstress\symbols\sys\rdr.DBG)

srv

(load from srv.sys deferred)

fe6c0000 fe6f0920

The second step is dumping out the stack pointer (esp on an x86, sp on an Intel Itanium) to look for addresses in the modules given by the x *! command:
kd> dd esp
fe4cc97c 80136039
fe4cc98c fe682ae4
fe4cc99c fe682a78
fe4cc9ac ff680e08
fe4cc9bc fe6a1198

00000270
801036fe
ffb5b030
801036fe
00000001

00000000
00000000
00000000
00000000
fe4cca78

00000000
fe68f57a
00000000
00000000
ffae9d98

fe4cc9cc
fe4cc9dc
fe4cc9ec

02000901 fe4cca68 ffb50030 ff680e08

ffa449a8 8011c901 fe4cca78 00000000
80127797 80110008 00000246 fe6a1430

kd> dd
fe4cc9fc
fe4cca0c
fe4cca1c
fe4cca2c
fe4cca3c
fe4cca4c
fe4cca5c

00000270
ffa449a8
ffa449a8
fe685968
ffb0ad48
00000000
c00000d6

fe4cca6c

fe680ba4 fe682050 00000000 fe4ccbd4

fe6a10ae
ff680e08
e12820c8
ff680e08
ffb0ad38
ffa44a84
00000000

00000270
fe6b2c04
e1235308
e1235308
00100000
e1235308
004ccb28

ffa44abc
ff680e08
ffa449a8
ffa449a8
ffb0ad38
0000000a
fe4ccbc4

To determine which values are likely function addresses and which are parameters or saved registers, the first thing to consider is what the different types of information look
like on the stack. Most integers are going to be smaller value, which means they will be mostly zeros when displayed as DWORDs (like 0x00000270). Most pointers to local
addresses will be near the stack pointer (like fe4cca78). Status codes usually begin with a c (c00000d6). Unicode and ASCII strings can be identified by the fact that each
character will be in the range of 20-7f. (In KD, the dc (Display Memory) command will show the characters on the right.) Most importantly, the function addresses will be in
the range listed by x *!.
Notice that all modules listed are in the ranges of 77f70000 to 8040c000 and fe4c0000 to fe6f0920. Based on these ranges, the possible function addresses in the preceding list
are: 80136039, 801036fe (listed twice, so more likely a parameter), fe682ae4, fe68f57a, fe682a78, fe6a1198, 8011c901, 80127797, 80110008, fe6a1430, fe6a10ae, fe6b2c04,
fe685968, fe680ba4, and fe682050. Investigate these locations by using an ln (List Nearest Symbols) command for each address:
kd> ln 80136039
(80136039)
NT!_KiServiceExit+0x1e | (80136039)
NT!_KiServiceExit2-0x177
kd> ln fe682ae4
(fe682ae4)
rdr!_RdrSectionInfo+0x2c | (fe682ae4)
rdr!_RdrFcbReferenceLock-0xb4
kd> ln 801036fe
(801036fe)
NT!_KeWaitForSingleObject | (801036fe)
NT!_MmProbeAndLockPages-0x2f8
kd> ln fe68f57a
(fe68f57a)
rdr!_RdrDereferenceDiscardableCode+0xb4
(fe68f57a)
rdr!_RdrUninitializeDiscardableCode-0xa
kd> ln fe682a78
(fe682a78)
rdr!_RdrDiscardableCodeLock | (fe682a78) rdr!_RdrDiscardableCodeTimeout-0x38
kd> ln fe6a1198
(fe6a1198)
rdr!_SubmitTdiRequest+0xae | (fe6a1198)
rdr!_RdrTdiAssociateAddress-0xc
kd> ln 8011c901
(8011c901)
NT!_KeSuspendThread+0x13 | (8011c901)
NT!_FsRtlCheckLockForReadAccess-0x55
kd> ln 80127797

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1016 of 1651

(80127797)
NT!_ZwCloseObjectAuditAlarm+0x7 | (80127797)
NT!_ZwCompleteConnectPort-0x9
kd> ln 80110008
(80110008)
NT!_KeWaitForMultipleObjects+0x27c | (80110008) NT!_FsRtlLookupMcbEntry-0x164
kd> ln fe6a1430
(fe6a1430)
rdr!_RdrTdiCloseConnection+0xa | (fe6a1430)
rdr!_RdrDoTdiConnect-0x4
kd> ln fe6a10ae
(fe6a10ae)
rdr!_RdrTdiDisconnect+0x56 | (fe6a10ae)
rdr!_SubmitTdiRequest-0x3c
kd> ln fe6b2c04
(fe6b2c04)
rdr!_CleanupTransportConnection+0x64 | (fe6b2c04)rdr!_RdrReferenceServer-0x20
kd> ln fe685968
(fe685968)
rdr!_RdrReconnectConnection+0x1b6
(fe685968)
rdr!_RdrInvalidateServerConnections-0x32
kd> ln fe682050
(fe682050)
rdr!__strnicmp+0xaa | (fe682050)
rdr!_BackPackSpinLock-0xa10
As noted before, 801036fe is not likely to be part of the stack trace as it is listed twice. If the return addresses have an offset of zero, they can be ignored (you cannot return to
the beginning of a function). Based on this information, the stack trace is revealed to be:
NT!_KiServiceExit+0x1e
rdr!_RdrSectionInfo+0x2c
rdr!_RdrDereferenceDiscardableCode+0xb4
rdr!_SubmitTdiRequest+0xae
NT!_KeSuspendThread+0x13
NT!_ZwCloseObjectAuditAlarm+0x7
NT!_KeWaitForMultipleObjects+0x27c
rdr!_RdrTdiCloseConnection+0xa
rdr!_RdrTdiDisconnect+0x56
rdr!_CleanupTransportConnection+0x64
rdr!_RdrReconnectConnection+0x1b6
rdr!__strnicmp+0xaa
To verify each symbol, unassemble immediately before the return address specified to see if it does a call to the function above it. To reduce length, the following is edited
(the offsets used were found by trial and error):
kd> u 80136039-2 l1
// looks ok, its a call
NT!_KiServiceExit+0x1c:
80136037 ffd3
call
ebx
kd> u fe682ae4-2 l1
// paged out (all zeroes) unknown
rdr!_RdrSectionInfo+0x2a:
fe682ae2 0000
add
[eax],al
kd> u fe68f57a-6 l1
// looks ok, its a call, but not anything above
rdr!_RdrDereferenceDiscardableCode+0xae:
fe68f574 ff15203568fe
call dword ptr [rdr!__imp__ExReleaseResourceForThreadLite]
kd> u fe682a78-6 l1
// paged out (all zeroes) unknown
rdr!_DiscCodeInitialized+0x2:
fe682a72 0000
add
[eax],al
kd> u fe6a1198-5 l1
// looks good, call to something above
rdr!_SubmitTdiRequest+0xa9:
fe6a1193 e82ee3feff
call rdr!_RdrDereferenceDiscardableCode (fe68f4c6)
kd> u 8011c901-2 l1
// not good, its a jump in the function
NT!_KeSuspendThread+0x11:
8011c8ff 7424
jz
NT!_KeSuspendThread+0x37 (8011c925)
kd> u 80127797-2 l1
// looks good, an int 2e -> KiServiceExit
NT!_ZwCloseObjectAuditAlarm+0x5:
80127795 cd2e
int
2e
kd> u 80110008-2 l1
// not good, its a test instruction not a call
NT!_KeWaitForMultipleObjects+0x27a:
80110006 85c9
test
ecx,ecx
kd> u 80110008-5 l1
// paged out (all zeroes) unknown
NT!_KeWaitForMultipleObjects+0x277:
80110003 0000
add
[eax],al
kd> u fe6a1430-6 l1
// looks good its a call to ZwClose...
rdr!_RdrTdiCloseConnection+0x4:
fe6a142a ff15f83468fe
call
dword ptr [rdr!__imp__ZwClose (fe6834f8)]
kd> u fe6a10ae-2 l1
// paged out (all zeroes) unknown
rdr!_RdrTdiDisconnect+0x54:
fe6a10ac 0000
add
[eax],al
kd> u fe6b2c04-5 l1
// looks good, call to something above
rdr!_CleanupTransportConnection+0x5f:
fe6b2bff e854e4feff
call
rdr!_RdrTdiDisconnect (fe6a1058)
kd> u fe685968-5 l1
// looks good, call to immediately above
rdr!_RdrReconnectConnection+0x1b1:
fe685963 e838d20200
call
rdr!_CleanupTransportConnection (fe6b2ba0)
kd> u fe682050-2 l1
rdr!__strnicmp+0xa8:
fe68204e 0000

//
add

paged out (all zeroes) unknown

[eax],al

Based on this, it appears that RdrReconnectConnection called RdrCleanupTransportConnection, to RdrTdiDisconnect, to ZwCloseObjectAuditAlarm, to

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1017 of 1651

KiSystemServiceExit. The other functions on the stack are probably leftover portions of previously active stacks.
In this case, the stack trace worked properly. Following is the actual stack trace to check the answer:
kd> k
ChildEBP RetAddr
fe4cc978 80136039 NT!_NtClose+0xd
fe4cc978 80127797 NT!_KiServiceExit+0x1e
fe4cc9f4
fe4cca10
fe4cca28
fe4cca78
fe4ccbd4
fe4ccbe8
fe4ccc98
fe4ccd08
fe4ccde4
fe4cce90
fe4cced0

fe6a1430
fe6b2c04
fe685968
fe688157
80106b1e
8014b289
8014decd
8014d6d2
8014d3ad
8016660d
80136039

NT!_ZwCloseObjectAuditAlarm+0x7
rdr!_RdrTdiCloseConnection+0xa
rdr!_CleanupTransportConnection+0x64
rdr!_RdrReconnectConnection+0x1b6
rdr!_RdrFsdCreate+0x45b
NT!IofCallDriver+0x38
NT!_IopParseDevice+0x693
NT!_ObpLookupObjectName+0x487
NT!_ObOpenObjectByName+0xa2
NT!_IoCreateFile+0x433
NT!_NtCreateFile+0x2d

The first entry was the current location based on the stack trace, but otherwise, the stack was correct up to the point where RdrReconnectConnection was called. The same
process could have been used to trace the entire stack. For a more exact method of manual stack walking, you would need to unassemble each potential function and follow
each push and pop to identify each DWORD on the stack.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Stack Overflow

A stack overflow is an error that user-mode threads can encounter. There are three possible causes for this error:

A thread uses the entire stack reserved for it. This is often caused by infinite recursion.
A thread cannot extend the stack because the page file is maxed out, and therefore no additional pages can be committed to extend the stack.
A thread cannot extend the stack because the system is within the brief period used to extend the page file.

Here is an example of how to debug this error. In this example, NTSD is running on the same computer as the target application and is redirecting its output to KD on the host
computer. See Controlling the User-Mode Debugger from the Kernel Debugger for details.
The first step is see what event caused the debugger to break in:
0:002> .lastevent
Last event: Exception C00000FD, second chance
You can look up exception code 0xC00000FD in ntstatus.h, which can be found in the Microsoft Windows SDK and the Windows Driver Kit (WDK). This exception code is
STATUS_STACK_OVERFLOW.
To double-check that the stack overflowed, you can use the k (Display Stack Backtrace) command:
0:002> k
ChildEBP
009fdd0c
009fde78
009fde98
009fdf00
009fdf3c
009fdf5c
009fdfec
009fdffc
009fe074
009fe0d0
009fe128
009fe148
009fe1b0
009fe1d8
009fe200
009fe220
009fe27c
009fe2e4
00000000

RetAddr
71a32520
77cf8290
77cfd634
77cd55e9
77cd63b2
71a45b30
71a45bb0
71a1d688
71a1db30
71a1f196
77cf8290
77cfd634
77cd4490
77cd46c8
77f7bb3f
77cd445e
77cfd634
009fe4a8
00000000

COMCTL32!_chkstk+0x25
COMCTL32!ListView_WndProc+0x4c4
USER32!_InternalCallWinProc+0x18
USER32!UserCallWinProcCheckWow+0x17f
USER32!SendMessageWorker+0x4a3
USER32!SendMessageW+0x44
COMCTL32!CCSendNotify+0xc0e
COMCTL32!CICustomDrawNotify+0x2a
COMCTL32!Header_Draw+0x63
COMCTL32!Header_OnPaint+0x3f
COMCTL32!Header_WndProc+0x4e2
USER32!_InternalCallWinProc+0x18
USER32!UserCallWinProcCheckWow+0x17f
USER32!DispatchClientMessage+0x31
USER32!__fnDWORD+0x22
ntdll!_KiUserCallbackDispatcher+0x13
USER32!DispatchMessageWorker+0x3bc
USER32!UserCallWinProcCheckWow+0x17f
0x9fe4a8

The target thread has broken into COMCTL32!_chkstk, which indicates a stack problem.
Now you should investigate the stack usage of the target process. The process has multiple threads, but the important one is the one that caused the overflow, so identify this
thread first:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1018 of 1651

0:002> ~*k
0 id: 570.574
.....

Suspend: 1 Teb 7ffde000 Unfrozen

1 id: 570.590
.....

Suspend: 1 Teb 7ffdd000 Unfrozen

. 2 id: 570.598
Suspend: 1 Teb 7ffdc000 Unfrozen
ChildEBP RetAddr
009fdd0c 71a32520 COMCTL32!_chkstk+0x25
.....
3

id: 570.760

Suspend: 1 Teb 7ffdb000 Unfrozen

Now you need to investigate thread 2. The period at the left of this line indicates that this is the current thread.
The stack information is contained in the TEB (Thread Environment Block) at 0x7FFDC000. The easiest way to list it is using !teb. However, this requires you to have the
proper symbols. For maximum versatility, assume you have no symbols:
0:002> dd 7ffdc000 L4
7ffdc000
009fdef0 00a00000 009fc000 00000000
To interpret this, you need to look up the definition of the TEB data structure. If you had complete symbols, you could use dt TEB to do this. But in this case, you will need to
look at the ntpsapi.h file in the Microsoft Windows SDK. For Windows XP and later versions of Windows, this file contains the following information:
typedef struct _TEB {
NT_TIB NtTib;
PVOID EnvironmentPointer;
CLIENT_ID ClientId;
PVOID ActiveRpcHandle;
PVOID ThreadLocalStoragePointer;
PPEB ProcessEnvironmentBlock;
ULONG LastErrorValue;
.....
PVOID DeallocationStack;
.....
} TEB;
typedef struct _NT_TIB {
struct _EXCEPTION_REGISTRATION_RECORD *ExceptionList;
PVOID StackBase;
PVOID StackLimit;
.....
} NT_TIB;
This indicates that the second and third DWORDs in the TEB structure point to the bottom and top of the stack, respectively. In this case, these addresses are 0x00A00000
and 0x009FC000. (The stack grows downward in memory.) You can calculate the stack size using the ? (Evaluate Expression) command:
0:002> ? a00000-9fc000
Evaluate expression: 16384 = 00004000
This shows that the stack size is 16 K. The maximum stack size is stored in the field DeallocationStack. After some calculation, you can determine that this field's offset is
0xE0C.
0:002> dd 7ffdc000+e0c L1
7ffdce0c
009c0000
0:002> ? a00000-9c0000
Evaluate expression: 262144 = 00040000
This shows that the maximum stack size is 256 K, which means more than adequate stack space is left.
Furthermore, this process looks clean it is not in an infinite recursion or exceeding its stack space by using excessively large stack-based data structures.
Now break into KD and look at the overall system memory usage with the !vm extension command:
0:002> .breakin
Break instruction exception - code 80000003 (first chance)
ntoskrnl!_DbgBreakPointWithStatus+4:
80148f9c cc
int
3
kd> !vm
*** Virtual Memory Usage ***
Physical Memory:
16268
(
65072
Page File: \??\C:\pagefile.sys
Current:
147456Kb Free Space:
Minimum:
98304Kb Maximum:
Available Pages:
2299
(
9196
ResAvail Pages:
4579
(
18316
Locked IO Pages:
93
(
372

Kb)
65988Kb
196608Kb
Kb)
Kb)
Kb)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1019 of 1651

Free System PTEs:

Free NP PTEs:
Free Special NP:
Modified Pages:
NonPagedPool Usage:
NonPagedPool Max:
PagedPool 0 Usage:
PagedPool 1 Usage:
PagedPool 2 Usage:
PagedPool Usage:
PagedPool Maximum:
Shared Commit:
Special Pool:
Shared Process:
PagedPool Commit:
Driver Commit:
Committed pages:
Commit limit:

42754
5402
348
757
811
6252
1337
893
362
2592
13312
3928
1040
3641
2592
887
45882
50570

(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(

171016
21608
1392
3028
3244
25008
5348
3572
1448
10368
53248
15712
4160
14564
10368
3548
183528
202280

Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)
Kb)

Total Private:
.....

33309

133236 Kb)

First, look at nonpaged and paged pool usage. Both are well within limits, so these are not the cause of the problem.
Next, look at the number of committed pages: 183528 out of 202280. This is very close to the limit. Although this display does not show this number to be at the limit, you
should keep in mind that while you are performing user-mode debugging, other processes are running on the system. Each time an NTSD command is executed, these other
processes are also allocating and freeing memory. That means you do not know exactly what the memory state was like at the time the stack overflow occurred. Given how
close the committed page number is to the limit, it is reasonable to conclude that the page file was used up at some point and this caused the stack overflow.
This is not an uncommon occurrence, and the target application cannot really be faulted for this. If it happens frequently, you may want to consider raising the initial stack
commitment for the failing application.
Analyzing a Single Function Call
It can also be useful to find out exactly how much stack space a certain function call is allocating.
To do this, disassemble the first few instructions and look for the instruction sub esp,number. This moves the stack pointer, effectively reserving number bytes for local data.
Here is an example:
0:002> k
ChildEBP
009fdd0c
009fde78
009fde98
009fdf00
009fdf3c
009fdf5c
009fdfec
009fdffc
009fe074
009fe0d0
009fe128
009fe148

RetAddr
71a32520
77cf8290
77cfd634
77cd55e9
77cd63b2
71a45b30
71a45bb0
71a1d688
71a1db30
71a1f196
77cf8290
77cfd634

0:002> u COMCTL32!Header_Draw
COMCTL32!Header_Draw :
71a1d625 55
push
71a1d626 8bec
mov
71a1d628 83ec58
sub
71a1d62b 53
push
71a1d62c 8b5d08
mov
71a1d62f 56
push
71a1d630 57
push
71a1d631 33f6
xor

ebp
ebp,esp
esp,0x58
ebx
ebx,[ebp+0x8]
esi
edi
esi,esi

This shows that Header_Draw allocated 0x58 bytes of stack space.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Failed Driver Unload

A driver will not unload if there is a leaked reference to DeviceObject or DriverObject. This is a common cause of failed driver unloads.
Apart from IoCreateDevice, there are several functions that take reference to DriverObject and DeviceObject. If you do not follow the guidelines for using the functions,
you will end up leaking the reference.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1020 of 1651

Here is an example of how to debug this problem. Although DeviceObject is used in this example, this technique works for all objects.
Fixing a driver that fails to unload
1. Put a breakpoint right after the driver calls IoCreateDevice. Get the DeviceObject address.
2. Find the object header by using the !object extension on this object address:
kd> !object 81a578c0
Object: 81a578c0 Type: (81bd0e70) Device
ObjectHeader: 81a578a8
HandleCount: 0 PointerCount: 3
Directory Object: e1001208 Name: Serial0
The first variable in the ObjectHeader is the pointer count or reference count.
3. Put a write breakpoint on the pointer count, using the ObjectHeader's address:
kd> ba w4 81a578a8 "k;g"
4. Use g (Go). The debugger will produce a log.
5. Look for the mismatched reference/dereference pair specifically, a missing dereference. (Note that ObReferenceObject is implemented as a macro inside the
kernel.)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Deadlock
When a thread needs exclusive access to code or some other resource, it requests a lock. If it can, Windows responds by giving this lock to the thread. At this point, nothing
else in the system can access the locked code. This happens all the time and is a normal part of any well-written multithreaded application. Although a particular code segment
can only have one lock on it at a time, multiple code segments can each have their own lock.
A deadlock arises when two or more threads have requested locks on two or more resources, in an incompatible sequence. For instance, suppose that Thread One has acquired
a lock on Resource A and then requests access to Resource B. Meanwhile, Thread Two has acquired a lock on Resource B and then requests access to Resource A. Neither
thread can proceed until the other thread's lock is relinquished, and, therefore, neither thread can proceed.
User-mode deadlocks arise when multiple threads of one application have blocked each others' access to the same resources. Kernel-mode deadlocks arise when multiple
threads (from the same process or from distinct processes) have blocked each others' access to the same kernel resource. The procedure used to debug a deadlock depends on
whether the deadlock occurs in user mode or in kernel mode.
Debugging a User-Mode Deadlock
When a deadlock occurs in user mode, use the following procedure to debug it:
1. Issue the !ntsdexts.locks extension. In user mode, you can just type !locks at the debugger prompt; the ntsdexts prefix is assumed.
2. This extension displays all the critical sections associated with the current process, along with the ID for the owning thread and the lock count for each critical section.
If a critical section has a lock count of zero, it is not locked. Use the ~ (Thread Status) command to see information about the threads that own the other critical
sections.
3. Use the kb (Display Stack Backtrace) command for each of these threads to determine whether they are waiting on other critical sections.
4. Using the output of these kb commands, you can find the deadlock: two threads that are each waiting on a lock held by the other thread. In rare cases, a deadlock could
be caused by more than two threads holding locks in a circular pattern, but most deadlocks involve only two threads.
Here is an illustration of this procedure. You begin with the !ntdexts.locks extension:
0:006> !locks
CritSec ftpsvc2!g_csServiceEntryLock+0 at 6833dd68
LockCount
0
RecursionCount
1
OwningThread
a7
EntryCount
0
ContentionCount
0
*** Locked
CritSec isatq!AtqActiveContextList+a8 at 68629100
LockCount
2
RecursionCount
1
OwningThread
a3
EntryCount
2
ContentionCount
2
*** Locked
CritSec +24e750 at 24e750
LockCount
6
RecursionCount
1
OwningThread
a9
EntryCount
6
ContentionCount
6

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1021 of 1651

*** Locked
The first critical section displayed has no locks and, therefore, can be ignored.
The second critical section displayed has a lock count of 2 and is, therefore, a possible cause of a deadlock. The owning thread has a thread ID of 0xA3.
You can find this thread by listing all threads with the ~ (Thread Status) command, and looking for the thread with this ID:
0:006> ~
0 Id:
1 Id:
2 Id:
3 Id:
4 Id:
5 Id:
. 6 Id:
7 Id:
8 Id:

1364.1330 Suspend:
1364.17e0 Suspend:
1364.135c Suspend:
1364.1790 Suspend:
1364.a3 Suspend: 1
1364.1278 Suspend:
1364.a9 Suspend: 1
1364.111c Suspend:
1364.1588 Suspend:

1 Teb: 7ffdf000 Unfrozen

1 Teb: 7ffde000 Unfrozen
1 Teb: 7ffdd000 Unfrozen
1 Teb: 7ffdc000 Unfrozen
Teb: 7ffdb000 Unfrozen
1 Teb: 7ffda000 Unfrozen
Teb: 7ffd9000 Unfrozen
1 Teb: 7ffd8000 Unfrozen
1 Teb: 7ffd7000 Unfrozen

In this display, the first item is the debugger's internal thread number. The second item (the Id field) contains two hexadecimal numbers separated by a decimal point. The
number before the decimal point is the process ID; the number after the decimal point is the thread ID. In this example, you see that thread ID 0xA3 corresponds to thread
number 4.
You then use the kb (Display Stack Backtrace) command to display the stack that corresponds to thread number 4:
0:006> ~4 kb
4 id: 97.a3
Suspend: 0 Teb 7ffd9000 Unfrozen
ChildEBP RetAddr Args to Child
014cfe64 77f6cc7b 00000460 00000000 00000000 ntdll!NtWaitForSingleObject+0xb
014cfed8 77f67456 0024e750 6833adb8 0024e750 ntdll!RtlpWaitForCriticalSection+0xaa
014cfee0 6833adb8 0024e750 80000000 01f21cb8 ntdll!RtlEnterCriticalSection+0x46
014cfef4 6833ad8f 01f21cb8 000a41f0 014cff20 ftpsvc2!DereferenceUserDataAndKill+0x24
014cff04 6833324a 01f21cb8 00000000 00000079 ftpsvc2!ProcessUserAsyncIoCompletion+0x2a
014cff20 68627260 01f21e0c 00000000 00000079 ftpsvc2!ProcessAtqCompletion+0x32
014cff40 686249a5 000a41f0 00000001 686290e8 isatq!I_TimeOutContext+0x87
014cff5c 68621ea7 00000000 00000001 0000001e isatq!AtqProcessTimeoutOfRequests_33+0x4f
014cff70 68621e66 68629148 000ad1b8 686230c0 isatq!I_AtqTimeOutWorker+0x30
014cff7c 686230c0 00000000 00000001 000c000a isatq!I_AtqTimeoutCompletion+0x38
014cffb8 77f04f2c 00000000 00000001 000c000a isatq!SchedulerThread_297+0x2f
00000001 000003e6 00000000 00000001 000c000a kernel32!BaseThreadStart+0x51
Notice that this thread has a call to the WaitForCriticalSection function, which means that not only does it have a lock, it is waiting for code that is locked by something
else. We can find out which critical section we are waiting on by looking at the first parameter of the call to WaitForCriticalSection. This is the first address under Args to
Child: "24e750". So this thread is waiting on the critical section at address 0x24E750. This was the third critical section listed by the !locks extension that you used earlier.
In other words, thread 4, which owns the second critical section, is waiting on the third critical section. Now turn your attention to the third critical section, which is also
locked. The owning thread has thread ID 0xA9. Returning to the output of the ~ command that you saw previously, note that the thread with this ID is thread number 6.
Display the stack backtrace for this thread:
0:006> ~6 kb
ChildEBP RetAddr
0155fe38 77f6cc7b
0155feac 77f67456
0155feb4 6862142e
0155fec0 686222e1
0155fed0 68621412
0155fed8 686213d1
0155fee8 683331f7
0155fefc 6833984b
0155ff18 6833adcd
0155ff28 6833ad8f
0155ff38 6833324a
0155ff54 686211eb
0155ff88 68622676
0155ffb8 77f04f2c
0155ffec 00000000

Args to Child
00000414 00000000
68629100 6862142e
68629100 0009f238
0009f25c 00000001
0009f238 686213d1
0009f238 00000001
0009f238 00000001
ffffffff 00000000
77f05154 01f26a58
01f26a58 000a3410
01f26a58 00000000
01f26bac 00000000
000a3464 00000000
abcdef01 ffffffff
68622644 abcdef01

00000000
68629100
686222e1
0009f238
0009f238
01f26bcc
01f26bf0
00000000
00000000
0155ff54
00000040
00000040
000a3414
000ad1b0
00000000

ntdll!NtWaitForSingleObject+0xb
ntdll!RtlpWaitForCriticalSection+0xaa
ntdll!RtlEnterCriticalSection+0x46
isatq!ATQ_CONTEXT_LISTHEAD__RemoveFromList
isatq!ATQ_CONTEXT__CleanupAndRelease+0x30
isatq!AtqpReuseOrFreeContext+0x3f
isatq!AtqFreeContext+0x36
ftpsvc2!ASYNC_IO_CONNECTION__SetNewSocket
ftpsvc2!USER_DATA__Cleanup+0x47
ftpsvc2!DereferenceUserDataAndKill+0x39
ftpsvc2!ProcessUserAsyncIoCompletion+0x2a
ftpsvc2!ProcessAtqCompletion+0x32
isatq!AtqpProcessContext+0xa7
isatq!AtqPoolThread+0x32
kernel32!BaseThreadStart+0x51

This thread, too, is waiting for a critical section to be freed. In this case, it is waiting on the critical section at 0x68629100. This was the second critical section in the list
generated earlier by the !locks extension.
This is the deadlock. Thread 4, which owns the second critical section, is waiting on the third critical section. Thread 6, which owns the third critical section, is waiting on the
second critical section.
Having confirmed the nature of this deadlock, you can use the usual debugging techniques to analyze threads 4 and 6.
Debugging a Kernel-Mode Deadlock
There are several debugger extensions that are useful for debugging deadocks in kernel mode:

The !kdexts.locks extension displays information about all locks held on kernel resources and the threads holding these locks. (In kernel mode, you can just type !locks
at the debugger prompt; the kdexts prefix is assumed.)
The !qlocks extension displays the state of all queued spin locks.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1022 of 1651

The !wdfkd.wdfspinlock extension displays information about a Kernel-Mode Driver Framework (KMDF) spin-lock object.
The !deadlock extension is used in conjunction with Driver Verifier to detect inconsistent use of locks in your code that have the potential to cause deadlocks.

When a deadlock occurs in kernel mode, use the !kdexts.locks extension to list all the locks currently acquired by threads.
You can usually pinpoint the deadlock by finding one non-executing thread that holds an exclusive lock on a resource that is required by an executing thread. Most of the
locks are shared.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Device Installation Co-Installer

Some hardware device installation packages include DLL files known as co-installers, which assist with installing the device.
You cannot debug a co-installer in the same fashion as other modules. This is because of the unique way in which a co-installer is loaded, and because many installation
scenarios occur automatically without providing the developer an opportunity to break into the running process.
You can resolve this issue by programmatically installing the device. Attaching a debugger to the application which installs the device allows access to the co-installer itself.
The simplest way to accomplish this is to install or reinstall the device using the DevCon tool that is included in the Windows Driver Kit (WDK). You can then debug the
co-installer with WinDbg.
Use the following procedure to accomplish this task. This procedure assumes you have developed a working driver installation package for your device which uses a coinstaller. It also assumes that you have the latest copy of the WDK. For information on developing drivers, driver installation packages, and driver installation co-installers,
see the WDK documentation.
Debugging a Co-installer Using DevCon and WinDbg
1.
2.
3.
4.
5.

Plug in the hardware device.

Cancel the New Hardware Found wizard.
Start WinDbg.
Select Open Executable from WinDbg's File menu.
In the Open Executable dialog box, do the following:
1. In the file selection text box, select the DevCon tool (Devcon.exe). For this, browse to the WDK installation folder, then open the subdirectory tools, then open
the subdirectory devcon, then open the subdirectory that matches the processor architecture of your machine, and then select Devcon.exe. Click only once on
Devcon.exe and do not yet press Open.
2. In the Arguments text box, enter the following text, where INFFile is the filename of your Device Installation Information (INF) file, and HardwareID is the
hardware ID of your device:
update INFFile HardwareID

3. In the Start directory text box, enter the path to your device installation package.
4. Click Open.
6. The debugging process will begin, and WinDbg will break into the DevCon process before DevCon installs your driver.
7. Configure the debugger to break into the co-installer process when it is loaded. You can do this by either of the following methods:
In the Debugger Command window, use the sxe (Set Exceptions) command followed by ld: and then the filename of the co-installer, excluding the file
extension. There should be no space after the colon For example, if the name of the co-installer is mycoinst.dll, you would use the following command:
sxe ld:mycoinst
Select Event Filters from WinDbg's Debug menu. In the Event Filters dialog box, select Load module. Under Execution, select Enabled. Under Continue,
select Not Handled. Click the Argument button, and then in the text box enter the filename of the co-installer, excluding the file extension (for example, enter
"mycoinst" for mycoinst.dll). Click OK and then click Close.
8. Resume execution by pressing F5 or entering the g (Go) command in the Debugger Command window.
9. When the co-installer is loaded, execution will break back into the debugger. At this point, you can set any additional breakpoints that you need.

Limitations of This Procedure

In certain cases, running a device installation package under DevCon may result in slightly different behavior than that of a PnP installation, because of different security
tokens and the like. If you are trying to debug a specific problem in your co-installer, it is possible that this problem will not replicate if DevCon is involved. Therefore, before
using this technique, you should use DevCon to install your driver without a debugger attached to verify that this problem exists in both the PnP and the DevCon scenarios.
If the problem vanishes whenever DevCon initiates the installation, then you will have to debug your co-installer without using DevCon. One way of doing this is to use the
TList tool with the /m option to determine which process is loading the co-installer module, and then attaching the debugger to that process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading Bug Check Callback Data

Many drivers supply bug check callback routines. When Windows issues a bug check, it calls these routines before shutting down the system. One task these routines can do

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1023 of 1651

is indicate certain important parts of memory for debugging purposes.

In Windows 2000, and Windows XP prior to SP1, the bug check callback function is named BugCheckCallback. It is primarily used to write data to a region in memory
this data is called callback data.
In Windows XP SP1, Windows Server 2003, and later versions of Windows, there are multiple callback functions. BugCheckCallback is the same as its counterpart in earlier
versions of Windows, except that it is called after the dump file is written. Another callback function, BugCheckSecondaryDumpDataCallback, is called before the dump
file is written the data written by this routine is called secondary callback data.
How much of this information is available to the debugger depends on several factors:

If you are performing live debugging of a crashed system, callback data will be available if it has already been written by BugCheckCallback. Secondary callback data
will not be available, because it is not stored in any fixed memory location.
If you are debugging a Complete Memory Dump or Kernel Memory Dump in Windows 2000, or Windows XP prior to SP1, all callback data will be available.
If you are debugging a Complete Memory Dump or Kernel Memory Dump in Windows XP SP1, Windows Server 2003, or a later version of Windows, callback data
will not be available. The dump file will contain an image of the buffer that holds this data, but this image will have been made before the BugCheckCallback routine
wrote the callback data to the buffer. On the other hand, secondary callback data will be present.
If you are debugging a Small Memory Dump, callback data will not be available. Secondary callback data will be available in Windows XP SP1, Windows Server 2003,
or a later version of Windows.

See Varieties of Kernel-Mode Dump Files for more details on these different dump file sizes.
Displaying Callback Data
To display bug check callback data, you can use the !bugdump extension.
Without any parameters, !bugdump will display data for all callbacks.
To view data for one specific callback routine, use !bugdump Component, where Component is the same parameter that was passed to KeRegisterBugCheckCallback when
that routine was registered.
Displaying Secondary Callback Data
There are two methods for displaying secondary callback data in Windows XP SP1, Windows Server 2003, and later versions of Windows. You can use the .enumtag
command or you can write your own debugger extension.
Each block of secondary callback data is identified by a GUID tag. This tag is specified by the Guid field of the (KBUGCHECK_SECONDARY_DUMP_DATA)
ReasonSpecificData parameter passed to BugCheckSecondaryDumpDataCallback.
The .enumtag (Enumerate Secondary Callback Data) command is not a very precise instrument. It displays every secondary data block, showing the tag and then showing
the data in hexadecimal and ASCII format. It is generally useful only to determine what tags are actually being used for secondary data blocks.
To use this data in a more practical way, it is recommended that you write your own debugger extension. This extension must call methods in the dbgeng.h header file. For
details, see Writing New Debugger Extensions.
If you know the GUID tag of the secondary data block, your extension should use the method IDebugDataSpaces3::ReadTagged to access the data. Its prototype is as
follows:
STDMETHOD(ReadTagged)(
THIS_
IN LPGUID Tag,
IN ULONG Offset,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG TotalSize
) PURE;
Here is an example of how to use this method:
UCHAR RawData[MY_DATA_SIZE];
GUID MyGuid = .... ;
Success = DataSpaces->ReadTagged(

&MyGuid, 0, RawData,
sizeof(RawData), NULL);

If you supply a BufferSize that is too small, ReadTagged will succeed but will write only the requested number of bytes to Buffer. If you specify a BufferSize that is too large,
ReadTagged will succeed but will write only the actual block size to Buffer. If you supply a pointer for TotalSize, ReadTagged will use it to return the size of the actual
block. If the block cannot be accessed, ReadTagged will return a failure status code.
If two blocks have identical GUID tags, the first matching block will be returned, and the second block will be inaccessible.
If you are not sure of the GUID tag of your block, you can use the IDebugDataSpaces3::StartEnumTagged, IDebugDataSpaces3::GetNextTagged, and
IDebugDataSpaces3::EndEnumTagged methods to enumerate the tagged blocks. Their prototypes are as follows:
STDMETHOD(StartEnumTagged)(
THIS_
OUT PULONG64 Handle
) PURE;
STDMETHOD(GetNextTagged)(
THIS_
IN ULONG64 Handle,
OUT LPGUID Tag,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1024 of 1651

OUT PULONG Size

) PURE;
STDMETHOD(EndEnumTagged)(
THIS_
IN ULONG64 Handle
) PURE;
Debugging Callback Routines
It is also possible to debug the callback routine itself. Breakpoints within callback routines work just like any other breakpoint.
If the callback routine causes a second bug check, this new bug check will be processed first. However, Windows will not repeat certain parts of the Stop process for
example, it will not write a second crash dump file. The Stop code displayed on the blue screen will be the second bug check code. If a kernel debugger is attached, messages
about both bug checks will usually appear.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging an Itanium Firmware Failure

If a computer running an Itanium-based processor crashes, it is possible that the cause is a firmware failure.
Use the following procedure to analyze this problem:
1. Get a stack trace. If the stack trace hangs partway through, that is a sign that a firmware failure may have occurred:
kd> kb
...
e0000165`993b2c50
e0000165`993b2c50
e0000165`993b2c90
e0000165`993b3800
e0000165`993b3800
e0000165`993b3800
e0000165`993b3b40
e0000165`993b3b40

e0000165`993b4840
e0000165`993b4840
e0000165`993b4718
e0000165`993b46e0
e0000165`993b4680
e0000165`993b4678
e0000165`993b4648
e0000165`993b4648

e0000000`8306e8c0
e0000000`8306ffe0
e0000000`83070640
e0000000`83090310
e0000000`83087d40
e0000165`985b63a4
e0000165`985b6360
e0000165`985b6360

ntkrnlmp!DbgBreakPointWithStatus+0x8
ntkrnlmp!KiBugCheckDebugBreak+0x40
ntkrnlmp!KeBugCheck2+0x980
ntkrnlmp!KeBugCheckEx+0x20
ntkrnlmp!KiMemoryFault+0x3f0
ntkrnlmp!KiGenericExceptionHandler+0x290
0xe0000165`985b63a4
0xe0000165`985b6360

DBGHELP: Can't find runtime function entry info for e0000165`985b6360, results might be unreliable!
In this example, the stack trace failed in the middle of a C++ runtime function.
2. Take a look at the bug check information:
kd> .bugcheck
Bugcheck code 000000D1
Arguments 60000165`97ec42d5 00000000`0000000f 00000000`00000001 e0000165`985b63a0
3. Look up the bug check code parameters in the Bug Check Code Reference section. Pay particular attention to any parameters that specify the address of the fault. In this
case, you have bug check code 0xD1 (DRIVER_IRQL_NOT_LESS_OR_EQUAL), whose fourth parameter indicates the address that caused the failure.
Notice that this address, 0xE0000165`985B63A0, is within a few bytes of the address at which the stack trace failed.
Also notice that the DbgHelp error message indicates that symbol information is unavailable at this same address.
4. To further investigate this address, use the ln (List Nearest Symbols) command:
kd> ln e0000165`985b63a0
In this example, the ln command has returned no nearby symbols.
5. Use the !lmi extension to investigate the module containing this address:
kd> !lmi e0000165`985b63a0
Loaded Module Info: [e0000165`985b63a0]
e0000165985b63a0 is not a valid address.
This address does not appear to be contained in a loaded module.
6. Use the lm (List Loaded Modules) command to list all of the loaded modules, sorted by address. From the resulting display (not shown here), you see that this address
is not present in a loaded module but falls between the following two modules:
e0000165`9793c000 e0000165`979b2fe0
e0000165`98644000 e0000165`98693e60

ks
mup

(deferred)
(deferred)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1025 of 1651

By subtracting the end address of the ks module from the starting address of the mup module, you see that the size of the gap between these two modules is over 1 MB,
which is large.
7. Determine if the memory contains valid instructions by unassembling the code with the u (Unassemble) command:
kd> u e0000165`985b63a0 L3
e0000165`985b63a0
mov.m ar.ccv=r0 ;;
e0000165`985b63a4
cmpxchg1.acq ret1=[r36], ret0, ar.ccv
e0000165`985b63a8
nop.i 0 ;;
The address does contain valid instructions. In particular, it contains a memory dereference. Unassemble the commands prior to this address:
kd> ub e0000165`985b63a0
...
e0000165`985b6340
e0000165`985b6344
e0000165`985b6348
...

L30
alloc
nop.f
mov

r34=ar.pfs, 5, 0, 1, 0
0
r33=rp ;;

You have found a function entry point.

Thus, you see that valid instructions in kernel address space that do not belong to any loaded module were executing. This can be explained in one of the following ways:

Memory was allocated, raw code was written to that memory, the memory was marked executable, and then the memory was referenced.
A firmware failure has occurred.

Because the first option is extremely improbable, the cause must be an Itanium-based-firmware failure.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a Dual-Boot Machine

How should you respond when the alternate operating system does not start on a dual-boot machine?
First, check that the boot options point to the correct path for the other operating system. See Configuring Software on the Target Computer for details.
On an x86 computer, you should also verify that boosect.ini exists. This file contains the boot record for the other operating system. To unhide this file, use the attrib -r -s -h
boosect.ini command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Windows Setup and the OS Loader

If your computer hangs in text-mode at the Starting Windows screen and has not connected into the debugger, it may be possible to modify your setup to allow the debugger
to connect during startup.
Before debugging can begin, you must start your target computer in Safe Mode and make the following preparations:

Install the checked version of $LDR$ on the target computer. If you install the full checked build of Windows, this file will be included. If you want to install only this
file, you need to look for it under the name setupldr.bin. Copy this file to the root of the first bootable partition on the target computer and rename it $LDR$ (with no
file name extension). For instructions on how to install a full checked build or individual checked files, see the Windows Driver Kit.
Make sure the symbols for the checked version of $LDR$ are included in the debugger's symbol path.
Set the debugger baud rate to 19200.
Modify the file txtsetup.sif on the target computer by adding the /debugstop, /debugport, and /baudrate switches to the OsLoadOptions line. Here is an example of a
modified txtsetup.sif file:
OsLoadOptions = "/fastdetect /noguiboot /debugstop /debugport=com2 /baudrate=19200"
; OsLoadOptionsVar = "/fastdetect"
; SetupCmdLinePrepend = "CDB"
The exact contents of your file may differ from this. The baud rate should match that used by the debugger (19200 is recommended). The COM port should be the port
on the target computer to which the debugging cable is attached.

After these steps have been completed, use the following procedure to connect the debugger:
Debugging Windows Setup and the OS Loader
1. Start up the debugger with the -d command-line option, or use CTRL+K to cause the debugger to break in when the first kernel module is loaded.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1026 of 1651

2. When the debugger breaks in, you will see a message that the symbol checksum cannot be verified. Ignore this message! If you want to verify that your symbols are
correct, do a stack trace and make sure the first line of the stack trace says osloader!DbgBreakPoint.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging CSRSS
The Client Server Run-Time Subsystem (CSRSS) is the user-mode process that controls the underlying layer for the Windows environment. There are a number of problems
that make it necessary to debug CSRSS itself.
Debugging CSRSS is also useful when the Windows subsystem terminates unexpectedly with a Bug Check 0xC000021A (STATUS_SYSTEM_PROCESS_TERMINATED).
In this case, debugging CSRSS will catch the failure before it gets to an "unexpected" point.
Controlling NTSD from the Kernel Debugger
The easiest way to debug CSRSS is to use NTSD and control it from the kernel debugger.
Enabling CSRSS Debugging
CSRSS debugging must be enabled before you can proceed. If the target computer is running a checked build of Windows, CSRSS debugging is always enabled. If the target
computer is running a free build of Windows, you will have to enable CSRSS debugging through the Global Flags Utility (GFlags).
To do this, start the GFlags utility, select the System Registry radio button, and select Enable debugging of Win32 subsystem.
Alternatively, you can use the following GFlags command-line:
gflags /r +20000
Or, if you prefer, you can edit the registry key manually instead of using GFlags. Open the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager
Edit the GlobalFlag value entry (of type REG_DWORD) and set the bit 0x00020000.
After using GFlags or manually editing the registry, you must reboot for the changes to take effect.
Starting NTSD
Because you will be controlling the user-mode debugger from the kernel debugger, you will need to set up a kernel debugging connection. See Kernel-Mode Setup for details.
After the registry has been properly configured, it is a simple matter of starting NTSD as follows:
ntsd -See Controlling the User-Mode Debugger from the Kernel Debugger for an explanation of how to proceed.
You will have to set your symbol path to a location on your host computer or to some other location on your network. When CSRSS is being debugged, network
authentication on the target computer will not work properly.
Note that you may see an "in page io error" message. This is another manifestation of a hardware failure.
In Windows XP and later versions of Windows, when the debugging session ends, the debugger will detach from CSRSS while the CSRSS process is still running. This
avoids termination of the CSRSS process itself.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging WinLogon
WinLogon is the user-mode process that handles the task of interactive users logging on and logging off, and handles all instances of CTRL+ALT+DELETE.
Controlling NTSD from the Kernel Debugger
The easiest way to debug WinLogon is to use NTSD and control it from the kernel debugger.
Enabling WinLogon Debugging
Because you will be redirecting the user-mode debugger output to the kernel debugger, you will need to set up a kernel debugging connection. See Kernel-Mode Setup for
details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1027 of 1651

To attach a debugger to WinLogon, you must go through the registry so the process is debugged from the time it starts up. To set up WinLogon debugging, set
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\WinLogon.EXE\Debugger to:
ntsd -d -x -g
The -d option passes control to the kernel debugger. The -x option causes the debugger to capture access violations as second-chance exceptions. The -g option causes the
WinLogon process to run after the attachment. Do not add the -g if you want to start debugging before Winlogon.exe begins (for example, if you want to set an initial
breakpoint).
In addition, you should set the GlobalFlag value under the winlogon.exe key to REG_SZ "0x000400F0". This sets heap checking and
FLG_ENABLE_KDEBUG_SYMBOL_LOAD. However, since this second flag only affects the kernel debugger, symbols must also be copied to the target computer before
starting the debugger.
The registry change requires a reboot to take effect.
Performing the Debugging
After the next reboot, the debugger will break into WinLogon automatically.
See Controlling the User-Mode Debugger from the Kernel Debugger for an explanation of how to proceed.
You will have to set your symbol path to a location on your host computer or to some other location on your network. When WinLogon is being debugged, network
authentication on the target computer will not work properly.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging a User-Mode Failure with KD

To properly debug user-mode failures, you need CDB or WinDbg. However, sometimes a user-mode exception will break into KD because no user-mode debugger is present.
There are also times when it is helpful to monitor what specific user-mode processes are doing while debugging a kernel-mode problem.
By default, the kernel debugger attempts to load the first user-mode symbol that matches the address specified (for a k, u, or ln command).
Unfortunately, user-mode symbols are often not specified in the symbol path or the first symbol is not the correct one. If the symbols are not there, either copy them into the
symbol path or use a .sympath (Set Symbol Path) command to point to the full symbol tree, and then use the .reload (Reload Module) command. If the wrong symbol is
loaded, you can explicitly load a symbol by doing a .reload <binary.ext>.
Most of the Windows DLLs are rebased so they load at different addresses, but there are exceptions. Video adapters are the most common exceptions. There are dozens of
video adapters that all load at the same base address, so KD will almost always find ati.dll (the first video symbol, alphabetically). For video, there is also a .sys file loaded
that can be identified by using a !drivers extension. With that information, you can issue a .reload to get the correct video DLLs. There are also times when the debugger gets
confused and reloading specific symbols will help give the correct stack. Unassemble the functions to see if the symbols look correct.
Similar to the video DLLs, almost all executables load at the same address, so KD will report access. If you see a stack trace in access, do a !process and then a .reload of the
executable name given. If the executable does not have symbols in the symbol path, copy them there and do the .reload again.
Sometimes KD or WinDbg has trouble loading the correct user-mode symbols even when the full symbol tree is in the symbol path. In this case, ntdll.dll and kernel32.dll are
two of the most common symbols that would be required. In the case of debugging CSRSS from KD, winsrv.dll and csrsrv.dll are also common DLLs to load.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Extra Tools
This section includes:
ADPlus
Application Verifier
Dr. Watson
DumpChk
GFlags
Kill Tool
Logger and LogViewer
Remote Tool

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1028 of 1651

TList
UMDH
USBView
Tools Related to Symbol Files and Source Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus
ADPlus (adplus.vbs), also known as Autodump+, is a console-based Microsoft Visual Basic script. This tool automates the CDB debugger to produce memory dumps and log
files that contain debug output from one or more processes.
This section includes the following topics:
Introduction to ADPlus
Running ADPlus
Windows 2000 Server Configuration
Common ADPlus Scenarios
ADPlus Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Introduction to ADPlus
This section includes the following topics:
ADPlus Overview
When ADPlus Can Be Used
ADPlus Limitations and Restrictions
ADPlus Modes of Operation
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Overview
ADPlus automates the CDB debugger to produce memory dumps and log files that contain debug output from one or more processes.
Every time that you run ADPlus, debugging information (such as memory dumps and text files that contain debug information) is put in a new, uniquely named folder (such
as C:\Temp\Crash_Mode__Date_01-22-2001__Time_09-41-08AM) on the local file system or a remote network share. In addition, each file that ADPlus creates is also given
a unique name (such as PID-1708__Inetinfo.exe__Date_01-22-2001__Time_09-41-08AM.log) to avoid overwriting older files with newer ones.
ADPlus works with any user-mode process or service such as Internet Information Services (IIS), Microsoft Transaction Server (MTS), or Microsoft COM+ applications.
ADPlus has the following features:

ADPlus uses the latest Microsoft debuggers for speed and reliability.
ADPlus dumps memory asynchronously for multiple processes so that each process is frozen and dumped at the same time. This process provides an effective
"snapshot" of the whole application at the time ADPlus was run. It is important to capture all of the processes that make up a given application and all of the processes
that a given application uses at the same time so that you can capture the state of the application at the time that the problem occurs. This snapshot is especially
important for applications that make remote procedure calls to other processes.
ADPlus has a command-line interface. Because ADPlus does not have a graphical user interface (GUI), you can run it with the -quiet option in a remote command shell
(a Command Prompt window that is controlled through Remote.exe). The -quiet option suppresses all dialog boxes and logs all output to the event log. For more

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1029 of 1651

information about how to run ADPlus from a remote command shell, see Running in Crash Mode Remotely.
When ADPlus monitors for crashes, it can notify you or a computer of a crash through the Microsoft Windows Messenger service. This feature is activated though the notify command-line option.
When ADPlus monitors a process in crash mode and a failure (that is, crash) occurs, ADPlus sends important information about the type of failure to the event log.
ADPlus supports XCOPY deployment. That is, if you copy the Debugging Tools for Windows installation folder to a new location, ADPlus still works correctly. In
addition, ADPlus does not require that you register any custom Component Object Model (COM) components on the system. Therefore, this tool is ideal for use on
production servers that have a locked-down software configuration. To remove ADPlus, you have to only delete the folder that it was installed or copied to.

Note The Exception Monitor tool is obsolete. ADPlus contains all of the functionality of Exception Monitor.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

When ADPlus Can Be Used

ADPlus can create a detailed dump file in a variety of scenarios. This file contains debugging information that you must have to isolate the cause of problems that occur in
complex environments.
When Should You Use ADPlus?
You should use ADPlus to capture debugging information if you are experiencing the following problems:

Processes that stop responding (that is, hang).

Processes that have 100 % CPU utilization on a single processor computer, 50 % utilization on a dual processor computer, 25 % utilization on a quad processor
computer, and so on.
Processes that fail (that is, crash) or shut down unexpectedly.

When Should You Not Use ADPlus?

You should not use ADPlus in the following situations:

If you have to troubleshoot an application or process that ends unexpectedly during startup.
You can use ADPlus only together with processes that start successfully. If you have to troubleshoot processes that end unexpectedly during startup, you should use
CDB, WinDbg, or UserDump instead.

If there is a noticeable performance effect when you use ADPlus in crash mode.
This performance effect is typically caused by dynamic-link libraries (DLLs) or applications that throw many Microsoft Visual C++ EH exceptions (which occur when
you use the C++ throw statement or when you use try/catch blocks). Applications that write lots of information to the debug output stream can also cause a decrease in
performance. Frequently, ADPlus does not affect performance noticeably when it is running in crash mode.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Limitations and Restrictions

The following notes and restrictions apply to ADPlus:

You must install the Microsoft Windows Script Host components before you can run ADPlus. The current version of ADPlus requires version 5.6 of the scripting host.
You can run ADPlus with earlier versions of the scripting host if you start ADPlus in a Command Prompt window by using the install directory of Debugging Tools for
Windows as the default directory. However, the -quiet switch requires version 5.5 in any event.
Windows Script Host components might already be installed if you have installed recent versions of certain Microsoft software products. If you want to install or
upgrade the Windows Script Host, visit the Windows Script section of the MSDN Web site.

The -iis option requires version 4.0 or a later version of Internet Information Services (IIS), formerly known as Internet Information Server.
If you use the -quiet option, ADPlus logs information to the event log on systems that are equipped with the Windows Script Host version 5.5 or later.
If you use the -o option, the specified path must not contain more than one nonexistent folder. For example, if you specify -o C:\Temp1\Temp2 and the C:\Temp1 and
\Temp2 folders do no exist, ADPlus displays an error message and does not create these folders. If you specify -o C:\Temp1, ADPlus creates the C:\Temp1 folder if it
does not exist and puts all output files in that folder. If you are specifying multiple subfolders and using the -o option, you should make sure that all of the subfolders
exist before you run ADPlus.
In COM+, you can configure a server package to start in the debugger in the Advanced tab in the Properties dialog box of the package. If you enable the Launch in
Debugger option, ADPlus cannot attach the CDB debugger to a process. (By default, only one debugger can be attached to a process at a time.)
When a remote procedure call (RPC) is made from a process that ADPlus is analyzing in crash mode to another process that has failed or has been shut down, the log
file that ADPlus creates for the process that is being monitored might contain one or more of the following exceptions.
Unknown exception - code 80010105 (first chance)
Unknown exception - code 800706be (first chance)
Unknown exception - code 800706ba (first chance)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1030 of 1651

These exceptions are expected. RPC raises these exceptions when a call is made from a process that is being monitored to a nonexistent or failed process.

This exception typically appears after IIS calls an out-of-process (high-isolation) Web site that has failed. This exception might be followed by two instances of the
following exception.
Unknown exception - code 800706ba (first chance)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Modes of Operation

ADPlus has two modes of operation:

You can use hang mode to troubleshoot processes that stop responding (that is, hang), 100 % CPU utilization, and other problems that do not involve a failure (that is,
crash). When you use ADPlus in hang mode, you must wait until the process stops responding before you run the script.
You can use crash mode to troubleshoot failures that typically activate a postmortem debugger or any other type of error that causes an application or service to end
unexpectedly. When you use ADPlus in crash mode, you must start ADPlus before the failure occurs. You can configure ADPlus by using the -notify option to notify
an administrator or a computer of a failure.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Hang Mode
In hang mode, ADPlus immediately produces full memory dumps for all of the processes that are specified at the command prompt after the script has finished running.
ADPlus puts each .dmp file that it creates into a folder that contains the date and time stamp from when ADPlus was run. And each file name contains the process name, the
process ID, and the date and time stamp from when ADPlus was run. While the process memory is being dumped to a file, the process is frozen, with the debugger noninvasively attached to it. After the memory dump is finished, the debugger detaches and the process resumes.
You can use ADPlus in hang mode instead of UserDump to dump the memory for one or more processes. In addition, hang mode works inside a Terminal Server session.
-MiniOnSecond Switch
When you specify the -MiniOnSecond command-line parameter for ADPlus, ADPlus produces log files from a scripted debug session and minidump files (which are
typically less than 100 KB ). This parameter is typically faster than creating full memory dumps for each process that is specified on the command line. (In earlier versions of
ADPlus, this feature was called quick mode.)
A minidump file is especially useful if you do not plan to analyze the file yourself. You can create a .zip file that contains the dump file and send it in an e-mail message to a
professional support technician. This process is easier than having to put the files on an FTP site or use some other method of transfer.
-NoDumpOnSecond Switch
When you use the -NoDumpOnSecond command-line parameter, ADPlus does not create any dump files.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Crash Mode
In crash mode, ADPlus attaches the CDB debugger to all processes that are specified at the command prompt and automatically configures the debugger to monitor for the
following kinds of exceptions:

Invalid handle
Illegal instruction
Integer divide-by-zero
Floating-point divide-by-zero
Integer overflow
Invalid lock sequence
Access violation
Stack overflow
C++ EH exception
Unknown exception

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1031 of 1651

You can use ADPlus in crash mode instead of UserDump when you are troubleshooting these kinds of exceptions.
Because crash mode uses an "invasive" attach through the CDB debugger, you cannot use this mode in a Microsoft Windows 2000 Terminal Server session, because these
operating systems do not permit a debugger in one window station to attach to a process in a different window station. Crash mode is supported in a Terminal Server session
on Windows XP and later versions of Windows. Hang mode does work inside a Terminal Server session on any platform.
Note For a workaround in Windows 2000 Terminal Server by using remote.exe, see Running in Crash Mode Remotely. For more information about invasive and noninvasive attaching, see Starting the Debugger.
When ADPlus is running in crash mode, a debugger remains attached to each process that is specified at the command prompt for the lifetime of that process until a fatal
exception is trapped and the process fails (that is, crashes), or until a user presses CTRL+C to detach the debugger from that process. To manually detach the debugger from
the process, you must maximize the debugger window and press CTRL+C to break into the debugger. When you press CTRL+C, ADPlus traps the command, begins to list
the stacks for all threads to a log file, and then produces a minidump file of the process before it detaches from the debugger. Because crash mode performs an invasive attach,
the process is ended when the debugger is detached, and you have to restart it. If the process is a Microsoft Transaction Server (MTS) or COM+ process, the process is
restarted automatically the next time that a call is made to a component in that package.
First-Chance Exceptions
Each kind of exception (access violation, stack overflow, and so on) can be raised to a debugger as a "first chance" or "second chance" exception. First-chance exceptions are
not fatal unless they are not handled properly by an error handler. If a first-change exception is not handled properly by an error handler, they are raised again as a secondchance exception (which only a debugger can handle). If a debugger does not handle a second-chance exception, the application is shut down.
By default, when ADPlus detects a first-chance (nonfatal) exception for all kinds of exceptions (except unknown and EH exceptions), ADPlus does the following:
1. Pauses the process to log the date and time that the exception occurred in the log file for the process that is being monitored.
2. Logs the thread ID and call stack for the thread that raised the exception in the log file for the process that is being monitored.
3. Produces a uniquely-named minidump file of the process at the time that the exception occurred and then resumes the process. (This step is equivalent to .dump -u /m.)
By default, ADPlus does not produce a unique minidump file for first-chance EH and unknown exceptions because processes frequently encounter many of these exceptions.
These kinds of exceptions are typically handled by error handling code in a process or DLL. In other words, these exceptions are typically handled exceptions, and they do not
become second-chance (unhandled) exceptions, which end the process.
However, you can configure ADPlus to produce unique minidump files for first-chance EH and unknown exceptions. For more information about how to configure ADPlus,
see ADPlus Command-Line Options and ADPlus Configuration Files.
Second-Chance Exceptions
When ADPlus detects a second-chance (fatal) exception for all kinds of exceptions (including EH and unknown exceptions), ADPlus does the following:
1.
2.
3.
4.
5.

Pauses the process.

Logs the date and time that the exception occurred.
Logs the thread ID and the call stack for the thread that raised the exception.
Produces a full memory dump of the process at the time that the fatal exception occurred.
Exits the debugger. This step ends the process.

ADPlus keeps a separate log file for each process that it monitors.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Running ADPlus
This section includes the following topics:
Running ADPlus for the First Time
ADPlus Command Line
ADPlus Configuration Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Running ADPlus for the First Time

To run ADPlus, open a Command Prompt window, move to the folder where you installed or copied the debuggers, and type adplus.vbs.
You might be prompted to change your default script interpreter from WScript.exe to CScript.exe. We strongly recommend that you enable ADPlus to set CScript as the
default script interpreter.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1032 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Command Line

To use ADPlus, you must specify a series of command-line options or arguments to the script. At a minimum, ADPlus requires two command-line options:

One option specifies the mode of operation.

One option specifies a target process to operate against.

Commands are parsed from left to right. When you specify a target, ADPlus uses all of the options that it has parsed up to that point. This parsing enables you to create a long
command that has multiple targets and specify different options for each target.
To more easily specify options, you can store options in configuration files and use the -c parameter to point to these files. For more information about the ADPlus commandline options, see ADPlus Command-Line Options.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Configuration Files

If you use the -c parameter at the ADPlus command prompt, you can specify a configuration file. ADPlus reads its settings from this file so that you do not have to retype
lengthy and detailed command lines. There are also some settings that you can set only from a configuration file, not from a command line.
All configuration options have default values, so no option is mandatory. You can define all of your parameters in the configuration file or you can provide some parameters
by using the command-line options and other parameters in the configuration file.
The configuration file follows XML format, and you can include comments by using the  format. However, you can use only the <Tag>Text </Tag> syntax
for the open and closing tags. You cannot use the short format (<Tag Text />).
This section includes the following topics:
ADPlus Configuration File Sections
Using ADPlus Configuration Files
ADPlus Configuration File Samples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Configuration File Sections

An ADPlus configuration file is divided into the following sections:
<ADPlus>

<Settings>

</Settings>
<PreCommands>

</PreCommands>
<PostCommands>

</PostCommands>
<Exceptions>

</Exceptions>
<Breakpoints>

</Breakpoints>
<HangActions>

</HangActions>
<LinkConfig>
<!-allows to link to another config file -->

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1033 of 1651

</ LinkConfig >

</ADPlus>
These sections are described in the following topics:
Settings
PreCommands
PostCommands
Exceptions
Breakpoints
HangActions
LinkConfig
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Settings
The Settings section enables you to define the primary settings for ADPlus. Most of these settings are equivalent to command-line parameters.
You can include as many instances as you want for the ProcessID, ProcessName, Spawn. and Notify elements.
<Settings>
<AttachInterval> inseconds </AttachInterval>
<AttachRepeats> numberofrepeatedattachments </AttachRepeats>
<RunMode> runmode </RunMode>
<LastScriptCommand> LastCommand </LastScriptCommand>
<Option> IIS </Option>
<Option> Quiet </Option>
<Option> NoTlist </Option>
<Option> NoTsCheck </Option>
<Option> NoFreeSpaceChecking </Option>
<OutputDir> OutputDirectoryName </OutputDir>
<ProcessID> PID </ProcessID>
<ProcessName> ProcessName </ProcessName>
<GenerateScript> ScriptName </GenerateScript>
<Spawn> Spawn Command </Spawn>
<Sympath> Symbol Path </Sympath>
<SympathPlus> Symbol Path to add </SympathPlus>
<Notify> { ComputerName | UserName } </Notify>
<Debugger> Debugger </ Debugger >
</Settings>
The Settings section contains the following elements:
AttachInterval
Same as the IntervalInSeconds parameter of the r command-line option.
AttachRepeats
Same as the Repeats parameter of the r command-line option.
runmode
runmode can be either CRASH or HANG.
LastCommand
Can be Q, QD, G, GN or Void. The first four options are equivalent to q, qq (Quit), qd (Quit and Detach), g (Go), and gn, gN (Go with Exception Not Handled)
debugger commands.
Void indicates that no debugger command is added. In this situation, you must manually enter the last command in the debug session.
The default behavior is Q. Setting LastCommand to something other than the default is required only if you will use the CTL+C behavior (bpe exception) to induce
dumps.
IIS
Same as the -iis command-line option.
Quiet
Same as the -quiet command-line option.
NoTlist
Same as the -NoTlist command-line option.
NoTsCheck
Same as the -NoTsCheck command-line option.
NoFreeSpaceChecking
Same as the -NoFreeSpaceChecking command-line option.
OutputDirectoryName

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1034 of 1651

Same as the -o command-line option.

PID
Same as the -p command-line option.
ProcessName
Same as the -pn command-line option.
ScriptName
Same as the -gs command-line option.
Spawn Command
Same as the -sc command-line option.
Symbol Path
Same as the -y command-line option.
Symbol Path to add
Same as the -yp command-line option.
{ ComputerName | UserName }
Same as the -Notify command-line option.
Debugger
Same as the -dbg command-line option.
For more information about the corresponding command-line switches, see ADPlus Command-Line Options.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

PreCommands
The PreCommands section has the following format.
<PreCommands>
<Cmd> some command </Cmd>
<ShellSync> some command line </ShellSync>
<ShellAsync> some command line </ShellAsync>
</PreCommands>
With the <Cmd> tag, you can define additional debugger commands that you want to include in the final script, before the commands that are related to each exception are
defined. You can include multiple <Cmd> tags. The related text has to be a command that the CDB debugger understands. For example, you could use the following text to
load a custom extension.
<Cmd> .load SomeExtension.dll </Cmd>
With the <ShellSync> and <ShellAsync> tags, you can define an application that you want to be run before ADPlus starts to attach to the selected processes.
You can run these applications synchronously or asynchronously.
These applications are run only one time, regardless of how many processes you are attaching to.
The following example shows the ShellSync element.
<ShellSync> notepad.exe c:\myfolder\somefile.txt </ShellSync>

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Log
Adds a log entry that is related to the exception.
EventLog
Adds an event log that is related to the exception.
MiniDump
Creates a minidump.
FullDump
Creates a full dump.
MiniDumpOver
Creates a minidump and overwrites multiple instances for the same exception.
FullDumpOver
Creates a full dump and overwrites multiple instances for the same exception.
Stack
Lists the faulting call stack into the log.
Stacks
Lists all thread call stacks into the log.
LoadedModules
Lists all loaded modules.
MatchingSymbols
Lists all modules with matching symbols.
Void
Does nothing.
CustomActions
Specifies any debugger commands. Separate multiple actions with semicolons. You can include any debugger commands that are available in CDB.
<CustomActions>!runaway;!heap</CustomActions>
{ G | Q | QD }
Specifies how to return from the debugger after the breakpoint is done. These parameters work like the g, q, and qd debugger commands. QD is supported only in
Microsoft Windows XP and later versions of Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

HangActions
The HangActions section enables you to select the actions that you want to take when you are running ADPlus in hang mode.
<HangActions>
<Option> MiniDump </Option>
<Option> FullDump </Option>
<Option> NoDump </Option>
<Option> Clear </Option>
<Actions> Actions </Actions>
<CustomActions> CustomActions
</HangActions>

</CustomActions>

The parameters have the following meanings:

MiniDump
Generates a mini dump.
FullDump
Generates a full dump.
NoDump
No dump is created in hang mode.
Clear
Clears all selections. Typically, you use this command before you define your own actions with the tags later in this topic.
Actions
Enables you to select the set of actions to be taken in hang mode.
You can use the following actions (which are not case sensitive):
MiniDump
Creates a minidump
FullDump
Creates a full dump.
NoDump
Does not create a dump.
Stacks
Lists all thread call stacks into the log.
LoadedModules
Lists all loaded modules.
MatchingSymbols
Lists all modules that have matching symbols.
Heap
Executes the !heap extension.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1038 of 1651

Handle
Executes the !handle extension.
Dlls
Executes the !dlls extension.
Locks
Executes the !ntsdexts.locks extension.
ThreadUsage
Executes the !runaway extension.
Separate multiple actions with semicolons, as follows.
<Actions> MiniDump;Stacks;Heap

</Actions>

CustomActions
Enables you to select additional actions to be taken in hang mode. You can include any debugger commands that are available in CDB, as follows.
<CustomActions> !runaway;!heap </CustomActions>
The following example shows a complete <HangActions> section.
<HangActions>
<Option> Clear </Option>
<Actions> Stacks;FullDump;LoadedModules
</HangActions>

</Actions>

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

LinkConfig
The LinkConfig section enables you to link to another configuration file.
The following example shows this section.
<LinkConfig> c:\adp\config2.cfg </LinkConfig>

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using ADPlus Configuration Files

This section includes the following topic:
Using the j Command in Configuration Files
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the j Command in Configuration Files

When you are using the j (Execute If - Else) command in custom action tags, you must include a return go action in each branch of the j command. This action can be a g
(go), gc (Go from Conditional Breakpoint), gh (Go with Exception Handled), or gn (Go with Exception Not Handled) command. In addition, you should use VOID in
the <ReturnAction> tag.
When you are using j together with breakpoints, you should use gc instead of g. For a sample configuration file that has a conditional breakpoint, see Sample Configuration
File for Conditional Breakpoints.
When you are using a file path (such as in a .dump command), the behavior is different in bp and exceptions. In bp, you must use two backslashes (\\) instead of one
backslash (\) in the file path. In exceptions, you do not have to use the second backslash.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1039 of 1651

December 09, 2009

Debugging Tools for Windows

ADPlus Configuration File Samples

This section contain the following samples of ADPlus configuration files:
Sample Configuration File for Breakpoints
Sample Configuration File for Conditional Breakpoints
Sample Configuration File for Custom Exceptions
Sample Configuration File for Conditional CLR Exceptions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Sample Configuration File for Breakpoints

The following sample shows you how to configure ADPlus for breakpoints.
<ADPlus>
<!-Configuring ADPlus for breakpoints
-->

<Breakpoints>
<NewBP>
<Address> ntdll!RtlEnterCriticalSection </Address>
<Actions> Log;Stacks </Actions>
<CustomActions> r </CustomActions>
</NewBP>
<NewBP>
<Address> 77f5b380 </Address>
<Actions> Log;Stacks </Actions>
<CustomActions> r </CustomActions>
</NewBP>
</Breakpoints>
</ADPlus>

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Sample Configuration File for Conditional Breakpoints

The following sample shows you how to configure ADPlus for conditional breakpoints.
ADPlus>
<!-Configuring ADPlus to create a conditional breakpoint
When using j we need to include the "g" command into each branch due to its special syntax
with j everything after the two branches is ignored
For this reason we need to use VOID in ReturnAction
Note - when using j commands with breakpoints it may be more convenient to use gc instead of g
if you plan to do live debug; see documentation for gc in debugger.chm
-->

<Breakpoints>
<NewBP>
<Address> mscorsvr!RaiseTheException </Address>
<Type> BU </Type>
<Actions> VOID </Actions>
<CustomActions> j (poi(poi(poi(poi(esp+4))+8)+48) = 02000004) '.time;du poi((poi(esp+4)+10))+c;.dump /u /mfh
<ReturnAction> VOID </ReturnAction>
</NewBP>
</Breakpoints>
</ADPlus>

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1040 of 1651

Memory
Process
Processor
System
Thread

Additional Information
For more information about how to debug a process that is consuming 100% of CPU, see Tracking Down a Processor Hog.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Process Ends Unexpectedly

If a process randomly fails (that is, crashes) or shuts down unexpectedly, you can run ADPlus in crash mode to obtain a memory dump of the process that is failing before the
problem occurs.
For example, use one of the following commands.
The following command runs ADPlus in crash mode and causes it to attach the CDB debugger to Inetinfo.exe and all Mtx.exe or Dllhost.exe processes that are running on the
computer. ADPlus then waits for any first-chance and second-chance exceptions. By default, because the -o option is omitted, ADPlus put all files in a subfolder below the
installation folder.
ADPlus -crash -iis
The following command runs ADPlus in crash mode and causes it to attach the CDB debugger to Inetinfo.exe and all Mtx.exe or Dllhost.exe processes that are running on the
computer. The -quiet option suppresses all message boxes and logs all output to the event log. Because the -notify option is used, the debuggers notify all users who are
logged on to the computer named RemoteComputer whenever a failure is detected or when the process that is being monitored shuts down. Because the -o option is used, all
output is put in the C:\Temp folder. If the folder does not exist, it is created.
ADPlus -quiet -crash -iis -notify RemoteComputer -o c:\temp
The following command is the same as the previous one except that it logs all output to a server. A new subfolder is created under \\server\share. The subfolder's name is
based on the name of the local computer. Therefore, if you are running ADPlus on a cluster of servers, each server on which ADPlus is running logs its own unique folder
under \\server\share. You do not have to create unique folders for each server because they are created automatically.
Running from a Local Console
If you are running ADPlus in crash mode from the local console instead of remotely, you must remain logged on to the console for the duration of the debug session.
For example, when you start ADPlus by using the -iis option to monitor IIS, when the starting user logs out of the console, the copies of CDB that are running on the console
are closed (along with all other running applications). Therefore, debugging stops, and the process that is being monitored is ended.
To avoid this issue, you can lock the console session (press CTRL+ALT+DELETE and then click Lock Computer), or run ADPlus inside a remote command shell that has
been configured not to require an interactive logon.
For more information about how to schedule a remote command shell to run noninteractively, see Running in Crash Mode Remotely.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1043 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

MTS or COM+ Server Application Ends Unexpectedly

Custom Component Object Model (COM) components that run inside an MTS or COM+ server application actually run inside a surrogate process (Mtx.exe or Dllhost.exe).
These surrogate processes have properties and settings that you can configure through the Component Services Microsoft Management Console (MMC) snap-in.
By default, MTS or COM+ server applications are configured to shut down after 3 minutes of idle time. To make sure that these processes remain running while the debugger
is attached and monitoring for exceptions, you must configure them to "Leave running when idle".
In addition, MTS and COM+ implement a failfast. This safeguard is designed to fail (or shut down) MTS or COM+ processes that generate unhandled access violations.
By default, failfast is enabled in MTS or COM+ applications that raise unhandled access violation exceptions. Therefore, a failing MTS/COM+ server application can never
raise a second-chance access violation exception. (That is, this application is shut down after the first-chance access violation.) By default, ADPlus is configured to produce a
minidump file only on first-chance exceptions.
To debug an MTS or COM+ server application, do the following:
1. Configure the MTS or COM+ server application to "Leave running when idle."
2. Set ADPlus to create a full dump on a first-chance exception. For more information about this configuration, see ADPlus Command-Line Options and ADPlus
Configuration Files.
3. Run ADPlus in crash mode and wait for the application to fail.
Because MTS and COM+ shut down a server application, and because the process cannot raise a second-chance exception because of the failfast policy, you can obtain only a
first-chance access violation memory dump.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Running in Crash Mode Remotely

There are many occasions when you must initiate ADPlus in crash mode from a local client computer to monitor a process that ends unexpectedly on one or more remote
servers in a cluster of servers. Typically, on Microsoft Windows 2000, you can initiate ADPlus in crash mode remotely by using Terminal Services. However, because you
cannot debug applications that are running in different window stations on Windows 2000, ADPlus disables crash-mode functionality when it detects that it is running in of a
Terminal Services session.
Instead, you must first create a batch file that opens a Command Prompt window on the remote server that has been shared by using the Remote.exe utility. Then, schedule this
batch file to run on the target server by using the AT command (which causes the command shell to run noninteractively, similar to a service). The remote command shell is
then connected to a local workstation or client computer that uses the same Remote.exe utility that was used to start it.
To start a remote command shell on a server by using the AT command, you must follow the correct procedure on the remote server and the local client.
Ideally, you should install the debuggers on the local client computer. If you cannot install the debuggers on the local client computer, you should at least put a copy of the
Remote.exe utility on the local client. The following procedure assumes that Debugging Tools for Windows package is installed in C:\Debuggers on the remote server and that
this package (or at least Remote.exe) is installed in D:\Debuggers on the local client. Adjust this procedure to the actual installation on your computers.
To set up a remote command shell on the server, do the following:
1. Create a new batch file that is named Remoteshell.cmd in the C:\Debuggers folder.
2. Add the following line to this batch file:
c:\debuggers\remote.exe /s "cmd.exe" remoteshell
3. At the console on the server or in a Terminal Services session, open a new Command Prompt window, and type the following command:
AT 15:00 c:\debuggers\remoteshell.cmd
In this command, "15:00" is 1 minute later than the current time. For example, if the current time is 14:59, type 15:00.
4. Wait for the AT command to run.
5. At the command prompt, type AT without parameters to verify that the task has run without errors.
To connect to the remote command shell from the client, do the following:
1. At a command prompt, move to the D:\Debuggers directory.
2. Type the following command:
remote.exe /c RemoteServer remoteshell
In this command, RemoteServer is the name of the remote server.
After you run this command, your local command shell is connected to the remote command shell that is running on the server, and all commands that you type locally

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1044 of 1651

are run on the remote server. For example, the dir c:\ command lists the contents of the remote server's drive C.
3. In the remote command shell, run ADPlus in crash mode as if you were running it locally from the console. However, you must use the -quiet option to suppress all
message boxes that ADPlus displays by default. If you do not use this option, the remote command shell stops responding (that is, hangs) after you run ADPlus and
does not return to a prompt. Then, you must close the Command Prompt window on the server and start a new instance.
4. To send a debug break (CTRL+C) to a process that ADPlus is currently debugging remotely through crash mode, use the Breakin.exe utility. By default, this utilityis
installed together with the debuggers in the root of the debuggers directory. For example, to stop debugging IIS (Inetinfo.exe) that is running with a process ID of 1975,
type the following command in the remote command shell:
breakin.exe 1975
Alternatively, you can use the Kill.exe utility to end any processes that are being debugged. This utility is located in the root directory of the Debugging Tools for
Windows installation tree.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Monitoring ADPlus in Crash Mode

To determine where ADPlus has captured information about a failure (that is, crash) or if a process that is being monitored in crash mode has shut down, you can do the
following:

Use the -notify option, and make sure that the messenger service is started on the server that is being debugged and on the client computer that receives notifications.
In the output directory, open the .log file for each process in a text editor, and scroll to the end of the file. Look for the following text:
0:070> * -------- AutodumpPlus 4.01 finished running at: -------0:070> .time
Debug session time: Mon Aug 06 15:25:15 2001
System Uptime: 3 days 17:00:34
Process Uptime: 1 days 3:10:38
0:070> * -------------------------------------------------------

In the output directory, look for any .dmp files that contain the phrase "__2nd_chance". If a memory dump is labeled with this phrase, a process has failed.
In the output directory, look for any .dmp files that contain the phrase "__Process_was_shutdown". If a memory dump is labeled with this phrase, an administrator
ended the process or, if the process is an MTS or COM+ application, it might have been shut down because the idle limit was reached.
In the output directory, look for any .dmp files that contain the phrase "__CTRL-C". If a memory dump is labeled with this phrase, a debug break exception was thrown
from a DLL that was running inside the process or someone pressed CTRL+C from the console (or used Breakin.exe if running remotely) to stop the current debugging
session.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ADPlus Command-Line Options

ADPlus uses the following syntax.
adplus.vbs [-quiet] [-c ConfigurationFile] { -hang | -crash }
{ -iis | -pn Process | -p PID | -sc SpawningCommandLine }
[-notify Name] [-o Directory] [-cdh] [-cdc]
[-cdj] [-gs ScriptName] [ -ce CustomExceptionCode]
[-bp BreakpointParameters] [-y SymbolPath]
[-yp SymbolPathToAdd] [-FullOnFirst] [-MiniOnSecond]
[-NoDumpOnFirst] [-NoDumpOnSecond] [-NoTlist]
[-NoTsCheck] [-dbg Debugger] [-r Repeats IntervalInSeconds]
[-lcq] [-lcg] [-lcgn] [-lcv]
adplus.vbs -Help
The command is parsed from left to right. When you specify a target, ADPlus uses all of the options that it has parsed up to that point. This kind of parsing enables you to
create a long command that has multiple targets and to specify different options for each target. To specify options easily, you can store them in configuration files and use the
-c parameter to point to these files.
Parameters
-quiet
Suppresses all modal dialog boxes. This option is useful if you are running ADPlus in a remote command shell where modal dialog boxes can cause ADPlus to wait
indefinitely for a user to press OK.
For best results, make sure that this option is the first option that is passed to Adplus.vbs.
-c ConfigurationFile

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1045 of 1651

Enables you to provide an external configuration file that has additional information. You can use more than one configuration file by using several -c switches, as
follows.
adplus -c c:\t\file1.cfg

-c c:\t\file2.cfg

You can omit a required switch at the command prompt if you specify the equivalent setting in the configuration file. For more information about these files, see ADPlus
Configuration Files.
-hang
Configures ADPlus to run in hang mode. When ADPlus is running in hang mode, you must start ADPlus after a process stops responding (that is, hangs) or is consuming
high CPU utilization.
-crash
Configures ADPlus to run in crash mode. When ADPlus is running in crash mode, you must start ADPlus before the process fails (that is, crashes) or becomes unstable.
-iis
Debugs Internet Information Server (IIS) 4.0 or later. When you use ADPlus with the -iis option, ADPlus monitors all of the IIS in-process (Inetinfo.exe) and out-ofprocess (Mtx.exe and Dllhost.exe) applications. You can use this option in addition to the -pn or -p options, or you can use -iis by itself to analyze IIS and all running
MTS or COM+ applications in crash mode or hang mode.
If you are trying to analyze IIS 3.0 (or earlier), you should use the -pn option and specify Inetinfo.exe as the process to monitor.
-pn Process
Specifies a process name that ADPlus should analyze. Process should include the file name extension. To specify more than one process, use multiple -pn options (for
example, -pn process1.exe -pn process2.exe).
-p PID
Specifies the process ID (PID) of a process that ADPlus should analyze. To specify more than one process, use multiple -p options (for example, -p 1896 -p 1702).
-sc SpawningCommandLine
Enables you to provide a command. The debugger creates the process inside the debugger and starts monitoring it. This option is available only in crash mode, and you
must add the -sc switch as the last option, because everything that is provided after this option is considered to be the command to use to create the selected process. If
you want to create more than one process, use the -c switch and a configuration file.
-notify Name
(Crash mode only) Sends a message if a failure occurs. Name is the computer or user who receives the message. Whenever the debugger detaches from the process
because of a second-chance exception, or whenever you press CTRL+C to stop debugging, a notification is sent to this computer or remote user or computer through the
local messenger service. The local messenger service must be running on the target computer for this message to work.
-o Directory
Tells ADPlus where to put the debug output files. You should put long file names and file names that contain spaces in double quotation marks. If you use a UNC path
(\\server\share), ADPlus creates a new folder immediately below the UNC path that is specified with the name of the server that ADPlus is running on (for example,
\\server\share\Web1 or \\server\share\Web2). This option is useful if ADPlus is running on multiple computers in a Web farm that are all putting their output on the same
network share.
-cdh
Signals ADPlus to use the default configuration file for hang mode. You should name the default configuration file ADP_Default_Hang.cfg and you must store it in the
same directory as Adplus.vbs.
-cdc
Signals ADPlus to use the default configuration file for crash mode. You should name the default configuration file ADP_Default_Crash.cfg and you must store it in the
same directory as Adplus.vbs.
-cdj
Signals ADPlus to use the default configuration file for postmortem debugging mode. You should name the default configuration file ADP_Default_JIT.cfg and you must
store it in the same directory as Adplus.vbs. This file is typically used if you decide to use ADPlus as the default postmortem debugger. The configuration for this mode
should be similar to hang mode.
-gs ScriptName
Creates a script named ScriptName to use together with the debugger ADPlus save the script to a file. When you use this switch, you do not have to select any process to
debug.
-ce CustomExceptionCode
Enables you to add custom exceptions for the debugger to monitor.
-bp BreakpointParameters
Enables you to define breakpoints for the debugger to monitor. BreakpointParameters has the syntax of address;parameters. You must separate the additional parameters
by semicolons and the parameters cannot contain spaces. You can use any of the following parameters:
MiniDump, FullDump or NoDump
Indicates whether you want a dump. By default, there is no dump.
Integer
Indicates the number of passes to ignore.
Q or QD or G
Indicates whether you want to quit, quit and detach, or go after the action. The default value is G.
BP or BU or BM
Indicates the type of debugger command that was used to create the breakpoint. The default value is BP. If you use BM, you can define multiple breakpoints by
using wildcard characters in the address.
If you do not include any optional parameters, the default behavior is to create a log, list the call stack, and then let the target run.
-y SymbolPath
Enables you to define the symbol path. This option accepts multiple folders separated by semicolons, including references to symbol servers.
-yp SymbolPathToAdd
Enables you to add a symbol path of the path that is already defined in the debugger . This option accepts multiple folders separated by semicolons, including references
to symbol servers.
-FullOnFirst
Creates full dumps on first chance for all defined exceptions. The default behavior is to have minidumps created on first chance. If several first-chance exceptions of the
same type occur, the dump files are overwritten. If you want another type of behavior, you can use the configuration file for additional options.
-MiniOnSecond
Creates minidumps on second chance for all defined exceptions. The default behavior is to have full dumps created on second chance.
-NoDumpOnFirst
Creates no dumps on first chance for all defined exceptions. The default behavior is to have minidumps created on first chance.
-NoDumpOnSecond
Creates no dumps on second chance for all defined exceptions. The default behavior is to have full dumps created on second chance.
-NoTlist
Does not use the TList tool to obtain the list of running processes. You should use this option only if you are experiencing problems with ADPlus that are related to the
TList tool.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1046 of 1651

If you use -NoTlist, you cannot use the -pn switch. In addition, the dump file names do not include the package name for COM+ applications.
-NoTsCheck
Enables ADPlus to attach to a target in a Terminal Server session, if you started the target in the same session as ADPlus. You have to use this switch only in Microsoft
Windows 2000. If this switch is not included in those operating systems, you cannot use ADPlus in a Terminal Server session. In Windows XP and later versions of
Windows, ADPlus can freely attach to targets in Terminal Server, regardless of what session they were started on, and you do not have to use this switch.
-dbg Debugger
Enables you to select the debugger to use. The default debugger is CDB, but you can select WinDbg or NTSD instead. Debugger should include the debugger name and
the .exe extension.
-r Repeats IntervalInSeconds
Enables you to do repeated hang attachments. This option is ignored in crash mode. Repeats specifies the number of times that you want ADPlus to run in hang mode.
IntervalInSeconds specifies the interval, in seconds, between each run.
-lcq
Sets the last script command to Q (quit).
-lcg
Sets the last script command to G (go).
-lcgn
Sets the last script command to GN (go not handled).
-lcv
Sets the last script command to void (no command; waits for user input).
-Help
Displays help information for ADPlus.
Additional Information
For more information about ADPlus, see ADPlus.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Application Verifier
Application Verifier (AppVerif.exe) is a dynamic verification tool for user-mode applications. This tool monitors application actions while the application runs, subjects the
application to a variety of stresses and tests, and generates a report about potential errors in application execution or design.
Application Verifier can detect errors in any user-mode applications that are not based on managed code, including user-mode drivers. It finds subtle programming errors that
might be difficult to detect during standard application testing or driver testing.
You can use Application Verifier alone or in conjunction with a user-mode debugger. This tool runs on Microsoft Windows XP and later versions of Windows. The current
user must be a member of the Administrators group on the computer.
Application Verifier is not included in Debugging Tools for Windows, but you can download and install it from the Microsoft Download Center Web site. The tool comes
with its own documentation. To read the documentation, start Application Verifier and from the Help menu, click Help, or press F1.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Dr. Watson
Dr. Watson for Windows, Drwtsn32.exe, creates memory dump files from user-mode programs which have crashed.
This section includes:
Using Dr. Watson to Create a Dump File
Installing Dr. Watson as the Postmortem Debugger
Reading a Dr. Watson Log File
Dr. Watson Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Dr. Watson to Create a Dump File

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1047 of 1651

The Dr. Watson for Windows program (Drwtsn32.exe) is preinstalled in your system directory (typically c:\winnt\system32) when Windows is set up. The default options are
set the first time Dr. Watson for Windows runs, which can be either when an application error occurs or when you run it from the command prompt or the Run dialog box.
To run Dr. Watson, the following command line is generally used:
drwtsn32 -p ProcessID
For other options, see the Dr. Watson Command-Line Options.
By default, Dr. Watson is set up to save a memory dump file immediately upon the failure of a user-mode component. By default, this file is named User.dmp. Its default
location depends on the version of Windows that is being used:

In Windows 2000, the default location is the %AllUsersProfile%\Documents\DrWatson folder.

In Windows XP and later versions of Windows, the default location is the %AllUsersProfile%\Application Data\Microsoft\Dr Watson folder.

This dump file is as large as the amount of RAM dedicated to the user-mode process on the system that failed. It includes the contents of the failed user-mode's memory
segment at the time that the error occurred.
As with any user-mode debugging session, symbols for the appropriate executables and DLLs must exist on the local computer. If a warning message box is enabled (see
Enabling Postmortem Debugging), you can copy the symbols when the message box appears. However, the symbols should not be copied after the debugger has started.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Installing Dr. Watson as the Postmortem Debugger

When an application error occurs, Windows can respond in several different ways, depending on the postmortem debugging settings. If these settings instruct a debugging tool
to create a dump file, a user-mode memory dump file will be created.
The default postmortem setting is for a dump file to be written by Dr. Watson. This means that when an application crashes, Dr. Watson will be activated and will save a
memory dump file. For details on how to alter this, see Enabling Postmortem Debugging.
If these settings have been changed, you can reinstall Dr. Watson as the postmortem debugger by running Dr. Watson with the -i option:
drwtsn32 -i
For details, see Dr. Watson Command-Line Options.
Dr. Watson on Windows XP and later versions of Windows
If Dr. Watson is activated on Windows XP or later, a message box will appear. This message box gives you the option of sending an error report to Microsoft. If you choose
Don't Send, a dump file will be created and stored on your hard disk. If you choose Send Error Report, a dump file will be created and stored on your hard disk, and will
also be transmitted to Microsoft over the Internet.
However, if you have manually set the \\HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\AeDebug\Auto value to zero, the Don't Send
button will simply terminate the application. The Send Error Report button will create a dump file and send it to Microsoft but will not store it on your hard disk. A third
button, Debug, will create a dump file and store it on your hard disk.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading a Dr. Watson Log File

The Dr. Watson log file records the details of the crash dump creation process. (It is distinct from the actual dump file.)
Log File Section Explanation
When an application exception (or program error) occurs, Dr. Watson generates a log file (Drwtsn32.log). The log file will always start with the following line:
Application exception occurred:
The next part of the log file always contains program error information. The error number listed corresponds to the error generated by the system.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1048 of 1651

The Faulting Application as Listed in the Dr. Watson Log File

The next part of the log file contains system information about the user and the computer on which the program error occurred:

System Information Section of the Dr. Watson Log File

The next part of the log file contains the list of tasks that were running on the system at the time that the program error occurred:

Task List Section of the Dr. Watson Log File

The next part of the log file contains the list of modules that the program loaded:

Module List Section of the Dr. Watson Log File

The next part of the log file contains the state dump for the thread ID that is listed. The state dump consists of a register dump, disassembly of the code surrounding the
current program counter, a stack back trace, and a raw stack dump. The first part of the state dump lists the thread ID:
The next part of the state dump contains the register dump:

State Dump Section of the Dr. Watson Log File

The next part of the state dump contains the instruction disassembly:

Instruction Disassembly Section of the Dr. Watson Log File

The next part of the state dump contains the stack back trace:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1049 of 1651

Stack Back Trace Section of the Dr. Watson Log File

The final part of the state dump contains the raw stack dump:

Raw Stack Dump Section of the Dr. Watson Log File

Following the state dump, the final part of the log file contains the symbol table:

Symbol Table Section of the Dr. Watson Log File

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Dr. Watson Command-Line Options

The Dr. Watson command line uses the following syntax:
drwtsn32 [-i] [-g] [-p pid] [-e event] [-?] [/?]
Parameters
-i
Installs Dr. Watson as the postmortem debugger. For details, see Installing Dr. Watson as the Postmortem Debugger.
-g
Ignored. Provided for compatibility with WinDbg and CDB.
-p pid
Specifies the process ID to debug.
-e event
Specifies the event to signal for process attach completion.
-?
Displays command-line option help.
/?
Displays a message box containing a list of options.
Additional Information
For more information, see Dr. Watson.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DumpChk
DumpChk (the Microsoft Crash Dump File Checker tool), DumpChk.exe, is a program that performs a quick analysis of a crash dump file. This enables you to see summary
information about what the dump file contains. If the dump file is corrupt in such a way that it cannot be opened by a debugger, DumpChk reveals this fact.
This section includes:
Using DumpChk
DumpChk Command-Line Options

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1050 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Page 1053 of 1651

on the computer. However, prior to Windows Vista, users with at least Guest account access can launch a program from the Global Flags dialog box.
When features do not work, or work differently, on particular operating system versions, the differences are explained in the description of the feature.
This topic includes:
GFlags Overview
GFlags Details
GFlags Commands
GFlags Flag Table
GFlags and PageHeap
Global Flags Dialog Box
GFlags Examples
Global Flag Reference
Caution Incorrect use of this tool can degrade system performance or prevent Windows from starting, requiring you to reinstall Windows.
Important Pool tagging is permanently enabled on Windows Server 2003 and later versions of Windows, including Windows Vista. On these systems, the Enable pool
tagging check box on the Global Flags dialog box is dimmed and commands to enable or disable pool tagging fail.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GFlags Overview
GFlags (gflags.exe), the Global Flags Editor, enables and disables advanced internal system diagnostic and troubleshooting features. You can run GFlags from a Command
Prompt window or use its graphical user interface dialog box.
Use GFlags to activate the following features:
Registry
Set system-wide debugging features for all processes running on the computer. These settings are stored in the GlobalFlag registry entry
(HKEY_LOCAL_MACHINE\ SYSTEM\ CurrentControlSet\ Control\ Session Manager\ GlobalFlag). They take effect when you restart Windows and remain
effective until you change them and restart again.
Kernel flag settings
Set debugging features for this session. These settings are effective immediately, but are lost when Windows shuts down. The settings affect all processes started after
this command completes.
Image file settings
Set debugging features for a particular program. These settings are stored in a GlobalFlag registry entry for each program (HKEY_LOCAL_MACHINE\
SOFTWARE\ Microsoft\ Windows NT\ CurrentVersion\ Image File Execution Options\ ImageFileName\ GlobalFlag). They take effect when you restart the
program and remain effective until you change them.
Debugger
Specify that a particular program always runs in a debugger. This setting is stored in the registry. It is effective immediately and remains effective until you change it.
(This feature is available only in the Global Flags dialog box.)
Launch
Run a program with the specified debugging settings. The debugging settings are effective until the program stops. (This feature is available only from the Global Flags
dialog box.)
Special Pool
Request that allocation with a specified pool tag or of a specified size are filled from the special pool. This feature helps you to detect and identify the source of errors in
kernel pool use, such as writing beyond the allocated memory space, or referring to memory that has already been freed.
Beginning in Windows Vista, you can enable, disable, and configure the special pool feature (Kernel Special Pool Tag) as a kernel flags setting, which does not require
a reboot, or as a registry setting, which requires a reboot.
Page heap verification
Enable, disable, and configure page heap verification for a program. When enabled, page heap monitors dynamic heap memory operations, including allocation and free
operations, and causes a debugger break when it detects a heap error.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GFlags Details
GFlags enables and disables system features by editing the Windows registry and internal settings. This section explains the operation of GFlags in detail and includes tips for

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1054 of 1651

using GFlags most efficiently.

General Information

To display the GFlags dialog box, at the command line, type gflags (with no parameters).
On Windows Server 2003 and earlier versions of Windows, to set flags in the registry or in kernel mode, you must be a member of the Administrators group on the
computer. However, users with at least Guest account access can launch a program from the GFlags dialog box.
GFlags system-level registry settings appear in the registry immediately, but do not take effect until you restart the system.
GFlags image file registry settings appear in the registry immediately, but do not take effect until you restart the process.
The debugger and launch features in the GFlags dialog box are program specific. You can only set them on one image file at a time.

Flag Details

To clear all flags, set the flag to -FFFFFFFF. Setting the flag to 0 adds 0 to the current flag value.
When you set the flags for an image file to FFFFFFFF (0xFFFFFFFF), Windows clears all flags for the image file and deletes the GlobalFlag entry in the image file
registry key. The image file registry key is retained.

Dialog Box and Command Line

You can run GFlags by using its handy dialog box or from the command line. Most features are available in both forms, with the following exceptions.
Dialog box only

Launch. Start a program using the specified flags.

Run the program in a debugger.
Special Pool on systems prior to Windows Vista. On Windows Vista and later versions of Windows, you can configure the Special Pool feature at the command line or
in the Gflags dialog box.

Command line only

Set the size of the user mode stack trace database (/tracedb).
Set page heap verification options.

Registry Information
GFlags settings that are saved between sessions are stored in the registry. You can use the registry APIs, Regedit, or reg.exe to query or change these values. The following
table lists the types of settings and where they are stored in the registry.
Systemwide settings ("Registry")
Program-specific settings ("Image file")
for all users of the computer.
Page heap options for an image file for
all users of the computer
User mode stack trace database size
(tracedb)
Create user mode stack trace database
(ust, 0x1000) for an image file
Load image using large pages if
possible
Special Pool

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\GlobalFlag
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution
Options\ImageFileName\GlobalFlag
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution
Options\ImageFileName\PageHeapFlags
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution
Options\ImageFileName\StackTraceDatabaseSizeInMb
Windows adds the image file name to the value of the USTEnabled registry entry (HKLM\SOFTWARE\Microsoft\Windows
NT\CurrentVersion\Image File Execution Options\USTEnabled).
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\UseLargePages.
HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\PoolTag

(Kernel Special Pool Tag)

Verify Start / Verify End
Debugger for an image file
Object Reference Tracing

HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management\PoolTagOverruns. The Verify Start option

sets the value to 0. The Verify End option sets the value to 1.
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ImageFileName\Debugger
HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Kernel\ObTraceProcessName, ObTracePermanent and
ObTracePoolTags

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GFlags Commands
To use GFlags, type the following commands at the command line.
You can use the GFlags commands and the Global Flags Dialog Box interchangeably.
Syntax
To open the GFlags dialog box:
gflags
To set or clear global flags in the registry:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1055 of 1651

gflags /r [{+ | -}Flag [{+ | -}Flag...]]

To set or clear global flags for the current session:
gflags /k [{+ | -}Flag [{+ | -}Flag...]]
To set or clear global flags for an image file:
gflags
gflags

/i ImageFile [{+ | -}Flag [{+ | -}Flag...]]

/i ImageFile /tracedb SizeInMB

To set or clear the Special Pool feature (Windows Vista and later)
gflags {/r | /k} {+ | -}spp {PoolTag | 0xSize}
To enable or disable the Object Reference Tracing feature (Windows Vista and later)
gflags {/ro | /ko} [/p] [/i ImageFile | /t PoolTag;[PoolTag...]]
gflags {/ro | /ko} /d
To enable and configure page heap verification:
gflags /p /enable ImageFile [ /full [/backwards] | /random Probability | /size SizeStart SizeEnd | /address AddressStart
[/debug ["DebuggerCommand"] | /kdebug] [/unaligned] [/notraces] [/fault Rate [TimeOut]] [/leaks] [/protect] [/no_sync
To disable page heap verification:
gflags /p [/disable ImageFile] [/?]
To display help:
glags /?
Parameters
Flag
Specifies a three-letter abbreviation (FlagAbbr) or hexadecimal value (FlagHex) that represents a debugging feature. The abbreviations and hexadecimal values are listed
in the GFlags Flag Table.
Use one of the following flag formats:
Format
{+ | -}
FlagAbbr
[+ | -]
FlagHex

Description
Sets (+) or clears (-) the flag represented by the flag abbreviation. Without a plus (+) or minus (-) symbol, the command has no effect.
Adds (+) or subtracts (-) the hexadecimal value of a flag. A flag is set when its value is included in the sum. Add (+) is the default. Enter a hexadecimal
value (without 0x) that represents a single flag or enter the sum of hexadecimal values for multiple flags.

ImageFile
Specifies the name of an executable file, including the file name extension (for example, notepad.exe or mydll.dll).
/r
Registry. Displays or changes system-wide debugging flags stored in the registry. These settings take effect when you restart Windows and remain effective until you
change them.
With no additional parameters, gflags /r displays the system-wide flags set in the registry.
/k
Kernel flag settings. Displays or changes system-wide debugging flags for this session. These settings are effective immediately, but are lost when Windows shuts down.
The settings affect processes started after this command completes.
With no additional parameters, gflags /k displays system-wide flags set for the current session.
/i
Image file settings. Displays or changes debugging flags for a particular process. These settings are stored in the registry. They are effective for all new instances of this
process and they remain effective until you change them.
With no additional parameters, gflags /i ImageFile displays the flags set for the specified process.
/tracedb SizeInMB
Sets the maximum size of the user-mode stack trace database for the process. To use this parameter, the Create user mode stack trace database (ust) flag must be set for
the process.
SizeInMB is a whole number representing the number of megabytes in decimal units. The default value is the minimum size, 8 MB; there is no maximum size. To revert
to the default size, set SizeInMB to 0.
spp
(Windows Vista and later.) Sets or clears the Special Pool feature. For an example, see Example 14: Configuring Special Pool.
PoolTag
(Windows Vista and later.) Specifies a pool tag for the Special Pool feature. Use only with the spp flag.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1056 of 1651

Enter a four-character pattern for PoolTag, such as Tag1. It can include the ? (substitute for any single character) and * (substitute for multiple characters) wildcard
characters. For example, Fat* or Av?4. Pool tags are always case-sensitive.
0xSize
(Windows Vista and later.) Specifies a size range for the Special Pool feature. Use only with the spp flag. For guidance on selecting a size value, see "Selecting an
Allocation Size" in Special Pool.
/ro
Enables, disables, and displays Object Reference Tracing settings in the registry. To make a change to this setting effective, you must restart Windows.
Without additional parameters, /ro displays the Object Reference Tracing settings in the registry.
To enable Object Reference Tracing, you must include at least one pool tag (/t PoolTag) or one image file (/i ImageFile) in the command. For details, see Example 15:
Using Object Reference Tracing.
The following table lists the subparameters that are valid with /ro.
/t PoolTags Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags.
Enter a four-character pattern for PoolTags, such as Tag1.
If you specify more than one pool tag, Windows traces objects with any of the specified pool tags .
If you do not specify any pool tags, Windows traces all objects that are created by the image.
/i
Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter.
ImageFile
Enter an image file name, such as notepad.exe, with up to 64 characters. "System" and "Idle" are not valid image names.
If you do not specify an image file, Windows traces all objects with the specified pool tags. If you specify both an image file (/i) and one or more pool tags
(/t), Windows traces objects with any of the specified pool tags that are created by the specified image.
/d
/p

Clears the Object Reference Tracing feature settings. When used with /ro, it clears the settings in the registry.
Permanent. The trace data is retained until Object Reference Tracing is disabled, or the computer is shut down or restarted. By default, the trace data for an
object is discarded when the object is destroyed.

/ko
Enables, disables, and displays kernel flag (run time) Object Reference Tracing settings. Changes to this setting are effective immediately, but are lost when the system is
shut down or restarted. For details, see Example 15: Using Object Reference Tracing.
Without additional parameters, /ko displays the kernel flag (run time) Object Reference Tracing settings.
To enable Object Reference Tracing, you must include at least one pool tag (/t PoolTag) or one image file (/i ImageFile) in the command.
The following table lists the subparameters that are valid with /ko.
/t PoolTags Limits the trace to objects with the specified pool tags. Use a semicolon (;) to separate tag names. Enter up to 16 pool tags.
Enter a four-character pattern for PoolTags, such as Tag1.
If you specify more than one pool tag, Windows traces objects with any of the specified pool tags.
If you do not specify any pool tags, Windows traces all objects that are created by the image.
/i ImageFile Limits the trace to objects that are created by processes with the specified image file. You can specify only one image file with the /i parameter.
If you do not specify an image file, Windows traces all objects with the specified pool tags.
If you specify both an image file (/i) and one or more pool tags (/t), Windows traces objects with any of the specified pool tags that are created by the
specified image.
/d
/p

/p
Sets page heap verification options for a process.
With no additional parameters, gflags /p displays a list of image files for which page heap verification is enabled.
Page heap verification monitors dynamic heap memory operations, including allocate operations and free operations, and causes a debugger break when it detects a heap
error.
/disable ImageFile
Turns off page heap verification (standard or full) for the specified image file.
This command is equivalent to turning off the Enable page heap (hpa) flag for a process (gflags /i ImageFile -hpa). You can use the commands interchangeably.
/enable ImageFile
Turns on page heap verification for the specified image file.
By default, the /enable parameter turns on standard page heap verification for the image file. To enable full page heap verification for the image file, add the /full
parameter to the command or use the /i parameter with the +hpa flag.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

Stop on exception
Stop on hung GUI

FLG_STOP_ON_EXCEPTION
FLG_STOP_ON_HUNG_GUI

0x1
0x8

soe
shg

R,K,I
K

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GFlags and PageHeap

This version of GFlags includes the functionality of PageHeap (pageheap.exe), a tool that enables heap allocation monitoring in Windows. PageHeap enables Windows
features that reserve memory at the boundary of each allocation to detect attempts to access memory beyond the allocation.
The page heap options in GFlags let you select standard heap verification, which writes fill patterns at the end of each heap allocation and examines the patterns when the
allocations are freed, or full-page heap verification, which places an inaccessible page at the end of each allocation so that the program stops immediately if if accesses
memory beyond the allocation. Because full heap verification uses a full page of memory for each allocation, its widespread use can cause system memory shortages.

To enable standard page heap verification for all processes, use gflags /r +hpa or gflags /k +hpa.
To enable standard page heap verification for one process, use gflags /p /enable ImageFileName.
To enable full page heap verification for one process, use gflags /i ImageFileName +hpa or gflags /p /enable ImageFileName /full.

All page heap settings, except for /k, are stored in the registry and remain effective until you change them.
Use care in interpreting the Enable page heap check box for an image file in the GFlags dialog box. It indicates that page heap verification is enabled for an image file, but it
does not indicate whether it is full or standard page heap verification. If the check results from selecting the check box, then full page heap verification is enabled for the
image file. However, if the check results from use of the command-line interface, then the check can represent the enabling of either full or standard page heap verification for
the image file.
To determine whether full or standard page heap verification is enabled for a program, at the command line, type gflags /p. In the resulting display, traces indicates that
standard page heap verification is enabled for the program and full traces indicates that full page heap verification is enabled for the program.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1060 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Global Flags Dialog Box

You can use the Global Flags dialog box to set and clear global flags from a user interface that lists all flags by name. There is no need to look up flag abbreviations or
hexadecimal values.
Also, the dialog box provides access to the following features that are not available from the command line:

Debugger Specifies that a particular program always runs in a debugger.

Launch Runs a program with the specified debugging settings.
Kernel Special Pool Tag Configures the Special Pool feature.

This topic includes instructions for the following procedures:

Opening the Dialog Box
Setting and Clearing System-wide Flags
Setting and Clearing Kernel Flags
Setting and Clearing Image File Flags
Launching a Program with Flags
Running a Program in a Debugger
Configuring Special Pool
Configuring Object Reference Tracing
Pool tagging is permanently enabled on Windows Server 2003 and later versions of Windows. On these systems, the Enable pool tagging check box on the Global Flags
dialog box is dimmed, and commands to enable or disable pool tagging fail.
Use care in interpreting the Enable page heap check box for an image file in the Global Flags dialog box. This check box indicates that page heap verification is enabled for
an image file, but it does not indicate whether it is full or standard page heap verification. If the check results from selecting the check box, then full page heap verification is
enabled for the image file. However, if the check results from use of the command-line interface, then the check can represent the enabling of either full or standard page heap
verification for the image file.
To determine whether a full or standard page heap verification is enabled for a program, at the command line, type gflags /p. In the resulting display, traces indicates that
standard page heap verification is enabled for the program and full traces indicates that full page heap verification is enabled for the program.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Opening the Dialog Box

To open the Global Flags dialog box

Double-click the gflags.exe icon or, at the command line, or in the Run dialog box, type gflags (without parameters).
- OR

Click Start, point to All Programs, point to Debugging Tools for Windows, and then click Global Flags.
On Windows Vista, click Start, click All Programs, click Debugging Tools for Windows, right-click Global Flags and then click Run as administrator. If you omit
this step, Windows displays the System Registry Gflags Error: 5. The Gflags dialog box opens, but Gflags commands fail.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting and Clearing System-wide Flags

System-wide registry settings affect all processes running on Windows. They are saved in the registry and remain effective until you change them.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1061 of 1651

To set and clear system-wide registry flags

1. Click the System Registry tab.

The following illustration shows the System Registry tab on Windows Vista.
2. Set or clear a flag by selecting or clearing the check box associated with the flag.
3. When you have selected or cleared all of the flags that you want, click Apply.
4. Restart Windows to make the changes effective.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting and Clearing Kernel Flags

Kernel flag settings, also known as "run-time settings," affect the entire system. They take effect immediately without rebooting, but they are lost if you shut down or restart
the system.
Kernel settings take precedence over registry settings during run time, but when you shut down or restart the system, the kernel flag settings are lost and the registry settings
are effective again.
To set and clear kernel flags
1. Click the Kernel Flags tab.
The following illustration shows the Kernel Flags tab on Windows Vista.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1062 of 1651

2. Set or clear a flag by selecting or clearing the check box associated with the flag.
3. When you have selected or cleared all of the flags that you want, click Apply.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting and Clearing Image File Flags

Image file settings affect instances of the specified program that start after the command completes. They are saved in the registry and remain effective until you change them.
To set and clear the image file registry flags
1. Click the Image File tab.
The following illustration shows the Image File tab on Windows Vista.

2. In the Image box, type the name of an executable file or DLL, including the file name extension,and then press the TAB key.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1063 of 1651

This activates the check boxes on the Image File tab.

3. Set or clear a flag by selecting or clearing the check box associated with the flag.
4. When you have selected or cleared all of the flags you want, click Apply.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Launching a Program with Flags

This feature runs a program once with the specified flags. These settings affect only the instance of the program launched. They are not saved in the registry.
To launch a program with flags
1. Click the Image File tab.
2. In the Image box, type the name of an executable file or DLL, including the file name extension, and any commands for the program, and then press the TAB key.
This activates the Launch button and the check boxes on the Image File tab.
3. Set or clear a flag by selecting or clearing the check box associated with the flag.
4. Click the Launch button.
The following illustration shows the Launch button on the Image File tab on Windows Vista.

Notes Flags set in the registry do not affect the instance of the program that is launched.
Flags set in the dialog box are used for the launched instance even when they are not image file flags.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Running a Program in a Debugger

This feature configures the program so that it always runs in a debugger with the specified options. This setting is saved in the registry. It affects all new instances of the
program and remains effective until you change it.
To run a program in a debugger
1. Click the Image File tab.
2. In the Image box, type the name of an executable file or DLL, including the file name extension,and then press the TAB key.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1064 of 1651

This activates the check boxes on the Image File tab.

3. Click the Debugger check box to select it.
The following illustration shows the Debugger check box on the Image File tab in Windows Vista.

4. In the Debugger box, type the command to run the debugger, including the path (optional) and name of the debugger and parameters. For example, ntsd -d -g -G -x or
c:\debuggers\cdb.exe -g -G.
5. Click Apply.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Special Pool

The Gflags Special Pool feature directs Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is
within a specified size range.
For detailed information about this feature, see Special Pool.
In Windows Vista and later versions of Windows, you can configure the Special Pool feature as a system-wide registry setting or as a kernel flags setting that does not require
a reboot. In earlier versions of Windows, Special Pool is available only as a registry setting.
In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see GFlags Commands.
This section includes the following topics.
Requesting Special Pool by Pool Tag
Requesting Special Pool by Allocation Size
Canceling Requests for Special Pool
Detecting Overruns and Underruns
Note Use Driver Verifier to request special pool for allocations by a particular driver. For more information, see the "Special Pool" topic in the "Driver Verifier" section of
the Windows Driver Kit (WDK).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1065 of 1651

Requesting Special Pool by Pool Tag

You can request special pool for all allocations that use a specified pool tag. Only one pool tag on the system can be associated with kernel special pool requests at one time.
In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see GFlags Commands.
To request special pool by pool tag
1. Select the System Registry tab or the Kernel Flags tab.
On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the System Registry
tab.
2. In the Kernel Special Pool Tag section, click Text, and then type a four-character pattern for the tag.
The tag can include the ? (single character) and * (multiple characters) wildcard characters. For example, Fat* or Av?4.
3. The following illustration shows a tag entered as text on the System Registry tab.

4.
5. Click Apply.
When you click Apply, GFlags changes the selection from Text to Hex and displays the ASCII characters as hexadecimal values in reverse (lower endian) order. For
example, if you type Tag1, GFlags displays the tag as 0x31676154 (1gaT). This is the way that it is stored in the registry and displayed by the debugger and other tools.
The following illustration shows the effect of clicking Apply.

Comments
To use this feature effectively, make sure that your driver or other kernel-mode program uses a unique pool tag. If you suspect that your driver is consuming all of the special
pool, consider using multiple pool tags in your code. You can then test your driver several times, assigning special pool to one pool tag in each test.
Also, select a pool tag with a hexadecimal value that is greater than the page size of the system. For kernel mode code, if you enter a pool tag that has a value less than
PAGE_SIZE, Gflags requests special pool for all allocations whose size is within the corresponding range and requests special pool for allocations with an equivalent pool
tag. For example, if you select a size of 30, special pool will be used for all allocations between 17 and 32 bytes in size, and for allocations with the pool tag 0x0030.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Requesting Special Pool by Allocation Size

You can request special pool for allocations within a specified size range.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1066 of 1651

In Windows Vista and later versions of Windows, you can also use the command line to request special pool by pool tag. For information, see GFlags Commands.
Note This method is rarely useful for diagnosing driver errors, because it affects all kernel pool requests of the specified size, regardless of which driver or kernel module
requested the allocation.
To request special pool by allocation size
1. Select the System Registry tab or the Kernel Flags tab.
On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the System Registry
tab.
2. In the Kernel Special Pool Tag section, click Hex, and then type a number in hexadecimal format that represents a range of sizes. All allocations within this size range
will be allocated from special pool. This number must be less than PAGE_SIZE.
3. Click Apply.
The following illustration shows an allocation size entered as a hexadecimal value.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Canceling Requests for Special Pool

You can use GFlags to cancel a request for allocation from the special pool if the request was made by using GFlags. You cannot use GFlags to cancel a request for special
pool that was made by using Driver Verifier.
In Windows Vista and later versions of Windows, you can also use the command line to cancel special pool requests. For information, see GFlags Commands.
To cancel requests for special pool
1. Select the System Registry tab or the Kernel Flags tab.
On Windows Vista and later versions of Windows, this option is available on both tabs. On earlier versions of Windows, it is available only on the System Registry
tab.
2. Delete the text or hexadecimal value from the Kernel Special Pool Tag box.
3. Click Apply.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1067 of 1651

Detecting Overruns and Underruns

You can use the Verify Start or Verify End option in GFlags to align allocations from the special pool so that they are best suited to detect overruns (accessing memory past
the end of the allocation) or underruns (accessing memory that precedes the beginning of the allocation).

Verify Start enables underrun detection on allocations from the special pool. This causes a bug check when a program tries to access memory preceding its special pool
memory allocation.
Verify End enables overrun detection on allocations from the special pool. This causes a bug check when a program tries to access memory beyond its special pool
memory allocation. Because overruns are much more common, Verify End is the default.

In Windows Vista and later versions of Windows, this option is available on the System Registry and Kernel Flags tabs. In earlier versions of Windows, it is available only
on the System Registry tab.
To specify special pool alignment:
1. Click the System Registry tab.
2. Click Verify Start or Verify End.
3. Click Apply.
The following illustration shows the Verify Start and Verify End settings on the System Registry tab.

Comments
The Verify Start and Verify End alignment settings apply to all allocations from the special pool, including special pool allocation requests set in Driver Verifier. If you set
the alignment without specifying a pool tag or allocation size, then the settings apply only to requests set in Driver Verifier.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Configuring Object Reference Tracing

You can use Gflags to enable, disable, and configure the Object Reference Tracing feature of Windows. Object Reference Tracing records sequential stack traces whenever an
object reference counter is incremented or decremented. The traces can help you to detect object reference errors, including double-dereferencing, failure to reference, and
failure to dereference objects. This feature is supported only in Windows Vista and later versions of Windows. For detailed information about this feature, see Object
Reference Tracing.
To enable Object Reference Tracing
1. In the Gflags dialog box, select the System Registry tab or the Kernel Flags tab.
2. In the Object Reference Tracing section, select Enable.
You must limit the trace to objects with specified pool tags, to objects created by a specified process, or both.
3. To limit the trace to objects with a particular pool tag, type the pool tag name. To list multiple pool tags, use semicolons (;) to separate the pool tags. When you list
multiple pool tags, the trace includes objects with any of the specified pool tags. Pool tags are case sensitive.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1068 of 1651

For example, Fred;Tag1.

4. To limit the trace to objects that are created by a particular process, type the image name of the process. You can specify only one image file name.
When you specify both pool tags and a process, the trace includes objects that are created by the process that have any of the specified pool tags.
5. To retain the trace after the trace object is destroyed, select Permanent.
When you select Permanent, the trace is retained until you disable object reference tracing, or shut down or restart Windows.
6. Click Apply or OK.
The following illustration shows Object Reference Tracing enabled on the Kernel Flags tab. This trace will include only objects that were created by the notepad.exe process
that have the pool tag Fred or Tag1. Because this is a run time (kernel flags) setting, the trace starts immediately. If it were a registry setting, you would have to restart
Windows to start the trace.

To disable Object Reference Tracing

1. In the Gflags dialog box, select the System Registry tab or the Kernel Flags tab. Object Reference Tracing will appear on the latter tab only in Windows Vista and
later versions of Windows.
2. In the Object Reference Tracing section, clear the Enable check box.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GFlags Examples
The following examples show how to submit GFlags commands and how to use GFlags features in practical scenarios.
This section includes the following topics.
Example 1: Displaying Global Flags
Example 2: Setting a Flag by Using a Flag Abbreviation
Example 3: Setting a Flag by Using Its Hexadecimal Value
Example 4: Setting Multiple Flags
Example 5: Clearing a Flag
Example 6: Clearing All Flags
Example 7: Clearing All Flags for an Image File
Example 8: Enlarging the User-Mode Stack Trace Database

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1069 of 1651

Example 9: Detecting a Pool Memory Leak

Example 10: Detecting a Heap Memory Leak in a Process
Example 11: Enabling Page Heap Verification
Example 12: Using Page Heap Verification to Find a Bug
Example 13: Listing Image Files with Global Flags
Example 14: Configuring Special Pool
Example 15: Using Object Reference Tracing
The examples in the second section apply to features available only in Windows Vista and later versions of Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 1: Displaying Global Flags

The commands demonstrated in this example display the system-wide flags set in the registry, the system flags set for the session (kernel mode), and the flags set for an image
file.
The following GFlags command displays the current value of the system-wide flags set in the registry. It uses the /r parameter to specify the system-wide registry entry.
gflags /r
In response, GFlags displays a single hexadecimal value representing the sum of all flags set and a list of the flags set.
Current
ptg
ust
bhd

Boot Registry Settings are: 40001400

- Enable pool tagging
- Create user mode stack trace database
- Enable bad handles detection

In this example, the results show that there are three tags set, with a combined value of 0x40001400.

Enable pool tagging (ptg) = 0x400

Create user mode stack trace database (ust) = 0x1000
Enable bad handles detection (bhd) = 0x40000000

The following command displays the flags set for the current session. It uses the /k parameter to indicate kernel mode.
gflags /k
The following command displays flags set in the registry for the image file notepad.exe. It uses the /i parameter to indicate image file mode and specifies the image file.
gflags /i notepad.exe
Remember that the flag value displayed might not be the current, effective flag value. Changes to the system-wide flags are not effective until you restart Windows. Changes
to image file flag settings are not effective until you restart the program.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 2: Setting a Flag by Using a Flag Abbreviation

The following command sets the Show loader snaps flag for the notepad.exe image file. Show Loader Snaps takes snapshots of the load process, capturing in detail the
loading and unloading of executable images and their supporting library modules.
The command uses the /i parameter to indicate image file mode and specifies the name of the image file notepad.exe. To identify the flag, the command uses sls, the
abbreviation for Show Loader Snaps, and it precedes the abbreviation with a plus sign (+) to indicate that the flag is set. Without the plus sign, the command has no effect.
gflags /i notepad.exe +sls
In response, GFlags displays the flags set for notepad.exe. The display indicates that the command is successful. The Show Loader Snaps feature is enabled for all new
sessions of the Notepad program.
Current Registry Settings for notepad.exe executable are: 00000002
sls - Show Loader Snaps

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1070 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 3: Setting a Flag by Using Its Hexadecimal Value

The following command sets the system-wide Enable page heap flag. Enable Page Heap adds a guard page and other tracking features to each heap allocation.
The command uses the /r parameter to indicate system-wide registry mode. To identify the flag, the command uses 2000000, which represents 0x2000000, the hexadecimal
value for Enable page heap.
Although the command sets a flag, it omits the plus (+) sign. When using hexadecimal values, the sign is optional and add (+) is the default.
gflags /r 2000000
In response, GFlags displays the system-wide flags set in the registry. The display indicates that the command is successful. The Enable page heap feature will be enabled for
all processes when Windows restarts.
Current Boot Registry Settings are: 02000000
hpa - Enable page heap

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 4: Setting Multiple Flags

The following command sets these three flags for the current session:

Enable heap free checking (hfc, 0x20)

Enable heap parameter checking (hpc, 0x40)
Enable heap validation on call (hvc, 0x80)

This command uses the /k parameter to specify kernel mode (session only). It sets the value for kernel mode to E0 (0xE0), the sum of the hexadecimal values of the selected
flags (0x20 + 0x40 + 0x80).
gflags /k e0
In response, GFlags displays the revised value of flags set for the session. The display indicates that the command is successful and that the three flags specified in the
command are set.
Current
hfc
hpc
hvc

Running Kernel Settings are: 000000e0

- Enable heap free checking
- Enable heap parameter checking
- Enable heap validation on call

You can use several different GFlags commands to set flags. Each of the following commands has the same effect as the command used in this example and the methods can
be used interchangeably:
gflags /k +20 +40 +80
gflags /k +E0
gflags /k +hfc +hpc +hvc
Kernel (run time) flags are effective immediately and remain effective until Windows shuts down.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 5: Clearing a Flag

The following command clears the system-wide Enable page heap flag set in the registry. The command uses the /r parameter to indicate the system-wide registry mode and
hpa, the abbreviation for the Enable page heap flag. The minus sign (-) indicates that the flag is to be cleared.
gflags /r -hpa

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1071 of 1651

In response, GFlags displays the current value of the system-wide registry entry. The display indicates that the command is successful and that there are no longer any flags
set.
Current Boot Registry Settings are: 00000000
Note that the following command, which uses the hexadecimal value of the Enable Page Heap flag, has the same effect as the command used in this example. These
commands can be used interchangeably:
gflags /r -02000000

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 6: Clearing All Flags

This example demonstrates two different ways to clear all flags set in the registry and for the session:

Subtract the current flag value.

Subtract high values.

Note The methods demonstrated by this example clear flags only. They do not reset the maximum stack trace size or kernel special pool tag to the default values.

Subtract the Current Flag Value

The following command clears all flags set in the system-wide flag entry in the registry by subtracting the current value of the entry. In this example, the current value is
0xE0. The command uses the /r parameter to indicate the system-wide registry mode and the E0 value with a minus sign (-) to subtract E0 from the flag value.
gflags /r -E0
In response, GFlags displays the revised value of system-wide flag registry entry. A value of zero indicates that the command is successful and that there are no longer any
system-wide flags set in the registry.
Current Boot Registry Settings are: 00000000
Note that the following commands have the same effect as the command used in this example and can be used interchangeably:
gflags /r -20 -40 -80
gflags /r -hfc -hpc -hvc

Subtract High Values

The following command clears all system-wide flags by subtracting high values (0xFFFFFFFF) from the system-wide flag setting.
gflags /r -ffffffff
In response, GFlags displays the revised value of the system-wide flag entry. A value of zero indicates that the command is successful and that there are no longer any systemwide flags set in the registry.
Current Boot Registry Settings are: 00000000
Tip Type this command into Notepad, then save the file as clearflag.bat. Thereafter, to clear all flags, just type ClearFlag.
Finally, the following example demonstrates that the intuitive method of clearing all flags does not work.
The following command appears to set the value of the system-wide flag entry to 0. However, it actually adds zero to the system-wide flag value. In this example, the current
value of the system-wide flag entry is 0xE0.
gflags /r 0
In response, GFlags displays the system-wide flag value after the command completes:
Current
hfc
hpc
hvc

Boot Registry
- Enable heap
- Enable heap
- Enable heap

Settings are: 000000e0

free checking
parameter checking
validation on call

The command has no effect because it adds the value 0 to system-wide flag entry.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1072 of 1651

Debugging Tools for Windows

Example 7: Clearing All Flags for an Image File

The following command clears all flags and image debugger options for an image file. The command adds high-values (0xFFFFFFFF) to the current flag value. GFlags
responds by deleting the GlobalFlag registry entry for the image file, thereby deleting all of the values it stores.
This command does not affect flags set in the system-wide GlobalFlag registry entry or flags set for the session (kernel mode).
gflags /i notepad.exe ffffffff
In response, GFlags displays a message indicating that there are no flags set for the image file:
No Registry Settings for notepad.exe executable

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 8: Enlarging the User-Mode Stack Trace Database

The following GFlags command increases the maximum size of the user-mode stack trace database for myapp.exe, a fictitious program, from 8 MB to 24 MB.
The command uses the /i parameter to specify the image file. It uses the /tracedb parameter to set the maximum stack trace database size and the value 24 to indicate the size
in megabytes. The command uses decimal units. (Hexadecimal units are not valid.)
gflags /i MyApp.exe /tracedb 24
As the following error message indicates, this command fails because the Create user mode stack trace database (+ust) flag is not set for the MyApp image file. You cannot
set the size of a trace database until you create one.
Failed to set the trace database size for `MyApp.exe'
The following commands fix the error. The first command creates a trace database for myapp.exe and the second command sets the maximum size of the trace database to 24
MB. These commands cannot be combined into a single command. The following display shows the commands and the success message from GFlags.
gflags /i MyApp.exe +ust
Current Registry Settings for MyApp.exe executable are: 00001000
ust - Create user mode stack trace database
gflags /i MyApp.exe /tracedb 24
Trace database size for `MyApp.exe' set to 24 Mb.
GFlags can change the size of the user-mode stack trace database, but it does not display it. To display the trace database size, use registry APIs, Regedit, or Reg (reg.exe), a
tool included in Windows XP and Windows Server 2003, to check the value of the StackTraceDatabaseSizeInMB registry entry (HKLM\Software\Microsoft\Windows
NT\CurrentVersion\Image File Execution Options\ImageFileName\StackTraceDatabaseSizeInMB).
(A version of Reg is included in Windows XP, but that version does not permit the /v and /s switches in the same command.)
The following command uses Reg to query the value of StackTraceDatabaseSizeInMB:

reg query "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\MyApp.exe" /v StackTraceDatabaseSizeInM

In response, Reg displays the value of StackTraceDatabaseSizeInMB, which confirms that the new value, 24 (0x18), was set. This value becomes effective when you restart
myapp.exe.
! REG.EXE VERSION 3.0
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\MyApp.exe
StackTraceDatabaseSizeInMB REG_DWORD
0x18
Tip Type the reg query command into Notepad, then save the file as tracedb.bat. Thereafter, to display the value of StackTraceDatabaseSizeInMB, just type TraceDb.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1073 of 1651

Example 9: Detecting a Pool Memory Leak

The following example uses GFlags to set the system-wide Enable pool tagging flag in the registry. Then, it uses PoolMon (poolmon.exe), a tool in the Windows Driver Kit,
to display the size of the memory pools.
PoolMon monitors the bytes in the paged and nonpaged memory pools and sorts them by pool tag. By running PoolMon periodically, you can identify pools that expand
continuously over time. This pattern often indicates a memory leak.
Notes Pool tagging is permanently enabled in Windows Server 2003 and later versions of Windows. On these systems, the Enable pool tagging check box on the Global
Flags dialog box is dimmed, and commands to enable or disable pool tagging fail.
If pool tagging is not enabled, PoolMon fails and displays the following message: "Query pooltags Failed c0000002."
To detect a pool memory leak
1. To enable pool tagging for all processes in versions of Windows earlier than Windows Server 2003, set the system-wide Enable pool tagging flag in the registry. The
following command line uses the flag abbreviation method, but you can identify the flag by its hexadecimal value or use the Global Flags dialog box:
gflags /r +ptg
2. Restart the computer to make the registry change effective.
3. Run PoolMon periodically by using the following command. In this command, the /b parameter sorts the pools in descending size order.
poolmon /b
In response, PoolMon displays allocations from the memory pools in descending size order , including the number of allocate operations and free operations, and the
amount of memory remaining in the pool (in the Bytes column).
Memory: 16224K Avail: 4564K PageFlts: 31 InRam Krnl: 684K P: 680K
Commit: 24140K Limit: 24952K Peak: 24932K Pool N: 744K P: 2180K
Tag Type
Allocs
Frees
Diff
Bytes
Per Alloc
----------------------------------------------------------------------CM
Strg
Fat
MmSt

Paged
Paged
Paged
Paged

1283
10385
6662
614

(
(
(
(

0)
10)
8)
0)

1002
6658
4971
441

(
(
(
(

0)
4)
6)
0)

281 1377312 (
3727 317952 (
1691 174560 (
173
83456 (

0) 4901
512)
85
128) 103
0) 482

If the value in the Bytes column for an allocation expands continuously for no obvious reason, there might be a memory leak in that pool.
4. Clear the Enable pool tagging flag.
The following command line uses the flag abbreviation method, but you can identify the flag by its hexadecimal value or use the Global Flags dialog box:
gflags /r -ptg
5. Restart Windows to make the registry change effective.
Note Use the append symbol (>>) to redirect the PoolMon output to a log file. Later, you can examine the log file for pool size trends. For example:
poolmon.exe /b >> poolmon.log

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 10: Detecting a Heap Memory Leak in a Process

This example uses GFlags and User Mode Dump Heap (UMDH, umdh.exe), a tool included in Microsoft Debugging Tools for Windows. For information about UMDH, see
the Debugging Tools Web site.
To detect a leak in heap memory in notepad.exe
1. Set the Create user mode stack trace database (ust) flag for the notepad.exe image file.
The following command uses GFlags to set the Create user mode stack trace database flag. It uses the /i parameter to identify the image file and the ust abbreviation
for the flag.
gflags /i Notepad.exe +ust
As a result of this command, a user-mode stack trace is created for all new instances of the Notepad process.
2. Set the symbol file path.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1074 of 1651

The following command creates an environment variable that stores the path to the directory of symbol files:
set _NT_SYMBOL_PATH=C:\Windows\symbols
3. Start Notepad.
4. Find the process identifier (PID) of the Notepad process.
You can find the PID of any running process from Task Manager or Tasklist (tasklist.exe), a tool included in Windows XP Professional and Windows Server 2003
operating systems. In this example, the Notepad PID is 1228.
5. Run UMDH.
The following command runs UMDH (umdh.exe). It uses the -p: parameter to specify the PID that, in this example, is 1228. It uses the /f: parameter to specify the name
and location of the output file for the heap dump, notepad.dmp.
umdh -p:1228 -f:notepad.dmp
In response, UMDH writes a complete dump of all active heaps to the notepad.dmp file.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 11: Enabling Page Heap Verification

The following commands enable full and standard page heap verification for myapp.exe, a fictitious program.
The first command enables standard page heap verification for myapp.exe. It uses the /p parameter to enable page heap for a process. By default, /p enables standard page
heap.
gflags /p /enable myapp.exe
The following commands enable full page heap verification for the myapp.exe program. Although these commands create different settings in the registry, they are all
functionally equivalent to selecting the Enable page heap check box for the myapp.exe image file in the Global Flags dialog box. These methods can be used
interchangeably.
gflags /p /enable myapp.exe /full
gflags /i myapp.exe +hpa
gflags /i myapp.exe +02000000
The following commands disable full or standard page heap verification for the myapp.exe program, regardless of the command or dialog box method used to enable page
heap verification.
gflags /p /disable myapp.exe
gflags /i myapp.exe -hpa
gflags /i myapp.exe -02000000
Note When using the /debug or /kdebug parameters, use the /p /disable parameters to turn off the page heap verification (not the /i -hpa parameters). The /p /disable
parameters disable page heap verification and delete registry entries that the debugger reads.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 12: Using Page Heap Verification to Find a Bug

The following series of commands demonstrates how to use the page heap verification features of GFlags and the NTSD debugger to detect an error in heap memory use. In
this example, the programmer suspects that a fictitious application, pheap-buggy.exe, has a heap error, and proceeds through a series of tests to identify the error.
For details on NTSD, see CDB and NTSD.

Step 1: Enable standard page heap verification

The following command enables standard page heap verification for pheap-buggy.exe:
gflags /p /enable pheap-buggy.exe

Step 2: Verify that page heap is enabled

The following command lists the image files for which page heap verification is enabled:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1075 of 1651

gflags /p
In response, GFlags displays the following list of programs. In this display, traces indicates standard page heap verification, and full traces indicates full page heap
verification. In this case, pheap-buggy.exe is listed with traces, indicating that standard page heap verification is enabled, as intended.
pheap-buggy.exe: page heap enabled with flags (traces )

Step 3: Run the debugger

The following command runs the CorruptAfterEnd function of pheap-buggy.exe in NTSD with the -g (ignore initial breakpoint) and -x (set second-chance break on access
violation exceptions) parameters:
ntsd -g -x pheap-buggy /CorruptAfterEnd
When the application fails, NTSD generates the following display, which indicates that it detected an error in pheap-buggy.exe:

===========================================================
VERIFIER STOP 00000008: pid 0xAA0: corrupted suffix pattern
00C81000 : Heap handle
00D81EB0 : Heap block
00000100 : Block size
00000000 :
===========================================================
Break instruction exception - code 80000003 (first chance)
eax=00000000 ebx=00d81eb0 ecx=77f7e257 edx=0006fa18 esi=00000008 edi=00c81000
eip=77f7e098 esp=0006fc48 ebp=0006fc5c iopl=0
nv up ei pl zr na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000
efl=00000246
ntdll!DbgBreakPoint:
77f7e098 cc
int
3
The header information includes the address of the heap with the corrupted block (00C81000 : Heap handle), the address of the corrupted block (00D81EB0 : Heap block),
and the size of the allocation (00000100 : Block size).
The "corrupted suffix pattern" message indicates that the application violated the data integrity pattern that GFlags inserted after the end of the pheap-buggy.exe heap
allocation.

Step 4: Display the call stack

In the next step, use the addresses that NTSD reported to locate the function that caused the error. The next two commands turn on line number dumping in the debugger and
display the call stack with line numbers.
C:\>.lines
Line number information will be loaded
C:\>kb
ChildEBP
WARNING:
0006fc5c
0006fcd8
0006fcfc
0006fd4c
0006fdc0
0006fe78
0006ff24
0006ff3c
0006ff4c
0006ffc0
0006fff0

RetAddr Args to Child

Stack unwind information not available. Following frames may be wrong.
77f9e6dd 00000008 77f9e3e8 00c81000 ntdll!DbgBreakPoint
77f9f3c8 00c81000 00000004 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x2879
77f9f5bb 00c81000 01001002 00000010 ntdll!RtlpNtEnumerateSubKey+0x3564
77fa261e 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x3757
77fc0dc2 00c80000 01001002 00d81eb0 ntdll!RtlpNtEnumerateSubKey+0x67ba
77fbd87b 00c80000 01001002 00d81eb0 ntdll!RtlSizeHeap+0x16a8
010013a4 00c80000 01001002 00d81eb0 ntdll!RtlFreeHeap+0x69
01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x2b [d:\nttest\base\testsrc\kernel\rtl\pageheap\phe
0100157f 00000002 00c65a68 00c631d8 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349]
00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204

As a result, the debugger displays the call stack for pheap-buggy.exe with line numbers. The call stack display shows that the error occurred when the TestCorruptAfterEnd
function in pheap-buggy.exe tried to free an allocation at 0x00c80000 by calling HeapFree, a redirect to RtlFreeHeap.
The most likely cause of this error is that the program wrote past the end of the buffer that it allocated in this function.

Step 5: Enable full page heap verification

Unlike standard page heap verification, full page heap verification can catch the misuse of this heap buffer as soon as it occurs. The following command enables full page
heap verification for pheap-buggy.exe:
gflags /p /enable pheap-buggy.exe /full

Step 6: Verify that full page heap is enabled

The following command lists the programs for which page heap verification is enabled:
gflags /p

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1076 of 1651

In response, GFlags displays the following list of programs. In this display, traces indicates standard page heap verification, and full traces indicates full page heap
verification. In this case, pheap-buggy.exe is listed with full traces, indicating that full page heap verification is enabled, as intended.
pheap-buggy.exe: page heap enabled with flags (full traces )

Step 7: Run the debugger again

The following command runs the CorruptAfterEnd function of pheap-buggy.exe in the NTSD debugger with the -g (ignore initial breakpoint) and -x (set second-chance
break on access violation exceptions) parameters:
ntsd -g -x pheap-buggy /CorruptAfterEnd
When the application fails, NTSD generates the following display, which indicates that it detected an error in pheap-buggy.exe:
Page heap: process 0x5BC created heap @ 00880000 (00980000, flags 0x3)
ModLoad: 77db0000 77e8c000
kernel32.dll
ModLoad: 78000000 78046000
MSVCRT.dll
Page heap: process 0x5BC created heap @ 00B60000 (00C60000, flags 0x3)
Page heap: process 0x5BC created heap @ 00C80000 (00D80000, flags 0x3)
Access violation - code c0000005 (first chance)
Access violation - code c0000005 (!!! second chance !!!)
eax=00c86f00 ebx=00000000 ecx=77fbd80f edx=00c85000 esi=00c80000 edi=00c16fd0
eip=01001398 esp=0006ff2c ebp=0006ff4c iopl=0
nv up ei pl nz na po nc
cs=001b ss=0023 ds=0023 es=0023 fs=0038 gs=0000
efl=00000206
pheap-buggy!TestCorruptAfterEnd+1f:
01001398 889801010000
mov
[eax+0x101],bl
ds:0023:00c87001=??
With full page heap verification enabled, the debugger breaks at an access violation. To find the precise location of the access violation, turn on line number dumping and
display the call stack trace.
The numbered call stack trace appears as follows: The line displaying the problem appears in bold text.
ChildEBP
0006ff3c
0006ff4c
0006ffc0
WARNING:
0006fff0

RetAddr Args to Child

01001450 00000000 00000001 0006ffc0 pheap-buggy!TestCorruptAfterEnd+0x1f [d:\nttest\base\testsrc\kernel\rtl\pageheap\phe
0100157f 00000002 00c16fd0 00b70eb0 pheap-buggy!main+0xa9 [d:\nttest\base\testsrc\kernel\rtl\pageheap\pheap77de43fe 00000000 00000001 7ffdf000 pheap-buggy!mainCRTStartup+0xe3 [crtexe.c @ 349]
Stack unwind information not available. Following frames may be wrong.
00000000 0100149c 00000000 78746341 kernel32!DosPathToSessionPathA+0x204

The stack trace shows that the problem occurs in line 184 of pheap-buggy.exe. Because full page heap verification is enabled, the call stack starts in the program code, not in a
system DLL. As a result, the violation was caught where it happened, instead of when the heap block was freed.

Step 8: Locate the error in the code

A quick inspection reveals the cause of the problem: The program tries to write to the 257th byte (0x101) of a 256-byte (0x100) buffer, a common off-by-one error.
*((PCHAR)Block + 0x100) = 0;

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 13: Listing Image Files with Global Flags

GFlags displays the flags set for a particular image file, but it does not display all image files that have flags set.
Windows stores flags for an image file that the GlobalFlag registry entry in a registry subkey named for the image file in the following registry path,
HKEY_LOCAL_MACHINE\ SOFTWARE\ Microsoft\ Windows NT\ CurrentVersion\ Image File Execution Options\ ImageFileName\ GlobalFlag.
To determine which image files have flags set, use Reg (reg.exe), a tool included in Windows Server 2003.
The following Reg Query command searches for the GlobalFlag registry entry in the specified registry path. The -v parameter specifies the GlobalFlag registry entry. The /s
parameter makes the search recursive.
reg query "HKLM\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options" /v GlobalFlag /s
In response, Reg displays all instances of the GlobalFlag registry entry in the path and the value of the entry.
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\notepad.exe
GlobalFlag
REG_SZ
0x00001000
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\photohse.EXE
GlobalFlag
REG_SZ
0x00200000
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\printhse.EXE

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

GlobalFlag

Page 1077 of 1651

REG_SZ

0x00200000

Tip Type the Reg command into Notepad, then save the file as imageflags.bat. Thereafter, to find image files for which flags have been set, just type ImageFlags.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 14: Configuring Special Pool

Beginning in Windows Vista, you can configure the Special Pool feature as a kernel flag setting or as a registry setting. If you configure it as a kernel flag (run time) setting,
you do not need to restart the computer to make the change effective. In earlier versions of Windows, Special Pool is available only as a registry setting.
Also, beginning in Windows Vista, you can set and configure the Special Pool feature from the command line. In earlier versions of Windows, you can set and configure the
Special Pool feature only in the Global Flags dialog box.
Request Special Pool by pool tag without rebooting
The following command requests special pool for all allocations with the Tag1 pool tag. This setting becomes effective immediately, but it is lost if you shut down or restart
Windows.
This command uses the /k parameter to specify a kernel flag (run time) setting and the +spp abbreviation to set a special pool request.
gflags /k +spp Tag1
Gflags responds by printing:
Special Pool set to 0x31676154
PoolTagOverruns set to 0x1
Current Running Kernel Settings are: 00000000
Notice that the special pool allocation request is not a kernel flag setting and is not reflected in the kernel settings value.
Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to
underruns, use the Gflags Dialog Box. For information, see Detecting Overruns and Underruns.
You cannot display the pool tag at the command line. To verify that the pool tag is a kernel setting, use the Gflags Dialog Box.
Request Special Pool by pool tag in the registry
The following command requests special pool for all allocations with the Tag1 pool tag. Because this setting is stored in the registry, you must restart the computer to make it
effective, but it remains effective until you change it.
This command uses the /r parameter to specify a registry setting and the +spp abbreviation to set a special pool request.
gflags /r +spp Tag1
Gflags responds by printing:
Special Pool set to 0x31676154
PoolTagOverruns set to 0x1
Current Boot Registry Settings are: 00000000
Notice that the special pool allocation request is not a registry flag setting and is not reflected in the registry settings value.
Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to
underruns, use the Gflags Dialog Box. For information, see Detecting Overruns and Underruns.
To verify that the value has been added to the registry, use Reg or Regedit to display the value of the PoolTag entry in the
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management key.
For example:
c:>reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" -v PoolTag
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management
PoolTag
REG_DWORD
0x31676154
Request Special Pool by size without rebooting
The following command requests special pool for allocations of 1 to 8 bytes on an x86 computer with a PAGE_SIZE of 0x1000 and allocation granularity of 8 bytes.
This command uses the /k parameter to specify a kernel flag (run time) setting and the +spp abbreviation to set a special pool request. The size value is preceded by 0x to
indicate that it is a size and not a pool tag.
The value, 0x10, is calculated by adding the allocation granularity (8 bytes) to the largest size in the range (8 bytes) for a total of 16 bytes (0x10). For help in determining the
correct value to enter, see "Selecting an Allocation Size" in Special Pool.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1078 of 1651

gflags /k +spp 0x10

Gflags responds by printing:
Special Pool set to 0x10
PoolTagOverruns set to 0x1
Current Running Kernel Settings are: 00000000
Again, the special pool allocation request is not a kernel flag setting and is not reflected in the kernel settings value.
Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to
underruns, use the Gflags Dialog Box. For information, see Detecting Overruns and Underruns.
Request Special Pool by size in the registry
The following command requests special pool for allocations of 1024 to 1040 bytes on an x64 computer with a PAGE_SIZE of 0x1000 and allocation granularity of 16 bytes.
This command uses the /r parameter to specify a system-wide registry setting and the +spp abbreviation to set a special pool request. The size value is preceded by 0x to
indicate that it is a size and not a pool tag.
The value, 0x420, is calculated by adding the allocation granularity (16 bytes) to the largest size in the range (1040 bytes) for a total of 1056 bytes (0x420). For help in
determining the correct value to enter, see "Selecting an Allocation Size" in Special Pool.
gflags /r +spp 0x420
Gflags responds by printing:
Special Pool set to 0x420
PoolTagOverruns set to 0x1
Current Boot Registry Settings are: 00000000
Again, the special pool allocation request is not a registry flag setting and is not reflected in the registry settings value.
Also, a special pool allocation request does not change the value of the overrun (0x1) or underrun (0x0) setting for special pool. To change from overruns, the default, to
underruns, use the Gflags Dialog Box. For information, see Detecting Overruns and Underruns.
To verify that the value has been added to the registry, use Reg or Regedit to display the value of the PoolTag entry in the
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management key.
For example:
c:>reg query "HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management" -v PoolTag
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management
PoolTag
REG_DWORD
0x420
Cancel a Special Pool Request
The following command cancels a request for Special Pool as a kernel flag (run time) setting. The command is the same for a request by pool tag or by size.
gflags /k -spp
The following command cancels a request for Special Pool as a registry setting. The command is the same for a request by pool tag or by size.
gflags /r -spp
When the command is successful, Gflags responds by printing:
Special Pool value has been deleted.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Example 15: Using Object Reference Tracing

Object Reference Tracing is a Windows feature that records a sequential stack trace when an object is referenced or dereferenced. It is designed to detect errors in object
handling that can lead to crashes or memory leaks. Some of these errors are difficult to detect because they do not appear consistently. For detailed information, see Object
Reference Tracing.
You can configure Object Reference Tracing by using the Global Flags dialog box or at a command prompt. The following examples use the command prompt. For
information about using the Global Flags dialog box to configure Object Reference Tracing, see Configuring Object Reference Tracing.
You can use Gflags to enable, disable, and configure Object Reference Tracing. The process is as follows:

Use Gflags to enable Object Reference Tracing in the registry or as a kernel flag (run time) setting. If you add the setting to the registry, you must restart the
computer to start tracing. If you enable the run time version of the settings, the trace starts immediately, but the trace settings revert to those in the registry key when

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1079 of 1651

you shut down or restart the computer.

Start the process that creates the suspect object. The trace includes only objects created by processes that are started after the trace begins. If the process starts during
or soon after restarting, add the trace settings to the registry, and then restart the system.
Use the !obtrace debugger extension to view the trace. By default, the trace is maintained until the object is destroyed, but you can use the /p parameter to maintain
the trace until tracing is disabled.
Use Gflags to disable Object Reference Tracing.in the registry or as a kernel flag (run time) setting. If you delete the setting from the registry, you must restart the
computer to end tracing. If you disable the run time version of the settings, the trace ends immediately, but the trace settings revert to those in the registry when you shut
down or restart the computer.

These examples show how to use Gflags to enable and disable object reference tracing. \
Enable Run-time Tracing
The following command enables Object Reference Tracing at the command prompt. The command uses the /ko parameter to enable Object Reference Tracing as a kernel flag
(run time) setting. The command uses the /t parameter to specify the pool tags Tag1 and Fred. As a result, all objects that are created with Tag1 or Fred are traced.
gflags /ko /t Tag1;Fred
Because the command changes the kernel flag (run-time) settings, object reference tracing starts immediately. The trace will include all objects with the pool tags Tag1 or
Fred that are created by processes that start after the command is submitted.
Gflags responds by printing the following message:
Running Kernel Settings :
Object Ref Tracing Enabled
Temporary Traces
Pool Tags: Tag1;Fred
Process Name: All Processes
This message indicates that Object Reference Tracing is enabled. "Temporary Traces" indicates that all records of the trace are deleted when the object is destroyed. To make
the trace "permanent," use the /p parameter, which directs Windows to retain the trace data until Object Reference Tracing is disabled, or the computer is shut down or
restarted.
Enable Tracing in the Registry
The following command adds an Object Reference Tracing configuration to the registry. The trace that you configure begins when you restart the computer.
The command uses the /ro parameter to enable Object Reference Tracing as a registry setting. The command uses the /i to specify the process for notepad.exe and the /t
parameter to specify the pool tags Tag1 and Fred. As a result, all objects that are created by the Notepad process with the Tag1 or Fred pool tags are traced. The command
also uses the /p parameter, which retains the trace data until the tracing is disabled.
gflags /ro /t Tag1;Fred /i Notepad.exe /p
When you submit the command, Gflags stores the information in the registry. However, because registry settings are not effective until you restart the computer, this object
reference tracing is configured, but is not yet started.
Gflags responds by printing the following message:
Boot Registry Settings :
Object Ref Tracing Enabled
Permanent Traces
Pool Tags: Tag1;Fred
Process Name: Notepad.exe
The message indicates that Object Reference Tracing is enabled in the registry. "Permanent Traces" indicates that the trace data will be retained until you shut down or restart
the computer. The message also lists the pool tags and image file names that will be traced.
Display the Object Reference Tracing Configuration
You can display the Object Reference Tracing configuration that is currently effective or is stored in the registry to be used when the computer is restarted.
In this example, there is one Object Reference Tracing configuration stored in the registry and a different one configured for run time. The run-time trace begins immediately
(and overrides any registry settings). However, if you restart the system, the run-time settings are lost, and the Object Reference Tracing session registry settings become
effective.
The following command displays the run time Object Reference Tracing configuration. It uses the /ko parameter with no other parameters.
gflags /ko
Running Kernel Settings :
Object Ref Tracing Enabled
Temporary Traces
Pool Tags: Tag1;Fred
Process Name: All Processes
If Object Reference Tracing is enabled, as it is in this example, the settings that are displayed describe a trace that is in progress.
The following command displays the Object Reference Tracing configuration data stored in the registry. It uses the /ro parameter with no other parameters.
gflags /ro

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1080 of 1651

In response, Gflags displays the data stored in the registry:

Boot Registry Settings :
Object Ref Tracing Enabled
Permanent Traces
Pool Tags: Tag1;Fred
Process Name: Notepad.exe
If you have restarted the computer since you added the Object Reference Tracing configuration to the registry, the settings that are displayed in response to a gflags /ro
command describe the trace that is in progress. However, if you have not yet restarted, or you have restarted, but then started a run-time object reference trace (/ko), the
settings that are stored in the registry are not currently effective, but they will become effective again when you reboot the system.
Disable Object Reference Tracing
When you disable run-time (kernel flag) Object Reference Tracing settings, the trace stops immediately. When you disable Object Reference Tracing settings in the registry,
the trace stops when you restart the computer.
The following command disables run-time Object Reference Tracing. It uses the /d parameter to disable all settings. You cannot disable settings selectively.
gflags /ko -d
When the command succeeds, Gflags responds with the following message:
Running Kernel Settings :
Object Ref Tracing Disabled
The following command disables run-time Object Reference Tracing.
The following command disables Object Reference Tracing settings in the registry. It uses the /d parameter to disable all settings. You cannot disable settings selectively. This
command is effective when you restart the computer.
gflags /ro -d
When the command succeeds, Gflags responds with the following message:
Boot Registry Settings :
Object Ref Tracing Disabled

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Global Flag Reference

This reference describes the flags that GFlags sets.
Note The symbolic name of each flag is provided for reference only. Because symbolic names change, they are not a reliable identifier of a global flag.
The global flags include:
Buffer DbgPrint Output
Create kernel mode stack trace database
Create user mode stack trace database
Debug initial command
Debug WinLogon
Disable heap coalesce on free
Disable paging of kernel stacks
Disable protected DLL verification
Disable stack extension
Early critical section event creation
Enable application verifier
Enable bad handles detection
Enable close exception
Enable debugging of Win32 subsystem

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1081 of 1651

Enable exception logging

Enable heap free checking
Enable heap tagging
Enable heap tagging by DLL
Enable heap tail checking
Enable heap validation on call
Enable loading of kernel debugger symbols
Enable object handle type tagging
Enable page heap
Enable pool tagging
Enable system critical breaks
Load DLLs top-down
Load image using large pages if possible
Maintain a list of objects for each type
Object Reference Tracing
Show loader snaps
Special Pool
Stop on exception
Stop on hung GUI
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Buffer DbgPrint Output

The Buffer DbgPrint Output flag suppresses debugger output from DbgPrint, DbgPrintEx, KdPrint, and KdPrintEx calls.
Abbreviation
ddp
Hexadecimal value 0x08000000
Symbolic Name
FLG_DISABLE_DBGPRINT
Destination
System-wide registry entry, kernel flag
Comments
When debugger output is suppressed, it does not automatically appear in the kernel debugger. However, the message is always sent to the DbgPrint buffer, where it can be
accessed by using the !dbgprint debugger extension.
For information about the functions that communicate with the debugger, see Sending Output to the Debugger.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Create kernel mode stack trace database

The Create kernel mode stack trace database flag creates a run-time stack trace database of kernel operations, such as resource objects and object management operations,
and works only when using the checked build of Windows.
Abbreviation
kst
Hexadecimal value 0x2000
Symbolic Name
FLG_KERNEL_STACK_TRACE_DB
Destination
System-wide registry entry

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1082 of 1651

Comments
GFlags displays this flag as a kernel flag setting, but it is not effective at run time, because the kernel is already started.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Create user mode stack trace database

The Create user mode stack trace database flag creates a run-time stack trace database in the address space of a particular process (image file mode) or all processes
(system-wide).
Abbreviation
ust
Hexadecimal value 0x1000
Symbolic Name
FLG_USER_STACK_TRACE_DB
Destination
System-wide registry entry, kernel flag, image file registry entry

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug initial command

The Debug initial command flag debugs the Client Server Run-time Subsystem (CSRSS) and the WinLogon process.
Abbreviation
dic
Hexadecimal value 0x4
Symbolic Name
FLG_DEBUG_INITIAL_COMMAND
Destination
System-wide registry entry, kernel flag
Comments
NTSD debugs the processes (using the command ntsd -d), but control is redirected to the kernel debugger.
For details on NTSD, see CDB and NTSD.
See Also
Debug WinLogon, Enable debugging of Win32 subsystem
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debug WinLogon
The Debug WinLogon flag debugs the WinLogon service.
Abbreviation
dwl
Hexadecimal value 0x04000000
Symbolic Name
FLG_DEBUG_INITIAL_COMMAND_EX
Destination
System-wide registry entry
Comments
NTSD debugs Winlogon (by using the command ntsd -d -g -x), but control is redirected to the kernel debugger.
For details on NTSD, see CDB and NTSD.
See Also
Debug initial command, Enable debugging of Win32 subsystem

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1083 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enable page heap

The Enable page heap flag turns on page heap verification, which monitors dynamic heap memory operations, including allocate and free operations, and causes a debugger
break when the verifier detects a heap error.
Abbreviation
hpa
Hexadecimal value 0x02000000
Symbolic Name
FLG_HEAP_PAGE_ALLOCS
Destination
System-wide registry entry, kernel flag, image file registry entry
Comments
This option enables full page heap verification when set for image files and standard page heap verification when set in the system registry or as a kernel flag.

Full page heap verification (for /i) places a zone of reserved virtual memory at the end of each allocation.
Standard page heap verification (for /r or /k) places random patterns at the end of an allocation and examines the patterns when a heap block is freed.

Setting this flag for an image file is the same as typing gflags /p enable ImageFile /full for the image file at the command line.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enable pool tagging

The Enable pool tagging flag collects data and calculates statistics about pool memory allocations sorted by pool tag value.
Abbreviation
ptg
Hexadecimal value 0x400
Symbolic Name
FLG_POOL_ENABLE_TAGGING
Destination
System-wide registry entry
Comments
This flag is permanently set in Windows Server 2003 and later versions of Windows. On these systems, the Enable pool tagging check box in the Global Flags dialog box is
dimmed and commands to enable or disable pool tagging fail.
Use ExAllocatePoolWithTag or ExAllocatePoolWithQuotaTag to set the tag value. When no tag value is specified (ExAllocatePool, ExAllocatePoolWithQuota),
Windows creates a tag with the default value of "None." Because data for all allocations with a "None" tag is combined, you cannot distinguish the data for a specific
allocation. For information about these routines, see the Windows Driver Kit (WDK).
In Windows XP and earlier systems, this flag also directs Windows to attach a pool tag even when the pool memory is allocated by using ExAllocatePoolWithQuotaTag.
Otherwise, the tag bytes are used to store the quota values. In Windows Server 2003, tag values and quota values are stored in separate fields that are attached to every pool
memory allocation.
Note To display the data that Windows collects about a tagged allocation, use PoolMon, a tool that is included in the Windows Driver Kit.
The description of the Enable Pool Tagging flag in the Windows XP Support Tools documentation is incomplete. This flag directs Windows to collect and process data by
tag value.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1089 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Enable system critical breaks

The Enable system critical breaks flag forces a system break into the debugger.
Abbreviation
scb
Hexadecimal value 0x100000
Symbolic Name
FLG_ENABLE_SYSTEM_CRIT_BREAKS
Destination
System-wide registry entry, kernel flag, image file registry entry
Comments
When set for a process (image file), this flag forces a system break into the debugger whenever the specified process stops abnormally. This flag is effective only when the
process calls the RtlSetProcessBreakOnExit and RtlSetThreadBreakOnExit interfaces.
When set system-wide (registry or kernel flag), this flag forces a system break into the debugger whenever processes that have called the RtlSetProcessBreakOnExit and
RtlSetThreadBreakOnExit interfaces stop abnormally.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Load DLLs top-down

The Load DLLs top-down flag loads DLLs at the highest possible address.
Abbreviation
ltd
Hexadecimal value 0x20000000
Symbolic Name
FLG_LDR_TOP_DOWN
Destination
System-wide registry entry, kernel flag, image file registry entry
Comments
This flag is used to test 64-bit code for pointer truncation errors, because the most significant 32 bits of the pointers are not zeros. It is designed for code running on the 64-bit
versions of Windows Server 2003 and later versions of Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Load image using large pages if possible

The Load image using large pages if possible setting directs the system to use large pages (4 MB) rather than the standard small pages (4 KB) when mapping binaries into
the process address space.
This setting is most helpful for large executable files, because it significantly reduces the number of page table entries in physical memory.
Abbreviation
lpg
Hexadecimal value (none)
Symbolic Name
Destination
Image file registry entry
Comments
This setting is not technically a global flag, because its value is stored in a separate registry entry, not as a value of the GlobalFlag registry entry. As a result, you cannot set it
by using a hexadecimal value, and when you select this setting for an image file, it appears in the Other settings field of the display.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1090 of 1651

Maintain a list of objects for each type

The Maintain a list of objects for each type flag collects and maintains a list of active objects by object type, for example, event, mutex, and semaphore.
Abbreviation
otl
Hexadecimal value 0x4000
Symbolic Name
FLG_MAINTAIN_OBJECT_TYPELIST
Destination
System-wide registry entry
Comments
To display the object list, use Open Handles (oh.exe), a tool included in the Windows 2000 Resource Kit, and now available for download from the
2000 Resource Kit Web site. Because Open Handles automatically sets the OTL flag, but does not clear it, use GFlags -otl to clear the flag.

Microsoft Windows

Note The linked lists created when you set this flag use eight bytes of overhead for each object. Remember to clear this flag when your analysis is complete.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Object Reference Tracing

The Object Reference Tracing feature records sequential stack traces each time that an object reference counter is incremented or decremented. The traces can help you to
detect object reference errors, including double-dereferencing, failure to reference, and failure to dereference objects. This feature is supported only in Windows Vista and
later versions of Windows.
For information about configuring the Object Reference Tracing feature in the Global Flags dialog box, see Configuring Object Reference Tracing. For information about
configuring the Object Reference Tracing feature at the command prompt, see GFlags Commands. For an example, see Example 15: Using Object Reference Tracing.
Object reference traces are most useful when you suspect that a particular object is not being referenced or dereferenced properly, typically because increased pool usage
indicates that an object is leaking, or a process or session cannot be ended, even though its handle count is zero. Unlike traces that are recorded in logs for later review, object
reference traces are designed to be used in real time, while the process is running and the object is being referenced and dereferenced. You view an object reference trace in
the debugger by using the !obtrace debugger extension. Because this extension requires a specified object address, you must know in advance which object is the likely
source of the error.
The following rules apply to Object Reference Tracing:

You can run only one object reference trace at a time.

Because a kernel-wide trace is not practical, you must limit the trace to objects that are created with specified pool tags, or to objects that are created by a specified
process (indicated by an image file name), or both.
You can specify only one image file for each trace. If you specify an image file, the trace is limited to objects that are created by the processes that the image represents.
Objects that are referenced by the process, but are created by a different process, are not traced.
You can specify a maximum of 16 pool tags for each trace. Objects with any of the specified pool tags are traced.
If you specify both an image file and one or more pool tags, the trace is limited to objects that are created by the process and have any of the specified pool tags.
Object Reference Tracing cannot trace processes that are already running when a trace is started. The trace includes only the objects of processes that start after the trace
begins.
Objects marked for tracing are traced until the object is destroyed or tracing is disabled. By default, the traces for an object are maintained only until the object is
destroyed, but you can specify a "permanent" trace (/p) where the trace is retained until tracing is disabled.
You can store the Object Reference Tracing configuration as a registry setting or a kernel flag (run-time) setting. If you have both registry and kernel flag settings, the
run-time settings take precedence, but are lost when you shut down or restart the computer.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Show loader snaps

The Show loader snaps flag captures detailed information about the loading and unloading of executable images and their supporting library modules and displays the data in
the kernel debugger console.
Abbreviation
sls
Hexadecimal value 0x2
Symbolic Name
FLG_SHOW_LDR_SNAPS
Destination
System-wide registry entry, kernel flag, image file registry entry
Comments
For system-wide (registry or kernel flag), this flag displays information about driver loading and unloading operations.
For per-process (image file), this flag displays information about loading and unloading of DLLs.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1091 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Special Pool
The Special Pool feature configures Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is
within a specified size range.
Abbreviation
spp
Hexadecimal value (None)
Symbolic Name
(None)
Destination
System-wide registry entry
(Windows Vista and later) System-wide registry entry, kernel flag

Selecting a Pool Tag

When requesting special pool for a particular pool tag, make sure that your driver or other kernel-mode program uses a unique pool tag.
Also, when creating a pool tag (such as by using ExAllocatePoolWithTag), consider entering the tag characters in reverse order. For example, if the tag is Fred, consider
entering it as dreF (0x64657246). Pool tags are stored in the registry and displayed in the debugger and other tools in reverse (lower endian) order. If you enter them in
reverse order, they are displayed in forward order (0x46726564)
If you suspect that your driver is consuming all of the special pool, consider using multiple pool tags in your code. You can then test your driver several times, assigning
special pool to one pool tag in each test.
Also, select a pool tag with a hexadecimal value that is greater than the page size of the system. For kernel mode code, if you enter a pool tag that has a value less than
PAGE_SIZE, Gflags requests special pool for all allocations whose size is within the corresponding range and requests special pool for allocations with an equivalent pool
tag. For example, if you select a size of 30, special pool will be used for all allocations between 17 and 32 bytes in size, and for allocations with the pool tag 0x0030.
Selecting an Allocation Size
Use the following guidelines to select an allocation size for the Special Pool feature.
On a computer with an x86 processor, PAGE_SIZE is 0x1000 and the allocation size ranges are 8 bytes in length. To configure the Special Pool feature for all allocations with
sizes in this range, enter a number equal to the maximum of this range plus 8. (This number is always a multiple of 8.) The following table illustrates these values:
Size range
Enter this number
1 to 8 bytes
10 (decimal 16)
9 to 16 bytes
18 (decimal 24)
17 to 24 bytes
20 (decimal 32)
...
...
0xFE9 to 0xFF0 bytes FF8 (decimal 4088)
On a computer with an AMD x86-64 processor, PAGE_SIZE is 0x1000 and the allocation size ranges are 16 bytes in length. To configure the Special Pool feature for all
allocations with sizes in this range, enter a number equal to the maximum of this range plus 16. (This number is always a multiple of 16.) The following table illustrates these
values:
Size range
Enter this number
1 to 16 bytes
20 (decimal 32)
17 to 32 bytes
30 (decimal 48)
33 to 48 bytes
40 (decimal 64)
...
...
0xFD1 to 0xFE0 bytes FF0 (decimal 4080)
On a computer with an Intel Itanium processor, PAGE_SIZE is 0x2000 and the allocation size ranges are 16 bytes in length. To configure the Special Pool feature for all
allocations with sizes in this range, enter a number equal to the maximum of this range plus 16. (This number is always a multiple of 16.) The following table illustrates these
values:
Size range
Enter this number
1 to 16 bytes
20 (decimal 32)
17 to 32 bytes
30 (decimal 48)
33 to 48 bytes
40 (decimal 64)
...
...
0x1FD1 to 0x1FE0 bytes 1FF0 (decimal 8176)
On a computer with any processor, you can use an asterisk ( * ) or 0x2A (decimal 42) to configure the Special Pool feature for all memory allocations on the system.
Comments
For information about configuring the Special Pool feature in the Global Flags Dialog Box, see Configuring Special Pool. For information about configuring the Special Pool
feature at the command line, see GFlags Commands. For an example, see Example 14: Configuring Special Pool.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1092 of 1651

The Special Pool feature of Gflags directs Windows to request memory allocations from a reserved memory pool when the memory is allocated with a specified pool tag or is
within a specified size range. To request special pool for all allocations by a particular driver, use Driver Verifier. For more information, see the "Special Pool" topic in the
"Driver Verifier" section of the Windows Driver Kit (WDK).
The special pool features of Gflags and Driver Verifier help you to detect and identify the source of errors in kernel pool use, such as writing beyond the allocated memory
space, or referring to memory that has already been freed.
Not all special pool requests are fulfilled. Each allocation from the special pool uses one page of nonpageable physical memory and two pages of virtual address space. If the
special pool is exhausted, memory is allocated from the standard pool until the special pool becomes available again. When a special pool request is filled from the standard
pool, the requesting function returns a success status. It does not return an error, because the allocation has succeeded, even though it was not filled from special pool.
The size of the special pool increases with the amount of physical memory on the system; ideally this should be at least 1 Gigabyte (GB). On x86 machines, because virtual
(in addition to physical) space is consumed, do not use the /3GB boot option when using special pool. It is also a good idea to increase the pagefile minimum/maximum
quantities by a factor of two or three.
You can also configure the Special Pool feature to align memory allocation to detect references to memory preceding the allocation ("underruns") or references to memory
beyond the allocation ("overruns"). This feature is available only in the Global Flags dialog box on all versions of Windows. For details, see Detecting Overruns and
Underruns.
On Windows Vista and later versions of Windows, you can configure the Special Pool feature as a registry setting that requires a reboot, but remains effective until you
change it, or as a kernel flag setting that does not require a reboot, but is effective only until you reboot or shut down Windows. In earlier versions of Windows, Special Pool
is only available as a registry setting.
On Windows Vista and later versions of Windows, you can configure the Special Pool feature either by using the Global Flags dialog box or at the command line. In earlier
version of Windows, this feature is available only in the Global Flags dialog box.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Stop on exception
The Stop on exception flag causes the kernel to break into the kernel debugger whenever a kernel-mode exception occurs.
Abbreviation
soe
Hexadecimal value 0x1
Symbolic Name
FLG_STOP_ON_EXCEPTION
Destination
System-wide registry entry, kernel flag, image file registry entry
Comments
Windows passes all first chance exceptions (except for STATUS_PORT_DISCONNECT) with a severity of Warning or Error to the debugger before passing them to a local
exception handler.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Stop on hung GUI

The Stop on hung GUI flag appears in GFlags, but it has no effect on Windows.
Abbreviation
shg
Hexadecimal value 0x8
Symbolic Name
FLG_STOP_ON_HUNG_GUI
Destination
Kernel flag

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kill Tool
The Kill tool, kill.exe, terminates one or more processes and all of their threads. This tool works only on processes running on the local computer.
This section includes:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1093 of 1651

Kill Tool Commands

Kill Tool Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kill Tool Commands

Use the following command syntax to run the Kill tool.

kill [/f] { PID | Pattern* }

Parameters
/f
Forces the termination of the process without prompting the user for confirmation. This option is required to terminate a protected process, such as a system service.
PID
Specifies the process identifier (PID) of the task to be terminated.
To find the PID for a task, use TaskList in Microsoft Windows XP and later or TList in Windows 2000.
Pattern*
Specifies all or part of the name of a task or window. The Kill tool terminates all processes whose process names or window names match the pattern. The asterisk is
required.
Before using a pattern that might match many process or window names unintentionally, use the tlist pattern command to test the pattern. See TList for details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Kill Tool Examples

The following examples demonstrate the use of the Kill tool.
Terminate by name
The following command terminates processes whose names begin with "myapp."
kill myapp*
Terminate by PID
The following command terminates the process whose process ID (PID) is 2520:
kill 2520
Terminate forcibly
The following command terminates processes whose names begin with "my*." It does not prompt for confirmation. This command succeeds even when this process is a
system service:
kill /f my*

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Logger and LogViewer

The Debugging Tools for Microsoft Windows package includes a pair of tools named Logger and LogViewer. These provide an alternative to standard user-mode debugging.
Logger can monitor the actions of a user-mode target application and record all of its API calls. The resulting information can be displayed in the debugger, saved as a text
file, or displayed in a powerful interactive format by the LogViewer tool.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1094 of 1651

This section includes:

Logger
LogViewer
The Logger Manifest
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Logger
The Logger tool can be activated through two different vehicles. One way is to use the stand-alone Logger.exe program. The other is to start CDB or WinDbg, and use the
Logexts.dll debugger extensions. Both of these methods will produce the same type of log output. However, the best vehicle to use on any NT-based operating system is CDB
or WinDbg with the Logexts.dll extension commands.
The Logger vehicle works as well, but using the debugger gives you the full power of the debugger along with the power of Logger.
This section includes:
Using the Debugger and Logexts.dll
Using Logger.exe
Logger Restrictions and Limitations
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the Debugger and Logexts.dll

One way to activate Logger is to start CDB or WinDbg and attach to a user-mode target application as usual. Then, use the !logexts.logi or !logexts.loge extension command.
This will insert code at the current breakpoint that will jump off to a routine that loads and initializes Logexts.dll in the target application process. This is referred to as
"injecting Logger into the target application."
There will actually be two instances of Logexts.dll running, since this module is both a debugger extension DLL and the program that is injected into the target application.
The debugger and target instances of Logexts.dll communicate through a shared section of memory that includes the output file handles, current category mask, and a pointer
to the log output buffer.
Attaching to the Target Application
For information about attaching the debugger to the target application, see Attaching to a Running Process (User Mode) or Spawning a New Process (User Mode).
Using the Logger Extension Commands
For the full syntax of each extension, see its reference page.
!logexts.logi
Injects Logger into the target application. This initializes logging, but does not enable it.
!logexts.loge
Enables logging. If !logexts.logi has not been used, this extension will initialize and then enable logging.
!logexts.logd
Disables logging. This will cause all API hooks to be removed in an effort to allow the program to run freely. COM hooks are not removed because they cannot be reenabled at will.
!logexts.logo
Displays or modifies output options. Three types of output are possible: messages sent directly to the debugger, a text file, or an .lgv file. The .lgv file contains much
more information than the other two; it can be read with LogViewer.
If you disable the text file output, a .txt file of size zero will still be created. This may overwrite a previously-saved text file in the same location.
!logexts.logc
Displays available API categories, controls which categories will be logged and which will not, and displays the APIs that are contained in any category.
If a category is disabled, the hooks for all APIs in that category will be removed so that there is no longer any performance overhead. COM hooks are not removed
because they cannot be re-enabled at will.
Enabling only certain categories can be useful when you are only interested in a particular type of interaction that the program is having with Windows for example,
file operations. This reduces the log file size and also reduces the effect that Logger has on the execution speed of the process.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1095 of 1651

!logexts.logb
Displays or flushes the current output buffer. As a performance consideration, log output is flushed to disk only when the output buffer is full. By default, the buffer is
2144 bytes.
Since the buffer memory is managed by the target application, the automatic writing of the buffer to the log files on the disk will not occur if there is an access violation
or some other non-recoverable error in the target application. In such cases, you should use this command to manually flush the buffer to the disk, or else the most
recently-logged APIs may not appear in the log files.
!logexts.logm
Displays or creates a module inclusion/exclusion list. It is often desirable to only log those API calls that are made from a certain module or set of modules. To facilitate
that, Logger allows you to specify a module inclusion list or, alternatively, a module exclusion list. For instance, you would use an inclusion list if you only wanted to log
calls from one or two modules. If you wanted to log calls made from all modules except a short list of modules, you would use an exclusion list. The modules Logexts.dll
and Kernel32.dll are always excluded, since Logger is not permitted to log itself.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Logger.exe
One way to activate Logger is to run the stand-alone Logger.exe program. This is essentially a very small debugger that can only take a single target. To run it, include the
name of the target application on the command line:
logger Target
When this is activated, it will load the specified application, and insert code into the target application that will jump off to a routine that loads and initializes Logexts.dll in the
target application process. This is referred to as "injecting Logger into the target application."
The Logger.exe utility and the Logexts.dll module are the two components of this Logger vehicle. They communicate through a shared section of memory that includes the
output file handles, current category mask, and a pointer to the log output buffer.
A window entitled Logger (debugger) will appear. This window will display the progress of Logger.
Change Settings Dialog Box
After the initialization finishes and the initial display is complete, the Change Settings dialog box will appear. This allows you to configure the Logger settings. The various
settings are described here:
API Settings
This list displays the available API categories. The highlighted categories will be logged; the non-highlighted categories will not. The first time you run Logger, all
categories will be highlighted. However, on subsequent runs, Logger will keep track of which categories are selected for a given target application.
If a category is disabled, the hooks for all APIs in that category will be removed so that there is no longer any performance overhead. COM hooks are not removed
because they cannot be re-enabled at will.
Enabling only certain categories can be useful when you are only interested in a particular type of interaction that the program is having with Windows for example,
file operations. This reduces the log file size and also reduces the effect that Logger has on the execution speed of the process.
Logging
This section contains Enable and Disable radio buttons. Disabling logging will cause all API hooks to be removed in an effort to allow the program to run freely. COM
hooks are not removed because they cannot be re-enabled at will.
Inclusion / Exclusion List
This section controls the module inclusion/exclusion list. It is often desirable to log only those function calls that are made from a certain module or set of modules. To
facilitate that, Logger allows you to specify a module inclusion list or, alternatively, a module exclusion list. For instance, you would use an inclusion list if you only
wanted to log calls from one or two module. If you wanted to log calls made from all modules except a short list of modules, you would use an exclusion list. The
modules Logexts.dll and Kernel32.dll are always excluded, since Logger is not permitted to log itself.
Flush the Buffer
This button will flush the current output buffer. As a performance consideration, log output is flushed to disk only when the output buffer is full. By default, the buffer is
2144 bytes.
Since the buffer memory is managed by the target application, the automatic writing of the buffer to the log files on the disk will not occur if there is an access violation
or some other non-recoverable error in the target application. In such cases, you should try to activate the target application's window and hit F12 to get this dialog box
back, and then press Flush the Buffer. If this is not done, the most recently-logged functions might not appear in the log files.
Go
This causes the target application to begin executing.
Running the Target Application
Once you have chosen the settings, click Go. The dialog box will close and the target application will begin to run.
If you make the target application's window active and press F12, it will break into Logger. This will cause the target application to freeze and the Change Settings dialog
box to reappear. You can alter the settings if you wish, and then press Go to continue execution.
You can let the target application run for as long as you wish. If it terminates normally or due to an error, the logging will stop and cannot be restarted.
When you wish to exit, select File | Exit and click Yes. If the target application is still running, it will be terminated.
Limitations of Logger.exe

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1096 of 1651

When you are running Logger through the Logger.exe tool, it will create only one output file an .lgv file. No text file will be written. However, a .txt file of size zero will be
created; this could overwrite a text log written by the debugger previously.
The output file will always be placed in LogExts subdirectory of the desktop; this location cannot be changed.
These limitations will not apply if you are running Logger through the debugger and Logexts.dll.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Logger Restrictions and Limitations

Logger increases stack consumption for a process because it introduces an additional "wrapping" function before the actual function call.
This can expose bugs in applications that are usually related to uninitialized variables. Since Logger alters stack usage, a local variable declared in a function call might take a
different initial value than it does without the presence of Logger. If the program uses this variable without initializing it, the program might crash or otherwise behave
differently than if Logger was not present.
Unfortunately, there is no easy way around such problems. The only workaround is to try disabling categories of functions in an attempt to isolate the area that is causing the
problem.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

LogViewer
The LogViewer utility can manipulate an .lgv file, which is a compressed log file produced by the Logger tool. To load a file, simply launch Logviewer.exe through Windows
Explorer or from a Command Prompt window. It will take a moment to parse the manifest files. Once this is complete, you can invoke File | Open and select the desired .lgv
file.
Once LogViewer has opened an .lgv file, it will display a list of all functions in the order they were logged. LogViewer supports powerful commands to filter out functions
that you are not interested in. It can also save a filtered version of the log file as a text file.
This section includes:
Reading the LogViewer Display
Filtering the LogViewer Function List
Exporting LogViewer Files to Text
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Reading the LogViewer Display

LogViewer displays a list of all functions in the order they were logged.
Each row of the display contains several columns. The significance of each column is as follows.
Column
Meaning
+/If this column contains a "+" (plus sign), it indicates that the function takes one or more parameters. To see the parameters and their values, either double click
on the row or hit the right arrow key when the row is outlined in red. To hide it again, double click it again or hit the left arrow key when the row is outlined in
red.
There is also a "d#" value in this column. This indicates the "depth" of the function call (in other words, how deep the call is nested in other logged function
calls).
#
Thrd
Caller
Module

The sequential row number of the function call. This is useful when you have filters applied and are interested to know how far apart two function calls are.
The thread number on which the function call was made. This number is not a thread ID, but is rather an assigned number based on the order that threads were
created in the process.
The instruction address that made the function call. This is derived from the return address for the call. It is actually the return address minus 5 bytes (the typical
size of a call dword ptr instruction).
The module that contains the calling instruction.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

API
Function
Return
Value

Page 1097 of 1651

The name of the function. The name of the module that contains the function is omitted for brevity.
The value returned by the function, if it is not a void function.

Double-clicking on a row in the viewer will expand the row to reveal the parameters to the function and their values "going in" to the function. If they are designated as OUT
parameters, their value "coming out" is shown on the right.
You can also use the ENTER key or the right and left arrow keys to expand and collapse rows.
Function calls that returned failure status codes are shaded in pink.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Filtering the LogViewer Function List

Logger usually captures some function calls that are not needed for your analysis. These can be filtered out by Logger when it creates the log file. However, this process is not
reversible, so it is usually preferable to allow all functions to be logged, and then filter the display in LogViewer.
There are several ways to filter out function calls in LogViewer:

In the main viewing area, selected a function by clicking on it or using the cursor keys. (When a function is selected, LogViewer outlines it in red.) Then, press the
DELETE key, or right-click and select Hide. This will hide all instances of that function call from view.
Select View | APIs Display. A dialog box will appear that has three areas. On the right is an alphabetical listing of all functions, and on the left are categorical
groupings. You can enable or disable the display of any function by checking or clearing the box to the left of its name.
Select View | Modules Display. A dialog box will appear that allows you to select calling modules; only those functions that were called from these modules will be
displayed.
Select View | First Level Calls Only. This will display only calls that have "d0" in the left column. It is often desirable to hide function calls that are made by other
logged functions. (For example, it is usually not interesting to know that ShellExecuteEx makes thirty different registry calls during its course of execution.)

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Exporting LogViewer Files to Text

A powerful way to manipulate log files is to export them to text. This allows you to find specific parameter values by using the Find facility of any text editor. Although it is
possible for a text file to be generated by Logger directly, you will have more flexibility if you use LogViewer to filter the function calls or add aliasing, and then export this
information into a text file.
To create a text file from an .lgv file, open the file in LogViewer, and then select File | Export to Text. In the dialog box, choose a file name and location.
There are several options at the bottom of the dialog box:
Export Diff Information
This option will alias all pointers, handle values, and other values that change from execution to execution. Instead of outputting the actual value of a pointer (for
example, "0x00123FA2"), LogViewer will output "Pointer." Similarly, handles will be aliased as "HeapHandle1" or some other value that will not register as a diff when
the two files are compared using a differencing tool.
Include Non-Visible Rows
This option disables whatever filters are currently applied to the view while exporting.
Create a Separate File For Each Thread
This option splits up the text file by thread, making it easier to follow a thread of execution. This is useful if you intend to "diff" two instances of execution.
Export Range
This option specifies the range of rows to export.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The Logger Manifest

This section includes:
Overview of the Logging Manifest
Manifest File Placement

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1098 of 1651

Manifest File Format

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Overview of the Logging Manifest

The logging manifest is the group of "header" files that define the functions and COM interfaces that are intercepted and logged. These are not true C++ header files they
are in a slightly different format that explicitly declares the information needed by Logger.
For example, the manifest format facilitates the following features:

Designation of OUT parameters. These are parameters that should be logged both on their way into an function and also on their way out.
Definition of flag masks. This feature allows LogViewer to break a DWORD flag into its constituent bit labels for easier reading.
Definition of failure cases. This feature allows LogViewer to shade the rows of functions that have returned a failure status code or another error code. Also, if the
function sets the "LastError" value for the thread, LogViewer can store away the error code and expand it to its corresponding human-readable error message.
Designation of parameters that can be aliased for log differencing. This feature gives LogViewer the option of assigning a constant string to a value that changes from
execution to execution like pointers and handles when it exports the data to a file. You can then use a differencing tool to compare two execution logs for discrepancies.
If pointers and handle values were not aliased, they would produce uninteresting discrepancies when the two files are compared.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Manifest File Placement

The primary manifest file must be named Main.h.
When Logger is running, Main.h must be located in the Manifest subdirectory of the directory containing Logexts.dll.
LogViewer is more flexible than Logger. It will search for Main.h in the following directories in this order:
1.
2.
3.
4.

The Manifest directory subordinate to the directory containing Logviewer.exe

The WinExt\Manifest directory subordinate to the directory containing logviewer.exe
The %WinDir%\System32\Manifest directory
The %WinDir%\System\Manifest directory

All additional manifest files must reside in the same directory as Main.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Manifest File Format

The file format for the manifest files borrows as much from C++ and IDL as possible. As a result, it is fairly easy to take a normal C++ SDK header file and modify it to be a
manifest file. The parser fully supports C and C++ style comments to help you organize and document the file.
If you are attempting to add a manifest file or make alterations to an existing file, the best way to do it is to just experiment. When you issue a !logexts.logi or !logexts.loge
command in the debugger, Logger will attempt to parse the manifest files. If it encounters a problem, it will produce an error message which might indicate the mistake.
A manifest file is made up of the following basic elements: module labels, category labels, function declarations, COM interface definitions, and type definitions. Other types
of elements exist as well, but these are the most important.

Module Labels
A module label simply declares what DLL exports the functions that are declared thereafter. For example, if your manifest file is for logging a group of functions from
Comctl32.dll, you would include the following module label before declaring any function prototypes:
module COMCTL32.DLL:
A module label must appear before any function declarations in a manifest file. A manifest file can contain any number of module labels.

parameter to a function and there is a separate parameter that has an [iid] label, Logger will compare the passed in IID against all declared GUIDs. If there is a match and
a COM interface was declared that has the same name as the IID, Logger will hook all the functions in that interface and log them.
Here is an example:
STDAPI CoCreateInstance(
REFCLSID rclsid,
//Class identifier (CLSID) of the object
LPUNKNOWN pUnkOuter, //Pointer to controlling IUnknown
CLSCTX dwClsContext, //Context for running executable code
[iid] REFIID riid,
//Reference to the identifier of the interface
[out] COM_INTERFACE_PTR * ppv
//Address of output variable that receives
//the interface pointer requested in riid
);
In this example, riid has an [iid] modifier. This indicates to Logger that the pointer returned in ppv is a COM interface pointer for the interface identified by riid.
It is also possible to declare a function as follows:
DDRESULT DirectDrawCreateClipper( DWORD dwFlags, [out] LPDIRECTDRAWCLIPPER *lplpDDClipper, IUnknown *pUnkOuter );
In this example, LPDIRECTDRAWCLIPPER is defined as a pointer to the IDirectDrawClipper interface. Since Logger can identify which interface type is being
returned in the lplpDDClipper parameter, there is no need for an [iid] modifier on any of the other parameters.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Tool
The Remote tool, Remote.exe, is a command-line tool that lets you run and control any console program from a remote computer.
The Remote tool includes the following components:

A server application that starts a console program and opens a named pipe for client connections.
A client application that establishes a connection to a server. Commands typed on the client computer are sent to the console application on the server, and the remote
client displays the output from the server's console window.
A query feature that lists the remote sessions running on a server computer.

With the Remote tool, you can start multiple server sessions on a single computer where multiple clients can connect to each session. The sessions are limited only by the
computer's resources.
This is an older tool that has been eclipsed by more sophisticated tools, primarily Remote Desktop. However, because it is simple and uses very few resources, it is still
widely used, typically for remote debugging.
The Remote tool requires that commands be submitted on both the local and remote computers. As such, to use this tool on a computer without a local user, you must develop
an alternate way to submit the commands and to restart the computer, if necessary.
The Remote tool can compromise security on your computer, because it does not authenticate users or use Microsoft Windows permissions. By default, any remote computer
that can connect and provide the session name can use the named pipe that this tool creates, although you can use Remote tool options to include and exclude particular users
and groups.
This section includes:
Remote Tool Concepts
Remote Tool Commands
Remote Tool Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Tool Concepts

The following concepts are used in the Remote tool.

Client and Server

The Remote tool uses a client-server paradigm that avoids the words local and remote, which are relative terms that can be confusing when there are multiple users and
multiple computers.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1102 of 1651

Commands that you type at the client and server computers appear in the Command Prompt windows of both computers.
The Server
The server is the computer on which the console program runs. The Remote Server is the instance of the Remote tool running on the server. The server establishes and names
the remote session (named pipe), issues the command to start the console program, and determines who is permitted to connect to the session.
The Client
The client is a remote computer that sends commands to the console program. The Remote Client is the instance of the Remote tool running on the client computer. The client
connects to the remote session that the server established and uses the remote session (named pipe) that the server created to send commands to the console program that runs
on the server.
The Remote tool supports multiple clients in each remote session. Each client is running one Remote Client. All of the clients can send commands to the console program
running on the server, and all of the clients can see the commands sent and output displayed.

Visible Session
When remote sessions are visible, they appear in the list of remote sessions on the computer. To display the list, use the Remote Server query command (/q).
By default, only debugger sessions are visible, that is, sessions in which the value of the Command parameter include the words kd, dbg, remoteds, ntsd, or cdb; otherwise,
the session is not visible. The Command parameter is part of the Remote tool command on the server.
To make a session visible, add the /v parameter to the Remote Server command. To make a debugger session invisible, add the /-v parameter to the command.
For help with the Remote Server query command, see Remote Server Query Command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Tool Commands

The Remote tool has a separate command syntax for the client and server sides of a session. Commands to start a server session must be entered first because they establish
the communications pipe to which the client connects.
The Remote tool also has a query command and a separate set of commands that you use to communicate with the Remote tool (instead of the console program) during a
remote session.
These commands are described in the following topics:
Remote Server Syntax
Remote Client Syntax
Remote Server Query Command
Remote Session Commands
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Server Syntax

To start the server side of the Remote tool, use the following syntax at the command line.
Syntax
remote /s Command SessionName [/f Color] [/b] [/u User [/u User...]] [/ud User [/ud User...]] [/v | /-v]
Parameters
/s
Starts a server session.
Command
Specifies the command that starts the console-based program. The command can include parameters. If the command includes spaces, enclose it in quotation marks.
SessionName
Assigns a name to the remote session. If the name includes spaces, enclose it in quotation marks. This parameter is not case-sensitive.
/f
Specifies the color of the text in the server command window.
/b
Specifies the background color of the server command window.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1103 of 1651

Color
Specifies a color. Valid values are black, blue, green, cyan, red, purple, yellow, white, lblack, lblue, lgreen, lred, lpurple, lyellow, and lwhite.
/u
Specifies users or groups that are permitted to connect to the remote session; by default, everyone is permitted. When you use this parameter, everyone is denied
permission, except for the users and groups specified by the User subparameter.
/ud
Specifies users or groups that are denied permission to connect to the remote session; by default, no one is denied permission.
User
Specifies the name of a user or group in [domain | computer]\{user | group} format. When specifying users or groups on the local computer, omit the computer name.
/v
Makes a session visible. For more information, see Visible Session.
By default, only debugger sessions are visible, that is, sessions in which the value of the Command parameter include the words kd, dbg, remoteds, ntsd, or cdb;
otherwise, the session is not visible.
-v
Makes a remote debugger session invisible. For more information, see Visible Session.
Comments
The Command and SessionName parameters must appear in the order shown on the syntax line.
To end a remote session, type @k. For more information, see Remote Session Commands.
The Remote tool will not create a session that the current user does not have permission to join.
When starting more than one remote session on a single computer, open a new command window for each session. Also, use a different session name for each session.
Because the session names are used to label the named pipes, they must be unique on the computer.
Sample Usage
remote
remote
remote
remote

/s
/s
/s
/q

"i386kd -v" TestSession

"cmd" "My Remote Session" /f white /b black /u Server01\Administrators
"ntsd -d -g -x" DebugIt /-v
Server01

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Client Syntax

To start the client side of the Remote tool, use the following syntax at the command line.
Syntax
remote /c Server SessionName [/L Lines] [/f] [/b] [/k ColorFile]
Parameters
/c
Connects the client to a remote session.
Server
Specifies the computer name of the server that established the session.
SessionName
Specifies the name of the remote session. This parameter is not case-sensitive.
/L Lines
Specifies the number of lines from the console display that are sent to the client computer. The default is 200 lines. Lines is a decimal number.
/f
Specifies the color of the text in the server command window.
/b
Specifies the background color of the server command window.
Color
Specifies a color. Valid values are black, blue, green, cyan, red, purple, yellow, white, lblack, lblue, lgreen, lred, lpurple, lyellow, and lwhite.
/k ColorFile
Indicates the path (optional) and name of a formatted text file that specifies the colors for displaying the output on the client computer.
The color file associates keywords in the output with text colors. When the keywords appear in a line of output, the Remote tool applies the associated text color to that
line. For the format of the file, see Comments.
/q Computer
Displays the remote sessions available on the specified computer. Only visible sessions appear in the list. (See /v in Remote Server Syntax.)
Comments
The Server and SessionName parameters must appear in the order shown on the syntax line.
To disconnect from a remote session, type @q. For more information, see Remote Session Commands.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1104 of 1651

Keyword Color File. The format of the keyword color file is as follows. The keyword interpreter is not case sensitive.
The keyword or phrase appears on a line by itself. The colors associated with that keyword appear by themselves on the following line, as shown in the syntax:
Keyword
TextColor[, BackgroundColor]
For example, the following file directs Remote to display lines that include the word "error" in black text on a light red background; to display lines that include the word
"warning" in light blue (on the default background), and lines that include the phrase "Windows Vista" in light green on the default background.
ERROR
black, lred
WARNING
lblue
Windows Vista
lgreen
Sample Usage
remote
remote
remote
remote

/c
/c
/c
/q

Server01 TestSession
Domain1\ComputerA0 "cmd" "My Remote Session"
Server01 TestSession /L 50 /f black /b white /k c:\remote_file.txt
Server01

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Server Query Command

To display a list of available sessions on a local or Remote Server, use the following syntax.
Syntax
remote /q Computer
Parameters
/q
Query. Displays the visible remote sessions on the specified computer.
Computer
Specifies the name of the computer. This parameter is required (even on the local computer).
Comments
The query display includes only server sessions; it does not display client connections to remote sessions.
The query display includes only visible sessions. There is no command to display invisible sessions.
The query display includes all visible sessions, including those that restrict users (/u and /ud). The user might not have permission to connect to all of the sessions in the list.
When there are no remote sessions running on the server, the Remote tool displays the following message:
No Remote servers running on \\Computer
However, when the only remote sessions running on the computer are invisible remote sessions, the Remote tool displays the following message:
No visible sessions on server \\Computer

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Session Commands

Use the following commands to communicate with the Remote tool during a console session.
@H
Displays the session commands on server and client computers. Works on server and client computers.
@M Message
Displays the specified message on all server and client computers in the session. Works on server and client computers.
@P Message

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1105 of 1651

Generates a pop-up window on the server computer with the specified message. On client computers, the message appears in the command window. Works on server and
client computers.
@Q
Quit. Disconnects a client computer from the session. Works only on a client computer.
@K
Disconnects all clients and ends the remote session. Works only on a server computer.
Comments
For samples, see "Using the Session Commands" in Remote Tool Examples.
In response to the session commands, the Remote tool displays a label with the day and time that the command was executed. The time for all events is displayed in the time
zone of the server computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Tool Examples

The examples in this section demonstrate the use of the Remote tool and show sample input and output.
Basic Server Command
The following command starts a remote session on the computer.
The command uses the /s parameter to indicate a server-side command. It uses the command, cmd, to start the Windows command shell (Cmd.exe), and names the session
test1.
remote /s cmd test1
In response, the Remote tool starts the session and displays the command that clients would use to connect to the session.
**************************************
***********
REMOTE
************
***********
SERVER
************
**************************************
To Connect: Remote /C SERVER06 "test1"
Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
Basic Client Command
The following command connects to a remote session on the Server01 computer. The command uses the /c parameter to indicate a client-side command. It specifies the name
of the server computer, Server01, and the name of the session on that computer, test1.
remote /c server01 test1
In response, the Remote tool displays a message reporting that the client computer is connected to the session on the server computer. The message displays the name of the
server computer and local user (Server04 user1).
**************************************
***********
REMOTE
************
***********
CLIENT
************
**************************************
Connected...
Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
C:\Program Files\Debugging Tools for Windows>
**Remote: Connected to SERVER04 user1 [Tue 9:39 AM]
After the client connects to the server, the commands typed at the command prompt on the client and server computers appear on both displays..
For example, if you type dir at the command prompt of the client computer, the directory display appears in the Command Prompt window on both the client and server
computers.
Using Server Options
The following server-side command starts a remote session with the NTSD debugger.
The command uses the /s parameter to indicate a server-side command. The next parameter, "ntsd -d -v", is the console command that starts the debugger, along with the
debugger options. Because the console command includes spaces, it is enclosed in quotation marks. The command includes a name for the session, debugit.
The command uses the /u parameter to permit only administrators of the computer and a particular user, User03 in Domain01, to connect to the session. It uses the /f and /b

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1106 of 1651

options to specify black text (foreground) on a white background.

Finally, the command uses the /-v parameter to make the session invisible to user queries. Debugger sessions are visible by default.
remote /s "ntsd -d -v" DebugIt /u Administrators /u Domain01\User03
/f black /b white /-v
In response, the Remote tool creates a session named DebugIt and starts NTSD with the specified parameters. The message indicates that only the specified users have
permission to connect. It also changes the command window to the specified colors.
**************************************
***********
REMOTE
************
***********
SERVER
************
**************************************
Protected Server! Only the following users or groups can connect:
Administrators
Domain01\User03
To Connect: Remote /C SERVER06 "debugit"
Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
Using Client Options
The following command connects to the remote session with the NTSD debugger that was started in the previous example.
The command uses the /c parameter to indicate a client-side command. It specifies the name of the server computer, server06, and the name of the remote session, debugit.
The command also includes the /k parameter to specify the location of a keyword color file.
remote /c server06 debugit /k c:\remote_client.txt
The color file includes the following text:
Registry
white, blue
Token
red, white
This text instructs the Remote tool to display lines of output with the word "registry" (not case sensitive) in white text on a blue background and to display lines of output with
the word "token" in red text on a white background.
In response, the Remote tool connects the client to the server session and displays the following message.
**************************************
***********
REMOTE
************
***********
CLIENT
************
**************************************
Connected...
Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
The client can now send commands to the NTSD debugger on the server computer. The output from the command appears on both the client and server computers.
Lines of output with the word "registry" are displayed on the client computer in white text on a blue background, and lines of output with the word "kernel" in red text on a
white background.
Querying a Session
The Remote tool includes a query parameter (/q) that displays a list of remote sessions on a particular computer. The display includes only visible sessions (debugger sessions
started without the /-v parameter and non-debugger sessions started with the /v parameter).
You can query for sessions from the server or client computers. You must specify the computer name, even when querying for sessions on the local computer.
The following command queries for sessions on the local computer, Server04.
remote /q Server04
In response, the Remote tool reports that there are no remote sessions running on the local computer.
Querying server \\Server04
No Remote servers running on \\Server04
In contrast, in response to a query about sessions on a different computer, Server06, the Remote tool lists the sessions running on that computer.
Querying server \\Server06
Visible sessions on server Server06:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1107 of 1651

ntsd
cmd

[Remote /C SERVER06 "debug"] visible

[Remote /C SERVER06 "test"] visible

The display lists the visible sessions, the console programs running on those sessions (NTSD and the Command Prompt window), and the command that connects to the
session. The session name appears in the command syntax in quotation marks.
The display does not show the permissions established for these sessions, if any. Therefore, the display might include sessions that you do not have permission to join.
Using the Session Commands
You can use the remote session commands at any time during a remote session.
The following command sends a message to all computers connected to the session.
@M I think I found the problem.
As a result, the message appears in the Command Prompt windows of all computers in the session. The message includes the computer name and the day and time of the
message.
@m I think I found the problem.

[SERVER01

Wed 11:53 AM]

When the message is sent from the server computer, "Local" appears in the label instead of the computer name.
@m I think I found the problem.

[Local

Wed 11:52 AM]

The following command generates a pop-up message that appears on the server computer. On all client computers in the session, it writes a message to the Command Prompt
window.
@P Did you see that?
On client computers, the pop-up message appears in the command window.
From SERVER02

[Wed 11:58 AM]

Did you see that?

The time that appears in the message label is always the time on the server computer, even if the client computer that sent the message is in a different time zone.
Ending a Remote Session
The following examples demonstrate how to use the remote session commands to disconnect a client computer from a session and to end a remote session. Only the server
computer that started the remote session can end it.
To disconnect a client computer from a remote session, on the client computer, type @q.
In response, the following message appears on the client computer that disconnected.
*** SESSION OVER ***
On all other computers in the session, the Remote tool posts a message with the name of the computer and user who disconnected, and the day and time of the disconnect.
**Remote:

Disconnected from SERVER04 User01

[Wed 12:01 PM]

To end a remote session, on the server computer, type @k. This command automatically disconnects the clients, and then ends the session.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

TList
TList (Task List Viewer), Tlist.exe, is a command-line tool that displays the processes running on the local computer along with useful information about each process.
TList displays:

All processes running on the computer, along with their process IDs (PIDs).
A tree showing which processes created each process.
Details of the process, including its virtual memory use and the command that started the process.
Threads running in each process, including their thread IDs, entry points, last reported error, and thread state.
The modules running in each process, including the version number, attributes, and virtual address of the module.

You can use TList to search for a process by name or PID, or to find all processes that have loaded a specified module.
In Windows XP and later versions of Windows, TList was replaced by TaskList (Tasklist.exe), which is described in Help and Support for those systems. TList is included in
Debugging Tools for Windows to support users who do not have access to TaskList.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1108 of 1651

This section includes:

TList Commands
TList Examples
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

TList Commands
The syntax of the TList command is as follows:
tlist [/p ProcessName | PID | Pattern | /t | /c | /e | /k | /m [Module] | /s | /v
Parameters
tlist
Without additional parameters, TList displays all running processes, their process identifiers (PIDs), and the title of the window in which they are running, if any.
/p ProcessName
Displays the process identifier (PID) of the specified process.
ProcessName is the name of the process (with or without file name extension), not a pattern.
If the value of ProcessName does not match any running process, TList displays -1. If it matches more than one process name, TList displays only the PID of the first
matching process.
PID
Displays detailed information about the process specified by the PID. For information about the display, see the Comments section below. To find a process ID, type
tlist without additional parameter.
Pattern
Displays detailed information about all processes whose names or window titles match the specified pattern. Pattern can be a complete name or a regular expression.
/t
Displays a task tree in which each process appears as a child of the process that created it.
/c
Displays the command line that started each process.
/e
Displays the session identifier for each process.
/k
Displays the COM components active in each process.
/m Module
Lists tasks in which the specified DLL or executable module is loaded. Module can be a complete module name or a module name pattern.
/s
Displays the services that are active in each process.
/v
Displays details of running processes including the process ID, session ID, window title, command line, and the services running in the process.
Comments
In its detailed display of a process (tlist PID or tlist Pattern), TList displays the following information.

Process ID, executable name, friendly name of the program.

Current working directory (CWD).
The command line that started the process (CmdLine).
Current virtual address space values.
Number of threads.
A list of threads running in the process. For each thread, TList displays the thread ID (TID), the function that the thread is running, the address of the entry point, the
address of the last reported error (if any), and the thread state.
A list of the modules loaded for the process. For each module, TList displays the version number, attributes, virtual address of the module, and the module name.

When using the /e parameter, valid session identifiers appear in the process list only under the following conditions. Otherwise, the session identifier is zero (0).

On Windows 2000 and Windows Server 2003, at least one user must be connected to a session other than the console session.
On Windows XP, Fast User Switching must be enabled and more than one user must be connected to the non-console session.
On Windows Vista, where all processes are associated with two Terminal Services sessions by default, at least one user must be connected to the non-console session.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

TList Examples

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1109 of 1651

The following examples demonstrate how to use TList.

Simplest TList Command (tlist)
Typing tlist without additional parameters displays a list of running processes, their process IDs (PIDs), and the title of the window in which they are running, if any.
c:\>tlist
0
4
308
356
380
424
436
604
776
852
1000
1036
1064
1076
1244
1492
1980
1764
1832
2076
2128
4068

System Process
System
smss.exe
csrss.exe
winlogon.exe
services.exe
lsass.exe
svchost.exe
svchost.exe
spoolsv.exe
clisvcl.exe
InoRpc.exe
InoRT.exe
InoTask.exe
WTTSvc.exe
Sysparse_com.exe
explorer.exe
launch32.exe
msmsgs.exe
ctfmon.exe
ISATRAY.EXE
tlist.exe

NetDDE Agent

OleMainThreadWndName
Program Manager
SMS Client User Application Launcher
MSBLNetConn
IsaTray

Find a process ID (-p)

The following command uses the -p parameter and process name to find the process ID of the Explorer.exe (Explorer) process.
In response, TList displays the process ID of the Explorer process, 328.
c:\>tlist -p explorer
328
Find process details using PID
The following command uses the process ID of the process in which Explorer is running to find detailed information about the Explorer process.
c:\>tlist 328
In response, TList displays details of the Explorer process including the following elements:

Process ID, executable name, program friendly name.

The following is an excerpt of the output resulting from this command.

328 explorer.exe
Program Manager
CWD:
C:\Documents and Settings\user01\
CmdLine: C:\WINDOWS\Explorer.EXE
VirtualSize:
90120 KB
PeakVirtualSize:
104844 KB
WorkingSetSize: 19676 KB
PeakWorkingSetSize: 35716 KB
NumberOfThreads: 17
332 Win32StartAddr:0x010160cc LastErr:0x00000008 State:Waiting
1232 Win32StartAddr:0x70a7def2 LastErr:0x00000000 State:Waiting
1400 Win32StartAddr:0x77f883de LastErr:0x00000000 State:Waiting
1452 Win32StartAddr:0x77f91e38 LastErr:0x00000000 State:Waiting
1484 Win32StartAddr:0x70a7def2 LastErr:0x00000006 State:Waiting
1904 Win32StartAddr:0x74b02ed6 LastErr:0x00000000 State:Ready
1948 Win32StartAddr:0x72d22ecc LastErr:0x00000000 State:Waiting
.... (thread data deleted here)
6.0.2800.1106
5.1.2600.1217
5.1.2600.1106
7.0.2600.1106
5.1.2600.1106
5.1.2600.1254
5.1.2600.1106
5.1.2600.1255

shp
shp
shp
shp
shp
shp
shp
shp

0x01000000
0x77F50000
0x77E60000
0x77C10000
0x77DD0000
0x78000000
0x77C70000
0x77D40000

Explorer.EXE
ntdll.dll
kernel32.dll
msvcrt.dll
ADVAPI32.dll
RPCRT4.dll
GDI32.dll
USER32.dll

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

....

Page 1110 of 1651

(module data deleted here)

Find multiple processes (Pattern)

The following command searches for processes by a regular expression that represents the process name or window name of one or more processes. In this example, the
command searches for a process whose process name or window name begins with "ino."
c:\>tlist ino*
In response, TList displays process details for Inorpc.exe, Inort.exe, and Inotask.exe. For a description of the output, see the "Find process details using PID" subsection
above.
Display a process tree (/t)
The following command displays a tree that represents the processes running on the computer. Processes appear as the children of the process that created them.
c:\>tlist /t
The resulting process tree follows. This tree shows, among other things, that the System (4) process created the Smss.exe process, which created Csrss.exe, Winlogon.exe,
Lsass.exe and Rundll32.exe. Also, Winlogon.exe created Services.exe, which created all of the service-related processes.
System Process (0)
System (4)
smss.exe (404)
csrss.exe (452)
winlogon.exe (476) NetDDE Agent
services.exe (520)
svchost.exe (700)
svchost.exe (724)
svchost.exe (864)
svchost.exe (888)
spoolsv.exe (996)
scardsvr.exe (1040)
alg.exe (1172)
atievxx.exe (1200) ATI video bios poller
InoRpc.exe (1248)
InoRT.exe (1264)
InoTask.exe (1308)
mdm.exe (1392)
dllhost.exe (2780)
lsass.exe (532)
rundll32.exe (500)
explorer.exe (328) Program Manager
WLANMON.exe (1728) TI Wireless LAN Monitor
ISATRAY.EXE (1712) IsaTray
cmmon32.exe (456)
WINWORD.EXE (844) Tlist.doc - Microsoft Word
dexplore.exe (2096) Platform SDK - CreateThread
Find process by module (/m)
The following command finds all of the processes running on the computer that load a particular DLL.
c:\>tlist /m
In response, TList displays process details for Inorpc.exe, Inort.exe, and Inotask.exe. For a description of the output, see the "Find process details using PID" subsection
above.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

UMDH
The User-Mode Dump Heap (UMDH) tool, Umdh.exe, analyzes the Microsoft Windows heap memory allocations for a given process. UMDH has the following modes.

Analyze a running process ("Mode 1"). UMDH captures and analyzes the heap memory allocations for a process. For each allocation, UMDH displays the size of the
allocation, the size of the overhead, the pointer to the allocation and the allocation stack. If a process has more than one active memory heap, UMDH captures all heaps.
This analysis can be displayed in realtime or saved in a log file.
Analyze UMDH log files ("Mode 2"). UMDH analyzes the log files it has previously created. UMDH can compare two logs created for the same process at different
times, and display the calls in which the allocation size increased the most. This technique can be used to find memory leaks.

This section includes:

Preparing to Use UMDH
UMDH Commands

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1111 of 1651

Interpreting a UMDH Log

Interpreting a Log Comparison
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Preparing to Use UMDH

You must complete the configuration tasks described in this section before using UMDH to capture the heap allocations for a process. If the computer is not configured
correctly, UMDH will not generate any results or the results will be incomplete or incorrect.
Create the user-mode stack trace database
Before using UMDH to capture the heap allocations for a process, you must configure Windows to capture stack traces.
To enable stack trace capturing for a process, use GFlags to set the Create user mode stack trace database flag for the process. This can be done by either of the following
methods:

In the GFlags graphical interface, choose the Image File tab. Type the process name, including the file name extension (for example, Notepad.exe). Press the TAB key,
select Create user mode stack trace database, and then click Apply.
Or, equivalently, use the following GFlags command line, where ImageName is the process name (including the file name extension):
gflags /i ImageName +ust

By default, the amount of stack trace data that Windows gathers is limited to 32 MB on an x86 processor, and 64 MB on an x64 or Itanium-based processor. If you must
increase the size of this database, choose the Image File tab in the GFlags graphical interface, type the process name, press the TAB key, check the Stack Backtrace (Megs)
check box, type a value (in MB) in the associated text box, and then click Apply.
Note: Increase this database only when necessary, because it may deplete limited Windows resources. When you no longer need the larger size, return this setting to its
original value.
These settings affects all new instances of the program. It does not affect currently running instances of the program.
Access the Necessary Symbols
Before using UMDH, you must have access to the proper symbols for your application. UMDH uses the symbol path specified by the environment variable
_NT_SYMBOL_PATH. Set this variable equal to a path containing the symbols for your application.
If you also include a path to Windows symbols, the analysis may be more complete. The syntax for this symbol path is the same as that used by the debugger; for details, see
Symbol Path.
For example, if the symbols for your application are located at C:\MyApp\Symbols, and you have installed the Windows symbol files to \\myshare\winsymbols, you would use
the following command to set your symbol path:
set _NT_SYMBOL_PATH=c:\myapp\symbols;\\myshare\winsymbols
As another example, if the symbols for your application are located at C:\MyApp\Symbols, and you want to use the public Microsoft symbol store for your Windows symbols,
using C:\MyCache as your downstream store, you would use the following command to set your symbol path:
set _NT_SYMBOL_PATH=c:\myapp\symbols;srv*c:\mycache*http://msdl.microsoft.com/download/symbols
Disable BSTR Caching
Automation (formerly known as OLE Automation) caches the memory used by BSTR strings. This can prevent UMDH from correctly determining the owner of a memory
allocation. To avoid this problem, you must disable BSTR caching.
To disable BSTR caching, set the OANOCACHE environment variable equal to one (1). This setting must be made before launching the application whose allocations are to
be traced.
Alternatively, you can disable BSTR caching from within the application itself by calling the .NET Framework SetNoOaCache function. If you choose this method, you
should call this function early, because any BSTR allocations that have already been cached when SetNoOaCache is called will remain cached.
If you need to trace the allocations made by a service, you must set OANOCACHE as a system environment variable and then restart Windows for this setting to take effect.
On Windows 2000, in addition to setting OANOCACHE equal to 1, you must also install the hotfix available with
and later versions of Windows.

KB 139071. This hotfix is not needed on Windows XP

Find the Process ID

UMDH identifies the process by its process identifier (PID). You can find the PID of any running process by using Task Manager, Tasklist (Windows XP and later operating
systems), or TList.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1112 of 1651

December 09, 2009

Debugging Tools for Windows

UMDH Commands
UMDH has two different modes, each with its own command syntax and parameters:

Analyze a Running Process Displays all the heap allocation in a process.

Analyze UMDH Logs Compares the allocation list made at two different times for the same process. Analyzing the differences can help to identify memory leaks.

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyze a Running Process

Use the following commands to record and analyze the heap memory allocations in a running process. This analysis focuses on stack traces.
Syntax
umdh -p:PID [-f:LogFile] [-v[:MsgFile]] | [-g] | [-h]
Parameters
-p:PID
Specifies the process to analyze. PID is the process ID of the process. This parameter is required.
To find the PID of a running process, use Task Manager, Tasklist (Windows XP and later operating systems), or TList.
-f:LogFile
Saves the log contents in a text file. By default, UMDH writes the log to stdout (command window).
LogFile specifies the path (optional) and name of the file. If you specify an existing file, UMDH overwrites the file.
Note If UMDH was not started in Administrator mode, or attempts to write to protected paths, it will be denied access.
-v[:MsgFile ]
Verbose mode. Generates detailed informational and error messages. By default, UMDH writes these messages to stderr.
MsgFile specifies the path (optional) and name of a text file. When you use this variable, UMDH writes the verbose messages to the specified file, instead of to stderr. If
you specify an existing file, UMDH overwrites the file.
-g
Logs the heap blocks that are not referenced by the process ("garbage collection").
-h
Displays help.
Comments
On Windows 2000, if UMDH is reporting errors finding the stack trace database, and you have enabled the Create user mode stack trace database option in GFlags, you
might have a symbol file conflict. To resolve it, copy the DBG and PDB symbol files for the application to the same directory, and try again.
Sample Usage
umdh
umdh
umdh
umdh
umdh

-?
-p:2230
-p:2230 -f:dump_allocations.txt
-p:2230 -f:c:\Log1.txt -v:c:\Msg1.txt
-p:2230 -g -f:garbage.txt

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Analyze UMDH Logs

Use the following commands to analyze UMDH logs that were created by running UMDH with the syntax described in Analyze a Running Process. This analysis focuses on
allocations, instead of stack traces.
You can analyze a single log file or compare logs from different runs to detect the changes in the program or driver's memory dump allocations over time.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1113 of 1651

Syntax
umdh [-d] [-v] [-l] File1 [File2] [-h | ?]
Parameters
-d
Displays numeric data in decimal numbers. The default is hexadecimal.
-v
Verbose mode. Includes the traces, as well as summary information. The traces are most helpful when analyzing a single log file.
-l
Includes file names and line numbers in the log. (Please note that the parameter is the lowercased letter "L," not the number one.)
File1 [File2]
Specifies the UMDH log files to analyze.
UMDH creates log files when you run it in the analyze a running process mode and save the log content in a text file (-f).
When you specify one log file, UMDH analyzes the file and displays the function calls in each trace in descending order of bytes allocated.
When you specify two log files, UMDH compares the files and displays in descending order the function calls whose allocations have grown the most between the two
trials.
-h | ?
Displays help.
Sample Usage
umdh dump.txt
umdh -d -v dump.txt
umdh dump1.txt dump2.txt

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Interpreting a UMDH Log

UMDH log files display the list of heap allocations in the process and the stacks where the allocations were made.
To generate a log, the following command can be used:
umdh -p:1204 -f:log1.txt
where 1204 is the process ID of the process being analyzed and log1.txt is the file in which the log will be created.
The log in this state is not readable as the symbols are not resolved. UMDH can be instructed to resolve the symbols by simulating a log comparison with an empty log, using
the command:
umdh v log1.txt

> result.txt

The result is interpreted as for a Log Comparison.

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Interpreting a Log Comparison

You can generate multiple UMDH logs of the same process over time. Then, you can use UMDH to compare the logs and determine which call stack allocations have grown
the most between trials.
For example, the following command directs UMDH to compare two UMDH logs, Log1.txt and Log2.txt, and redirects the output to a third file, Compare.txt.
umdh v Log1.txt Log2.txt > Compare.txt
The resulting Compare.txt file lists the call stacks recorded in each log and, for each stack, displays the change in heap allocations between the log files.
For example, the following line from the file shows the change in allocation size for the functions in the call stack labeled "Backtrace00053."
In Log1.txt, the calls in the stack accounts for 40,432 (0x9DF0) bytes, but in Log2.txt, the same call stack accounts for 61,712 (0xF110) bytes, a difference of 21,280 (0x5320)
bytes.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1114 of 1651

+ 5320 (f110 - 9df0) 3a allocs BackTrace00053

Total increase == 5320
Following is the stack for the allocation:
ntdll!RtlDebugAllocateHeap+0x000000FD
ntdll!RtlAllocateHeapSlowly+0x0000005A
ntdll!RtlAllocateHeap+0x00000808
MyApp!_heap_alloc_base+0x00000069
MyApp!_heap_alloc_dbg+0x000001A2
MyApp!_nh_malloc_dbg+0x00000023
MyApp!_nh_malloc+0x00000016
MyApp!operator new+0x0000000E
MyApp!LeakyFunc+0x0000001E
MyApp!main+0x0000002C
MyApp!mainCRTStartup+0x000000FC
KERNEL32!BaseProcessStart+0x0000003D
An examination of the call stack shows that the LeakyFunc function is allocating memory by using the Visual C++ run-time library. If examination of the other log files
shows that the allocation grows over time, you might be able to conclude that memory allocated from the heap is not being freed.
See Also
Using UMDH to Find a User-Mode Memory Leak
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

USBView
USBView (Universal Serial Bus Viewer, Usbview.exe) is a Windows graphical user interface application that enables you to browse all USB controllers and connected USB
devices on your computer.
USBView works on all versions of Windows. It is included in the Debugging Tools for Windows package to assist in the discovery of USB ports when initiating a USB
debugging session.
Using USBView
USBView can enumerate USB host controllers, USB hubs, and attached USB devices. It can also query information about the devices from the registry and through USB
requests to the devices.
The main USBView window contains two panes. The left pane displays a connection-oriented tree view, enabling you to select any USB device.
The right pane displays the USB data structures that pertain to the selected USB device. These structures include Device, Configuration, Interface, and Endpoint Descriptors,
as well as the current device configuration.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Tools Related to Symbol Files and Source Files

This section describes some tools that help you to analyze symbols and symbol files, alter the contents of symbol files, load source files from a source server, and cull the files
in the downstream store used by a symbol server or source server.
AgeStore
DBH
PDBCopy
SrcSrv
SymChk
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1115 of 1651

AgeStore
The AgeStore tool (agestore.exe) deletes files in a directory or directory tree, based on their last access dates. This program is particularly useful for removing old files from
the downstream store used by a symbol server, in order to conserve disk space.
This section includes:
Using AgeStore
AgeStore Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using AgeStore
AgeStore is a tool that deletes files in a directory or directory tree, based on their last access dates. Its primary use is for removing old files from the downstream store used by
a symbol server or a source server, in order to conserve disk space. It can also be used as a general file deletion tool.
AgeStore can delete all files in a single directory (the target directory), or in all the directories within a tree (the target tree). The -s option indicates that an entire tree is to be
targeted.
There are three ways to specify which files within the target directory or target tree are to be deleted. The agestore -date=Month-Day-Year command deletes all files that
were last accessed prior to the specified date. The agestore -days=NumberOfDays command deletes all files that were last accessed more than the specified number of days
ago. The agestore -size=SizeRemaining command deletes all files in the target directory or target tree, beginning with the least-recently-accessed files, until the total size of
the remaining files is less than or equal to SizeRemaining.
For example, the following command deletes all files in C:\MyDir that were last accessed prior to January 7, 2008:
agestore c:\mydir -date=01-07-2008
The following command deletes all files in the directory tree subordinate to C:\symbols\downstreamstore that were last accessed over thirty days ago:
agestore c:\symbols\downstreamstore -days=30 -s
The following command deletes files in the directory tree subordinate to C:\symbols\downstreamstore, beginning with those accessed longest ago, until the total size of all
files in this tree is less than or equal to 50,000 bytes:
agestore c:\symbols\downstreamstore -size=50000 -s
The -l option causes AgeStore to delete no files, but merely to list all the files that would be deleted without this option. Before you use any AgeStore command you should
run the intended command with the -l option added, to verify that it will delete exactly those files you intend it to delete.
For the complete command line syntax, see AgeStore Command-Line Options.
Running AgeStore on Windows Vista and Later
Because AgeStore deletes files based on the last time that they were accessed, it can run successfully only if your your file system stores Last Access Time (LAT) data. In the
NTFS file system, LAT data storage can be either enabled or disabled. If it is disabled, AgeStore will not run, but will display the following error message instead:
Last-Access-Time support is disabled on this computer.
Please read the documentation for more details.
In Windows 2000, Windows XP, and Windows Server 2003, LAT data storage is enabled by default. In Windows Vista and later versions of Windows, LAT data storage is
disabled by default, and therefore AgeStore will not run unless you first enable this data.
In Windows Vista and later versions of Windows, you can use the FSUtil (Fsutil.exe) tool to enable the gathering of LAT data. From a Command Prompt window, issue the
following command:
fsutil behavior set disablelastaccess 0
To disable the gathering of LAT data, using the following command:
fsutil behavior set disablelastaccess 1
These changes take effect after the next restart of Windows.
The FAT32 file system always stores LAT information (although only the date, and not the time, are stored). Therefore, AgeStore works with FAT32 file systems. However,
since AgeStore will not run when the NTFS LAT is disabled, you must enable NTFS LAT even if your file system is FAT32.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1116 of 1651

Debugging Tools for Windows

AgeStore Command-Line Options

The AgeStore command line uses the following syntax. The parameters can be included in any order.
agestore [PathSpec] -date=Month-Day-Year Options
agestore [PathSpec] -days=NumberOfDays Options
agestore [PathSpec] -size=SizeRemaining Options
agestore [PathSpec] -size Options
agestore -?
Parameters
PathSpec
Specifies the target directory in which files are to be deleted. If the -s option is used, PathSpec specifies the root directory of the target tree in which files are to be
deleted. PathSpec may be the absolute or relative path of a directory on the local computer, or a UNC path. If PathSpec contains spaces, it must be enclosed in quotation
marks. If PathSpec is omitted, AgeStore uses the current working directory.
-date=Month-Day-Year
Specifies the cutoff date for deleting files. All files that were last accessed prior to the specified date will be deleted. The date must be specified in the format
Month-Day-Year, with hyphens between the month and day and between the day and the year. Leading zeros in Month and Day are optional. The year can be specifed
with two digits or four. Thus you can indicate the date of January 5, 2008 as 01-05-2008 or 1-5-08.
-days=NumberOfDays
Specifies the cutoff date and time for deleting files. All files that were last accessed prior to the specified number of days ago will be deleted. NumberOfDays specifies an
integer number of 24-hour days. For example, if the specifier -days=3 is used at 6:00 PM on February 17, 2008, all files last accessed prior to 6:00 PM on February 14,
2008 will be deleted.
-size=SizeRemaining
Specifies the total size of the files that should remain after the deletion, in bytes. When this switch is used, AgeStore deletes files in the target directory or target tree,
beginning with the files accessed least recently, until the total size of the remaining files is less than or equal to SizeRemaining. When the -s option is used, AgeStore
targets an entire directory tree, and SizeRemaining specifies the total size of files that should remain in this entire directory tree after deletion.
-size
Causes AgeStore to list the total size of all files in the target directory or target tree. No files are deleted.
Options
Any combination of the following options.
-l
Causes AgeStore not to delete any files, but merely to list all the files that would be deleted if this same command were run without the -l option.
-s
Causes AgeStore to treat the entire directory tree subordinate to PathSpec as the target. When the -s option is not used, the directory specified by PathSpec becomes
the target directory in which files will be deleted. When the -s option is used, the directory specified by PathSpec and all subdirectories under it become the target
tree in which files will be deleted.
-k
Causes AgeStore to keep any empty subdirectories. If this option is not used, AgeStore deletes the target directory if it is completely empty after the command runs.
If the -s option is used without the -k option, all empty directories in the target directory tree will be deleted after AgeStore has completed its file deletion -- even the
root directory itself, if it becomes empty. If there are directories in this tree that happen to be already empty before AgeStore runs, AgeStore deletes these directories
as well. However, if the AgeStore command results in no file deletion (for example, if the -size=SizeRemaining parameter specifies a size larger than the total size of
all files in the target tree), empty directories are not deleted. If the -s option is not used, empty directories are never deleted, and the -k option is ignored.
-q
Quiet mode. If this option is not included, AgeStore lists all files as they are deleted.
-y
Suppresses the (y/n) prompt. If this option is not used, AgeStore prompts you with an "Are you sure?" prompt before deleting any files.
-?
Displays help text for the AgeStore command line.
Additional Information
For more information about the AgeStore tool, see Using AgeStore.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DBH
The DBH tool (dbh.exe) is a command-line tool that displays information about the contents of a symbol file.
DBH exposes the functionality of the DbgHelp API (dbghelp.dll) through a convienient command-line interface. Therefore, its behavior may change as DbgHelp is updated.
The source code for one version of DBH is available in the Windows Software Development Kit (WSDK).
This section includes:
Using DBH

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1117 of 1651

Additional DBH Examples

DBH Command-Line Options
DBH Commands
For more information about the DbgHelp API, see the Debug Help Library documentation, which is installed as part of Debugging Tools for Windows if you perform a
custom install and select the SDK feature and its subfeatures.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using DBH
DBH is a command-line tool that exposes many of the functions in the DbgHelp API (dbghelp.dll). It can display information about the contents of a symbol file, display
specific details of the symbols in the file, and search through the file for symbols matching various criteria.
The functionality provided by DBH is similar to that provided within WinDbg, KD, and CDB by commands such as x (Examine Symbols).
Running DBH in Interactive Mode
You start DBH with a simple command line, on which you specify the target module whose symbols you wish to investigate. See DBH Command-Line Options for the full
syntax.
When DBH starts, it loads the symbols for the specified module, and then presents you with a prompt at which you can type a variety of commands. See DBH Commands for
a list of available commands.
For example, the following sequence starts DBH by specifying the target process with process ID 4672, then executes the enum command at the DBH prompt to display
symbols matching a specific pattern, and then executes the q command to quit DBH:
C:\> dbh -p:4672
400000 : TimeTest
77820000 : ntdll
77740000 : kernel32
pid:4672 mod:TimeTest[400000]: enum TimeTest!ma*
index
1
3
5

address
42cc56 :
415810 :
415450 :

name
main
malloc
mainCRTStartup

pid:4672 mod:TimeTest[400000]: q
goodbye
Running DBH in Batch Mode
If you wish to run only a single DBH command, you can specify it at the end of the command line. This causes DBH to start, load the specified module, run the specified
command, and then exit.
For example, the previous example could be replaced with a single command line:
C:\> dbh -p:4672 enum TimeTest!ma*
400000 : TimeTest
77820000 : ntdll
77740000 : kernel32
index
1
3
5

address
42cc56 :
415810 :
415450 :

name
main
malloc
mainCRTStartup

This method of running DBH is called batch mode, because it can be easily used in batch files. This version of the command line can also be followed by a pipe ( | ) which
redirects the DBH output to another program.
Specifying the Target
DBH can select a target in three ways: by the process ID of a running process, by the name of the executable, or by the name of the symbol file. For example, if there is
exactly one instance of MyProg.exe currently running, with process ID 1234, then the following commands are almost equivalent:
C:\> dbh -v -p:1234
C:\> dbh -v c:\mydir\myprog.exe
C:\> dbh -v c:\mydir\myprog.pdb
One difference between these commands is that when you start DBH by specifying the process ID, DBH uses the actual virtual addresses being used by this process. When

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1118 of 1651

you start DBH by specifying the executable name or the symbol file name, DBH assumes that the module's base address is a standard value (for example, 0x01000000). You
can then use the base command to specify the actual base address, thus shifting the addresses of all the symbols in the module.
DBH does not attach to the target process in the way that a debugger does. DBH cannot cause a process to begin or end, nor can it alter how that process runs. For DBH to
attach to a process by its process ID, the target process has to be running, but once DBH has been started the target process can be terminated and DBH will continue to access
its symbols.
Decorated and Undecorated Symbols
By default, DBH uses undecorated symbol names when displaying and searching for symbols. If you turn off the SYMOPT_UNDNAME symbol option, or include the -d
option on the DBH command line, decorations will be included.
For information on symbol decorations, see Public and Private Symbols.
Exiting DBH
To exit DBH, use the q command at the DBH prompt.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Additional DBH Examples

Here are additional examples of commands that can be issued at the DBH prompt.
Displaying Private Symbols and Public Symbols
If the target is a full symbol file, then each public symbol appears twice in the file: in the public symbol table, and in the private symbol data. The copy in the public symbol
table often contains various decorations (prefixes and suffixes). For details, see Public and Private Symbols.
DBH can display information about this symbol from the private symbol data, from the public symbol table without decorations, and from the public symbol table with
decorations. Here is an example in which all three of these are displayed, using the command addr 414fe0 each time.
The first time this command appears in this example, DBH uses the default symbol options, so the resulting information comes from the private symbol data. Note that this
information includes the address, size, and data type of the function fgets. Then, the command symopt +4000 is used, which turns on the SYMOPT_PUBLICS_ONLY
option. This causes DBH to ignore the private symbol data, and therefore when the addr 414fe0 command is run the second time, DBH uses the public symbol table, and no
size or data type information is shown for the function fgets. Finally, the command symopt -2 is used, turning off the SYMOPT_UNDNAME option and causing DBH to
include decorations. When the addr 414fe0 runs this final time, it shows the decorated version of the function name, _fgets.
pid:4308 mod:TimeTest[400000]: addr 414fe0
fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

fgets
414fe0
113
0
7e
400000
0
0
SymTagNull (0)
SymTagFunction (5)
7d

pid:4308 mod:TimeTest[400000]: symopt +4000

Symbol Options: 0x10c13
Symbol Options: 0x14c13
pid:4308 mod:TimeTest[400000]: addr 414fe0
fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

fgets
414fe0
0
0
0
400000
0
0
SymTagNull (0)
SymTagPublicSymbol (a)
7f

pid:4308 mod:TimeTest[400000]: symopt -2

Symbol Options: 0x14c13

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1119 of 1651

Symbol Options: 0x14c11

pid:4308 mod:TimeTest[400000]: addr 414fe0
_fgets
name
addr
size
flags
type
modbase
value
reg
scope
tag
index

:
:
:
:
:
:
:
:
:
:
:

_fgets
414fe0
0
0
0
400000
0
0
SymTagNull (0)
SymTagPublicSymbol (a)
7f

If the -d command-line option had been used, the results would have shown the decorated public name from the beginning.
Determining the Decorations of a Specific Symbol
DBH can determine the decorations on a specific symbol. This can be useful when used in conjunction with a program that requires symbols to be specified with their
decorations, such as PDBCopy.
For example, suppose you know that the symbol file mysymbols.pdb contains a symbol whose undecorated name is MyFunction1. To find the decorated name, use the
following procedure.
First, start DBH without the -d command-line option, and then use the symopt +4000 command so that all information comes from the public symbol table:
C:\> dbh c:\mydir\mysymbols.pdb
mysymbols [1000000]: symopt +4000
Symbol Options: 0x10c13
Symbol Options: 0x14c13
Next, use the name command or the enum command to display the address of the desired symbol:
mysymbols [1000000]: enum myfunction1
index
2ab

address
102cb4e :

name
MyFunction1

Now use symopt -2 to make symbol decorations visible, and then use the addr command with the address of this symbol:
mysymbols [1000000]: symopt -2
Symbol Options: 0x14c13
Symbol Options: 0x14c11
mysymbols [1000000]: addr 102cb4e
_MyFunction1@4
name : _InterlockedIncrement@4
addr : 102cb4e
size : 0
flags : 0
type : 0
modbase : 1000000
value :
0
reg : 0
scope : SymTagNull (0)
tag : SymTagPublicSymbol (a)
index : 2ab
This reveals that the decorated name of the symbol is _MyFunction1@4.
Decoding Symbol Decorations
The undec command can be used to reveal the meaning of C++ symbol decorations. In the following example, the decorations attached to ??_C@_03GGCAPAJC@Sep?
$AA@ are decoded to indicate that it is a string:
dbh: undec ??_C@_03GGCAPAJC@Sep?$AA@
??_C@_03GGCAPAJC@Sep?$AA@ =
`string'
The following examples decode the decorations attached to three function names, revealing their prototypes:
dbh: undec ?gcontext@@3_KA

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1120 of 1651

?gcontext@@3_KA =
unsigned __int64 gcontext

dbh: undec ?pathcpy@@YGXPAGPBG1K@Z

?pathcpy@@YGXPAGPBG1K@Z =
void __stdcall pathcpy(unsigned short *,unsigned short const *,unsigned short const *,unsigned long)

main+ea
name
addr
size
flags
type
modbase
value
reg
scope
tag

:
:
:
:
:
:
:
:
:
:

main
42cc56
42b
0
2
400000
0
0
SymTagNull (0)
SymTagFunction (5)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1122 of 1651

index : 1
Finally, the del command can delete the symbol magic, returning all the symbols to their original ranges:
pid:6040 mod:MyModule[400000]: del magic
pid:6040 mod:MyModule[400000]: enum timetest!ma*
index
1
3
5

address
42cc56 :
415810 :
415450 :

name
main
malloc
mainCRTStartup

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DBH Command-Line Options

The DBH command line uses the following syntax.
dbh [Options] -p:PID [Command]
dbh [Options] ExecutableName [Command]
dbh [Options] SymbolFileName [Command]
dbh -?
dbh -??
Parameters
-p:PID
Specifies the process ID of the process whose symbols are to be loaded.
ExecutableName
Specifies the executable file whose symbols are to be loaded, including the file name extension (usually .exe or .sys). You should include a relative or absolute directory
path; if no path is included, the current working directory is assumed. If the specified file is not found in this location, DBH searches for it using SymLoadModuleEx.
SymbolFileName
Specifies the symbol file whose symbols are to be loaded, including the file name extension (.pdb or .dbg). You should include a relative or absolute directory path; if no
path is included, the current working directory is assumed.
Options
Any combination of the following options.
-d
Causes decorated names to be used when displaying symbols and searching for symbols. When this option is used, SYMOPT_PUBLICS_ONLY is turned on, and
both SYMOPT_UNDNAME and SYMOPT_AUTO_PUBLICS are turned off. This is equivalent to issuing the command symopt +4000 followed by
symopt -10002 after DBH is running.
-s:Path
Sets the symbol path to the specified Path value.
-n
Turns on noisy symbol loading. Additional information is displayed about the search for symbols. The name of each symbol file is displayed as it is loaded. If the
debugger cannot load a symbol file, it displays an error message. Error messages for .pdb files are displayed in text. Error messages for .dbg files are in the form of
an error code, explained in the winerror.h file. Not all of these messages are useful, but some of them may be helpful to analyze why a symbol file cannot be found
or matched. If an image file is loaded solely to recover symbolic header information, this is displayed as well.
Command
Causes DBH to run, execute the specified Command, and then exit. For a list of possible commands, see DBH Commands.
-?
Displays help text for the DBH command line.
-??
Displays help text for the DBH command line, and displays a list of all DBH commands.
Additional Information
For more information about the DBH tool, see Using DBH.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DBH Commands

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1123 of 1651

From the DBH command line, you can use a variety of commands to analyze symbols and symbol files.
The following table lists the commands that control the DBH options and perform other basic tasks.
Command
verbose
[on|off]
sympath
[Path]
symopt
Options

Effect
Turns verbose mode on or off. With no parameter, displays the current verbose mode setting.
Sets the symbol search path. With no parameter, displays the current symbol search path.
Sets the symbol options. With no + or -, the value of Options replaces the current symbol options. If + or - is used, Options specifies the options to be added or
removed; there must be a space before the + or - but no space after it. With no parameter, the current symbol options are displayed. When DBH is launched, the
default value of all the symbol options is 0x10C13. For a list of available options, see Setting Symbol Options.

symopt
+Options
symopt Options
symopt
help
quit

Displays help text for the DBH commands.

Quits the DBH program.

The following table lists the commands that load, unload, and rebase the target module. These commands cannot be used if DBH was started by specifying a process ID on the
command line.
Command
Effect
load File
Loads the specified module. File should specify the path, file name, and file name extension of either the executable file or the symbol file.
unload
Unloads the current module.
base Address Sets the default base address to the specified value. All symbol addresses will be determined relative to this base address.
The following table lists the commands that search for files and display directory information.
Command
findexe File
Path
finddbg File
Path
dir File Path
srchtree Path
File
ffpath File

Effect
Locates the specified executable file in the specified path, using the FindExecutableImage routine.
Locates the specified .dbg file in the specified path. Including the .dbg extension is optional.
Locates the specified file in the specified path or in any subdirectory under this path, using the EnumDirTree routine.
Locates the specified file in the specified path or in any subdirectory under this path, using the SearchTreeForFile routine. This command is the same as
dir, except that the parameters are reversed.
Finds the specified file in the current symbol path.

The following table lists the commands that parse the module list and control the default module. The default module and its base address are displayed on the DBH prompt.
Command
mod
Address
refresh
omap
epmod PID
info
obj Mask
src Mask
enummod

Effect
Changes the default module to the module with the specified base address.
Refreshes the module list.
Displays the module OMAP structures.
Enumerates all the modules loaded for the specified process. PID specifies the process ID of the desired process.
Displays information about the currently loaded module.
Lists all object files associated with the default module that match the specified pattern. Mask may contain a variety of wildcard characters and specifiers; see
String Wildcard Syntax for details.
Lists all source files associated with the default module that match the specified pattern. Mask may contain a variety of wildcard characters and specifiers; see
String Wildcard Syntax for details.
Enumerates all loaded modules. There is always at least one module, unless DBH is running without a target, in which case there are none.

The following table lists the commands that display and search for symbols.
Command
enum Module!Symbol

enumaddr Address
addr Address
name [Module!]Symbol
next [Module!]Symbol

Effect
Enumerates all symbols matching the specified module and symbol. Module specifies the module to search (without the file name extension).
Symbol specifies a pattern that the symbol must contain. Both Module and Symbol may contain a variety of wildcard characters and specifiers;
see String Wildcard Syntax for details.
Enumerates all symbols associated with the specified address.
Displays detailed information about the symbols associated with the specified address.
Displays detailed information about the specified symbol. An optional Module specifier may be included. Wildcards should not be used,
because if multiple symbols match the pattern, name only displays the first of them.
Displays detailed information about the next symbol after the specified symbol or address. If a symbol is specified by name, an optional
Module specifier may be included, but wildcards should not be used.

next Address

prev [Module!]Symbol

Displays detailed information about the first symbol previous to the specified symbol or address. If a symbol is specified by name, an optional
Module specifier may be included, but wildcards should not be used.

prev Address

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

line File#LineNum

srclines File LineNum

laddr Address
linenext
lineprev
locals Function [Mask]
type TypeName
elines [Source [Obj]]

index Value
scope Address

Page 1124 of 1651

Displays the hexadecimal address of the binary instruction associated with the specified source line, and any symbols associated with this line.
Also sets the current line number equal to the specified line number. File specifies the name of the source file, and LineNum specifies the line
number within that file; these should be separated with a number sign ( # ).
Displays the object files associated with the specified source line, and the hexadecimal address of the binary instruction associated with this
line. Does not change the current line number. File specifies the name of the source file, and LineNum specifies the line number within that
file; these should be separated with a space.
Displays the source file and line number corresponding to the symbol located at the specified address.
Increments the current line number, and displays information about the new line number.
Decrements the current line number, and displays information about the new line number.
Displays all local variables contained within the specified function. If Mask is included, only those locals matching the specified pattern are
displayed; see String Wildcard Syntax for details.
Displays detailed information about the specified data type. TypeName specifies the name of the data type (for example, WSTRING). If no
type name matches this value, any matching symbol will be displayed. Unlike most DBH command parameters, TypeName is case-sensitive.
Enumerates all source lines matching the specified source mask and object mask. Source specifies the name of the source file, including the
absolute path and file name extension. Obj specifies the name of the object file, including the relative path and file name extension. Both
Source and Obj may contain a variety of wildcard characters and specifiers; see String Wildcard Syntax for details. If a parameter is omitted
this is equivalent to using the asterisk (*) wildcard. If you do not wish to specify path information, prefix the file name with *\ to indicate a
wildcard path.
Displays detailed information about the symbol with the specified index value.
Displays detailed information about the parent of the specified symbol. The symbol may be specified by address or by name.

scope [Module!]Symbol
srch [mask=Symbol]
[index=Index] [tag=Tag]
[addr=Address] [globals]
uw Address
dtag
etypes
dump

Searches for all symbols that match the specified masks. Symbol specifies the symbol name. It should not include the module name, but it may
contain wildcard characters and specifiers; see String Wildcard Syntax for details. Index specifies the hexadecimal address of a symbol to be
used as the parent for the search. Tag specifies the hexadecimal symbol type classifier (SymTagXxx) value that must match the symbol.
Address specifies the address of the symbol. If globals is included, only global symbols will be displayed.
Displays the unwind information for the function at the specified address.
Displays all the symbol type classifier (SymTagXxx) values.
Enumerates all data types.
Displays a complete list of all symbol information in the target file.

The following table lists the commands that relate to symbol servers and symbol stores.
Command
home [Path]

Effect
Sets the home directory used by SymSrv and SrcSrv for the default
downstream store. If the symbol path contains a reference to a symbol
server that uses a default downstream store, then the sym subdirectory of
the home directory will be used for the downstream store. With no
parameter, home displays the current home directory.

srvpath
Tests whether the specified path is the path of a symbol store.
Path
srvind File Finds the symbol server index that corresponds to the specified file. The symbol
server index is a unique value based on the contents of the file, regardless of
whether it actually has been added to any symbol store. File should specify the file
name and absolute path of the desired file.
fii File
Displays the symbol server indexes for the specified binary file and its associated
files.
getfile File Displays the file with the specified name and symbol server index. File specifies
Index
the name of the desired file; this should not include its path. Index specifies the
symbol server index of the desired file. DBH uses the SymFindFileInPath routine
to search the tree under the current symbol path for a file with this name and this
index.
sup Path
Stores a file in a symbol store, based on the values of the parameters. Path
File1 File2 specifies the directory path of the symbol store. File1 and File2 are used to create
a delta value, which is in turn used to determine the file being stored.
storeadd
Adds the specified file to the specified symbol store. Store should be the root path
File Store
of the symbol store.
The following table lists the DBH commands that apply to real and imaginary symbols.
Command
undec Name
add Name
Address Size
del Name

Effect
Reveals the meaning of the decorations attached to the specified symbol name. Name can be any string; it need not correspond to a currently loaded symbol.
If Name contains C++ decorations, the meaning of these decorations is displayed.
Adds the specified imaginary symbol to the list of symbols loaded in DBH. Name specifies the name of the symbol to be added, Address specifies its
hexadecimal address, and Size its hexadecimal size in bytes. This is treated like any other symbol in later DBH commands, until the DBH session is ended
with quit or unload, or until the imaginary symbol is deleted with del. The actual target symbol file is not altered.
Deletes an imaginary symbol previously added with the add command. The symbol can be specified either by name or by address. This cannot be used to
delete real symbols.

del Address

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1125 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

PDBCopy
The PDBCopy tool (pdbcopy.exe) is a command-line tool that removes private symbol information from a symbol file. It can also remove selected information from the public
symbol table.
This section includes:
Using PDBCopy
Choosing Which Public Symbols to Remove
PDBCopy Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Perforce
Microsoft Visual SourceSafe
Microsoft Team Foundation Server

You can also create a custom script to index your code for a different source control system. One such module for Subversion is included in this package. Anyone interested in
using SrcSrv with CVS should send e-mail to [email protected].
SrcSrv includes five tools that are used in the source indexing process:
The Srcsrv.ini File
The Ssindex.cmd Script
The SrcTool Utility
The PDBStr Tool
The VSSDump Tool
These tools are installed with Debugging Tools for Windows in the subdirectory srcsrv, and should remain installed in the same path as SrcSrv. The PERL scripts in these
tools require PERL 5.6 or later.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The Srcsrv.ini File

The Srcsrv.ini file is the master list of all source control servers. Each entry has the following format:
MYSERVER=ServerInfo
When using Perforce, the ServerInfo consists of the full network path to the server, followed by a colon, followed by the port number it uses. For example:
MYSERVER=machine.corp.company.com:1666
Srcsrv.ini is a required file when you are actually source indexing a build using the modules shipped with this package. This entry creates an alias that is used to describe the
server info. The value should be unique for every server that you support.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1130 of 1651

This file can also be installed on the computer running the debugger. When SrcSrv starts, it looks at Srcsrv.ini for values; these values override the information contained in
the .pdb file. This enables users to configure a debugger to use an alternative source control server at debug time. However, if you manage your servers well and do not
rename them, there should be no need to include this file with your client debugger installations.
This file also serves other purposes on the client side. For more information, see the sample Srcsrv.ini file installed with SrcSrv tools.
Using a Different Location or File Name
By default, SrcSrv uses as its master configuration file the file named Srcsrv.ini, located in the srcsrv subdirectory of the Debugging Tools for Windows installation directory.
You can specify a different file for configuration by setting the SRCSRV_INI_FILE environment variable equal to the full path and file name of the desired file.
For example, if several people want to share a single configuration file, they could place it on a share accessible to all of their systems, and then set an environment variable
like the following:
set SRCSRV_INI_FILE=\\ourserver\ourshare\bestfile.txt

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The Ssindex.cmd Script

The Ssindex.cmd script builds the list of files checked into source control along with the version information of each file. It stores a subset of this information in the .pdb files
generated when you built the application. SSIndex uses one of the following Perl modules to interface with source control:

p4.pm (Perforce)
vss.pm (Visual SourceSafe)
tfs.pm (Team Foundation Servers)
svn.pm (Subversion)

For more information, run Ssindex.cmd with the -? or -?? (verbose help) option or examine the script.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The SrcTool Utility

The SrcTool (Srctool.exe) utility lists all files indexed within the .pdb file. For each file, it lists the full path, source control server, and version number of the file. You can use
this information for reference.
You can also use SrcTool to list the raw source file information from the .pdb file. To do this, use the s switch on the command line.
SrcTool has other options as well. Use the ? switch to see them. Of most interest is that this utility can be used to extract all of the source files from version control. This is
done with the -x switch.
Note: Previous versions of this program created a directory called src below the current directory when extracting files. This is no longer the case. If you want the src
directory used, you must create it yourself and run the command from that directory.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The PDBStr Tool

The PDBStr (Pdbstr.exe) tool is used by the indexing scripts to insert the version control information into the srcsrv alternative stream of the target .pdb file. It can also read
any stream from a .pdb file. You can use this information to verify that the indexing scripts are working properly.
For more information, run PDBStr with the -? option.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1131 of 1651

The VSSDump Tool

The VSSDump (Vssdump.exe) tool is used by the indexing script for Microsoft Visual SourceSafe. It gathers the list of source files to be indexed. This program is also a
valuable command-line utility that you can use to examine which files may be processed by the indexing script.
To prepare for source indexing, edit Srcsrv.ini so that it contains an entry for your version control server. This is an operation that you must do only once. Details are listed in
the sample version Srcsrv.ini. You can use an environment variable or switch to the indexing script to denote the location of this file. However, it is best to put it in the same
directory as the script because the contents of this file are intended to be global across all projects in your business or development system. This file serves to uniquely
identify different version control servers. Note that you can provide a different version of this file to debuggers so that they look at a replicated copy of the version control
server, which can be useful if you want to reduce traffic on the server.
To source-index a particular build, make certain that no source files are checked out on the build computer. If any files are checked out and edited, those changes are not
reflected in the final source indexed .pdb files. Furthermore, if your build process includes a pre-compilation pass that generates source files from other files, you must check
in those generated files to version control as part of the pre-compilation.
Upon completion of the build, set the current working directory to be the root of all source files and generated .pdb files. Then run SSIndex. You must specify what version
control system you are using as a parameter. For example:
ssindex.cmd server=vss
SSIndex accepts parameters that allow you to run the script from anywhere and to specify the location of the source files and .pdb files separately. This is most useful if the
source is kept in another location from the output .pdb files. For example:
ssindex.cmd server=vss source=c:\source symbols=c:\outputdir
These directories can also be specified with environment variables. Use the -? or -?? command line options for more information.
Here is an example of the output generated by this script:
C:\ >ssindex.cmd -system=vss -?
-------------------------------------------------------------------------------SSIndex.cmd [/option=<value> [...]] [ModuleOptions] [/Debug]
General SrcSrv settings:
NAME
SWITCH
ENV. VAR
Default
----------------------------------------------------------------------------1) srcsrv.ini
Ini
SRCSRV_INI
.\srcsrv.ini
2) Source root
Source
SRCSRV_SOURCE
.
3) Symbols root
Symbols
SRCSRV_SYMBOLS .
4) Control system
System
SRCSRV_SYSTEM
<N/A>
5) Save File (opt.) Save
SRCSRV_SAVE
<N/A>
6) Load File (opt.) Load
SRCSRV_LOAD
<N/A>
Visual Source Safe specific settings:
NAME
SWITCH
ENV. VAR
Default
----------------------------------------------------------------------------A) VSS Server
Server
SSDIR
<N/A>
B) VSS Client
Client
SSROOT
<Current directory>
C) VSS Project
Project
SSPROJECT
<N/A>
D) VSS Label
Label
SSLABEL
<N/A>
Precedence is: Default, environment, cmdline switch. (ie. env overrides default,
switch overrides env).
Using '/debug' will turn on verbose output.
Use "SSIndex.cmd -??" for verbose help information.
See SrcSrv documentation for more information.
-------------------------------------------------------------------------------You can also use one of the provided wrapper scripts (Vssindex.cmd) to avoid specifying the version control system. The script source-indexes all .pdb files found in the
current directory and below with version control information to locate all source files found in the current directory and below. You can specify different locations for these
files by using environment variables and command-line switches.
Upon completion of the source indexing, you can test the output by running SrcTool on the .pdb files. This program displays data that indicates whether or not the .pdb file is
source indexed. It also displays the specific information for every source file. Lastly, it displays the number of indexed sources and the number of sources that no indexing
information was found for. It sets an %ERRORLEVEL% of -1 if the file is not source-indexed. Otherwise, it sets %ERRORLEVEL% to the number of indexed source files.
VSSDump can also be used independently to diagnose issues while source-indexing. The syntax is as follows:
vssdump.exe Options
Options can be any combination of the following options.
-a
Causes all projects to be searched, rather than restricting to the current project. This option may not be used with the p option.
-p ProjectName
Causes VSSDump to restrict its search to the project specified by ProjectName. If this option is not present, the current project is used. This option may not be used with
the a option.
-d RootDirectory
Causes VSSDump to restrict its search to the root directory specified by RootDirectory. If this option is not present, the current directory is used.
-l Label
Causes VSSDump to list only those files with a label that matches that specifed by Label.
VSSDump-v SharePath
Specifies that the location of the Virtual SourceSafe database is in SharePath. This option overrides the path specified in the SSDIR environment variable.
-r
Causes VSSDump to search subdirectories recursively.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1132 of 1651

-f
Causes VSSDump to list directories containing source files without listing the files themselves.
-i
Causes VSSDump to ignore the current directory and list the entire project. This option may not be used with r.
-s
Causes VSSDump to format ouput for use with script files.
-c
Causes VSSDump to display only the Virtual SourceSafe configuration information.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Source Control Systems

SrcSrv includes provider modules for Visual SourceSafe (vss.pm), Perforce (p4.pm), Team Foundation Servers (tfn.pm), and Subversion (svn.pm). There is also a Concurrent
Versions Systems (CVS) module for use with SrcSrv, but it has not been tested extensively. It is also possible to generate your own modules to support other versions of
control systems.
This section includes:
Using Visual SourceSafe
Debugging with Visual SourceSafe
Using CVS
Using Other Source Control Systems
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Visual SourceSafe

Visual SourceSafe is an x86-based application, and the source indexing scripts and tools associated with it are installed only with the x86 package of Debugging Tools for
Windows.
To successfully use Visual SourceSafe with SrcSrv, several defaults must be set in the system, including the Visual SourceSafe default database, the current project, and the
working folder. You must also stamp each build project with a label so that Visual SourceSafe can differentiate between versions of a given file. Finally, you must set up any
credentials needed to access the Visual SourceSafe database.
Visual SourceSafe Database
The default Visual SourceSafe database can be set with the SSDIR environment variable. If it is not set there, the SrcSrv indexing script can usually determine this from the
registry. If it cannot, the script prompts you to set SSDIR. Regardless, this database value must be listed in your Srcsrv.ini file along with a simple alias to identify the
database. More instructions can be found in the comments in Srcsrv.ini. You should add the entry in the variables section of Srcsrv.ini using the following syntax:
MYDATABASE=\\server\VssShare
Current Project
Visual SourceSafe uses the concept of a current project. The SrcSrv indexing script respects this value and limits processing to those source files that are part of the current
project. To display the current project, use the following command:
ss.exe project
To change the current project, use the following command:
ss.exe cp Project
where Project indicates the current project. For example, to process all projects, set the current project to the root:
ss.exe cp $/
Working Folder
Visual SourceSafe projects are associated with working folders. A working folder is the location on the client computer that corresponds to the root of a project. However it is
possible for such a computer to obtain and build source without a working folder being specified, usually when creating projects through the Visual Studio interface or by
using the command:
ss.exe get -R

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1133 of 1651

However, this mode of operation is incompatible with SrcSrv indexing. SrcSrv requires that a working folder be specified. To set the working folder, use the command:
ss.exe workfold Project Folder
where Project indicates the current project and Folder indicates the location corresponding to the root of the project.
Labels
Visual SourceSafe cannot determine what version of a file exists within the working directory of a build machine. Consequently, you must use labels to stamp the project with
an identifier that is used to extract source files on the debugger client. Thus, before indexing, you must verify that all changes are checked into the database and then apply a
label to the project. Labels can be applied using the command:
ss.exe label Project
where Project indicates the current project.
In the following example, the label VERSION_3 is applied to a project called $/sdktools:
E:\nt\user>ss.exe label $/sdktools
Label for $/sdktools: VERSION_3
Comment for $/sdktools:
This is a comment.
After the label is applied, you can specify this label to the SrcSrv indexing script by setting the environment variable, SSLABEL, or by passing it as a command-line
parameter, as in the following example:
vssindex.cmd label=VERSION_3
Again, this label is required for SrcSrv indexing to work. Note that if you pass a label that does not exist in the project, it can take a long time for the script to complete and
the results are of no use.
Credentials
If your Visual SourceSafe database requires a user and optional password for access, these values must be set through the SSUSER and SSPWD environment variables. This
applies not only at the time the build is indexed, but also on the debugger client.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging with Visual SourceSafe

In order for source files indexed using Visual SourceSafe to work properly with the debugger, you must configure your system properly.
If the Visual SourceSafe database requires a user and optional password for access, these values must be set using the SSUSER and SSPWD environment variables.
Furthermore, the version of SrcSrv that ships with Visual Studio 2005 cannot detect whether Visual SourceSafe is prompting for credentials, which causes the application to
stop responding.. Upgrade to the version of SrcSrv that ships with Debugging Tools for Windows to prevent this.
If Visual SourceSafe is not set in the path of your debugging computer, you can get around this by adding an entry to the Srcsrv.ini file that works with your debugger. When
using a standard installation of Visual Studio, this file should be located in
%PROGRAMFILES%\Microsoft Visual Studio 8\Common7\IDE\srcsrv.ini
In the [trusted commands] section of Srcsrv.ini, add an entry of the form
ss.exe=Path
where Path is the location of Ss.exe.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using CVS
The CVS module for Source Server was developed using Concurrent Versions System (CVS) 1.11.17 (client). It has not been tested with any other versions of CVS.
Furthermore, the current version of the module is a beta version.
CVSROOT
On the computer on which you source index the build, CVSROOT cannot contain password and user information. Use cvs.exe to set your credentialing information.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1134 of 1651

To prepare the Srcsrv.ini file for CVS indexing you must enter an alias for your repository that uniquely distinguishes it from any others in your network. This repository must
match the value of CVSROOT in your environment. There is no need to set this value in the copy of Srcsrv.ini that you keep with your debugger clients because the alias is
defined in the source indexed .pdb file.
Client Computer
The client computer that extracts files during debugging does not need a CVS sandbox or CVSROOT set. It does need CVS binaries in the path, and if the repository is
locked, you must set the username and password with Cvs.exe.
Revision Tags
CVS is unable to extract a file by its version number. Instead, it must be done using what is known as a tag. When indexing a CVS-based system, you must ensure that all
changes are checked into the repository and then apply a tag using the cvs tag command. Then, when indexing the file, make certain you use the label command-line
parameter to specify the tag that you want to associate with the build you are indexing. You can achieve the same result by setting CVS_LABEL in the environment. Other
values can be set from the environment or the command line. Use the -?? command-line option with SSIndex to examine your choices and to verify that all was configured
correctly:
ssindex.cmd system=cvs -??

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Other Source Control Systems

Included in this package is Svn.pm. A closer look at this file shows how you can modify one of the existing scripts to support the Subversion Version Control system. Other
control systems, even a control system that you create yourself, can be supported by creating your own provider module.
This section includes:
Creating Your Own Provider Module
Creating Your Own Source Control System
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Creating Your Own Provider Module

In general, to create your own provider module, you must implement the following set of interfaces.
$module::SimpleUsage()
Purpose
Displays simple module usage information to STDOUT.
Parameters
None
Return Value
None
$module::VerboseUsage()
Purpose
Displays in-depth module usage information to STDOUT.
Parameters
None
Return Value
None
$objref = $module::new(@CommandArguments)
Purpose
Initializes an instance of the provider module.
Parameters
@CommandArguments
All @ARGV arguments that are not recognized by ssindex.cmd as being general arguments.
Return Value
A reference that can be used in later operations.
$objref->GatherFileInformation($SourcePath, $ServerHashReference)
Purpose
Enables the module to gather the required source-indexing information for the directory specified by the $SourcePath parameter. The module should not assume that
this entry is called only once for each object instancebecause SSIndex may call it multiple times for different paths.
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1135 of 1651

$SourcePath
The local directory containing the source to be indexed.
$ServerHashReference
A reference to a hash containing all of the entries from the specified Srcsrv.ini file.
Return Value
None
($VariableHashReference, $FileEntry) = $objref->GetFileInfo($LocalFile)
Purpose
Provides the necessary information to extract a single, specific file from the source control system.
Parameters
$LocalFile
A fully qualified file name.
Return Values
$VariableHashReference
A hash reference of the variables necessary to interpret the returned $FileEntry. Ssindex.cmd caches these variables for every source file used by a single debug
file to reduce the amount of information written to the source index stream.
$FileEntry
The file entry to be written to the source index stream to allow SrcSrv to extract this file from source control. The exact format of this line is specific to the
source control system.
$TextString = $objref->LongName()
Purpose
Provides a descriptive string to identify the source control system to the end user.
Parameters
None
Return Value
$TextString
The descriptive name of the source control system.
@StreamVariableLines=$objref->SourceStreamVariables()
Purpose
Enables the source control system to add source-control-specific variables to the source stream for each debug file. The sample modules use this method for writing
the required EXTRACT_CMD and EXTRACT_TARGET variables.
Parameters
None
Return Value
@StreamVariableLines
The list of entries for the source stream variables.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Creating Your Own Source Control System

This section enables you to understand how to prepare instrumentation scripts so that SrcSrv can be integrated into your build or version control system. The implementation
is dependent on the language specification version that ships with SrcSrv.
Many of the specifics of how Srcsrv.dll is called by symbol handler code are discussed. However, this information is not static and will not become so in the future. No one
should attempt to write code that calls Srcsrv.dll directly. This is reserved for DbgHelp or the Visual Studio products. Third-party vendors wanting to integrate such
functionality into their products should use the SymGetSourceFile function. This function, along with others in the DbgHelp API, is described in the DbgHelp
documentation, which can be found in the sdk/help subdirectory of the Debugging Tools for Windows installation directory.
If you do not see this documentation in your current debugger installation, it is because you did not perform a full installation. See Customizing the Installation for details.
This section includes:
Language Specification 1
Language Specification 2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Language Specification 1
The first version of SrcSrv works as follows. (This behavior may change in future versions.)
First, the client calls SrcSrvInit with the target path to be used as a base for all source file extractions. This path is stored in the special variable TARG.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1136 of 1651

When DbgHelp loads a modules .pdb file, it extracts the SrcSrv stream from the .pdb file and passes this data block to SrcSrv by calling SrcSrvLoadModule.
Then when DbgHelp needs to obtain a source file, it calls SrcSrvGetFile to retrieve a specified source file from version control.
SrcSrv reviews all the source file entries in the data block for an entry that matches exactly the requested source specification. This match is found in VAR1.
After SrcSrv finds the entry, it fills in the special variables (VAR1, VAR2, etc.) with the contents of this source file entry. Then the SRCSRVTRG variable is resolved using
these special variables.
The following shows how the SRCSRVTRG variable is resolved using the special variables. We assume that the source path is still:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
Each line shows the resolution of one more special variable. The resolved variables are bold.
SRCSRVTRG=%sdtrg%
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%( sdktools/debuggers/srcsrv/shell.cpp )\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\ sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%( c:\db\srcsrv\shell.cpp)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp
Notice how this generated target path is unique and does not allow two versions of the same file to be extracted to the same location.
SrcSrv now looks to see if the file is already there. If it is, SrcSrv returns the location to the caller. Otherwise, SrcSrv builds the execution command to extract the file by
resolving SRCSRVCMD.
In the following example, each line shows the resolution of one more special variable. The resolved variables are bold.
DEPOT=//depot
WIN_SDKTOOLS= sserver.microsoft.com:4444
SRCSRVCMD=%sdcmd%
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
sd.exe -p sserver.microsoft.com:4444 print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp
sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp
sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp
sd.exe -p sserver.microsoft.com:4444 print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp

-q %depot%/%va
-q //depot
-q //depot/ sd
-q

Now SrcSrv executes this command. If the result of this command is a file in the expected location, this path is returned to the caller.
Note that if a variable cannot be resolved, an attempt is made to look it up as an OS environment variable. If that fails, the variable name is deleted from the text being
processed.
Two consecutive percent sign characters are interpreted as a single percent sign.
Source Server Data Blocks
SrcSrv relies on two blocks of data within the .pdb file, the source file list and the data block.
The source file list is created automatically when a module is built. This list contains fully qualified paths to the source files used to build the module.
The data block is created during source indexing. At this time, an alternative stream named "srcsrv" is added to the .pdb file. The script that inserts this data is dependent on
the specific build process and source control system in use.
The data block is divided into three sections: ini, variables, and source files. The data block has the following syntax.
SRCSRV: ini -----------------------------------------------VERSION=1
VERCTRL=<source_control_str>
DATETIME=<date_time_str>
SRCSRV: variables -----------------------------------------SRCSRVTRG=%sdtrg%
SRCSRVCMD=%sdcmd%
SRCSRVENV=var1=string1\bvar2=string2
DEPOT=//depot
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4%
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
WIN_SDKTOOLS= sserver.microsoft.com:4444
SRCSRV: source files --------------------------------------<path1>*<var2>*<var3>*<var4>
<path2>*<var2>*<var3>*<var4>
<path3>*<var2>*<var3>*<var4>
<path4>*<var2>*<var3>*<var4>
SRCSRV: end -----------------------------------------------All text is interpreted literally, except for text enclosed in percent signs (%). Text enclosed in percent signs is treated as a variable name to be resolved recursively, unless it is
one of the following functions:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1137 of 1651

%fnvar%()
The parameter text should be enclosed in percent signs and treated as a variable to be resolved.
%fnbksl%()
All forward slashes (/) in the parameter text should be replaced with backward slashes (\).
%fnfile%()
All path information in the parameter text should be stripped out, leaving only the file name.
The [ini] section of the data block contains variables that describe the requirements. The indexing script can add any number of variables to this section. The following are
examples:
VERSION
The language specification version. This variable is required. If you develop a script based on the current language specification, set this value to 1. The SrcSrv client
code does not attempt to execute any script that has a value greater than its own. Current versions of SrcSrv use a value of 2.
VERCTL
A string that describes the source version control system. This variable is optional.
DATETIME
A string that indicates the date and time the .pdb file was processed. This variable is optional.
The [variables] section of the data block contains variables that describe how to extract a file from source control. It can also be used to define commonly used text as
variables to reduce the size of the data block.
SRCSRV
Describes how to build the target path for the extracted file. This is a required variable.
SRCSRVCMD
Describes how to build the command to extract the file from source control. This includes the name of the executable file and its command-line parameters. This is
required if any extraction command must be executed.
SRCSRVENV
Lists environment variables to be created during the file extraction. This is a string. Separate multiple entries with a backspace character (\b). This is an optional variable.
SRCSRVVERCTRL
Specifies the version control system in use. For Perforce, this is perforce. For Visual SourceSafe, this is vss. For Team Foundation Server, this is tfs. This variable is used
to persist server errors. This is an optional variable.
SRCSRVVERRDESC
Specifies the text to display when the version control client is unable to contact the server that contains the source files to extract. SrcSrv uses this value to check for
connection problems. This is an optional variable.
SRCSRVERRVAR
Indicates which variable in a file entry corresponds to a version control server. It is used by SrcSrv to identify commands that do not work, based on previous failures.
The format of the text is varX where X is the number of the variable being indicated. This is an optional variable.
The [source files] section of the data block contains an entry for each source file that has been indexed. The contents of each line are interpreted as variables with the names
VAR1, VAR2, VAR3, and so on until VAR10. The variables are separated by asterisks. VAR1 must specify the fully qualified path to the source file as listed elsewhere in
the .pdb file. For example:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
is interpreted as follows:
VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3
In this example, VAR4 is a revision number. However, most source control systems support labeling files in such a way that the source state for a given build can be restored.
Therefore, you could instead use the label for the build. The sample data block could be modified to contain a variable such as the following:
LABEL=BUILD47
Then, presuming the source control system uses the at sign (@) to indicate a label, you could modify the SRCSRVCMD variable as follows:
sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%
Handling Server Errors
Sometimes a client is unable to extract any files at all from a single version control server. This can be because the server is down and off the network or because the user does
not have appropriate privileges to access the source. However, the time consumed attempting to get this source can slow things down significantly. In this situation, it is best
to disable any attempt to extract from a source that has been proven to be unavailable.
Whenever SrcSrv fails to extract a file, it examines the output text produced by the command. If any part of this command contains an exact match for the contents of the
SRCSRVERRDESC, all future commands to the same version control server are skipped. Note that you can define multiple error strings by adding numbers or arbitrary text
to the end of the SRCSRVERRDESC variable name. Here is an example:
SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error
The identity of the server is acquired from SRCSRVERRVAR. So if SRCSRVERRVAR contains var2 and the file entry in the .pdb file looks like this:
c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3
all future attempts to obtain source using a file entry that contains TOOLS_PRJ in variable 2 are bypassed.
You can also add error indicators on the debugger client by editing Srcsrv.ini. See the included sample version of srcsrv.ini for details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1138 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Language Specification 2
This package ships with a srcsrv.dll that can operate without SRCSRVCMD being defined in the srcsrv data stream of a .pdb file. While such capability is of no use for
normal file extraction from source control systems, it is useful for direct access of files from a UNC share or HTTP site. See HTTP Sites and UNC Shares for more details.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

HTTP Sites and UNC Shares

It is possible to set up a Web site that provides version-specific source to WinDbg using SrcSrv. Such a mechanism does not provide dynamic extraction of the source files
from version control, but it is a valuable feature because it allows you to set the source path of WinDbg to a single unified path that provides source from many versions of
many modules, instead of having to set separate paths for each debugging scenario. This is not of interest to debugging clients that have direct access to the actual version
control systems but can be of assistance to those wanting to provide secure HTTP-based access to source from remote locations. The Web sites in question can be secured
through HTTPS and smart cards, if desired. This same technique can be used to provide source files through a simple UNC share.
This section includes:
Setting Up the Web Site
Extracting Source Files
Modifying the Source Indexing Streams in a .pdb File
Using UNC Shares
Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Up the Web Site

Set up a Web site from which to share the source files and note the root directory of the site. Your source is then available from a site such as:
https://SrcMachineName/source
In order to make your source files accessible over the Internet, you must configure the directories containing the source files.
Begin by selecting the directory in which your indexed source resides. In our examples, we call this directory c:\source and the name of the server on the network
\SrcMachineName. Permissions must be set so that users can access the site, and you must add the security groups that must access the source content over the network. The
amount of security to enable varies from environment to environment. For some installations, this group is Everyone.
To set up the permissions for the directory:
1.
2.
3.
4.
5.
6.
7.
8.
9.

Open Windows Explorer.

Expand My Computer.
Expand the C: drive.
Right-click c:\source and choose Sharing and Security.
Check the Share this folder button.
Click the Permissions button.
Verify that the desired security groups have read access by adding them under Group or user names and checking the appropriate box.
Click OK to exit Permissions.
Click OK to exit Source Properties.

The source directory can now be used for debugging by another computer with a source path of srv*\\SrcMachineName\source.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1139 of 1651

Debugging Tools for Windows

Extracting Source Files

To extract all of the source files from all the modules for which you want to provide source, use the command:
srctool.exe -x
This tool must be executed on .pdb files that have already been source-indexed for your version control system on a computer that has version control access. This places all
source files into a common directory tree. Copy the contents of this tree to the root of the Web site. You can do this as often as you want on any new products or modules that
you want to add. There is no worry about files overwriting each other because the directory tree structure keeps dissimilar files separated and uniquely accessible.
Walk
The Walk (Walk.cmd) script is included in Debugging Tools for Windows. This script searches recursively through a directory tree and executes any specified command on
any file that matches a specified file mask. The syntax is:
walk.cmd FileMask Command
where FileMask specifies a file mask, with or without an accompanying starting directory, and Command specifies the command to be executed.
Here is an example that runs the srctool.exe file extraction command on all .pdb files in c:\symbols and its subdirectories:
walk.cmd c:\symbols\*.pdb srctool.exe -x

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Modifying the Source Indexing Streams in a .pdb File

For the debugger clients to use the SrcSrv Web site, the .pdb files must be modified to point to it. To do this manually, you make a copy of all the .pdb files, change them, and
make them available from a separate location--usually the Web site itself.
Debugging Tools for Windows provides three files to assist in reconfiguring the .pdb files. The Cv2http.cmd and Cv2http.pl files extract the SrcSrv stream, modify it using a
Perl script, and put the altered stream back in the .pdb file. The syntax is as follows:
cv2http.cmd PDB Alias URL
where PDB specifies the name of the .pdbfile to modify, Alias specifies the logical name to apply to your Web site, and URL specifies the full URL of the site. Note that the
Alias parameter is stored in the PDB as a variable name that can be overridden on the debugger client in Scrsrv.ini, should you ever move the location of the Web site.
This script requires that all the standard SrcSrv tools be available in the path because it calls both SrcTool and PDBStr. Remember that Cv2http.pl is a Perl script and can be
modified to meet your needs.
The third file, the Walk (walk.cmd) script, modifies an entire set of .pdb files. For example:
walk.cmd *.pdb cv2http.cmd HttpAlias https:///source
The preceding command calls Cv2http.cmd on every .pdb file in a tree, using HttpAlias for the alias and https://server/source for the URL. For more details on Walk, see
Extracting Source Files.
After this command is executed on a tree of .pdb files, they are ready for installation into the Web site or whatever location in which you want to put them. Remember that
you can use SrcTool and PDBStr to examine the changes to the .pdb files.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using UNC Shares

The Cv2http.cmd, Cv2http.pl, and Walk (Walk.cmd) scripts are used to provide source files from a simple UNC share. The files Cv2http.cmd and Cv2http.pl extract the SrcSrv
stream, modify it using a Perl script, and put the altered stream back in the .pdb file. The syntax is as follows:
cv2http.cmd PDB Alias SourceRoot
where PDB specifies the name of the .pdbfile to modify, Alias specifies the logical name to apply to your Web site, and SourceRoot specifies the root of the UNC share to
which you extracted the source files. Note that the Alias parameter is stored in the PDB as a varaible name that can be overridden on the debugger client in Scrsrv.ini, should
you ever move the location of the Web site.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1140 of 1651

This script requires that all the standard SrcSrv tools be available in the path because it calls both SrcTool and PDBStr. Remember that Cv2http.pl is a Perl script and can be
modified to meet your needs.
The third file, the Walk (walk.cmd) script, modifies an entire set of .pdb files. For example:
walk.cmd *.pdb cv2http.cmd SourceRoot \\server\share
The preceding command calls Cv2http.cmd on every .pdb file in a tree, using SourceRoot for the alias and \\server\share for the UNC share. For more details on Walk, see
Extracting Source Files.
After this command is executed on a tree of .pdb files, they are ready for installation into the Web site or whatever location in which you want to put them. Remember that
you can use SrcTool and PDBStr to examine the changes to the .pdb files.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using HTTP Sites and UNC Shares in Conjuction with Regular Version Control
You may find that you must support your developers using the standard SrcSrv functionality that extracts files from version control but must also make source files available
through a Web site or UNC share. This could happen if you have set up a test lab that does not have access to version control. It is possible to support both users using the
same set of .pdb files.
First, extract the source files using SrcTool; see Extracting Source Files for details. Make the share available as either a Web site or UNC share. For the current purpose, you
should not convert the .pdb files using the Cv2http.cmd script.
Now on the computers that will use the HTTP/UNC shares, edit the Srcsrv.ini file that is in the debugger directory. In the variables section of the file, add the following three
statements:
MY_SOURCE_ROOT=\\server\share
SRCSRVCMD=
SRCSRVTRG=%MY_SOURCE_ROOT%\%var2%\%var3%\%var4%\%fnfile%(%var1%)
You should replace \\server\share with the root of the UNC share that you are providing or the URL of the Web site that contains the source files. You can also change
MY_SOURCE_ROOT to be any alias you want to describe this location. With these exceptions, everything else should be entered exactly as described.
All debuggers set up in this fashion ignore the standard version control extraction instructions and instead access the source files from the location specified. Meanwhile, all
debuggers without these items included in Srcsrv.ini use the normal version control mechanism to extract source files.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymChk
SymChk (the Microsoft Symbol Checker tool), Symchk.exe, is a program that compares executable files to symbol files to verify that the correct symbols are available.
This section includes:
Using SymChk
SymChk Command-Line Options
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using SymChk
The basic syntax for SymChk is as follows:
symchk [/r] FileNames /s SymbolPath
FileNames specifies one or more program files whose symbols are needed. If FileNames is a directory and the /r flag is used, this directory is explored recursively, and
SymChk will try to find symbols for all program files in this directory tree. SymbolPath specifies where SymChk is to search for symbols.
There are many more command-line optinos. For a full listing, see SymChk Command-Line Options.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1141 of 1651

The symbol path specified can include any number of local directories, UNC directories, or symbol servers. Local directories and UNC directories are not searched
recursively. Only the specified directory and a subdirectory based on the executable's extension are searched. For example, the query
symchk thisdriver.sys /s g:\symbols
will search g:\mysymbols and g:\mysymbols\sys.
You can specify a symbol server by using either of the following syntaxes as part of your symbol path:
srv*DownstreamStore*\\Server\Share
srv*\\Server\Share
This is very similar to using a symbol server in the debugger's symbol path. For details on this, see Using Symbol Servers and Symbol Stores.
If a downstream store is specified, SymChk will make copies of all valid symbol files found by the symbol server and place them in the downstream store. Only symbol files
that are complete matches are copied downstream.
SymChk always searches the downstream store before querying the symbol server. Therefore you should be careful about using a downstream store when someone else is
maintaining the symbol store. If you run SymChk once and it finds symbol files, it will copy those to the downstream store. If you then run SymChk again after these files
have been altered or deleted on the symbol store, SymChk will not notice this fact, since it will find what it is looking for on the downstream store and look no further.
Note SymChk always uses SymSrv (Symsrv.dll) as its symbol server DLL. On the other hand, the debuggers can choose a symbol server DLL other than SymSrv if one is
available. (SymSrv is the symbol server included in the Debugging Tools for Windows package.)
Examples
Here are some examples. The following command searches for symbols for the program Myapp.exe:
e:\debuggers> symchk f:\myapp.exe /s f:\symbols\applications
SYMCHK: Myapp.exe

FAILED

- Myapp.pdb is missing

SYMCHK: FAILED files = 1

SYMCHK: PASSED + IGNORED files = 0
You can try again with a different symbol path:
e:\debuggers> symchk f:\myapp.exe /s f:\symbols\newdirectory
SYMCHK: FAILED files = 0
SYMCHK: PASSED + IGNORED files = 1
The search was successful this time. If the verbose option is not used, SymChk will only list files for which it failed to find symbols. So in this example no files were listed.
You can tell that the search succeeded because there is now one file listed in the "passed" category and none in the "failed" category.
A program file is ignored if it contains no executable code. Many resource files are of this type.
If you prefer to see the file names of all program files, you can use the /v option to generate verbose output:
e:\debuggers> symchk /v f:\myapp.exe /s f:\symbols\newdirectory
SYMCHK: MyApp.exe

PASSED

SYMCHK: FAILED files = 0

SYMCHK: PASSED + IGNORED files = 1
The following command searches for a huge number of Windows symbols in a symbol server. There are a great variety of possible error messages:
e:\debuggers> symchk /r c:\windows\system32 /s srv*\\manysymbols\windows
SYMCHK: msisam11.dll
FAILED SYMCHK: msuni11.dll
FAILED SYMCHK: msdxm.ocx
FAILED s missing
SYMCHK: expsrv.dll
FAILED SYMCHK: imeshare.dll
FAILED SYMCHK: ir32_32.dll
FAILED SYMCHK: author.dll
FAILED SYMCHK: msvcrt40.dll
FAILED ......
SYMCHK: FAILED files = 211
SYMCHK: PASSED + IGNORED files = 4809

MSISAM11.pdb is missing
msuni11link.pdb is missing
Image is split correctly, but msdxm.dbg i
Checksum doesn't match with expsrv.DBG
imeshare.opt.pdb is missing
Built with no debugging information
rpctest.pdb is missing
Built with no debugging information

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1142 of 1651

Using a Manifest File with SymChk

In some cases, you might need to retrieve symbols for files that are on an isolated computer; that is, a computer that is either not on any network or is on a network that has no
symbol store. In that situation, you can use the following procedure to retrieve symbols.
1.
2.
3.
4.

Run SymChk with the /om parameter to create a manifest file that describes the files for which you want to retrieve symbols.
Move the manifest file to a network that has a symbol store.
Run SymChk with /im parameter to retrieve symbols for the files described int the manifest file.
Move the symbol files back to the isolated computer.

Example
Suppose yourApp.exe is running on an isolated computer. The following command creates a manifest file that describes all the symbols needed to debug the yourApp.exe
pocess.
C:\>SymChk /om c:\Manifest\man.txt /ie yourApp.exe
SYMCHK: FAILED files = 0
SYMCHK: PASSED + IGNORED files = 28
Now assume you have moved the manifest file to a different computer that is on a network that has access to a symbol store. The following command retrieves the symbols
described in the manifest file and places them in the mySymbols folder.
C:\>SymChk /im c:\FolderOnOtherComputer\man.txt /s srv*c:\mysymbols*\\aServer\symbols
SYMCHK: myApp.exe
ERROR - Unable to download file. Error reported was 2
. . .
SYMCHK: FAILED files = 28
SYMCHK: PASSED + IGNORED files = 28
Now you can move the symbols to the isolated computer and use them for debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SymChk Command-Line Options

SymChk uses the following syntax:
symchk [/r] [/v | /q ] FileNames /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /ie ExeFile /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /id DumpFile /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /ih HotFixFile /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /ip ProcessID /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /it TextFileList /s[Opts] SymbolPath Options
symchk [/r] [/v | /q ] /om Manifest FileNames
symchk [/v | /q ] /im ManifestList /s[Opts] SymbolPath Options
symchk [/v | /q ] /om Manifest /ie ExeFile
symchk [/v | /q ] /om Manifest /id DumpFile
symchk [/v | /q ] /om Manifest /ih HotFixFile
symchk [/v | /q ] /om Manifest /ip ProcessFile
symchk [/v | /q ] /om Manifest /it TextFileList
Parameters
/r
If Files specifies a directory, the /r option causes SymChk to recursively search all subdirectories under this directory for program files.
/v
Displays verbose information. This includes the file name of every program file whose symbols were investigated and whether it passed, failed, or was ignored.
/q
Enables quiet mode. All output will be suppressed (unless the /ot option is included).
FileNames
Specifies the program files whose symbols are to be checked. Absolute paths, relative paths, and UNC paths are permitted. An asterisk (*) wildcard is permitted. If
FileNames ends in a slash, it is taken to be a directory name, and all files within that directory are checked. If FileNames contains spaces, it must be enclosed in quotation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1143 of 1651

marks.
/ie ExeFile
Specifies the name of a program that is currently executing. The symbols for this program will be checked. ExeFile must include the name of the file and file extension
(usually .exe), but no path information. If there are two different executables with the same name, this option is not recommended. ExeFile can specify any program,
including a kernel-mode driver. If ExeFile is a single asterisk ( * ), SymChk will check the symbols for all running processes, including drivers.
/id DumpFile
Specifies a memory dump file. The symbols for this dump file will be checked.
/ih HotFixFile
Specifies a self-extracting Hotfix CAB file.
/ip ProcessID
Specifies the process ID of a program that is currently executing. The symbols for this program will be checked. ProcessID must be specified as a decimal number. There
are two special wildcards supported:
If ProcessID is zero ( 0 ), SymChk will check the symbols for all running drivers.
If ProcessID is a single asterisk ( * ), SymChk will check the symbols for all running processes, including drivers.
/it TextFileList
Specifies a text file that contains a list of program files. The symbols for all these programs will be checked. TextFileList must specify exactly one file (by relative,
absolute, or UNC path, but with no wildcards); if it contains spaces it should be enclosed in quotation marks. Within this file, each line indicates a program file (by
relative, absolute, or UNC paths), and an asterisk wildcard (*) is permitted. However, any line using this wildcard must use a relative path. If a line in this file contains
spaces, it should be enclosed in quotation marks. A semicolon within this file is a comment character everything between a semicolon and the end of the line will be
ignored.
/im ManifestList
Specifies that the input to the command is a manifest file previously created by using the /om parameter. The manifest file contains information about the files for which
symbols are retrieved. For more information about using a manifest file, see Using a Manifest File with SymChk.
/om Manifest
Specifies that a manifest file is created. The manifest file contains information about a set of files for which symbols will be retrieved, by using the /im parameter, at a
later time.
/s[Opts] SymbolPath
Specifies the directories containing symbols. Absolute paths, relative paths, and UNC paths are permitted. Any number of directories can be specified multiple
directories should be separated with semicolons. If SymbolPath contains spaces, it must be enclosed in quotation marks. If you wish to specify a symbol server within this
path, you should use one of the following syntaxes:
srv*DownstreamStore*\\Server\Share
srv*\\Server\Share
It is not recommended that you omit the /s[Opts] SymbolPath parameter, but if it is omitted, SymChk will point to the public symbol store by using the following default
path:
srv*%SystemRoot%\symbols*http://msdl.microsoft.com/download/symbols
Any number of the following options can follow /s. There can be no space between the /s and these options:
e
SymChk will check each path individually instead of checking all paths at once.
u
Downstream stores will be updated. If the symbol path includes a downstream store, the symbol store will be searched for the symbol files. Only symbol stores that
are being checked by SymChk will be updated.
p
Force checking for private symbols. Public symbols will be treated as not matching. The p option implies e and u, and cannot be used with s.
s
Force checking for public (split) symbols. Private symbols will be treated as not matching. The s option implies e and u, and cannot be used with p.
Options
The available options are divided into several classes. Each class of options controls a different set of features.
Output options. Any number of the following options can be specified. These options can be abbreviated by using /o only once for example, /oi /oe can be written
as /oie.
Option
Effect
/oe
Output will include individual errors. This option is only useful if /q is used, because individual errors are automatically displayed if quiet mode hasn't been
activated.
/op
Output will list each file that passes. (By default, SymChk only displays files that fail testing.)
/oi
Output will list each file that was ignored. (By default, SymChk only displays files that fail testing.)
/od
Output will include full details. Same as /oe /op /oi.
/ot
Output will include result totals. This option is only useful if /q is used, because these totals are automatically displayed if quiet mode hasn't been activated.
/ob
The full path for binaries will be included in all output messages.
/os
The full path for symbols will be included in all output messages.
/oc Dir SymChk will create a traditional symbol tree in the directory Dir that contains a list of all the symbol files checked.
DBG file options. These options control how SymChk checks .dbg symbol files. Only one of the following options can be specified.
Option
Effect
/ds
SymChk will verify that .dbg information was stripped from the executable and only appears in the .dbg file, and that the executable points to the .dbg file. If the
program was built without .dbg symbol files, this option has no effect. This is the default.
/de
SymChk will verify that .dbg information was not stripped from the executable and that the executable does not point to a .dbg file. If the program was built
without .dbg symbol files, this option has no effect.
/dn
SymChk will verify that .dbg information is not present in the image, and that the image does not point to a .dbg file.
PDB file options. These options control how SymChk checks .pdb symbol files. Only one of the following options can be specified.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1144 of 1651

Option
Effect
/pf
SymChk performs no checking on the contents of the .pdb file it just verifies that the files exist and match the binary. This is the default.
/ps
SymChk will verify that the .pdb files have been stripped of source line, data type, and global information.
/pt
SymChk will verify that the .pdb files contain data type information.
Filtering options. These options control how module filtering is performed when SymChk is checking processes or dump files. Only one of the following options can be
specified.
Option
/fm
Module

Effect
SymChk will only check dump files or processes associated with the specified module. Module must include the full filename, but must not include any part
of the directory path.

Symbol checking options. Any number of the following options can be specified.
Option
Effect
/cs
SymChk won't verify that CodeView data is present. (By default, the presence of CodeView data is verified.)
/cc
When SymChk is checking a hotfix CAB file, it will not look for symbols inside the cab. (By default, SymChk will look for symbols in the cab as well as in the
provided symbol path.)
/ea
SymChk won't verify symbols for the programs listed in the specified file. This allows you to veto certain programs that would otherwise be verified. File must
File
specify exactly one file (by relative, absolute, or UNC path, but without wildcards); if it contains spaces it should be enclosed in quotation marks. Within File,
each line indicates a program file (by relative, absolute, or UNC paths); no wildcards are permitted. If a line in this file contains spaces it should be enclosed in
quotation marks. A semicolon within this file is a comment character everything between a semicolon and the end of the line will be ignored. If a symbol
server is being used, symbols for these programs will not be copied to the downstream store.
/ee
Error messages for those programs listed in the specified file are suppressed. "Success" and "ignore" messages will appear as usual, and symbol files will be
File
copied to the downstream store as usual. The format of File and the format of its contents are the same as that for /ea File.
Additional Information
For more information about SymChk, see Using SymChk.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Engine and Extension APIs

This section includes:
Introduction
Debugger Engine Overview
Using the Debugger Engine API
Writing DbgEng Extensions
EngExtCpp Extensions
Writing WdbgExts Extensions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Introduction
This documentation describes how to use the debugger engine and how to write extensions that will run in WinDbg, KD, CDB, and NTSD. These debugger extensions can be
used when performing user-mode or kernel-mode debugging on Microsoft Windows.
Incomplete Documentation
This is a preliminary document and is currently incomplete.
For many concepts relating to the debuggers and the debugger engine that are not yet documented here, look in the Debuggers and Debugging Techniques sections of this
documentation.
To obtain some of the currently undocumented functionality of the debugger engine API, use the Execute method to execute individual debugger commands.
Debugger Engine
The debugger engine provides an interface for examining and manipulating debugging targets in user-mode and kernel-mode on Microsoft Windows.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1145 of 1651

The debugger engine can acquire targets, set breakpoints, monitor events, query symbols, read and write memory, and control threads and processes in a target.
You can use the debugger engine to write both debugger extension libraries and stand-alone applications. Such applications are debugger engine applications. A debugger
engine application that uses the full functionality of the debugger engine is a debugger. For example, WinDbg, CDB, NTSD, and KD are debuggers; the debugger engine
provides the core of their functionality.
The debugger engine API is specified by the prototypes in the header file dbgeng.h.
Extensions
You can create your own debugging commands by writing and building an extension DLL. For example, you might want to write an extension command to display a complex
data structure.
There are three different types of debugger extension DLLs:

DbgEng extension DLLs. These are based on the prototypes in the dbgeng.h header file. Each DLL of this type may export DbgEng extension commands. These
extension commands use the Debugger Engine API and may also use the WdbgExts API.
EngExtCpp extension DLLs. These are based on the prototypes in the engextcpp.h and dbgeng.h header files. Each DLL of this type may export DbgEng extension
commands. These extension commands use both the Debugger Engine API and the EngExtCpp extension framework, and may also use the WdbgExts API.
WdbgExts extension DLLs. These are based on the prototypes in the wdbgexts.h header file. Each DLL of this type exports one or more WdbgExts extension commands.
These extension commands use the WdbgExts API exclusively.

The DbgEng API can be used to create extensions or stand-alone applications. The WdbgExts API contains a subset of the functionality of the debugger engine API and can
be used only by extensions.
All debugger extensions should be compiled and built by using the Build utility. The Build utility is included in the Windows Driver Kit (WDK).
Extension code samples are installed as part of the Debugging Tools for Windows package if you perform a custom installation and select the SDK component and all its
subcomponents. They can be found in the sdk\samples subdirectory of the Debugging Tools for Windows installation directory.
The easiest way to write new debugger extensions is to study the sample extensions. Each sample extension includes makefile and sources files for use with the Build utility.
Both types of extensions are represented in the samples.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Engine Overview

Symbols
A symbol is a named unit of data or code from a source file that appears in a module. Information about symbols can include the name, type (if applicable), the address or
register where it is stored, and any parent or child symbols. Examples of symbols include variables (local and global), functions, and any entry point into a module.
The symbol information is used by the engine to help interpret data and code in the target. With this information, the engine can search for symbols by name or location in
memory and provide a description of a symbol.
The engine gets its information about symbols from symbol files, which are located on the local file system or loaded from a symbol server. When using a symbol server, the
engine will automatically use the correct version of the symbol file to match the module in the target. Symbol files can be loaded whenever the corresponding module is
loaded, or they can be loaded as needed.
Note Often optimizing compilers do not include accurate information in symbol files. This can cause the engine to misinterpret the value of some variables as the variable's
location or lifetime might be incorrectly described, causing the engine to look at the wrong piece of memory or think a variable value is live when it is dead (or vice versa). It
is also possible for an optimizing compiler to change the order of execution or to split a function into several pieces. Best results are usually obtained when debugging
unoptimized code.
Additional Information
For details about using symbols, see Using Symbols. For an overview of using symbol files and symbol servers, see Symbols in the Debuggers section of this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Memory
The debugger engine can directly read and write the target's main memory, registers, and other data spaces. In kernel-mode debugging, all of the target's memory is available,
including virtual memory, physical memory, registers, Model Specific Registers (MSRs), System Bus Memory, Control-Space Memory, and I/O Memory. In user-mode
debugging, only the virtual memory and registers are available.
The engine exposes, to the clients, all memory in the target using 64-bit addresses. If the target uses 32-bit addresses, when communicating with the target and the clients, the
engine will automatically convert between 32-bit and 64-bit addresses, as needed. If a 32-bit address is recovered from the targetfor example, by reading from memory or a
registerit must be sign-extended to 64 bits before it can be used in the debugger engine API. Sign extension is performed automatically by the ReadPointersVirtual
method.
Additional Information
For details about reading and writing memory, see Memory Access.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Threads and Processes

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1150 of 1651

Terminology
Thread and a process concepts are different between user-mode debugging and kernel-mode debugging.

In user-mode debugging, a process is an operating system process and a thread is an operating system thread.
In kernel-mode debugging, the debugger engine creates a virtual process for each target; this process represents the kernel and does not correspond to any operating
system process. For each physical processor in the target computer, the debugger creates a virtual thread; these threads represent the processors and do not correspond
to any operating system threads.

When an event occurs, the engine sets the event process and event thread to the process and thread (operating system or virtual) in which the event occurred.
The current thread is the thread (operating system or virtual) that the engine is currently controlling. The current process is the process (operating system or virtual) that the
engine is currently controlling. When an event occurs, the current thread and process are initially set to the event thread and process; but, they can be changed using the clients
while the session is accessible.
In kernel mode, the debugger keeps track of an implicit process and implicit thread. The implicit process is the operating system process that determines the translation from
virtual to physical memory addresses.
The implicit thread is the operating system thread that determines the target's registers, including call stack, stack frame, and instruction offset.
When an event occurs, the implicit thread and implicit process are initially set to the event thread and process; they can be changed while the session is accessible.
Thread and Process Data
The engine maintains several pieces of information about each thread and process. This includes the system thread and process ID and system handles, and the process
environment (PEB), the thread environment block (TEB), and their locations in target's memory.
Additional Information
For details about using thread and processes, see Controlling Threads and Processes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the Debugger Engine API

This section includes:
Debugger Engine API Overview
Debugger Engine Reference
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Engine API Overview

This section includes:
Interacting with the Engine
Using Input and Output
Monitoring Events
Using Breakpoints
Memory Access
Examining the Stack Trace
Controlling Threads and Processes
Using Symbols
Using Source Files
Connecting to Targets
Target Information

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1151 of 1651

Target State
Calling Extensions and Extension Functions
Assembling and Disassembling Instructions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Interacting with the Engine

Commands and Expressions
The debugger engine API provides methods to execute commands and evaluate expressions, like those typed into WinDbg's Debugger Command Window. To execute a
debugger command, use Execute. Or, to execute all of the commands in a file, use ExecuteCommandFile.
The method Evaluate will evaluate expressions using the C++ or MASM syntax. The syntax used by the debugger engine to evaluate expressionssuch as in the Evaluate
methodis given by GetExpressionSyntax and can be changed using SetExpressionSyntaxByName and SetExpressionSyntax. The number of different syntaxes that are
recognized by the debugger is returned by GetNumberExpressionSyntaxes, and their names are returned by GetExpressionSyntaxNames.
The type of value that is returned by Evaluate is determined by the symbols and constants used in the string that was evaluated. The value is contained in a DEBUG_VALUE
structure and can be cast to different types using CoerceValue and CoerceValues.
Aliases
Aliases are character strings that are automatically replaced with other character strings when used in debugger commands and expressions. For an overview of aliases, see
Using Aliases. The debugger engine has several classes of aliases.
The fixed-name aliases are indexed by number and have the names $u0, $u1, , $u9. The values of these aliases can be set using the SetTextMacro method and can be
retrieved using GetTextMacro method.
The automatic aliases and user-named aliases can have any name. The automatic aliases are defined by the debugger engine and the user-named aliases are defined by the
user through debugger commands or the debugger engine API. To define or remove a user-named alias, use the SetTextReplacement method. The GetTextReplacement
method returns the name and value of an automatic alias or a user-named alias. All the user-named aliases can be removed using the RemoveTextReplacements method. The
GetNumberTextReplacements method will return the number of user-name and automatic aliases; this can be used with GetTextReplacement to iterate over all these
aliases. The OutputTextReplacements method will print a list of all the user-named aliases, including their names and values.
Note if a user-named alias is given the same name as an automatic alias, the user-named alias will hide the automatic alias so that when retrieving the value of the alias by
name, the user-named alias will be used.
Engine Options
The engine has a number of options that control its behavior. These options are listed in DEBUG_ENGOPT_XXX. They are returned by GetEngineOptions and can be set
using SetEngineOptions. Individual options can be set using AddEngineOptions and unset using RemoveEngineOptions.
Interrupts
An interrupt is a way to force a break into the debugger or to tell the engine to stop processing the current command, for example, by pressing Ctrl+Break in WinDbg.
To request a break into the debugger, or to interrupt the debugger's current task, use SetInterrupt. To check if there has been an interrupt, use GetInterrupt.
Note When undertaking a long task from a debugger extension, it is recommended that the extension check GetInterrupt regularly and stop processing if an interrupt has
been requested.
When requesting a break into the debugger, the engine might time out if it takes too long for the target to carry out the break-in. This can occur if the target is in a nonresponsive state or if the break-in request is blocked or delayed by resource contention. The length of time the engine will wait is returned by GetInterruptTimeout and can
be set using SetInterruptTimeout.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Client Objects

For an overview of the role of client objects in interacting with the debugger engine, see Client Objects.
In general, a client's methods may be called only from the thread in which the client was created. Typically, methods called from the wrong thread will fail immediately. The
notable exception to this rule is the method CreateClient; this method may be called from any thread, and returns a new client that can be used in the thread from which it
was called. Other exceptions are documented in the reference section.
A string describing a client object is returned by the method GetIdentity or can be written to the engine's output stream using OutputIdentity.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1152 of 1651

COM Interfaces
The debugger engine API contains several COM interfaces; they implement the IUnknown interface.
Every one of the interfaces described in the section Client COM Interfaces is implemented by the client (though not necessarily at the latest version). You may use the COM
method IUnknown::QueryInterface to obtain each of these interfaces from any of the others.
The clients implement the IUnknown COM interface and use it for maintaining reference counts and interface selection. However, the clients are not registered COM objects.
The method IUnknown::AddRef is used to increment the reference count on the object, and the method IUnknown::Release is used to decrement the reference count. When
IUnknown::QueryInterface is called, the reference count is incremented, so when a client interface pointer is no longer needed IUnknown::Release should be called to
decrement the reference count.
The reference count will be initialized to one when the client object is created using DebugCreate or DebugConnect.
See the Platform SDK for more information about when reference counts should be incremented and decremented.
IUnknown::QueryInterface, DebugCreate, and DebugConnect each take an interface ID as one of their arguments. This interface ID can be obtained using the __uuidof
operator. For example:
IDebugClient * debugClient;
HRESULT Hr = DebugCreate( __uuidof(IDebugClient), (void **)&debugClient );

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Callback Objects

There are three callback COM interfaces that are used by the engine: IDebugEventCallbacks for notifying debugger extensions and applications of changes to the engine or
target, IDebugInputCallbacks for requesting input, and IDebugOutputCallbacks for sending output.
Callback objects are registered with clients. At most, one instance of each of the three callback interfaces can be registered with each client (the Unicode and ASCII versions
of a interface count as the same interface).
When a client is created, the engine remembers the thread in which it was created. The engine uses this same thread whenever it makes a call to a callback instance registered
with the client. If the thread is in use, the engine will queue the calls it needs to make. To allow the engine to make these calls, the method DispatchCallbacks should be
called whenever a client's thread is idle. The method ExitDispatch will cause DispatchCallbacks to return. If the thread is the same thread that was used to start the debugger
session, then the engine can make the callback calls during the WaitForEvent method, and DispatchCallbacks does not need to be called.
The method FlushCallbacks tells the engine to send all buffered output to the output callbacks.

Event Callback Objects

The IDebugEventCallbacks interface is used by the engine to notify the debugger extensions and applications of events and changes to the engine and target. An
implementation of IDebugEventCallbacks can be registered with a client using SetEventCallbacks. The current implementation registered with a client can be found using
GetEventCallbacks. The number of event callbacks registered across all clients can be found using GetNumberEventCallbacks.
For details on how the engine manages events, see Monitoring Events.

Input Callback Objects

The IDebugInputCallbacks interface is used by the engine to request input from debugger extensions and applications. An implementation of IDebugInputCallbacks can
be registered with a client using SetInputCallbacks. The current implementation registered with a client can be found using GetInputCallbacks. The number of input
callbacks registered across all clients can be found using GetNumberInputCallbacks.
For details on how the engine manages input, see Input and Output.

Output Callback Objects

The IDebugOutputCallbacks interface is used by the engine to send output to the debugger extensions and applications. An implementation of IDebugOutputCallbacks
can be registered with a client using SetOutputCallbacks. The current implementation registered with a client can be found using GetOutputCallbacks. The number of
output callbacks registered across all clients can be found using GetNumberOutputCallbacks.
For details on how the engine manages output, see Input and Output.
Note As is typical for COM objects, the engine will call IUnknown::AddRef on a callback COM object when it is registered with a client, and IUnknown::Release when
the object is replaced or the client is deleted.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Input and Output

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1153 of 1651

For an overview of the input and output streams in the debugger engine, see Input and Output.
Input
The engine will ask for input from all its clients if the Input method is called on a client. The input is returned to the caller of Input.
Input Callbacks
When the engine asks for input from a client, it uses the IDebugInputCallbacks object registered with that client. An IDebugInputCallbacks object may be registered with
a client using SetInputCallbacks. Each client can have at most one IDebugInputCallbacks object registered with it.
The request for input begins with the engine calling the IDebugInputCallbacks::StartInput method. This informs the IDebugInputCallbacks object that the engine is now
waiting for input.
If the IDebugInputCallbacks object has some input for the engine, it can call the ReturnInput method of any client. Once the ReturnInput method has been called, the
engine will not take any more input. Subsequent callers of this method will be informed that the input was not received.
The engine will then call IDebugInputCallbacks::EndInput to indicate that it has stopped waiting for input.
Finally, the engine will echo this input to the registered IDebugOutputCallbacks object of every client (except the one used to provide the input) by using
IDebugOutputCallbacks::Output with the bit-mask set to DEBUG_OUTPUT_PROMPT.
Output
Output may be sent to the engine using several client methods for example Output and OutputVaList. Upon receiving output, the engine sends it to some clients.
Clients use an output mask to indicate which types of output they are interested in. Whenever output is produced by the engine, it is accompanied by a mask specifying its
output type. If the type of output matches the output mask of the client, the client will receive the output. The output mask may be set by calling SetOutputMask and queried
using GetOutputMask. See DEBUG_OUTPUT_XXX for details of the output mask values.
The list of clients that the engine will send output to is controlled by the output control. Typically, the output control is set to send output to all clients; however, it can be
temporarily changed using ControlledOutput and ControlledOutputVaList. See DEBUG_OUTCTL_XXX for details about output control values.
Output may be buffered by the engine. If multiple pieces of output are passed to the engine, it may collect them and send them to the clients in one large piece. To flush this
buffer, use FlushCallbacks.
Each client object has an output width, which is the width of the output display for the client object. While this width is only used as a hint, some commands and extension
functions format their output based on this width. The width is returned by the GetOutputWidth method and can be set using the SetOutputWidth method.
Output Callbacks
When the engine sends output to a client, it uses the IDebugOutputCallbacks object registered with the client. An IDebugOutputCallbacks object may be registered with a
client using SetOutputCallbacks. Each client can have at most one IDebugInputCallbacks object registered with it.
To send the output, the engine calls the IDebugOutputCallbacks::Output method.
Output Line Prefix
Each client object has an output line prefix which is prepended to every line of output sent to the output callback associated with the client object. This can be used for
indentation or to place identifying marks on each line of output.
The output line prefix is returned by GetOutputLinePrefix and can be set using SetOutputLinePrefix. To temporarily change the output line prefix and later change it back
again, use PushOutputLinePrefix and PopOutputLinePrefix.
Log Files
The debugger engine supports opening a log file to record a debugging session. At most, one log file can be open at a time. Output sent to the output callbacks is also sent to
this log file (unless it is flagged to not be logged).
To open a log file, use OpenLogFile2 (or OpenLogFile). The method GetLogFile2 (or GetLogFile) returns the currently open log file. To close the log file, use
CloseLogFile.
The method SetLogMask can be used to filter the output sent to the log file, and GetLogMask will return the current log file filter.
Prompt
In an interactive debugging session, a prompt can be used to indicate to the user that the debugger is waiting for user input. The prompt is sent to the output callbacks using
the OutputPrompt and OutputPromptVaList methods. The contents of the standard prompt are returned by GetPromptText.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Monitoring Events
For an overview of events in the debugger engine, see Events.
Events occurring in a target or the debugger engine may be monitored using the IDebugEventCallbacks interface. An IDebugEventCallbacks object may be registered with

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1154 of 1651

a client using SetEventCallbacks. Each client can only have at most one IDebugEventCallbacks object registered with it.
When an IDebugEventCallbacks object is registered with a client, the engine will call the object's IDebugEventCallbacks::GetInterestMask to determine which events the
object is interested in. Only events in which the object is interested will be sent to it.
For each type of event, the engine calls a corresponding callback method on IDebugEventCallbacks. For events from the target, the DEBUG_STATUS_XXX value returned
from these calls specifies how the execution of the target should proceed. The engine collects these return values from each IDebugEventCallbacks object it calls and acts on
the one with the highest precedence.
Events from the Target That Break into the Debugger by Default
The following events break into the debugger by default:

Breakpoint Events
Exception Events (not documented here)
System Error

Events from the Target that Do Not Break into the Debugger by Default
The following events do not break into the debugger by default:

Create Process Event

Exit Process Event
Create Thread Event
Exit Thread Event
Load Module Event
Unload Module Event

Internal Engine Changes

The following are not actual events, but are merely internal engine changes:

Target Change
Engine Change
Engine Symbol Change
Session Status Change

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Event Filters
Event filters provide simple event filtering; they influence how the debugger engine proceeds after an event occurs in a target. When an event occurs, the engine determines
whether that event matches an event filter. If it does, the break status for the event filter influences whether the debugger will break into the target. If the event is an exception
event, the handling status determines whether the exception should be considered handled or not-handled in the target.
Note If more sophisticated event filtering is required, event callbacks can be used.
Event filters are divided into three categories.
1. Specific event filters. These are the filters for all the non-exception events. See DEBUG_FILTER_XXX for a list of these events.
2. Specific exception filters. The first specific exception filter is the default exception filter. The rest are filters for those exceptions for which the engine has built-in filters.
See Specific Exceptions for a list of the specific exception filters.
3. Arbitrary exception filters. These are filters for exception events that have been added manually.
The filters in categories 1 and 2 are collectively known as specific filters, and the filters in categories 2 and 3 are collectively known as exception filters. The number of filters
in each category is returned by GetNumberEventFilters.
An event matches a specific event filter if the type of the event is the same as the type of the filter. Some event filters have an additional parameter which further restricts the
events they match.
An exception event matches an exception filter if the exception code for the exception event is the same as the exception code for the exception filter. If there is no exception
filter with the same exception code as the exception event, the exception event will be handled by the default exception filter.
Commands and Parameters
Event filters can have a debugger command associated with them. This command is executed by the engine when an event matching the filter occurs.
GetEventFilterCommand and SetEventFilterCommand can be used to get and set this command. For exception filters, this command is executed on the first-chance of the
exception. A separate second-chance command can be executed upon the second-chance exception event. To get and set the second-chance command, use
GetExceptionFilterSecondCommand and SetExceptionSecondChanceCommand.
The parameters for specific event filters and exception filters are returned by GetSpecificFilterParameters and GetExceptionFilterParameters. The break status and
handling status for event filters can be set using SetSpecificFilterParameters and SetExceptionFilterParameters.
SetExceptionFilterParameters can also be used to add and remove arbitrary exception filters.
A short description of specific filters is returned by GetEventFilterText.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1155 of 1651

Some specific filters take arguments that restrict which events the filter matches. GetSpecificFilterArgument and SetSpecificFilterArgument will get and set arguments for
those specific filters which support arguments. If a specific filter has no argument, there is no restriction on which events it matches. The following table lists the event filters
that take arguments and how they restrict the events which match them:
Event
Match criteria
Create Process The name of the created process must match the argument.1
Exit Process
The name of the exited process must match the argument.1
The name of the loaded module must match the argument.1
Unload Module The base address of the unloaded module must be the same as the argument.2
Load Module

Target Output The debug output from the target must match the argument.3
Notes
1. The argument uses the string wildcard syntax and is compared with the image name (ignoring path) when the event occurs. If the name of the module or process is not
available, it is considered a match.
2. The argument is an expression that is evaluated by the engine when the argument is set.
3. The argument uses the string wildcard syntax and is compared with the debug output from the target. If the output is not known, it is considered a match.
Index and Exception Code
Each event filter has an index. The index is a number between zero and one less than the total number of filters (inclusive). The index range for each category of filters can be
found from the SpecificEvents, SpecificExceptions, and ArbitraryExceptions values returned by GetNumberEventFilters, as described in the following table:
Event Filters
Index of first filter
Specific event filters
0
specific exception filters SpecificEvents
arbitrary exception filters SpecificEvents + SpecificExceptions

Number of filters
SpecificEvents
SpecificExceptions
ArbitraryExceptions

The indices for the specific event filters are found in the first table located in the topic DEBUG_FILTER_XXX. The index of the default exception filter (the first specific
exception filter) is SpecificEvents. When an arbitrary exception filter is removed, the indices of the other arbitrary exception filters can change.
The exception filters are usually specified by exception code. However, some methods require the index of the exception. To find the index of an exception filter for a given
exception, use GetExceptionFilterParameters to iterate over all the exception filters until you find the one with the same exception code as the exception. The exception
codes for the specific exception filters can be found in the topic Specific Exceptions.
System Errors
When a system error occurs, the engine will break into the debugger or print the error to the output stream, if the error occurs at or below specified levels. These levels are
returned by GetSystemErrorControl and can be changed using SetSystemErrorControl.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Event Information
Whenever a debugging session is accessible, there is a last event. This is the event that caused the session to become accessible. The event target is the target which generated
the last event. When the session becomes accessible, the current target is set to the event target. The details of the last event are returned by GetLastEventInformation. The
instruction pointer for the last event and the memory at the instruction pointer when the event occurred are returned by the Request operations
DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET and DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM.
If the target is a crash dump file, the last event is the last event that occurred before the dump file was created. This event is stored in the dump file and the engine generates it
for the event callbacks when the dump file is acquired as a debugging target.
If the target is a kernel-mode target and a bug check occurred, the bug check code and related parameters can be found using ReadBugCheckData.
If the target is a user-mode Minidump, the dump file generator may store an additional event. Typically, this is the event that provoked the generator to save the dump file.
Details of this event are returned by GetStoredEventInformation and the Request operations DEBUG_REQUEST_TARGET_EXCEPTION_CONTEXT,
DEBUG_REQUEST_TARGET_EXCEPTION_THREAD, and DEBUG_REQUEST_TARGET_EXCEPTION_RECORD.
Dump files may contain a static list of events. Each event represents a snapshot of the target at a particular point in time. The number of events in this list is returned by
GetNumberEvents. For a description of each event in the list, use GetEventIndexDescription. To set an event from this list as the current event, use the method
SetNextEventIndex; after calling WaitForEvent, the event becomes the current event. To determine which event in the list is the current event, use
GetCurrentEventIndex.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Breakpoints

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1156 of 1651

For an overview of breakpoints in the debugger engine, see Breakpoints.

Breakpoints are event triggers which, when the breakpoint's conditions are satisfied, will halt execution of the target and break into the debugger. Breakpoints allow the user
to analyze and perhaps modify the target when execution reaches a certain point or when a certain memory location is accessed.
The debugger engine inserts a software breakpoint into a target by modifying the processor instruction at the breakpoint's location; this modification is invisible to the engine's
clients. A software breakpoint is triggered when the target executes the instruction at the breakpoint location. A processor breakpoint is inserted into the target's processor by
the debugger engine; its capabilities are processor-specific. It is triggered by the processor when the memory at the breakpoint location is accessed; what type of access will
trigger this breakpoint is specified when the breakpoint is created.
This topic includes:
Setting Breakpoints
Controlling Breakpoint Flags and Parameters
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Setting Breakpoints
Breakpoints are created with the AddBreakpoint method. This method creates an IDebugBreakpoint object that represents the breakpoint. It also set the breakpoint type
(software breakpoint or processor breakpoint). Once a breakpoint has been created, its type cannot be changed.
Breakpoints are deleted with the RemoveBreakpoint method. This also deletes the IDebugBreakpoint object; this object may not be used again.
Note Although IDebugBreakpoint implements the IUnknown interface, the methods IUnknown::AddRef and IUnknown::Release are not used to control the lifetime of
the breakpoint. These methods have no effect on the lifetime of the breakpoint. Instead, an IDebugBreakpoint object is deleted after the method RemoveBreakpoint is
called.
When the breakpoint is created, it is given a unique breakpoint ID. This identifier will not change. However, after the breakpoint has been deleted, its ID may be used for
another breakpoint. For details on how to receive notification of the removal of a breakpoint, see Monitoring Events.
When a breakpoint is created, it is initially disabled; this means that it will not cause the target to stop executing. This breakpoint may be enabled by using the method
AddFlags to add the DEBUG_BREAKPOINT_ENABLED flag.
When a breakpoint is first created, it has the memory location 0x00000000 associated with it. The location can be changed by using SetOffset with an address, or by using
SetOffsetExpression with a symbolic expression. The breakpoint's location should be changed from its initial value before it is used.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling Breakpoint Flags and Parameters

There are a number of methods that can be used to determine basic information about breakpoints:

GetId returns the breakpoint ID.

GetType returns the breakpoint type (software or processor) and the type of the effective processor on which the breakpoint is set.
GetAdder returns the client that added the breakpoint.
GetOffset returns the address of a breakpoint.
GetOffsetExpression returns the expression string that specifies the location of the breakpoint.

In addition to its location and breakpoint type, a breakpoint has several parameters controlling its behavior.
Breakpoint parameters can be controlled through a variety of specific methods. In addition, most of the parameters may be queried together using GetParameters.
Breakpoint Flags
Breakpoint flags are one kind of breakpoint parameters.
Breakpoint flags can be queried using GetFlags. They can be changed by using AddFlags, RemoveFlags, or SetFlags.
Breakpoint flags form a bit field. The possible flags that can be used in this bit field, and their meanings, are as follows:
DEBUG_BREAKPOINT_ENABLED
When this flag is set, the breakpoint is enabled and will have its normal effect. When this flag is not set, the breakpoint is disabled and will not have any effect. If you
wish to temporarily deactivate a breakpoint, you can remove this flag; it is then easy to add this flag back when you want to re-enable this breakpoint.
DEBUG_BREAKPOINT_ADDER_ONLY
When this flag is set, the breakpoint is a private breakpoint. This breakpoint is visible only to the client that added it. In this case, other clients will not be able to query
the engine for the breakpoint, and the engine will not send events generated by the breakpoint to other clients. All callbacks (event and output) related to this breakpoint
will be sent only to this client. See GetAdder.
DEBUG_BREAKPOINT_GO_ONLY

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1157 of 1651

When this flag is set, the breakpoint will only be triggered if the target is in unrestricted execution. It will not be triggered if the engine is stepping through instructions in
the target.
DEBUG_BREAKPOINT_ONE_SHOT
When this flag is set, the breakpoint will automatically remove itself the first time it is triggered.
DEBUG_BREAKPOINT_DEFERRED
When this flag is set, the breakpoint is deferred. This flag is set by the engine when the offset of the breakpoint is specified using a symbolic expression, and the engine
cannot evaluate the expression. Every time a module is loaded or unleaded in the target, the engine will attempt reevaluate the expression for all breakpoints whose
location is specified using an expression. Those that cannot be evaluated are flagged as deferred. This flag cannot be modified by any client.
Other Breakpoint Parameters
Breakpoint parameters also include:
Pass count
If the breakpoint has a pass count associated with it, it will not be activated until the target has passed the breakpoint the specified number of times. The pass count that
was originally set can be found by using GetPassCount. The number of times remaining that the engine will pass the breakpoint before it is activated can be found using
GetCurrentPassCount. The pass count can be reset to a new value by using SetPassCount.
Match thread
If the breakpoint has a thread associated with it, it will be ignored by the engine when it is encountered by any other thread. The thread can be found by using
GetMatchThreadId, and can be changed by using SetMatchThreadId.
Command
The breakpoint may have a command associated with it. The command is executed when the breakpoint is activated. This command can be found by using
GetCommand, and can be changed by using SetCommand.
Size
If the breakpoint is a processor breakpoint, it must have a specified size. This determines the size of the block of memory whose access will activate the breakpoint the
beginning of the block is the breakpoint's location. The size can be found by using GetDataParameters, and can be changed by using SetDataParameters.
Access type
If the breakpoint is a processor breakpoint, it must have an access type. This determines the type of access that will activate the breakpoint. For example, the breakpoint
may be activated if the target reads from, writes to, or executes the memory specified by the breakpoint. The access type can be found by using GetDataParameters, and
can be changed by using SetDataParameters.

Valid Parameters for Processor Breakpoints

The following access types are available for processor breakpoints:
Value
Description
DEBUG_BREAK_READ
The breakpoint will be triggered when the CPU reads memory in the breakpoint's memory block.
DEBUG_BREAK_WRITE
The breakpoint will be triggered when the CPU writes memory in the breakpoint's memory block.
DEBUG_BREAK_READ
The breakpoint will be triggered when the CPU reads or writes memory in the breakpoint's memory block.
| DEBUG_BREAK_WRITE
DEBUG_BREAK_EXECUTE The breakpoint will be triggered when the CPU fetches the instruction in the breakpoint's memory block.
DEBUG_BREAK_IO
The breakpoint will be triggered when the I/O port in the breakpoints memory block is accessed. (Windows XP and Microsoft Windows
Server 2003 only, kernel mode only, x86 only)
Not all access types and sizes are supported on all processors. The following access types and sizes are supported:
x86
All access types are supported. DEBUG_BREAK_READ behaves like DEBUG_BREAK_READ | DEBUG_BREAK_WRITE. The size must be 1, 2, or 4. The
breakpoint's address must be a multiple of the size.
x64
All access types are supported. DEBUG_BREAK_READ behaves like DEBUG_BREAK_READ | DEBUG_BREAK_WRITE. The size must be 1, 2, 4, or 8. The
breakpoint's address must be a multiple of the size.
Itanium
All access types except DEBUG_BREAK_IO are supported. The size must be a power of two; for DEBUG_BREAK_EXECUTE, the size must be 16. The breakpoint's
address must be a multiple of the size.
Itanium running in x86 mode
The is the same as for x86, except that DEBUG_BREAK_IO is not supported.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Memory Access
The debugger engine provides interfaces to directly read from and write to the target's main memory, registers, and other data spaces.
In user-mode debugging, only the virtual memory and registers can be accessed; the physical memory and other data spaces cannot be accessed.
The debugger engine API always uses 64-bit addresses when referring to memory locations on the target.
If the target uses 32-bit addresses, the native 32-bit address will automatically be sign-extended by the engine to 64-bit addresses. The engine will automatically convert
between 64-bit addresses and native 32-bit addresses when communicating with the target.
This section includes:
Virtual and Physical Memory
Registers

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1158 of 1651

Other Data Spaces

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Virtual and Physical Memory

The engine provides a number of methods for reading and writing the virtual and physical memory of a target.
Virtual Memory
When specifying a location in the virtual memory of a target, the target's virtual address space is used. In user-mode debugging, this is the virtual address space of the current
process. In kernel-mode debugging, this is the virtual address space of the implicit process. See Threads and Processes for more information about the current and implicit
process.
The virtual memory (of the target) can be read by using ReadVirtual and written using WriteVirtual.
Pointers in the target's memory can be read and written by using the convenience methods ReadPointersVirtual and WritePointersVirtual. These methods will
automatically convert between the 64-bit pointers used by the engine and the native pointers used by the target. These methods are useful when requesting memory that
contains pointers that will be used for subsequent requests for example, a pointer to a string.
The SearchVirtual and SearchVirtual2 methods can be used to search the target's virtual memory for a pattern of bytes.
The FillVirtual method can be used to copy a pattern of bytes, multiple times, to the target's virtual memory.
The target's virtual memory can also be read and written in a way that bypasses the debugger engine's virtual memory cache using the methods ReadVirtualUncached and
WriteVirtualUncached. These uncached versions are useful for reading virtual memory that is inherently volatile, such as memory-mapped device areas, without
contaminating or invalidating the cache. Uncached memory access should only be used in situations when it is required, as the performance of uncached access can be
significantly lower than cached access.
The engine provides some convenience methods to read strings from the target's virtual memory. To read a multibyte string from the target, use
ReadMultiByteStringVirtual and ReadMultiByteStringVirtualWide. To read a Unicode string from the target, use ReadUnicodeStringVirtual and
ReadUnicodeStringVirtualWide.
To find information about a memory location, use GetOffsetInformation. Not all of the virtual address space in the target contains valid memory. To find valid memory
within a region, use GetValidRegionVirtual. When manually searching for valid memory in a target, the method GetNextDifferentlyValidOffsetVirtual will find the next
location where the validity may change.
Physical Memory
The physical memory can only be directly accessed in kernel-mode debugging.
Physical memory on the target can be read by using ReadPhysical and ReadPhysical2, and written by using WritePhysical and WritePhysical2.
The FillPhysical method can be used to copy a pattern of bytes, multiple times, to the target's physical memory.
An address in the target's virtual address space can be translated to a physical address on the target by using the VirtualToPhysical method. The system's paging structures
used to translate a virtual address to a physical address can be found by using GetVirtualTranslationPhysicalOffsets.
Events
When the virtual or physical memory of the target is changed, the IDebugEventCallbacks::ChangeDebuggeeState callback method is called.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Registers
The debugger engine can be used to examine and alter the target's registers.
The registers available on the target depend on its processor architecture. For a description of the registers for the x86 and Itanium processors, see Processor Architecture. For
a complete description of the registers available for a processor, see that processor's documentation.
The Register Set
The GetNumberRegisters method can be used to find the number of registers on the target.
Each register is referred to by its index. The index of the first register is zero, and the index of the last register is the number of registers minus one. To find the index of a
register whose name is known, use GetIndexByName.
The method GetDescription returns information about a register. This includes the register's name, the type of values it can hold, and whether it is a subregister.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1159 of 1651

A subregister is a register that is contained within another register. When the subregister changes, the register that contains it also changes. For example, on an x86 processor,
the ax subregister is the same as the low 16 bits of the 32-bit eax register.
There are three special registers whose values may be found by using the following methods. The interpretation of the values of these registers is platform dependent.

The location of the current instruction may be found with GetInstructionOffset and GetInstructionOffset2.
The location of the current processor stack slot may be found with GetStackOffset and GetStackOffset2.
The location of the stack frame for the current function may be found with GetFrameOffset and GetFrameOffset2.

Manipulating Registers
The value of a register can be read by using the method GetValue. Multiple registers can be read by using GetValues and GetValues2.
A value can be written to a register by using the method SetValue. Multiple registers can be written by using SetValues and SetValues2.
When writing a value to a register, if the value supplied has a different type to the type of the register then the value is converted into the register's type. This conversion is the
same as that performed by the method CoerceValue. This conversion may result in data loss if the register's type is not capable of holding the value supplied.
Pseudo-Registers
Pseudo-registers are variables maintained by the debugger engine that hold certain values, for example, $teb is the name of the pseudo-register whose value is the address of
the current thread's Thread Environment Block (TEB). For more information, and a list of the pseudo-registers, see Pseudo-Register Syntax.
Each pseudo-register has an index. The index is a number between zero and the number of pseudo-registers (returned by GetNumberPseudoRegisters) minus one. To find
the index of a pseudo-register by its name, use GetPseudoIndexByName. The values of pseudo-registers can be read using GetPseudoValues, and values can be written to
pseudo-registers using SetPseudoValues. For a description of a pseudo-register, including its type, use GetPseudoDescription.
Note Not all of the pseudo-registers are available in all debugging sessions or at all times in a particular session.
Displaying Registers
The methods OutputRegisters and OutputRegisters2 format the target's registers and sends them to the clients as output.
Events
Whenever the values of the target's registers change, the engine will call the IDebugEventCallbacks::ChangeDebuggeeState callback method with the parameter Flags set
to DEBUG_CDS_REGISTERS.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Other Data Spaces

In kernel-mode debugging, it is possible to read and write data to a variety of data spaces in addition to the main memory and registers. The following data spaces can be
accessed:
System Bus
The methods ReadBusData and WriteBusData read and write system bus data.
Control-Space Memory
The methods ReadControl and WriteControl read and write control-space memory.
I/O Memory.
The methods ReadIo and WriteIo read and write system and bus I/O memory.
Model Specific Register (MSR)
The methods ReadMsr and WriteMsr read and write MSRs, which are control registers that enable and disable features, and support debugging, for a particular model
of CPU.
Handles
In user-mode debugging, information about system objects can be obtained using system handles owned by a target process. The method ReadHandleData can be used to
read this information.
System handles for thread and process system objects can be obtained by using the GetCurrentThreadHandle and GetCurrentProcessHandle methods. These handles are
also provided to the IDebugEventCallbacks::CreateThread and IDebugEventCallbacks::CreateProcess callback methods when create-thread and create-process
debugging event occur.
Note In kernel mode, the process and thread handles are artificial handles. They are not system handles.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Examining the Stack Trace

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1160 of 1651

A call stack contains the data for the functions calls made by a thread. The data for each function call is called a stack frame and includes the return address, parameters
passed to the function, and the function's local variables. Each time a function call is made a new stack frame is pushed onto the top of the stack. When that function returns,
the stack frame is popped off the stack.
Each thread has its own call stack, representing the calls made in that thread.
To get a stack trace, use the methods GetStackTrace and GetContextStackTrace. A stack trace can be printed using OutputStackTrace and OutputContextStackTrace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Controlling Threads and Processes

For an overview of threads and processes in the debugger engine, see Threads and Processes.
When an event occurs, the event thread and event process are set to the thread and process (operating system or virtual) in which the event occurred. They can be found using
GetEventThread and GetEventProcess, respectively.
Implicit Threads and Processes
In kernel-mode debugging the debugger engine will use the implicit process to determine which virtual address space to use when performing virtual to physical address
translation for example, in the methods VirtualToPhysical and ReadVirtual. When an event occurs, the implicit process is set to the current process.
The implicit process may be changed by using SetImplicitProcessDataOffset. To determine the implicit process use GetImplicitProcessDataOffset.
Note When setting breakpoints during a live kernel debugging session, the debugger engine will pass the virtual address of the breakpoint to the target, and the target will set
the breakpoint. In this case, only the process context of the target is used when handling the breakpoint; the value of the implicit process is irrelevant.
In kernel-mode debugging, the debugger engine will use the implicit thread to determine some of the target's registers. This includes the processor stack (see
GetStackOffset), the frame offset (see GetFrameOffset), and the instruction offset (see GetInstructionOffset). When an event occurs, the implicit thread is set to the
current thread.
The implicit thread may be changed by using SetImplicitThreadDataOffset. To determine the implicit thread, use GetImplicitThreadDataOffset.
Not all registers are determined by the implicit thread. Some registers will remain the same when the implicit thread is changed.
Warning The implicit process and implicit thread are independent. If the implicit thread does not belong to the implicit process, then user and session state for the implicit
thread will be in the wrong virtual address space and attempts to access this information will cause errors or provide incorrect results. This problem does not occur when
accessing kernel memory, since kernel memory addresses are constant across all virtual address spaces. Thus information for the implicit thread located in kernel memory
may be accessed independent of the implicit process.
Threads
The engine thread ID is used by the debugger engine to identify each operating system thread and each virtual thread for a target.
While a target is stopped, each thread also has an index relative to the process to which it belongs. For any process, the index of the first thread in the process is zero, and the
index of the last thread is the number of threads in the process minus one. The number of threads in the current process can be found by using GetNumberThreads. The total
number of threads in all processes in the current target can be found by using GetTotalNumberThreads.
The engine thread ID and system thread ID for one or more threads in the current process can be found from their index by using GetThreadIdsByIndex.
The engine maintains several pieces of information about each thread. This information may be queried for the current thread, and may be used to find the engine thread ID
for a thread.
system thread ID (user-mode debugging only).
The system thread ID of the current thread can be found by using GetCurrentThreadSystemId. For a given system thread ID, the corresponding engine thread ID may
be found by using GetThreadIdBySystemId.
thread environment block (TEB)
The address of the TEB for the current thread can be found by using GetCurrentThreadTeb. For a given TEB address, the corresponding engine thread ID may be
found by using GetThreadIdByTeb. In kernel-mode debugging, the TEB of a (virtual) thread is the TEB of the system thread that was running on the corresponding
processor when the last event occurred.
data offset
In user-mode debugging, the data offset of a (system) thread is the location of the TEB for that thread. In kernel-mode debugging the data offset of a (virtual) thread is the
KTHREAD structure for the system thread that was running on the corresponding processor when the last event occurred. The data offset of the current thread can be
found by using GetCurrentThreadDataOffset. For a given data offset, the corresponding engine thread ID may be found by using GetThreadIdByDataOffset.
system handle
The system handle of the current thread can be found by using GetCurrentThreadHandle. For a given system handle, the corresponding engine thread ID may be found
by using GetThreadIdByHandle. In kernel-mode debugging, an artificial handle is created for each (virtual) process. This handle can only be used with debugger engine
API queries.
Processes
The engine process ID is used by the debugger engine to identify each operating system process and each virtual process for a target.
While a target is stopped, each process has an index relative to the target. The index of the first process in the target is zero, and the index of the last process is the number of
processes in the target minus one. The number of processes in the current target can be found by using GetNumberProcesses.
The engine process ID and system process ID for one or more threads in the current target can be found from their index by using GetProcessIdsByIndex.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1161 of 1651

The engine maintains several pieces of information about each process. This information may be queried for the current process, and may be used to find the engine process
ID for a process.
system process ID (user-mode debugging only).
The system process ID of the current process can be found by using GetCurrentProcessSystemId. For a given system process ID, the corresponding engine process ID
may be found by using GetProcessIdBySystemId.
process environment block (PEB)
The address of the PEB for the current process can be found by using GetCurrentProcessPeb. For a given PEB address, the corresponding engine process ID may be
found by using GetProcessIdByPeb. In kernel-mode debugging, the PEB of the (virtual) process is the PEB of the system process that was running when the last event
occurred.
data offset
In user-mode debugging, the data offset of a (system) process is the location of the PEB of that process. In kernel-mode debugging, the data offset of the (virtual) process
is the KPROCESS structure for the system process that was running when the last event occurred. The data offset of the current process can be found by using
GetCurrentProcessDataOffset. For a given data offset, the corresponding engine process ID may be found by using GetProcessIdByDataOffset.
system handle
The system handle of the current process can be found by using GetCurrentProcessHandle. For a given system handle, the corresponding engine process ID may be
found by using GetProcessIdByHandle. In kernel-mode debugging, an artificial handle is created for the (virtual) process. This handle can only be used with debugger
engine queries.
Events
In live user-mode debugging, whenever a thread is created or exits in a target, the create-thread and exit-thread debugging events are generated. These events result in calls to
the IDebugEventCallbacks::CreateThread and IDebugEventCallbacks::ExitThread callback methods.
In live user-mode debugging, whenever a process is created or exits in a target, the create-process and exit-process debugging events are generated. These events result in calls
to the IDebugEventCallbacks::CreateProcess and IDebugEventCallbacks::ExitProcess callback methods.
For more information about events, see Monitoring Events.
Additional Information
For more information about threads and processes, including the TEB, KTHREAD, PEB, and KPROCESS structures, see Microsoft Windows Internals by David Solomon
and Mark Russinovich.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Symbols
For an overview of symbols, including using symbol files and symbol servers, see Symbols.
Symbol Names and Locations
To find the location of a symbol given its name, use GetOffsetByName. For details on the syntax used to specify symbol names, see Symbol Syntax and Symbol Matching.
If the exact name of a symbol is not known, or multiple symbols have the same name, StartSymbolMatch will begin a search for symbols whose names match a given
pattern. For details on the syntax, see String Wildcard Syntax.
To find the name of a symbol given its location, use GetNameByOffset. To find the names of symbols in a module near a given location, use GetNearNamebyOffset.
Note Whenever possible, qualify the symbol with the module name for example mymodule!main. Otherwise, if the symbol does not exist (for example, because of a
typographical error) the engine will have to load and search the symbols for every module; this can be a slow process, especially for kernel-mode debugging. If the symbol
name was qualified with a module name, the engine will only need to search the symbols for that module.
A symbol is uniquely identified using the structure DEBUG_MODULE_AND_ID. This structure is returned by the methods GetSymbolEntriesByName and
GetSymbolEntriesByOffset, which search for symbols based on their name and location, respectively.
The method GetSymbolEntryInformation returns a description of a symbol using the DEBUG_SYMBOL_ENTRY structure.
To find the offset of a field within a structure, use GetFieldOffset. To find the name of a field given its index within a structure, use GetFieldName. To find the name of an
enumeration constant given its value, use GetConstantName.
The method GetSymbolInformation can perform several requests for information about symbols.
Symbol Options
A number of options control how the symbols are loaded and unloaded. For a description of these options, see Setting Symbol Options.
Symbol options may be turned on by using AddSymbolOptions, and turned off by using RemoveSymbolOptions.
GetSymbolOptions returns the current symbol options. To set all the symbol options at once, use SetSymbolOptions.
Reloading Symbols
After loading symbol files, the engine stores the symbol information in an internal cache. To flush this cache, use Reload. These symbols will have to be loaded again now or
at a later time.
Synthetic Symbols

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1162 of 1651

Synthetic symbols are a way to label an arbitrary address for easy reference. Synthetic symbols can be created in any existing module. The method AddSyntheticSymbol
creates a new synthetic symbol. Synthetic symbols can be removed using RemoveSyntheticSymbol. Reloading the symbols for the module deletes all synthetic symbols
associated with that module.
Symbol Path
To add a directory or symbol server to the symbol path, use the method AppendSymbolPath. The whole symbol path is returned by GetSymbolPath and can be changed
using SetSymbolPath.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Modules
An image is an executable, DLL, or driver that Windows has loaded as part of a user-mode process or the kernel. The file from which the image was loaded is referred to as
its image file.
The debugger engine caches a list of modules for each process (or, in kernel-mode, the virtual process). Typically each module in this list represents an image in the process.
The engine's module list can be synchronized with the target using Reload.
Note In kernel-mode debugging, the engine's module list for the virtual process contains both the system-wide kernel-mode modules and the current process's user-mode
modules.
A module can be specified by its base address in the target's virtual address space, or by its index in the list of modules the engine maintains for the target. The module's index
equals its position in the list of modules, and therefore this index will change if a module with a lower index is unloaded. All unloaded modules have indexes; these are always
higher than the indexes of loaded modules. The base address of a module will not change as long as it remains loaded; in some cases it may change if the module is unloaded
and then reloaded.
The index is a number between zero and the number of modules in the target minus one. The number of modules in the current process can be found by calling
GetNumberModules.
The index can be used to find the base address by calling GetModuleByIndex. The base address of a module owning a symbol with a given name can be found using
GetSymbolModule.
The following methods return both the index and base address of the specified module:

To find a module with a given module name, use GetModuleByModuleName.

The module whose virtual address range contains a given address is returned by GetModuleByOffset. This method can be used to find the module index given the base
address of the module.

The following methods return information about modules specified either by base address or index:

The names of a module are returned by GetModuleNames and GetModuleNameString.

Version information for the module is returned by GetModuleVersionInformation.
Some of the parameters used to describe a module are returned by GetModuleParameters. For details on the parameters returned by this method, see
DEBUG_MODULE_PARAMETERS.

Unloaded Modules
During user-mode debugging, unloaded modules are tracked only in Windows Server 2003 and later versions of Windows. Earlier versions of Windows only tracked
unloaded modules in kernel mode. When they are tracked, they are indexed after the loaded modules. Hence any method that searches the target's modules will search all the
loaded modules and then the unloaded modules. Unloaded modules can be used to analyze failures caused by an attempt to call unloaded code.
Synthetic Modules
Synthetic modules can be created as a way to label a region of memory. These modules cannot contain real symbols, but they can contain synthetic symbols. The method
AddSyntheticModule creates a new synthetic module. Synthetic modules can be removed using RemoveSyntheticModule. Reloading all the modules in the target deletes
all synthetic modules.
Image Path
The executable image path is used by the engine when searching for executable images.
The executable image path can consist of several directories separated by semicolons (;). These directories are searched in order.
For an overview of the executable image path, see Executable Image Path.
To add a directory to the executable image path, use the method AppendImagePath. The whole executable image path is returned by GetImagePath and can be changed
using SetImagePath.
Additional Information
For more information about processes and virtual processes, see Threads and Processes.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1163 of 1651

December 09, 2009

Debugging Tools for Windows

Types
Type information from a module's symbol file is identified by two pieces of information: a type ID and the base address of the module to which the type belongs. The
following methods can be used to find a type ID:

GetTypeId returns the type ID for a given type name.

GetSymbolTypeId returns the type ID for the type of a symbol with the given name.
GetOffsetTypeId returns the type ID for the symbol found at the given location.

The name and size of a type are returned by GetTypeName and GetTypeSize, respectively.
The following convenience methods can be used for reading and writing typed data in the target's physical and virtual memory:
ReadTypedDataPhysical
WriteTypedDataPhysical
ReadTypedDataVirtual
WriteTypedDataVirtual
Printing Typed Data
To format typed data and send it to the output callbacks, use OutputTypedDataPhysical and OutputTypedDataVirtual for data in the target's physical and virtual memory
respectively.
The type options described in DEBUG_TYPEOPTS_XXX affect how the engine formats typed data before sending it to the output callbacks.
The type options may be turned on by using AddTypeOptions, and turned off by using RemoveTypeOptions.
GetTypeOptions returns the current type options. To set all the type options at once, use SetTypeOptions.
Interpreting Raw Data Using Type Information
The debugger engine API supports interpreting typed data. This provides a way to walk object hierarchies on the target, including finding members of structures,
dereferencing pointers, and locating array elements.
Typed data is described by instances of the DEBUG_TYPED_DATA structure and represents regions of memory on the target cast to a particular type. The
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation is used to manipulate these instances. They can be initialized to the result of expressions or by casting
regions of memory to a specified type. For a list of all the sub-operations that the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation supports, see
EXT_TDOP.
Additional Information
For details on output callbacks, see Input and Output.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Scopes and Symbol Groups

A symbol group contains a set of symbols for efficient manipulation as a group. A symbol group can be created and populated manually or can be automatically generated and
updated based on symbols in lexical scopes, such as local variables and function arguments. The interface IDebugSymbolGroup is used to represent a symbol group.
There are two ways to create a symbol group. An empty symbol group is returned by CreateSymbolGroup, and the symbol group for the current lexical scope is returned by
GetScopeSymbolGroup.
Note: The symbol group generated from the current scope is a snapshot of the local variables. If any execution occurs in the target, the symbols may no longer be accurate.
Also, if the current scope changes, the symbol group will no longer represent the current scope (because it will continue to represent the scope for which it was created).
Symbols can be added to a symbol group using AddSymbol, and removed using RemoveSymbolByIndex or RemoveSymbolByName. The method OutputAsType tells the
debugger to use a different symbol type when handling a symbol's data.
Note: The values for scoped symbols may not be accurate. In particular, the machine architecture and compiler optimizations may prevent the debugger from accurately
determining a symbol's value.
The symbol entry information is a description of a symbol, including its location and its type. To find this information for a symbol in a module, use the
IDebugSymbols3::GetSymbolEntryInformation. To find this information for a symbol in a symbol group, use IDebugSymbolGroup2::GetSymbolEntryInformation.
See DEBUG_SYMBOL_ENTRY for details of the symbol entry information.
The following methods return information about a symbol in a symbol group:

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1164 of 1651

GetSymbolName returns the name of the symbol.

GetSymbolOffset returns the absolute address in the target's virtual address space of the symbol, if the symbol has an absolute address.
GetSymbolRegister returns the register containing the symbol, if the symbol is contained in a register.
GetSymbolSize returns the size of the data for the symbol.
GetSymbolTypeName returns the name of the symbol's type.
GetSymbolValueText returns the value of the symbol as a string.

If a symbol is stored in a register or in a memory location known to the debugger engine, its value can be changed using WriteSymbol.
A symbol is a parent symbol if it contains other symbols. For example, a structure contains its members. A symbol is a child symbol if it is contained in another symbol. A
symbol may be both a parent and child symbol. Each symbol group has a flat structure and contains parent symbols and their children. Each symbol has a depth symbols
without parents in the symbol group have a depth of zero, and the depth of each child symbol is one greater than the depth of its parent. The children of a parent symbol may
or may not be present in the symbol group. When the children are present in the symbol group, the parent symbol is referred to as expanded. To add or remove the children of
a symbol in a symbol group, use ExpandSymbol.
The number of symbols in a symbol group is returned by GetNumberSymbols. The index of a symbol in a symbol group is an identification number; the index ranges from
zero to the number of symbols minus one. Each time a symbol is added to or removed from a symbol group for example, by expanding a symbol the index of all the
symbols in the symbol group may change.
The symbol parameters, including information about parent-child relationships, can be found by using GetSymbolParameters. This method returns a
DEBUG_SYMBOL_PARAMETERS structure.
The symbols in a symbol group can be printed to the debugger's output stream using the method OutputSymbols.
Scopes
The current scope, or current local context, determines the local variables exposed by the debugger engine. The scope has three components:
1. A stack frame.
2. A current instruction.
3. A register context.
If the stack frame is at the top of the call stack, the current instruction is the instruction that resulted in the last event. Otherwise the current instruction is the function call
which resulted in the next higher stack frame.
The methods GetScope and SetScope can be used to get and set the current scope. When an event occurs, the current scope is set to the scope of the event. The current scope
can be reset to the scope of the last event using ResetScope.
Thread Context
The thread context is the state preserved by Windows when switching threads. This is similar to the register context, except that there is some kernel-only processor state that
is part of the register context but not the thread context. This extra state is available as registers during kernel-mode debugging.
The thread context is represented by the CONTEXT structure defined in ntddk.h. This structure is platform-dependent and its interpretation depends on the effective processor
type. The methods GetThreadContext and SetThreadContext can be used to get and set the thread context.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Source Files

The debugger engine maintains a source path, which is a list of directories and source servers that contain source code files associated with the current targets. The debugger
engine can search these directories and source servers for the source files. With the help of symbol files, the debugger engine can match lines in the source files with locations
in the target's memory.
For an overview of using source files with debuggers, see Debugging in Source Mode. For an overview of source paths, see Source Path. For an overview of using source
servers from the debugger engine, see Using a Source Server.
Source Path
To add a directory or source server to the source path, use the method AppendSourcePath. The whole source path is returned by GetSourcePath and can be changed using
SetSourcePath. A single directory or source server can be retrieved from the source path using GetSourcePathElement.
To find a source file relative to the source path, use FindSourceFile or, for more advanced options when using source servers, use FindSourceFileAndToken.
FindSourceFileAndToken can also be used along with GetSourceFileInformation to retrieve variables related to a file on a source server.
Matching Source Files to Code in Memory
The debugger engine provides three methods for locating the memory locations that correspond to lines in a source file. To map a single line of source code to a memory
location, use GetOffsetByLine. To search for memory locations for more than one source line or for nearby source lines, use GetSourceEntriesByLine. The
GetSourceFileLineOffsets method will return the memory location of every line in a source file.
To perform the opposite operation and find the line of a source file that matches a location in the target's memory, use GetLineByOffset.
Note: the relationship between memory locations and lines in a source file is not necessarily one-to-one. It is possible for a single line of source code to correspond to multiple
memory locations and for a single memory location to correspond to multiple lines of source code.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1165 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Connecting to Targets
This section includes:
Live User-Mode Targets
Live Kernel-Mode Targets
Dump-File Targets
Remote Targets
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Live User-Mode Targets

The methods for creating and attaching to processes that are listed in this topic can be used for the local computer and for a remote computer running a process server.
A user-mode process can be created using Create Process or CreateProcess2, which execute a given command to create a process. The method AttachProcess can be used
to attach the debugger engine to an existing user-mode process. CreateProcessAndAttach and CreateProcessAndAttach2 create a new user-mode process and attach to it or
another user-mode process on the same computer. The Request operations DEBUG_REQUEST_GET_ADDITIONAL_CREATE_OPTIONS,
DEBUG_REQUEST_SET_ADDITIONAL_CREATE_OPTIONS, and DEBUG_REQUEST_SET_LOCAL_IMPLICIT_COMMAND_LINE can be used to set some of the
default options for creating processes.
Note The engine doesn't completely attach to the process until the WaitForEvent method has been called. Only after the process has generated an event for example, the
process creation event does it become available in the debugger session. See Debugging Session and Execution Model for more details.
The method GetRunningProcessSystemIds will return the process IDs of all the running processes on the computer. The process ID of a particular program can be found
using GetRunningProcessSystemIdByExecutableName. Given a process ID, a description of the process is returned by GetRunningProcessDescription.

Process Options
The process options determine part of the engine's behavior when attached to a user-mode process, including whether or not the debugger engine will automatically attach to
child processes created by the target process and what the engine does with the target processes when it exits. See DEBUG_PROCESS_XXX for a description of the process
options.
The process options can be queried using GetProcessOptions. They can be changed using AddProcessOptions, RemoveProcessOptions, and SetProcessOptions.

Disconnecting from Processes

There are three different ways for the engine to disconnect from a process.
1. Detach. Resume all the threads in the process so that it will continue running, no longer being debugged. DetachCurrentProcess will detach the engine from the
current process and DetachProcesses will detach the engine from all processes. Not all targets support detaching. The Request operation
DEBUG_REQUEST_TARGET_CAN_DETACH can be used to check if the target supports detaching.
2. Terminate. Attempt to kill the process. TerminateCurrentProcess will terminate the current process and TerminateProcesses will terminate all processes in the
debugger session.
3. Abandon. Remove the process from the list of processes being debugged. The operating system will still consider the process as being debugged and it will remain
suspended until another debugger attaches to it or it is killed. AbandonCurrentProcess will abandon the current process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Live Kernel-Mode Targets

To attach the debugger engine to a target computer for kernel-mode debugging, use the method AttachKernel.
Note The engine doesn't completely attach to the kernel until the WaitForEvent method has been called. Only after the kernel has generated an event for example, the
initial breakpoint does it become available in the debugger session. See Debugging Session and Execution Model for more details.
If the debugger engine is attached to a kernel which is not the local kernel and the connection is not an eXDI connection, the connection options used to find the target
computer can be queried using GetKernelConnectionOptions. The connection can also be re-synchronized or the connection speed changed using

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1166 of 1651

SetKernelConnectionOptions.
The debugger can attach to the local kernel, but only in a limited way and only if the computer was booted with the /debug boot switch. (In some Windows installations, local
kernel debugging is supported when other switches are used, such as /debugport, but this is not a guaranteed feature of Windows and should not be relied on.)
IsKernelDebuggerEnabled is used to determine if the local computer is available for debugging. For more information about kernel debugging on a single machine, see
Performing Local Kernel Debugging.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Dump-File Targets
For an introduction and overview of crash dump files, see Crash Dump Files.

Opening Dump Files

To open a crash dump file for use as a debugger target, use OpenDumpFile or OpenDumpfileWide. These methods are similar to the .opendump debugger command.
Note The engine doesn't completely attach to the dump file until the WaitForEvent method has been called. When a dump file is created from a process or kernel,
information about the last event is stored in the dump file. After the dump file is opened, the next time execution is attempted, the engine will generate this event for the event
callbacks. Only then does the dump file become available in the debugging session. See Debugging Session and Execution Model for more details.
Additional files can be used to assist in debugging a crash dump file. The methods AddDumpInformationFile and AddDumpInformationFileWide register files containing
page-file information to be used when the next dump file is opened. These methods must be called before the dump file is opened. GetNumberDumpFiles will return the
number of such files that were used when the current dump file was opened and GetDumpFile will return a description of these files.
User-mode minidump files contain several streams of information. These streams can be read using the Request operation
DEBUG_REQUEST_READ_USER_MINIDUMP_STREAM.

Creating Dump Files

To create a crash dump file of the current target user-mode or kernel-mode use WriteDumpFile2. This method is similar to the .dump debugger command.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Remote Targets
There are two different forms of remote debugging, depending on which computer (remote client or server) is the host computer. The host computer is the computer on which
the debugger engine is active. On the other computer, the debugger engine is merely acting as a proxy relaying commands and data to the host engine.
All debugger operations such as executing commands and extensions, and symbol loading are performed by the host engine. A debugger session is also relative to the
host engine.
To list the debugging servers and process servers currently running on a computer, use OutputServers.

Debugging Servers and Debugging Clients

A debugging server is an instance of the debugger engine acting as a host and listening for connections from debugging clients. The method StartServer will tell the
debugger engine to start listening for connections from debugging clients.
A debugging client is an instance of the debugger engine acting as a proxy, sending debugger commands and I/O to the debugging server. The function DebugConnect can be
used to connect to the debugging server.
The client object returned by DebugConnect is not automatically joined to the debugger session on the debugging server. The method ConnectSession can be used to join the
session, synchronizing input and output.
The communication between a debugging server and a debugging client mostly consists of debugger commands and RPC calls sent to the server, and command output sent
back to the client.

Process Servers, Kernel Connection Servers, and Smart Clients

Process servers and kernel connection servers are both instances of the debugger engine acting as proxies, listening for connections from smart clients, and performing
memory, processor, or operating system operations as requested by these remote clients. A process server facilitates the debugging of processes that are running on the same
computer. A kernel connection server facilitates the debugging of a Windows kernel debugging target that is connected to the computer that is running the connection server.
A process server can be started using the method StartProcessServer or the program DbgSrv. The method WaitForProcessServerEnd will wait for a process server started
with StartProcessServer to end. A kernel connection server can be activated using the program KdSrv.
A smart client is an instance of the debugger engine acting as a host engine and connected to a process server. The method ConnectProcessServer will connect to a process
server. Once connected, the methods described in Live User-Mode Targets can be used.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1167 of 1651

When the remote client is finished with the process server, it can disconnect using DisconnectProcessServer, or it can use EndProcessServer to request that the process
server shut down. To shut down the process server from the computer that it is running on, use Task Manager to end the process. If the instance of the debugger engine that
used StartProcessServer is still running, it can use Execute to issue the debugger command .endsrv 0, which will end the process server (this is an exception to the usual
behavior of .endsrv, which generally does not affect process servers).
The communication between a process server and a smart client typically consists of low-level memory, processor, and operating system operations and requests that are sent
from the remote client to the server. Their results are then sent back to the client.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Target Information
The method GetDebuggeeType returns the nature of the current target (for example, whether it is a kernel-mode or user-mode target), and how the debugger engine is
connected to it.
If the target is a crash dump file file, the method GetDumpFormatFlags will indicate what information is contained in the dump.
Target's Computer
The page size of the target's computer is returned by GetPageSize. IsPointer64Bit will indicate if the computer uses 32-bit or 64-bit addresses.
Note Internally, the debugger engine always uses 64-bit addresses for the target. If the target only uses 32-bit addresses, the engine automatically converts them when
communicating with the target.
The number of processors in the target's computer is returned by GetNumberProcessors.
There are three different processor types associated with the target's computer:

The actual processor type is the type of the physical processor in the target's computer. This is returned by GetActualProcessorType.
The executing processor type is the type of the processor used in the currently executing processor context. This is returned by GetExecutingProcessorType.
The effective processor type is the processor type the debugger uses when interpreting information from the target for example, setting breakpoints, accessing
registers, and getting stack traces. The effective processor type is returned by GetEffectiveProcessorType and can be changed using SetEffectiveProcessorType.

The effective processor type and executing processor type may differ from the actual processor type for example, when the physical processor is an x64 processor and it is
running in x86 mode.
The different executing processor types that are supported by the physical processor on the target's computer are returned by GetPossibleExecutingProcessorTypes. The
number of these is returned by GetNumberPossibleExecutingProcessorTypes.
The list of processor types that is supported by the debugger engine is returned by GetSupportedProcessorTypes. The number of supported processor types is returned by
GetNumberSupportedProcessorTypes.
The names (full and abbreviated) of a processor type are returned by GetProcessorTypeNames.
The current time on the target's computer is returned by GetCurrentTimeDate. The length of time the target's computer has been running since the last boot is returned by
GetCurrentSystemUpTime. Time information may not be available for all targets.
Target Versions
The Windows version running on the target's computer is returned by GetSystemVersionValues and the Request operation
DEBUG_REQUEST_GET_WIN32_MAJOR_MINOR_VERSIONS, and a description of the Windows version is returned by GetSystemVersionString. Some of this
information is also returned by GetSystemVersion.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Target State
The method OutputCurrentState will print the current state of the target to the debugger's output stream.
The current execution status of the target is returned by GetExecutionStatus. If the target is suspended, the method SetExecutionStatus can be used to resume execution in
one of the execution modes.
The method GetReturnOffset returns the address of the instruction that will execute when the current function returns.
GetNearInstruction returns the location of an instruction relative to a given address.
Examining the Stack Trace
A call stack contains the data for the function calls that are made by a thread. The data for each function call is called a stack frame and includes the return address,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1168 of 1651

parameters passed to the function, and the function's local variables. Each time a function call is made, a new stack frame is pushed onto the top of the stack. When that
function returns, the stack frame is popped off the stack. Each thread has its own call stack, which represents the calls that are made in that thread.
Note Not all of the data for a function call can be stored in the stack frame. Parameters and local variables, at times, can be stored in registers.
To retrieve the call stack or stack trace, use the methods GetStackTrace and GetContextStackTrace. The stack trace can be printed using OutputStackTrace and
OutputContextStackTrace.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Calling Extensions and Extension Functions

To load an extension library (or to obtain a handle for an already loaded extension library), use AddExtension. An extension library can be unloaded with RemoveExtension.
Extension commands can be called using CallExtension.
Extension Functions
Extension functions are functions that are exported by extension libraries. They can use any function prototype and are called directly using C function pointers.
They are not extension commands and are not available via debugger commands. Extension functions cannot be called remotely; they must be called directly. Hence they
cannot be used from debugging clients. They can only be called when the client object is inside the host engine - when not remotely debugging or when using a smart client.
Extension functions are identified within extension libraries by the "_EFN_" prepended to their names.
To obtain a pointer to an extension function, use GetExtensionFunction. The type of this function pointer should match the prototype of the extension function. The
extension function can now be called just like any other function pointer in C.
Example
If the following extension function was included in an extension library and loaded into the debugger engine:
HRESULT CALLBACK
_EFN_GetObject(IDebugClient * client, SomeObject * obj);
It could be called using:
typedef ULONG (CALLBACK * GET_OBJECT)(IDebugClient * client, SomeObject * obj);

HRESULT status = S_OK;

GET_OBJECT extFn = NULL;
SomeObject myObj;
if (g_DebugControl->
GetExtensionFunction(0,
"GetObject",
(FARPROC *) &extFn ) == S_OK &&
extFn)
{
status = (*extFn)(client, &myObj);
}

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Assembling and Disassembling Instructions

The debugger engine supports the use of assembly language for displaying and changing code in the target. For an overview of the use of assembly language in the debugger,
see Debugging in Assembly Mode.
Note: Assembly language is not supported for all architectures. And on some architectures not all instructions are supported.
To assemble a single assembly-language instruction and place the resulting processor instruction in the target's memory, use Assemble.
To disassemble a single instruction by taking a processor instruction from the target and producing a string that represents the assembly instruction, use Disassemble.
The method GetDisassembleEffectiveOffset returns the first effective address of the last instruction to be disassembled. For example, if the last instruction to be

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1169 of 1651

disassembled is move ax, [ebp+4], the effective address is the value of ebp+4. This corresponds to the $ea pseudo-register.
To send disassembled instructions to the output callbacks, use the methods OutputDisassembly and OutputDisassemblyLines.
The debugger engine has some options that control the assembly and disassembly. These options are returned by GetAssemblyOptions. They can be set using
SetAssemblyOptions and some options can be turned on with AddAssemblyOptions or turned off with RemoveAssemblyOptions.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugger Engine Reference

This section includes:
Client Functions
Client COM Interfaces
Callback COM Interfaces
Other COM Interfaces
Structures and Constants
Certain common methods are supported by all COM interfaces on Microsoft Windows. These methods are not listed individually in this reference section. For details, see
Using Client Objects.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Client Functions
This section includes:
DebugConnect
DebugCreate
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugConnect
The DebugConnect and DebugConnectWide functions create a new client object and return an interface pointer to it. The client object will be connected to a remote host.
HRESULT
DebugConnect(
IN PCSTR RemoteOptions,
IN REFIID InterfaceId,
OUT PVOID * Interface
);
HRESULT
DebugConnectWide(
IN PCWSTR RemoteOptions,
IN REFIID InterfaceId,
OUT PVOID * Interface
);
#ifdef UNICODE
#define DebugConnectT DebugConnectWide
#else
#define DebugConnectT DebugConnect
#endif

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1170 of 1651

Parameters
RemoteOptions
Specifies how the debugger engine will connect to the remote host. These are the same options that get passed to the -remote option on the command line. For details on
the syntax of this string, see Activating a Debugging Client.
InterfaceId
Specifies the interface identifier (IID) of the desired debugger engine client interface. This is the type of the interface that will be returned in Interface. For information
about the interface identifier, see COM Interfaces.
Interface
Receives an interface pointer for the new client. The type of this interface is specified by InterfaceId.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Comments
As with IUnknown::QueryInterface, when the returned interface is no longer needed, its IUnknown::Release method should be called.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
Client Objects, Process Server and Smart Client
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugCreate
The DebugCreate function creates a new client object and returns an interface pointer to it.
HRESULT
DebugCreate(
IN REFIID InterfaceId,
OUT PVOID * Interface
);
Parameters
InterfaceId
Specifies the interface identifier (IID) of the desired debugger engine client interface. This is the type of the interface that will be returned in Interface. For information
about the interface identifier, see COM Interfaces.
Interface
Receives an interface pointer for the new client. The type of this interface is specified by InterfaceId.
Return Value
S_OK
The function was successful.
E_NOINTERFACE
The client object doesn't implement the specified interface.
This method may also return other error values. See Return Values for more details.
Comments
The parameters passed to DebugCreate are the same as those passed to IUnknown::QueryInterface, and they are treated the same way.
As with IUnknown::QueryInterface, when the returned interface is no longer needed, its IUnknown::Release method should be called.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
Client Objects
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1171 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Client COM Interfaces

This section includes:
IDebugAdvanced
IDebugClient
IDebugControl
IDebugDataSpaces
IDebugRegisters
IDebugSymbols
IDebugSystemObjects
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugAdvanced
The IDebugAdvanced interface includes the following methods:
GetThreadContext
SetThreadContext
Request
GetSourceFileInformation
FindSourceFileAndToken
GetSymbolInformation
GetSystemObjectInformation
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetThreadContext
The GetThreadContext method returns the current thread context.
HRESULT
IDebugAdvanced::GetThreadContext(
OUT PVOID Context,
IN ULONG ContextSize
);
Parameters
Context
Receives the current thread context. The type of the thread context is the CONTEXT structure for the target's effective processor. The buffer Context must be large
enough to hold this structure.
ContextSize
Specifies the size of the buffer Context.
Return Value
S_OK
The method was successful.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1172 of 1651

This method may also return error values. See Return Values for more details.
Interface Version
GetThreadContext is available in all versions of IDebugAdvanced.
Comments
For more information about the thread context, see Scopes and Symbol Groups.
Note The CONTEXT structure varies with operating system and platform. Care should be taken when using the CONTEXT structure.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h. CONTEXT is defined in ntddk.h.
See Also
GetScope, SetThreadContext
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetThreadContext
The SetThreadContext method sets the current thread context.
HRESULT
IDebugAdvanced::SetThreadContext(
IN PVOID Context,
IN ULONG ContextSize
);
Parameters
Context
Specifies the thread context. The type of the thread context is the CONTEXT structure for the target's effective processor. The buffer Context must be large enough to
hold this structure.
ContextSize
Specifies the size of the buffer Context.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetThreadContext is available in all versions of IDebugAdvanced.
Comments
For more information about the thread context, see Scopes and Symbol Groups.
Note The CONTEXT structure varies with operating system and platform. Care should be taken when using the CONTEXT structure.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
SetScope, GetThreadContext
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Request

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1173 of 1651

The Request method performs a variety of different operations.

HRESULT
IDebugAdvanced2::Request(
IN ULONG Request,
IN OPTIONAL PVOID InBuffer,
IN ULONG InBufferSize,
OUT OPTIONAL PVOID OutBuffer,
IN ULONG OutBufferSize,
OUT OPTIONAL PULONG OutSize
);
Parameters
Request
Specifies which operation to perform. Request can be one of the values in the following table. Details of each operation can be found by following the link in the Request
column.
Request
Action
DEBUG_REQUEST_SOURCE_PATH_HAS_SOURCE_SERVER
Check the source path for a source server.
DEBUG_REQUEST_TARGET_EXCEPTION_CONTEXT
Return the thread context for the stored event in a user-mode minidump file.
DEBUG_REQUEST_TARGET_EXCEPTION_THREAD
Return the operating system thread ID for the stored event in a user-mode minidump file.
DEBUG_REQUEST_TARGET_EXCEPTION_RECORD
Return the exception record for the stored event in a user-mode minidump file.
DEBUG_REQUEST_GET_ADDITIONAL_CREATE_OPTIONS
Return the default process creation options.
DEBUG_REQUEST_SET_ADDITIONAL_CREATE_OPTIONS
Set the default process creation options.
DEBUG_REQUEST_GET_WIN32_MAJOR_MINOR_VERSIONS
Return the version of Windows that is currently running on the target.
DEBUG_REQUEST_READ_USER_MINIDUMP_STREAM
Read a stream from a user-mode minidump target.
DEBUG_REQUEST_TARGET_CAN_DETACH
Check to see if it is possible for the debugger engine to detach from the current process (leaving
the process running but no longer being debugged).
DEBUG_REQUEST_SET_LOCAL_IMPLICIT_COMMAND_LINE Set the debugger engine's implicit command line.
DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET Return the current event's instruction pointer.
DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM Return up to 64 bytes of memory at the current event's instruction pointer.
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI
Perform a variety of different operations that aid in the interpretation of typed data.
InBuffer
Specifies the input to this method. The type and interpretation of the input depends on the Request parameter.
InBufferSize
Specifies the size of the input buffer InBuffer. If the request requires no input, InBufferSize should be set to zero.
OutBuffer
Receives the output from this method. The type and interpretation of the output depends on the Request parameter. If OutBuffer is NULL, the output is not returned.
OutBufferSize
Specifies the size of the output buffer OutBufferSize. If the type of the output returned to OutBuffer has a known size, OutBufferSize is usually expected to be exactly that
size, even if OutBuffer is set to NULL.
OutSize
Receives the size of the output returned in the output buffer OutBuffer. If OutSize is NULL, this information is not returned.
Return Value
The interpretation of the return value depends on the value of the Request parameter. Unless otherwise stated, the following values may be returned.
S_OK
The method was successful.
S_FALSE
The method was successful. However, the output would not fit in the output buffer OutBuffer, so truncated output was returned.
E_INVALIDARG
The size of the input buffer InBufferSize or the size of the output buffer OutBufferSize was not the expected value.
This method may also return error values. See Return Values for more details.
Interface Version
Request is available in IDebugAdvanced2 and later versions.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
DEBUG_REQUEST_SOURCE_PATH_HAS_SOURCE_SERVER, DEBUG_REQUEST_TARGET_EXCEPTION_CONTEXT,
DEBUG_REQUEST_TARGET_EXCEPTION_THREAD, DEBUG_REQUEST_TARGET_EXCEPTION_RECORD,
DEBUG_REQUEST_GET_ADDITIONAL_CREATE_OPTIONS, DEBUG_REQUEST_SET_ADDITIONAL_CREATE_OPTIONS,
DEBUG_REQUEST_GET_WIN32_MAJOR_MINOR_VERSIONS, DEBUG_REQUEST_READ_USER_MINIDUMP_STREAM,
DEBUG_REQUEST_TARGET_CAN_DETACH, DEBUG_REQUEST_SET_LOCAL_IMPLICIT_COMMAND_LINE,
DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET, DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1174 of 1651

Debugging Tools for Windows

DEBUG_REQUEST_SOURCE_PATH_HAS_SOURCE_SERVER
The DEBUG_REQUEST_SOURCE_PATH_HAS_SOURCE_SERVER Request operation checks the source path for a source server.
Parameters
InBuffer
Not used.
OutBuffer
Not used.
Return Value
S_OK
The source path includes a source server
S_FALSE
The source path does not include a source server.
See Also
Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET
The DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET Request operation returns the current event's instruction pointer.
Parameters
InBuffer
Not used.
OutBuffer
The instruction pointer of the current event. The type of the instruction pointer is ULONG64.
Return Value
S_OK
The method was successful.
E_NOINTERFACE
The memory at the instruction pointer for the current event is not valid.
This method may also return error values. See Return Values for more details.
Comments
The memory at the instruction pointer for the current event can be read using the Request operation's
DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM.
See Also
Request, DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM
The DEBUG_REQUEST_READ_CAPTURED_EVENT_CODE_STREAM Request operation returns up to 64 bytes of memory at the current event's instruction pointer.
Parameters
InBuffer
Not used.
OutBuffer
The memory at the current event's instruction pointer. Up to 64 bytes of memory may be returned.
Comments
The memory returned is a snapshot of the memory taken when the event occurred. It does not reflect any changes that may have been made to the target's memory since the
event.
The current event's instruction pointer is returned by the Request operation DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET.
See Also
Request, DEBUG_REQUEST_GET_CAPTURED_EVENT_CODE_OFFSET
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_REQUEST_EXT_TYPED_DATA_ANSI
The DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation performs a variety of different sub-operations that aid in the interpretation of typed data.
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1182 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_EVALUATE
The EXT_TDOP_EVALUATE sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation returns the typed data description that represents
the value of an expression.
Parameters
Operation
Set to EXT_TDOP_EVALUATE for this sub-operation.
Flags
Specifies the bit flags that describe the target's memory in which the value of the expression resides. See EXT_TYPED_DATA for details of these flags.
InData
Specifies optional typed data whose value can be used in the expression specified by InStrIndex. This value is used by the expression as the pseudo-register $extin.
OutData
Receives the DEBUG_TYPED_DATA structure that represents the value of the expression.
InStrIndex
Specifies the expression to evaluate. This expression is evaluated by the default expression evaluator.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_EVALUATE is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_GET_TYPE_NAME
The EXT_TDOP_GET_TYPE_NAME sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation returns the type name of the specified
typed data.
Parameters
Operation
Set to EXT_TDOP_GET_TYPE_NAME for this sub-operation.
InData
Specifies the typed data whose type name is being requested.
StrBufferIndex
Receives the type name.
StrBufferChars
Specifies the size, in characters, of the ANSI string buffer StrBufferIndex.
StrCharsNeeded
Receives the size, in characters, of the type name.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_GET_TYPE_NAME is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1183 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

EXT_TDOP_OUTPUT_TYPE_NAME
The EXT_TDOP_OUTPUT_TYPE_NAME sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation prints the type name of the specified
typed data.
Parameters
Operation
Set to EXT_TDOP_OUTPUT_TYPE_NAME for this sub-operation.
InData
Specifies the typed data whose type name will be printed.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
The type name is sent to the debugger engine's output callbacks.
EXT_TDOP_OUTPUT_TYPE_NAME is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Receives the value pointed to.

Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_GET_DEREFERENCE is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_GET_TYPE_SIZE
The EXT_TDOP_GET_TYPE_SIZE sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation returns the size of the specified typed data.
Parameters
Operation
Set to EXT_TDOP_GET_TYPE_SIZE for this sub-operation.
InData
Specifies the typed data whose size is being requested.
Out32
Receives the size, in bytes, of the typed data.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_GET_TYPE_SIZE is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_OUTPUT_TYPE_DEFINITION
The EXT_TDOP_OUTPUT_TYPE_DEFINITION sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation prints the definition of the
type for the specified typed data.
Parameters
Operation
Set to EXT_TDOP_OUTPUT_TYPE_DEFINITION for this sub-operation.
InData
Specifies the typed data whose type's definition will be printed.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
The definition of the type is formatted and sent to the debugger engine's output callbacks.
EXT_TDOP_OUTPUT_TYPE_DEFINITION is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1187 of 1651

See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_GET_POINTER_TO
The EXT_TDOP_GET_POINTER_TO sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation returns a new typed data description that
represents a pointer to specified typed data.
Parameters
Operation
Set to EXT_TDOP_GET_POINTER_TO for this sub-operation.
InData
Specifies the original typed data description to which a pointer is returned.
OutData
Receives a typed data description that represents a pointer to the typed data specified by InData.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_GET_POINTER_TO is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, EXT_TDOP, EXT_TYPED_DATA, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP_SET_FROM_TYPE_ID_AND_U64
The EXT_TDOP_SET_FROM_TYPE_ID_AND_U64 sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation creates a typed data
description from a data type and a memory location.
Parameters
Operation
Set to EXT_TDOP_SET_FROM_TYPE_ID_AND_U64 for this sub-operation.
Flags
Specifies the bit flags that describe the target's memory in which the value of the typed data resides. See EXT_TYPED_DATA for details of these flags.
InData
Specifies the type and the memory location. This instance of the DEBUG_TYPED_DATA structure can be manually created and populated with the required members.
The following members are used:
ModBase
Specifies the location in the target's virtual memory of the base address of the module that contains the type.
Offset
Specifies the location in the target's memory of the data. Offset is a virtual memory address unless there are flags present in Flags that specify that Offset is a
physical memory address.
TypeId
Specifies the type ID of the type.
OutData
Receives the typed data description.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_SET_FROM_TYPE_ID_AND_U64 is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1188 of 1651

EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64
The EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64 sub-operation of the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation creates a typed data
description that represents a pointer to a specified memory location with a specified type.
Parameters
Operation
Set to EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64 for this sub-operation.
Flags
Specifies the bit flags that describe the target's memory in which the value of the typed data resides. See EXT_TYPED_DATA for details of these flags.
InData
Specifies the type and memory location. This instance of the DEBUG_TYPED_DATA structure can be manually created and populated with the required members. The
following members are used:
ModBase
Specifies the location in the target's virtual memory of the base address of the module that contains the type.
Offset
Specifies the location in the target's memory of the data. Offset is a virtual memory address unless there are flags present in Flags that specify that Offset is a
physical memory address.
TypeId
Specifies the type ID of the type.
OutData
Receives the typed data description that represents a pointer to the memory location and type.
Status
Receives the status code returned by this sub-operation. This is the same as the value returned by Request.
Comments
EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64 is a value in the EXT_TDOP enumeration.
The parameters for this sub-operation are members of the EXT_TYPED_DATA structure. The members of EXT_TYPED_DATA that are not listed in the preceding
Parameters section are not used by this sub-operation and should be set to zero. The descriptions of the members in the preceding Parameters section specify what the
members are used for. See EXT_TYPED_DATA for more details.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI EXT_TDOP, EXT_TYPED_DATA, Request,
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetSourceFileInformation
The GetSourceFileInformation and GetSourceFileInformationWide methods return specified information about a source file.
HRESULT
IDebugAdvanced2::GetSourceFileInformation(
IN ULONG Which,
IN PSTR SourceFile,
IN ULONG64 Arg64,
IN ULONG Arg32,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG InfoSize
);
HRESULT
IDebugAdvanced3::GetSourceFileInformationWide(
IN ULONG Which,
IN PWSTR SourceFile,
IN ULONG64 Arg64,
IN ULONG Arg32,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

OUT OPTIONAL PULONG

);

Page 1189 of 1651

InfoSize

#ifdef UNICODE
#define GetSourceFileInformationT GetSourceFileInformationWide
#else
#define GetSourceFileInformationT GetSourceFileInformation
#endif
Parameters
Which
Specifies the piece of information to return. The Which parameter can take one of the values in the following table.
DEBUG_SRCFILE_SYMBOL_TOKEN
Returns a token representing the specified source file on a source server. This token can be passed to FindSourceFileAndToken to retrieve information about the
file. The token is returned to the Buffer buffer as an array of bytes. The size of this token is a reflection of the size of the SrcSrv token.
DEBUG_SRCFILE_SYMBOL_TOKEN_SOURCE_COMMAND_WIDE
Queries a source server for the command to extract the source file from source control. This includes the name of the executable file and its command-line
parameters. The command is returned to the Buffer buffer as a Unicode string.
SourceFile
Specifies the source file whose information is being requested. The source file is looked up on all the source servers in the source path.
Arg64
Specifies a 64-bit argument. The value of Which specifies the module whose symbol token is requested. Regardless of the value of Which, Arg64 is a location within the
memory allocation of the module.
Arg32
Specifies a 32-bit argument. This parameter is currently unused.
Buffer
Receives the requested symbol information. The type of the data returned depends on the value of Which. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size in bytes of the Buffer buffer. If Buffer is NULL, BufferSize must also be NULL.
InfoSize
Specifies the size in bytes of the information returned to the Buffer buffer. This parameter can be NULL if the data is not required.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the information would not fit in the Buffer buffer, so the information or name was truncated.
This method may also return error values. See Return Values for more details.
Interface Version
GetSourceFileInformation is available in IDebugAdvanced2 and later versions. GetSourceFileInformationWide is available in IDebugAdvanced3 and later versions.
Comments
For more information about source files, see Using Source Files.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
FindSourceFileAndToken
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

FindSourceFileAndToken
The FindSourceFileAndToken and FindSourceFileAndTokenWide methods returns the filename of a source file on the source path or return the value of a variable
associated with a file token.
HRESULT
IDebugAdvanced2::FindSourceFileAndToken(
IN ULONG StartElement,
IN ULONG64 ModAddr,
IN PCSTR File,
IN ULONG Flags,
IN OPTIONAL PVOID FileToken,
IN ULONG FileTokenSize,
OUT OPTIONAL PULONG FoundElement,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

OUT OPTIONAL PULONG

);

IDebugAdvanced2::GetSystemObjectInformation(
IN ULONG Which,
IN ULONG64 Arg64,
IN ULONG Arg32,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG InfoSize
);
Parameters
Which
Specifies the type of object and the type of information to return about that object. Which can take the following value.
Value
Information returned
DEBUG_SYSOBJINFO_THREAD_BASIC_INFORMATION Returns details of the thread specified by engine thread ID.
Arg64
Specifies a 64-bit argument. This parameter has the following interpretations depending on the value of Which:
DEBUG_SYSOBJINFO_THREAD_BASIC_INFORMATION
Not used.
Arg32
Specifies a 32-bit argument. This parameter has the following interpretations depending on the value of Which:
DEBUG_SYSOBJINFO_THREAD_BASIC_INFORMATION
The engine thread ID of the desired thread.
Buffer
Receives the requested information. The type of data returned in Buffer depends on the value of Which.
Value
Return type
DEBUG_SYSOBJINFO_THREAD_BASIC_INFORMATION DEBUG_THREAD_BASIC_INFORMATION
BufferSize
Specifies the size, in bytes, of the buffer Buffer.
InfoSize
Receives the size of the information that is returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the information would not fit in the buffer Buffer, so the information was truncated.
This method may also return error values. See Return Values for more details.
Interface Version
GetSystemObjectInformation is available in IDebugAdvanced2 and later versions.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
IDebugSystemObjects
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugClient
The IDebugClient Interface includes the following methods:
DispatchCallbacks
ExitDispatch
FlushCallbacks
GetEventCallbacks
SetEventCallbacks
GetNumberEventCallbacks
GetInputCallbacks

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Introduction

Page 1197 of 1651

S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
FlushCallbacks is available in all versions of IDebugClient.
Comments
The engine sometimes merges compatible callback requests to reduce callback overhead; small pieces of output are collected into larger groups to reduce the number of
IDebugOutputCallbacks::Output calls. Using FlushCallbacks is necessary for a client to guarantee that all pending callbacks have been processed at a particular point. For
example, a caller can flush callbacks before starting a lengthy operation outside of the engine so that pending callbacks are not delayed until after the operation.
For more information about callbacks, see Callbacks.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
IDebugOutputCallbacks, IDebugOutputCallbacks::Output, DispatchCallbacks
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetEventCallbacks
The GetEventCallbacks and GetEventCallbacksWide methods return the event callbacks object registered with this client.
HRESULT
IDebugClient::GetEventCallbacks(
OUT IDebugEventCallbacks * * Callbacks
);
HRESULT
IDebugClient5::GetEventCallbacksWide(
OUT IDebugEventCallbacksWide * * Callbacks
);
#ifdef UNICODE
#define GetEventCallbacksT GetEventCallbacksWide
#define IDebugEventCallbacksT IDebugEventCallbacksWide
#else
#define GetEventCallbacksT GetEventCallbacks
#define IDebugEventCallbacksT IDebugEventCallbacks
#endif
Parameters
Callbacks
Receives an interface pointer to the event callbacks object registered with this client.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetEventCallbacks is available in all versions of IDebugClient. GetEventCallbacksWide is available in IDebugClient5 and later versions.
Comments
Each client can have at most one IDebugEventCallbacks or IDebugEventCallbacksWide object registered with it for receiving events.
If no event callbacks object is registered with the client, the value of Callbacks will be set to NULL.
The IDebugEventCallbacks interface extends the COM interface IUnknown. Before returning the IDebugEventCallbacks object specified by Callbacks, the engine calls
its IUnknown::AddRef method. When this object is no longer needed, its IUnknown::Release method should be called.
For more information about callbacks, see Callbacks.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Parameters
Count
Receives the number of input callbacks that have been registered.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetNumberInputCallbacks is available in IDebugClient5 and later versions.
Comments
Each client can have at most one input callback registered with it.
For more information about callbacks, see Callbacks.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
IDebugInputCallbacks, GetInputCallbacks, SetInputCallbacks, GetNumberOutputCallbacks, GetNumberEventCallbacks
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetOutputCallbacks
The GetOutputCallbacks and GetOutputCallbacksWide methods return the output callbacks object registered with the client.
HRESULT
IDebugClient::GetOutputCallbacks(
OUT IDebugOutputCallbacks * * Callbacks
);
HRESULT
IDebugClient5::GetOutputCallbacksWide(
OUT IDebugOutputCallbacksWide * * Callbacks
);
#ifdef UNICODE
#define GetOutputCallbacksT GetOutputCallbacksWide
#define IDebugOutputCallbacksT IDebugOutputCallbacksWide
#else
#define GetOutputCallbacksT GetOutputCallbacks
#define IDebugOutputCallbacksT IDebugOutputCallbacks
#endif
Parameters
Callbacks
Receives an interface pointer to the IDebugOutputCallbacks object registered with the client.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetOutputCallbacks is available in all versions of IDebugClient. GetOutputCallbacksWide is available in IDebugClient5 and later versions.
Comments
Each client can have at most one IDebugOutputCallbacks or IDebugOutputCallbacksWide object registered with it for output.
If no output callbacks object is registered with the client, the value of Callbacks will be set to NULL.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Interface Version
SetKernelConnectionOptions is available in all versions of IDebugClient. SetKernelConnectionOptionsWide is available in IDebugClient5 and later versions.
Comments
This method is available only for live kernel targets that are not local and not connected through eXDI. This method is reentrant.
For more information about connecting to live kernel-mode targets, see Live Kernel-Mode Targets.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
AttachKernel
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IsKernelDebuggerEnabled
The IsKernelDebuggerEnabled method checks whether kernel debugging is enabled for the local kernel.
HRESULT
IDebugClient2::IsKernelDebuggerEnabled();
Parameters
None
Return Value
S_OK
Kernel debugging is enabled for the local kernel.
S_FALSE
Kernel debugging is not enabled for the local kernel.
This method may also return error values. See Return Values for more details.
Interface Version
IsKernelDebuggerEnabled is available in IDebugClient2 and later versions.
Comments
Kernel debugging is available for the local computer if the computer was booted by using the /debug boot switch. In some Windows installations, local kernel debugging is
supported when other switchessuch as /debugportare used, but this is not a guaranteed feature of Windows and should not be relied on. For more information about
kernel debugging on a single computer, see Performing Local Kernel Debugging.
For more information about connecting to live kernel-mode targets, see Live Kernel-Mode Targets.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
AttachKernel
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetOutputMask
The GetOutputMask method returns the output mask currently set for the client.
HRESULT
IDebugClient::GetOutputMask(
OUT PULONG Mask

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1216 of 1651

);
Parameters
Mask
Receives the output mask for the client. See DEBUG_OUTPUT_XXX for details on how to interpret this value.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetOutputMask is available in all versions of IDebugClient.
Comments
For an overview of output in the debugger engine, see Input and Output.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
SetOutputMask, GetOtherOutputMask
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetOutputMask
The SetOutputMask method sets the output mask for the client.
HRESULT
IDebugClient::SetOutputMask(
IN ULONG Mask
);
Parameters
Mask
Specifies the new output mask for the client. See DEBUG_OUTPUT_XXX for a description of the possible values for Mask.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetOutputMask is available in all versions of IDebugClient.
Comments
For an overview of output in the debugger engine, see Input and Output.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
GetOutputMask, SetOtherOutputMask
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

#ifdef UNICODE
#define CreateProcess2T CreateProcess2Wide
#else
#define CreateProcess2T CreateProcess2
#endif
Parameters
Server
Specifies the process server that will be attached to the process. If Server is zero, the engine will create the local process without using a process server.
CommandLine
Specifies the command line to execute to create the new process.
OptionsBuffer
Specifies the process creation options. OptionsBuffer is a pointer to a DEBUG_CREATE_PROCESS_OPTIONS structure.
OptionsBufferSize
Specifies the size of the buffer OptionsBuffer. This should be set to sizeof(DEBUG_CREATE_PROCESS_OPTIONS).
InitialDirectory
Specifies the starting directory for the process. If InitialDirectory is NULL, the current directory for the process server is used.
Environment
Specifies an environment block for the new process. An environment block consists of a null-terminated block of null-terminated strings. Each string is of the form:
name=value
Note that the last two characters of the environment block are both NULL: one to terminate the string and one to terminate the block.
If Environment is set to NULL, the new process inherits the environment block of the process server. If the DEBUG_CREATE_PROCESS_THROUGH_RTL flag is set
in OptionsBuffer, then Environment must be NULL.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
CreateProcess2 and CreateProcess2Wide are available in IDebugClient5 and later versions.
Comments
This method is available only for live user-mode debugging.
If CreateFlags contains either of the flags DEBUG_PROCESS or DEBUG_ONLY_THIS_PROCESS, the engine will also attach to the newly created process. This is similar
to the behavior of CreateProcessAndAttach2 with its argument ProcessId set to zero.
For more information about creating and attaching to live user-mode targets, see Live User-Mode Targets.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
CreateProcessAndAttach2, AttachProcess, .create (Create Process), ConnectProcessServer, CreateProcess2, GetRunningProcessSystemIds,
GetRunningProcessDescription , DetachCurrentProcess, TerminateCurrentProcess, AbandonCurrentProcess
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CreateProcessAndAttach
The CreateProcessAndAttach and CreateProcessAndAttachWide methods create a process from a specified command line, then attach to another user-mode process. The
created process is suspended and only allowed to execute when the attach has completed. This allows rough synchronization when debugging both, client and server
processes.
HRESULT
IDebugClient::CreateProcessAndAttach(
IN ULONG64 Server,
IN OPTIONAL PSTR CommandLine,
IN ULONG CreateFlags,
IN ULONG ProcessId,
IN ULONG AttachFlags
);
HRESULT

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1221 of 1651

IDebugClient3::CreateProcessAndAttachWide(
IN ULONG64 Server,
IN OPTIONAL PWSTR CommandLine,
IN ULONG CreateFlags,
IN ULONG ProcessId,
IN ULONG AttachFlags
);
#ifdef UNICODE
#define CreateProcessAndAttachT CreateProcessAndAttachWide
#else
#define CreateProcessAndAttachT CreateProcessAndAttach
#endif
Parameters
Server
Specifies the process server to use to attach to the process. If Server is zero, the engine will connect to the local process without using a process server.
CommandLine
Specifies the command line to execute to create the new process. If CommandLine is NULL, then no process is created and these methods attach to an existing process,
as AttachProcess does.
CreateFlags
Specifies the flags to use when creating the process. For details on these flags, see DEBUG_CREATE_PROCESS_OPTIONS.CreateFlags.
ProcessId
Specifies the process ID of the target process the debugger will attach to. If ProcessId is zero, the debugger will attach to the process it created from CommandLine.
AttachFlags
Specifies the flags that control how the debugger attaches to the target process. For details on these flags, see DEBUG_ATTACH_XXX.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
CreateProcessAndAttach is available in all versions of IDebugClient. CreateProcessAndAttachWide is available in IDebugClient3 and later versions.
Comments
This method is available only for live user-mode debugging.
If CommandLine is not NULL and ProcessId is not zero, then the engine will create the process in a suspended state. The engine will resume this newly created process after
it successfully connects to the process specified in ProcessId.
Note The engine doesn't completely attach to the process until the WaitForEvent method has been called. Only after the process has generated an event for example, the
create-process event does it become available in the debugger session.
For more information about creating and attaching to live user-mode targets, see Live User-Mode Targets.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
CreateProcessAndAttach2, AttachProcess, .attach (Attach to Process), .create (Create Process), ConnectProcessServer, CreateProcess2,
GetRunningProcessSystemIds, GetRunningProcessDescription , DetachCurrentProcess, TerminateCurrentProcess, AbandonCurrentProcess
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CreateProcessAndAttach2
The CreateProcessAndAttach2 and CreateProcessAndAttach2Wide methods create a process from a specified command line, then attach to that process or another usermode process.
HRESULT
IDebugClient5::CreateProcessAndAttach2(
IN ULONG64 Server,
IN OPTIONAL PSTR CommandLine,
IN PVOID OptionsBuffer,
IN ULONG OptionsBufferSize,
IN OPTIONAL PCSTR InitialDirectory,
IN OPTIONAL PCSTR Environment,
IN ULONG ProcessId,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

IN ULONG
);

S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetRunningProcessSystemIds is available in all versions of IDebugClient.
Comments
This method is available only for live user-mode debugging.
For more information about creating and attaching to live user-mode targets, see Live User-Mode Targets.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
GetRunningProcessDescription, GetRunningProcessSystemIdByExecutableName, ConnectProcessServer, AttachProcess, CreateProcessAndAttach2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetRunningProcessSystemIdByExecutableName
The GetRunningProcessSystemIdByExecutableName and GetRunningProcessSystemIdByExecutableNameWide methods search for a process with a given executable
file name and return its process ID.
HRESULT
IDebugClient::GetRunningProcessSystemIdByExecutableName(
IN ULONG64 Server,
IN PCSTR ExeName,
IN ULONG Flags,
OUT PULONG Id
);
HRESULT
IDebugClient3::GetRunningProcessSystemIdByExecutableNameWide(
IN ULONG64 Server,
IN PCWSTR ExeName,
IN ULONG Flags,
OUT PULONG Id
);
#ifdef UNICODE
#define GetRunningProcessSystemIdByExecutableNameT GetRunningProcessSystemIdByExecutableNameWide
#else
#define GetRunningProcessSystemIdByExecutableNameT GetRunningProcessSystemIdByExecutableName
#endif
Parameters
Server
Specifies the process server to search for the executable name. If Server is zero, the engine will search for the executable name among the processes running on the local
computer.
ExeName
Specifies the executable file name for which to search.
Flags
Specifies a bit-set that controls how the executable name is matched. The following flags may be present:
Flag
Description
DEBUG_GET_PROC_FULL_MATCH ExeName specifies the full path name of the executable file name.
If this flag is not set, this method will not use path names when searching for the process.
DEBUG_GET_PROC_ONLY_MATCH Require that only one process match the executable file name ExeName.
Id
Receives the process ID of the first process to match ExeName.
Return Value
S_OK
The method was successful.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Interface Version
StartServer is available in all versions of IDebugClient. StartServerWide is available in IDebugClient5 and later versions.
Comments
The server that is started will be accessible by other debuggers through the transport specified in the Options parameter.
For more information about debugging servers, see Debugging Server and Debugging Client.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
DebugConnect, StartProcessServer, OutputServers
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ConnectSession
The ConnectSession method joins the client to an existing debugger session.
HRESULT
IDebugClient::ConnectSession(
IN ULONG Flags,
IN ULONG HistoryLimit
);
Parameters
Flags
Specifies a bit-set of option flags for connecting to the session. The possible values of these flags are:
Flag
Description
DEBUG_CONNECT_SESSION_NO_VERSION
Do not output the debugger engine's version to this client.
DEBUG_CONNECT_SESSION_NO_ANNOUNCE Do not output a message notifying other clients that this client has connected.
HistoryLimit
Specifies the maximum number of characters from the session's history to send to this client's output upon connection.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
ConnectSession is available in all versions of IDebugClient.
Comments
When the client object connects to a session, the most recent output from the session is sent to the client. If the session is currently waiting on input, the client object is given
the opportunity to provide input. Thus, the client object synchronizes with the session's input and output.
The client becomes a primary client and will appear among the list of clients in the output of the .clients debugger command.
For more information about debugging clients, see Debugging Server and Debugging Client. For more information about debugger sessions, see Debugging Session and
Execution Model.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
DebugConnect, StartServer, OutputServers
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1237 of 1651

Debugging Tools for Windows

EndSession
The EndSession method ends the current debugger session.
HRESULT
IDebugClient::EndSession(
IN ULONG Flags
);
Parameters
Flags
Specifies how to end the session. Flags can be one of the following values:
Flag
Description
DEBUG_END_PASSIVE
Perform cleanup for the session.
DEBUG_END_ACTIVE_TERMINATE Attempt to terminate all user-mode targets before performing cleanup for the session.
DEBUG_END_ACTIVE_DETACH
Attempt to disconnect from all targets before performing cleanup for the session.
DEBUG_END_REENTRANT
Perform only the cleanup that doesn't require acquiring locks. See Comments section for details.
DEBUG_END_DISCONNECT
Do not end the session. Disconnect the client from the session and disable the client.
This flag is intended for when remote clients disconnect. It generates a server message about the disconnection.

Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
EndSession is available in all versions of IDebugClient.
Comments
This method may be called at any time with Flags set to DEBUG_END_REENTRANT. If, for example, the application needs to exit but another thread is using the engine,
this method can be used to perform as much cleanup as possible.
Using DEBUG_END_REENTRANT may leave the engine in an indeterminate state. If this flag is used, no subsequent calls should be made to the engine.
For more information about debugger sessions, see Debugging Session and Execution Model.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugControl
The IDebugControl interface includes the following methods:
Assemble
AddAssemblyOptions
GetAssemblyOptions
RemoveAssemblyOptions
SetAssemblyOptions
Disassemble
Evaluate
Execute
ExecuteCommandFile

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1238 of 1651

AddBreakpoint
RemoveBreakpoint
GetBreakpointById
GetBreakpointByIndex
GetNumberBreakpoints
GetBreakpointParameters
ReadBugCheckData
GetCodeLevel
SetCodeLevel
GetDebuggeeType
GetDisassembleEffectiveOffset
OutputDisassembly
OutputDisassemblyLines
GetDumpFormatFlags
AddEngineOptions
GetEngineOptions
RemoveEngineOptions
SetEngineOptions
GetSystemErrorControl
SetSystemErrorControl
GetNotifyEventHandle
SetNotifyEventHandle
GetNumberEvents
GetCurrentEventIndex
SetNextEventIndex
GetEventIndexDescription
GetExpressionSyntax
SetExpressionSyntax
GetExpressionSyntaxNames
SetExpressionSyntaxByName
GetNumberExpressionSyntaxes
AddExtension
RemoveExtension
CallExtension
GetExtensionByPath
GetExtensionFunction
GetWindbgExtensionApis32
GetWindbgExtensionApis64
WaitForEvent
GetEventFilterCommand
SetEventFilterCommand
GetNumberEventFilters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

For more information about using assembly with the debugger engine API, see Assembling and Disassembling Instructions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
RemoveAssemblyOptions, SetAssemblyOptions, GetAssemblyOptions, DEBUG_ASMOPT_XXX, Assemble, Disassemble, .asm (Change Disassembly Options)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetAssemblyOptions
The GetAssemblyOptions method returns the assembly and disassembly options that affect how the debugger engine assembles and disassembles processor instructions for
the target.
HRESULT
IDebugControl3::GetAssemblyOptions(
OUT PULONG Options
);
Parameters
Options
Receives a bit-set that contains the assembly and disassembly options. For a description of these options, see DEBUG_ASMOPT_XXX.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
GetAssemblyOptions is available in IDebugControl3 and later versions.
Comments
For more information about using assembly with the debugger engine API, see Assembling and Disassembling Instructions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetAssemblyOptions, AddAssemblyOptions, RemoveAssemblyOptions, DEBUG_ASMOPT_XXX, Assemble, Disassemble, .asm (Change Disassembly Options)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

RemoveAssemblyOptions
The RemoveAssemblyOptions method turns off some of the assembly and disassembly options.
HRESULT
IDebugControl3::RemoveAssemblyOptions(
IN ULONG Options
);
Parameters
Options
Specifies the assembly and disassembly options to turn off. Options is a bit-set; the new value of the engine's options will equal the bitwise NOT of Options combined
with the old value by using the bitwise AND operator (

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1243 of 1651

). For a description of the assembly and disassembly options, see DEBUG_ASMOPT_XXX.

Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
RemoveAssemblyOptions is available in IDebugControl3 and later versions.
Comments
For more information about using assembly with the debugger engine API, see Assembling and Disassembling Instructions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
AddAssemblyOptions, SetAssemblyOptions, GetAssemblyOptions, DEBUG_ASMOPT_XXX, Assemble, Disassemble, .asm (Change Disassembly Options)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetAssemblyOptions
The SetAssemblyOptions method sets the assembly and disassembly options that affect how the debugger engine assembles and disassembles processor instructions for the
target.
HRESULT
IDebugControl3::SetAssemblyOptions(
IN ULONG Options
);
Parameters
Options
Specifies the new assembly and disassembly options to be used by the debugger engine. Options is a bit-set; it will replace the existing assembly and disassembly
options. For possible values, see DEBUG_ASMOPT_XXX. DEBUG_ASMOPT_DEFAULT can be used to set the default options.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
SetAssemblyOptions is available in IDebugControl3 and later versions.
Comments
For more information about using assembly with the debugger engine API, see Assembling and Disassembling Instructions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetAssemblyOptions, AddAssemblyOptions, RemoveAssemblyOptions, DEBUG_ASMOPT_XXX, Assemble, Disassemble, .asm (Change Disassembly Options)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Disassemble

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Introduction

IN ULONG Index,
OUT IDebugBreakpoint * *
);

Page 1250 of 1651

HRESULT
IDebugControl4::GetBreakpointByIndex2(
IN ULONG Index,
OUT IDebugBreakpoint2 * * Bp
);
Parameters
Index
Specifies the zero-based index of the breakpoint to return. This is specific to the current process. The value of Index should be between zero and the total number of
breakpoints minus one. The total number of breakpoints can be determined by calling GetNumberBreakpoints.
Bp
Receives the returned breakpoint.
Return Value
S_OK
The method was successful.
E_NOINTERFACE
No breakpoint was found with the given index, or the breakpoint with the given index is private.
This method can also return other error values. See Return Values for more details.
Interface Version
GetBreakpointByIndex is available in all versions of IDebugControl. GetBreakpointByIndex2 is available in IDebugControl4 and later versions.
Comments
The index and returned breakpoint are specific to the current process. The same index will return a different breakpoint if the current process is changed.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetNumberBreakpoints
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetNumberBreakpoints
The GetNumberBreakpoints method returns the number of breakpoints for the current process.
HRESULT
IDebugControl::GetNumberBreakpoints(
OUT PULONG Number
);
Parameters
Number
Receives the number of breakpoints.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
GetNumberBreakpoints is available in all versions of IDebugControl.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1251 of 1651

AddBreakpoint, RemoveBreakpoint
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetBreakpointParameters
The GetBreakpointParameters method returns the parameters of one or more breakpoints.
HRESULT
IDebugControl::GetBreakpointParameters(
IN ULONG Count,
IN OPTIONAL PULONG Ids,
IN ULONG Start,
OUT PDEBUG_BREAKPOINT_PARAMETERS Params
);
Parameters
Count
Specifies the number of breakpoints whose parameters are being requested.
Ids
Specifies an array containing the IDs of the breakpoints whose parameters are being requested. The number of items in this array must be equal to the value specified in
Count. If Ids is NULL, Start is used instead.
Start
Specifies the beginning index of the breakpoints whose parameters are being requested. The parameters for breakpoints with indices Start through Start plus Count minus
one will be returned. Start is used only if Ids is NULL.
Params
Receives the parameters for the specified breakpoints. The size of this array is equal to the value of Count. For details on the structure returned, see
DEBUG_BREAKPOINT_PARAMETERS.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the parameters for some of the breakpoints were not returned. The parameters that were not returned have their Id field set to
DEBUG_ANY_ID.
This method can also return error values. See Return Values for more details.
Interface Version
GetBreakpointParameters is available in all versions of IDebugControl.
Comments
Some of the parameters might not be returned. This happens if either a breakpoint could not be found or a breakpoint is private (see GetFlags).
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetParameters, GetBreakpointById, GetBreakpointByIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadBugCheckData
The ReadBugCheckData method reads the kernel bug check code and related parameters.
HRESULT
IDebugControl::ReadBugCheck(
OUT PULONG Code,
OUT PULONG64 Arg1,
OUT PULONG64 Arg2,
OUT PULONG64 Arg3,
OUT PULONG64 Arg4

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1256 of 1651

IN ULONG TotalLines,
IN ULONG64 Offset,
IN ULONG Flags,
OUT OPTIONAL PULONG OffsetLine,
OUT OPTIONAL PULONG64 StartOffset,
OUT OPTIONAL PULONG64 EndOffset,
OUT OPTIONAL PULONG64 LineOffsets
);
Parameters
OutputControl
Specifies the output control that determines which client's output callbacks receive the output. For possible values, see DEBUG_OUTCTL_XXX. For more information
about output, see Input and Output.
PreviousLines
Specifies the number of lines of instructions before the instruction at Offset to include in the output. Typically, each instruction is output on a single line. However, some
instructions can take up several lines of output; this can cause the number of lines output before the instruction at Offset to be greater than PreviousLines.
TotalLines
Specifies the total number of lines of instructions to include in the output. Typically, each instruction is output on a single line. However, some instructions can take up
several lines of output; this can cause the number of lines output to be greater than TotalLines.
Offset
Specifies the location in the target's memory of the instructions to disassemble. The disassembly output will start PreviousLines lines before these processor instructions.
Flags
Specifies the bit-flags that affect the behavior of this method. The following table lists the bits that can be set.
Bit-Flag
Effect when set
DEBUG_DISASM_EFFECTIVE_ADDRESS Compute the effective address of each instruction from the current register information and output it.
DEBUG_DISASM_MATCHING_SYMBOLS If the address of an instruction has an exact symbol match, output the symbol.
DEBUG_DISASM_SOURCE_LINE_NUMBER Include the source line number of each instruction in the output.
DEBUG_DISASM_SOURCE_FILE_NAME
Include the source file name in the output.
OffsetLine
Receives the line number in the output that contains the instruction at Offset. If OffsetLine is NULL, this information is not returned.
StartOffset
Receives the location in the target's memory of the first instruction included in the output. If StartOffset is NULL, this information is not returned.
EndOffset
Receives the locaiton in the target's memory of the instruction that follows the last disassembled instruction.
LineOffsets
Receives the locations in the target's memory of the instructions included in the output starting with the instruction at Offset. LineOffsets is an array that contains
TotalLines elements.
Offset is the value of first entry in this array unless there was an error disassembling the instructions before this instruction. In this case, the first entry will contain
DEBUG_ANY_ID and Offset will be placed in the second entry in the array (index one).
If the output for an instruction spans multiple lines, the element in the array that corresponds to the first line of the instruction will contain the address of the instruction.
If LineOffsets is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
OutputDisassemblyLines is available in all versions of IDebugControl.
Comments
The assembly language depends on the effective processor type of the target system. For information about the assembly language, see the processor documentation.
For an overview of using assembly in debugger applications, see Debugging in Assembly Mode. For more information about using assembly with the debugger engine API,
see Assembling and Disassembling Instructions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
Disassemble, OutputDisassembly, u (Unassemble)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Receives the level at which system errors are printed to the engine's output. If the level of the system error is less than or equal to OutputLevel, the error is printed to the
debugger console.
BreakLevel
Receives the level at which system errors break into the debugger. If the level of the system error is less than or equal to BreakLevel, the error breaks into the debugger.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetSystemErrorControl is available in all versions of IDebugControl.
Comments
The level of a system error can take one of the following three values, listed from lowest to highest: SLE_ERROR, SLE_MINORERROR, and SLE_WARNING. These
values are defined in Winuser.h.
When a system error occurs, the engine calls the IDebugEventCallbacks::SystemError method of the event callbacks. If the level is less than or equal to BreakLevel, the
error will break into the debugger. If the level is greater than BreakLevel, the engine will proceed with execution in the target as indicated by the
IDebugEventCallbacks::SystemError method calls. For more information about how the engine proceeds after an event, see Monitoring Events.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
IDebugEventCallbacks::SystemError, SetSystemErrorControl
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetSystemErrorControl
The SetSystemErrorControl method sets the control values for handling system errors.
HRESULT
IDebugControl::SetSystemErrorControl(
IN ULONG OutputLevel,
IN ULONG BreakLevel
);
Parameters
OutputLevel
Specifies the level at which system errors are printed to the engine's output. If the level of the system error is less than or equal to OutputLevel, the error is printed to the
debugger console.
BreakLevel
Specifies the level at which system errors break into the debugger. If the level of the system error is less than or equal to BreakLevel, the error breaks into the debugger.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetSystemErrorControl is available in all versions of IDebugControl.
Comments
The level of a system error can take one of the following three values, listed from lowest to highest: SLE_ERROR, SLE_MINORERROR, and SLE_WARNING. These
values are defined in Winuser.h.
When a system error occurs, the engine calls the IDebugEventCallbacks::SystemError method of the event callbacks. If the level is less than or equal to the BreakLevel
parameter, the error will break into the debugger. If the level is greater than BreakLevel, the engine will proceed with execution in the target as indicated by the
IDebugEventCallbacks::SystemError method calls. For more information about how the engine proceeds after an event, see Monitoring Events.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1261 of 1651

See Also
GetSystemErrorControl, IDebugEventCallbacks::SystemError
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetNotifyEventHandle
The GetNotifyEventHandle method receives the handle of the event that will be signaled after the next exception in a target.
HRESULT
IDebugControl::GetNotifyEventHandle(
OUT PULONG64 Handle
);
Parameters
Handle
Receives the handle of the event that will be signaled. If Handle is NULL, no event will be signaled.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetNotifyEventHandle is available in all versions of IDebugControl.
Comments
If an event to be signaled was set and an exception occurs in a target, when the engine resumes execution in the target again, the event will be signaled.
The event will only be signaled once. After it has been signaled, this method will return NULL to Handle, unless SetNotifyEventHandle is called to set another event to
signal.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetNotifyEventHandle
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetNotifyEventHandle
The SetNotifyEventHandle method sets the event that will be signaled after the next exception in a target.
HRESULT
IDebugControl::SetNotifyEventHandle(
IN ULONG64 Handle
);
Parameters
Handle
Specifies the handle of the event to signal. If Handle is NULL, no event will be signaled.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1262 of 1651

Interface Version
SetNotifyEventHandle is available in all versions of IDebugControl.
Comments
After setting the event to signal, and after the next exception occurs in a target, when the engine resumes execution in the target, the event will be signaled.
The event will only be signaled once. After it has been signaled, GetNotifyEventHandle will return NULL, unless this method is called to set another event to signal.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetNotifyEventHandle
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetNumberEvents
The GetNumberEvents method returns the number of events for the current target, if the number of events is fixed.
HRESULT
IDebugControl3::GetNumberEvents(
OUT PULONG Events
);
Parameters
Events
Receives the number of events stored in the target. If the target offers multiple events, Events will be set to the number of events available. Otherwise, Events will be set
to one.
Return Value
S_OK
The method was successful, and Events contains the total number of events possible for the target.
S_FALSE
The method was successful, but Events contains only the total number of events possible at the current time. Targets that support variable execution might have different
sets of events available at different points during the targets execution.
This method may also return error values. See Return Values for more details.
Interface Version
GetNumberEvents is available in IDebugControl3 and later versions.
Comments
Crash dump files contain a static list of events; each event represents a snapshot of the target at a particular point in time. If the current target is a crash dump file, this method
sets Events to the number of stored events and returns S_OK.
Live targets generate events dynamically and do not necessarily have a known set of events. If the current target is a live target with unconstrained number of events, this
method sets Events to the number of events currently available and returns S_FALSE.
For more information, see the topic Event Information.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetCurrentEventIndex, SetNextEventIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1263 of 1651

GetCurrentEventIndex
The GetCurrentEventIndex method returns the index of the current event within the current list of events for the current target, if such a list exists.
HRESULT
IDebugControl3::GetCurrentEventIndex(
OUT PULONG Index
);
Parameters
Index
Receives the index of the current event in the target. The index will be a number between zero and one less than the number of events returned by GetNumberEvents.
The index of the first event is zero.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetCurrentEventIndex is available in IDebugControl3 and later versions.
Comments
Targets that do not have fixed sets of events will always return zero to Index.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetNumberEvents, SetNextEventIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetNextEventIndex
The SetNextEventIndex method sets the next event for the current target by selecting the event from the static list of events for the target, if such a list exists.
HRESULT
IDebugControl3::SetNextEventIndex(
IN ULONG Relation,
IN ULONG Value,
OUT PULONG NextIndex
);
Parameters
Relation
Specifies how to interpret Value when setting the index of the next event. Possible values are: DEBUG_EINDEX_FROM_START, DEBUG_EINDEX_FROM_END,
and DEBUG_EINDEX_FROM_CURRENT.
Value
Specifies the index of the next event relative to the first, last, or current event. The interpretation of Value depends on the value of Relation, as follows.
Value of Relation
Next Event Index
DEBUG_EINDEX_FROM_START
Value.
DEBUG_EINDEX_FROM_END
Number of events minus Value.
DEBUG_EINDEX_FROM_CURRENT The current event index plus Value.
The resulting index must be greater than zero and one less than the number of events returned by GetNumberEvents.
NextIndex
Receives the index of the next event. If NextIndex is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1264 of 1651

Interface Version
SetNextEventIndex is available in IDebugControl3 and later versions.
Comments
If the specified event is the same as the current event, this method does nothing. Otherwise, this method sets the execution status of the target to DEBUG_STATUS_GO (and
notifies the event callbacks). When WaitForEvent is called, the engine will generate the specified event for the event callbacks and set it as the current event.
This method is only useful if the target offers a list of events.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetNumberEvents, GetCurrentEventIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetEventIndexDescription
The GetEventIndexDescription and GetEventIndexDescriptionWide methods describe the specified event in a static list of events for the current target.
HRESULT
IDebugControl3::GetEventIndexDescription(
IN ULONG Index,
IN ULONG Which,
IN OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DescSize
);
HRESULT
IDebugControl3::GetEventIndexDescriptionWide(
IN ULONG Index,
IN ULONG Which,
IN OPTIONAL PWSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DescSize
);
#ifdef UNICODE
#define GetEventIndexDescriptionT GetEventIndexDescriptionWide
#else
#define GetEventIndexDescriptionT GetEventIndexDescription
#endif
Parameters
Index
Specifies the index of the event whose description will be returned.
Which
Specifies which piece of the event description to return. Currently only DEBUG_EINDEX_NAME is supported; this returns the name of the event.
Buffer
Receives the description of the event. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size, in characters, of the Buffer buffer.
DescSize
Receives the size, in characters, of the description. If DescSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetEventIndexDescription is available in IDebugControl3 and later versions.
Comments
The amount of descriptive information available for a particular target varies depending on the type of the target.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1265 of 1651

Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetNumberEvents, GetCurrentEventIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetExpressionSyntax
The GetExpressionSyntax method returns the current syntax that the engine is using for evaluating expressions.
HRESULT
IDebugControl3::GetExpressionSyntax(
OUT PULONG Flags
);
Parameters
Flags
Receives the expression syntax. It is set to one of the following values:
DEBUG_EXPR_MASM
Expressions will be evaluated according to MASM syntax. For details of this syntax, see MASM Numbers and Operators.
DEBUG_EXPR_CPLUSPLUS
Expressions will be evaluated according to C++ syntax. For details of this syntax, see C++ Numbers and Operators.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetExpressionSyntax is available in IDebugControl3 and later versions.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetExpressionSyntax, SetExpressionSyntaxByName, Evaluate
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetExpressionSyntax
The SetExpressionSyntax method sets the syntax that the engine will use to evaluate expressions.
HRESULT
IDebugControl3::SetExpressionSyntax(
IN ULONG Flags
);
Parameters
Flags
Specifies the syntax that the engine will use to evaluate expressions. It can be one of the following values:
DEBUG_EXPR_MASM
Expressions will be evaluated according to MASM syntax. For details of this syntax, see MASM Numbers and Operators.
DEBUG_EXPR_CPLUSPLUS
Expressions will be evaluated according to C++ syntax. For details of this syntax, see C++ Numbers and Operators.
Return Value

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1266 of 1651

S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetExpressionSyntax is available in IDebugControl3 and later versions.
Comments
The expression syntax is a global setting within the engine, so setting the expression syntax will affect all clients.
The expression syntax of the engine determines how the engine will interpret expressions passed to Evaluate, Execute, and any other method that evaluates an expression.
After the expression syntax has been changed, the engine sends out notification to the IDebugEventCallbacks registered with each client. It also passes the
DEBUG_CES_EXPRESSION_SYNTAX flag to the IDebugEventCallbacks::ChangeEngineState method.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetExpressionSyntax, SetExpressionSyntaxByName, Evaluate
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetExpressionSyntaxNames
The GetExpressionSyntaxNames and GetExpressionSyntaxNamesWide methods return the full and abbreviated names of an expression syntax.
HRESULT
IDebugControl3::GetExpressionSyntaxNames(
IN ULONG Index,
OUT OPTIONAL PSTR FullNameBuffer,
IN ULONG FullNameBufferSize,
OUT OPTIONAL PULONG FullNameSize,
OUT OPTIONAL PSTR AbbrevNameBuffer,
IN ULONG AbbrevNameBufferSize,
OUT OPTIONAL PULONG AbbrevNameSize
);
HRESULT
IDebugControl4::GetExpressionSyntaxNamesWide(
IN ULONG Index,
OUT OPTIONAL PWSTR FullNameBuffer,
IN ULONG FullNameBufferSize,
OUT OPTIONAL PULONG FullNameSize,
OUT OPTIONAL PWSTR AbbrevNameBuffer,
IN ULONG AbbrevNameBufferSize,
OUT OPTIONAL PULONG AbbrevNameSize
);
#ifdef UNICODE
#define GetExpressionSyntaxNamesT GetExpressionSyntaxNamesWide
#else
#define GetExpressionSyntaxNamesT GetExpressionSyntaxNames
#endif
Parameters
Index
Specifies the index of the expression syntax. Index should be between zero and the number of expression syntaxes returned by GetNumberExpressionSyntaxes minus
one.
FullNameBuffer
Receives the full name of the expression syntax. If FullNameBuffer is NULL, this information is not returned.
FullNameBufferSize
Specifies the size, in characters, of the buffer FullNameBuffer.
FullNameSize
Receives the size, in characters, of the full name of the expression syntax. If FullNameSize is NULL, this information is not returned.
AbbrevNameBuffer
Receives the abbreviated name of the expression syntax. If AbbrevNameBuffer is NULL, this information is not returned.
AbbrevNameBufferSize
Specifies the size, in characters, of the buffer AbbrevNameBufferSize.
AbbrevNameSize

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

The GetExtensionByPath and GetExtensionByPathWide methods return the handle for an already loaded extension library.
HRESULT
IDebugControl::GetExtensionByPath(
IN PCSTR Path,
OUT PULONG64 Handle
);
HRESULT
IDebugControl4::GetExtensionByPathWide(
IN PCWSTR Path,
OUT PULONG64 Handle
);
#ifdef UNICODE
#define GetExtensionByPathT GetExtensionByPathWide
#else
#define GetExtensionByPathT GetExtensionByPath
#endif
Parameters
Path
Specifies the fully qualified path and file name of the extension library.
Handle
Receives the handle of the extension library.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
GetExtensionByPath is available in all versions of IDebugControl. GetExtensionByPathWide is available in IDebugControl4 and later versions.
Comments
Extension libraries are loaded into the host engine, which is where this method looks for the requested extension library. Path is a path and file name for the host engine.
For more information on using extension libraries, see Calling Extensions and Extension Functions.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
AddExtension
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetExtensionFunction
The GetExtensionFunction and GetExtensionFunctionWide methods return a pointer to an extension function from an extension library.
HRESULT
IDebugControl::GetExtensionFunction(
IN ULONG64 Handle,
IN PCSTR FuncName,
OUT FARPROC * Function
);
HRESULT
IDebugControl4::GetExtensionFunctionWide(
IN ULONG64 Handle,
IN PCWSTR FuncName,
OUT FARPROC * Function
);
#ifdef UNICODE
#define GetExtensionFunctionT GetExtensionFunctionWide
#else
#define GetExtensionFunctionT GetExtensionFunction

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1272 of 1651

#endif
Parameters
Handle
Specifies the handle of the extension library that contains the extension function. If Handle is zero, the engine will walk the extension library chain searching for the
extension function.
FuncName
Specifies the name of the extension function to return. When searching the extension libraries for the function, the debugger engine will prepend "_EFN_" to the name.
For example, if FuncName is "SampleFunction", the engine will search the extension libraries for "_EFN_SampleFunction".
Function
Receives the extension function.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
GetExtensionFunction is available in all versions of IDebugControl. GetExtensionFunctionWide is available in IDebugControl4 and later versions.
Comments
Extension libraries are loaded into the host engine and extension functions cannot be called remotely. The current client must not be a debugging client, it must belong to the
host engine.
The extension function can have any function prototype. In order for any program to call this extension function, the extension function should be cast to the correct
prototype.
For more information on using extension functions, see Calling Extensions and Extension Functions.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
See Also
AddExtension, CallExtension, GetExtensionByPath
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetWindbgExtensionApis64
The GetWindbgExtensionApis64 method returns a structure that facilitates using the WdbgExts API.
HRESULT
IDebugControl::GetWindbgExtensionApis64(
IN OUT WINDBG_EXTENSION_APIS64 * Api
);
Parameters
Api
Receives a WINDBG_EXTENSION_APIS64 structure. This structure contains the functions used by the WdbgExts API. The nSize member of this structure must be set
to the size of the structure before it is passed to this method.
Return Value
S_OK
The method was successful.
E_INVALIDARG
The value of Api->nSize does not equal the size of the structure WINDBG_EXTENSION_APIS64.
This method may also return other error values. See Return Values for more details.
Interface Version
GetWindbgExtensionApis64 is available in all versions of IDebugControl.
Comments
If you are including Wdbgexts.h in your extension code, you should call this method during the initialization of the extension DLL (see DebugExtensionInitialize).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Debugging Tools for Windows

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

SetInterruptTimeout
The SetInterruptTimeout method sets the number of seconds that the debugger engine should wait when requesting a break into the debugger.
HRESULT
IDebugControl::SetInterruptTimeout(
IN ULONG Seconds
);
Parameters
Seconds
Specifies the number of seconds that the engine should wait for the target when requesting a break into the debugger.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetInterruptTimeout is available in all versions of IDebugControl.
Comments
The engine requests a break into the debugger when SetInterrupt is called with the DEBUG_INTERRUPT_ACTIVE flag.
If an interrupt times out, the engine will generate a synthetic exception event. This event will be sent to event callback objects's IDebugEventCallbacks::Exception method.
Most targets do not support interrupt time-outs. Live user-mode debugging is one of the targets that does support them.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetInterruptTimeout, IDebugEventCallbacks::Exception, SetInterrupt
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

CloseLogFile
The CloseLogFile method closes the currently-open log file.
HRESULT
IDebugControl::CloseLogFile(
);
Parameters
None
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
CloseLogFile is available in all versions of IDebugControl.
Comments
If no log file is open, this method has no effect.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1290 of 1651

For more about log files, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
OpenLogFile2, GetLogFile2, OpenLogFile, GetLogFile, .logclose
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

For more information about log files, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetLogMask, GetOutputMask, OpenLogFile2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetLogMask
The SetLogMask method sets the output mask for the currently open log file.
HRESULT
IDebugControl::SetLogMask(
IN ULONG Mask
);
Parameters
Mask
Specifies the new output mask for the log file. See DEBUG_OUTPUT_XXX for details about this value.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
SetLogMask is available in all versions of IDebugControl.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetLogMask, SetOutputMask, OpenLogFile2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetReturnOffset
The GetReturnOffset method returns the return address for the current function.
HRESULT
GetReturnOffset(
OUT PULONG64 Offset
);
Parameters
Offset
Receives the return address.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1295 of 1651

GetReturnOffset is available in all versions of IDebugControl.

Comments
The return address is the location in the process's virtual address space of the instruction that will be executed when the current function returns.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Output
The Output and OutputWide methods format a string and send the result to output callbacks that have been registered with the engine's clients.
HRESULT
IDebugControl::Output(
IN ULONG Mask,
IN PCSTR Format,
...
);
HRESULT
IDebugControl4::OutputWide(
IN ULONG Mask,
IN PCWSTR Format,
...
);
#ifdef UNICODE
#define OutputT OutputWide
#else
#define OutputT Output
#endif
Parameters
Mask
Specifies the output-type bit field. See DEBUG_OUTPUT_XXX for possible values.
Format
Specifies the format string, as in printf. In general, conversion characters work exactly as in C. For the floating-point conversion characters the 64-bit argument is
interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It can not have any modifiers and it uses the debugger's internal address
formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space
Pointer in the host's virtual address space

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Address of a NULL-terminated ASCII string in

the process's virtual address space
Address of a NULL-terminated Unicode string in
the process's virtual address space
Address of an ANSI_STRING structure in the
process's virtual address space
Address of a UNICODE_STRING structure in
the process's virtual address space
Address in the process's virtual address space of
an item with symbol information
Address in the process's virtual address space of
an item with symbol information

Any 64-bit value

Text printed
The value of the pointer.
The value of the pointer. (This is equivalent to the standard C %p
character.)
The specified value. If this is greater than 0xFFFFFFFF, it is
printed as a 64-bit value. Otherwise, it is printed as a 32-bit value.
The specified string.
The specified string.
The specified string.
The specified string.
String that contains the name of the specified symbol (and
displacement, if any).
String that contains the name of the specified symbol (and
displacement, if any), as well as any available source line
information.

...
Specifies additional parameters that contain values to be inserted into the output during formatting.
Return Value
S_OK
The method was successful.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1296 of 1651

This method may also return error values. See Return Values for more details.
Interface Version
Output is available in all versions of IDebugControl. OutputWide is available in IDebugControl4 and later versions.
Comments
When generating very large output strings, it is possible to reach the limits of the debugger engine or of the operating system. For example, some versions of the debugger
engine have a 16K character limit for a single output. If you find that very large output is getting truncated, you might need to split your output into multiple requests.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
dprintf, ControlledOutput, OutputVaList, .printf
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ControlledOutput
The ControlledOutput and ControlledOutputWide methods format a string and send the result to output callbacks that were registered with some of the engine's clients.
HRESULT
IDebugControl::ControlledOutput(
IN ULONG OutputControl,
IN ULONG Mask,
IN PCSTR Format,
...
);
HRESULT
IDebugControl4::ControlledOutputWide(
IN ULONG OutputControl,
IN ULONG Mask,
IN PCWSTR Format,
...
);
#ifdef UNICODE
#define ControlledOutputT ControlledOutputWide
#else
#define ControlledOutputT ControlledOutput
#endif
Parameters
OutputControl
Specifies an output control that determines which of the clients' output callbacks will receive the output. For possible values, see DEBUG_OUTCTL_XXX. For more
information about output, see Input and Output.
Mask
Specifies the output-type bit field. See DEBUG_OUTPUT_XXX for possible values.
Format
Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument
is interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers and it uses the debugger's internal
address formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space.
Pointer in the host's virtual address space.

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

Address of a NULL-terminated ASCII string in

Any 64-bit value.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

ULONG64

%ly

ULONG64

Page 1297 of 1651

Address in the process's virtual address space of

an item with symbol information.
Address in the process's virtual address space of
an item with symbol information.

String that contains the name of the specified symbol (and

displacement, if any).
String that contains the name of the specified symbol (and
displacement, if any), as well as any available source line
information.

...
Specifies additional parameters that represent values to be inserted into the output during formatting.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
ControlledOutput is available in all versions of IDebugControl. ControlledOutputWide is available in IDebugControl4 and later versions.
Comments
When generating very large output strings, it is possible to reach the limits of the debugger engine or of the operating system. For example, some versions of the debugger
engine have a 16K character limit for a single output. If you find that very large output is getting truncated, you might need to split your output into multiple requests.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
ControlledOutputVaList, dprintf, Output, .printf
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputVaList
The OutputVaList and OutputVaListWide methods format a string and send the result to the output callbacks that are registered with the engine's clients.
HRESULT
IDebugControl::OutputVaList(
IN ULONG Mask,
IN PCSTR Format,
IN va_list Args
);
HRESULT
IDebugControl4::OutputVaListWide(
IN ULONG Mask,
IN PCWSTR Format,
IN va_list Args
);
#ifdef UNICODE
#define OutputVaListT OutputVaListWide
#else
#define OutputVaListT OutputVaList
#endif
Parameters
Mask
Specifies the output-type bit field. See DEBUG_OUTPUT_XXX for possible values.
Format
Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument
is interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers, and it uses the debugger's internal
address formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space.
Pointer in the host's virtual address space.
Any 64-bit value.

Text printed
The value of the pointer.
The value of the pointer. (This is equivalent to the standard C %p
character.)
The specified value. If this is greater than 0xFFFFFFFF, it is

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Page 1298 of 1651

printed as a 64-bit value; otherwise, it is printed as a 32-bit value.

Address of a NULL-terminated ASCII string in The specified string.
the process's virtual address space.
Address of a NULL-terminated Unicode string in The specified string.
the process's virtual address space.
Address of an ANSI_STRING structure in the
The specified string.
process's virtual address space.
Address of a UNICODE_STRING structure in the The specified string.
process's virtual address space.
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any).
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any), as well as any available source line
information.

Args
Specifies additional parameters that represent values to be inserted into the output during formatting. Args must be initialized using va_start. This method does not call
va_end.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
OutputVaList is available in all versions of IDebugControl. OutputVaListWide is available in IDebugControl4 and later versions.
Comments
When generating very large output strings, it is possible to reach the limits of the debugger engine or of the operating system. For example, some versions of the debugger
engine have a 16K character limit for a single output. If you find that very large output is getting truncated, you might need to split your output into multiple requests.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h. The macros va_list, va_start, and va_end are defined in Stdarg.h.
See Also
ControlledOutputVaList, dprintf, Output
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ControlledOutputVaList
The ControlledOutputVaList and ControlledOutputVaListWide methods format a string and send the result to output callbacks that were registered with some of the
engine's clients.
HRESULT
IDebugControl::ControlledOutputVaList(
IN ULONG OutputControl,
IN ULONG Mask,
IN PCSTR Format,
IN va_list Args
);
HRESULT
IDebugControl4::ControlledOutputVaList(
IN ULONG OutputControl,
IN ULONG Mask,
IN PCWSTR Format,
IN va_list Args
);
#ifdef UNICODE
#define ControlledOutputVaListT ControlledOutputVaListWide
#else
#define ControlledOutputVaListT ControlledOutputVaList
#endif
Parameters
OutputControl

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1299 of 1651

Specifies an output control that determines which client's output callbacks will receive the output. For possible values, see DEBUG_OUTCTL_XXX. For more
information about output, see Input and Output.
Mask
Specifies the output-type bit field. See DEBUG_OUTPUT_XXX for possible values.
Format
Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument
is interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers, and it uses the debugger's internal
address formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space.
Pointer in the host's virtual address space.

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Address of a NULL-terminated ASCII string in

the process's virtual address space.
Address of a NULL-terminated Unicode string in The specified string.
the process's virtual address space.
Address of an ANSI_STRING structure in the
The specified string.
process's virtual address space.
Address of a UNICODE_STRING structure in the The specified string.
process's virtual address space.
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any).
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any), as well as any available source line
information.

);

Page 1306 of 1651

AbbrevNameSize

HRESULT
IDebugControl4::GetProcessorTypeNamesWide(
IN ULONG Type,
OUT OPTIONAL PWSTR FullNameBuffer,
IN ULONG FullNameBufferSize,
OUT OPTIONAL PULONG FullNameSize,
OUT OPTIONAL PWSTR AbbrevNameBuffer,
IN ULONG AbbrevNameBufferSize,
OUT OPTIONAL PULONG AbbrevNameSize
);
#ifdef UNICODE
#define GetProcessorTypeNamesT GetProcessorTypeNamesWide
#else
#define GetProcessorTypeNamesT GetProcessorTypeNames
#endif
Parameters
Type
Specifies the type of the processor whose name is requested. See GetActualProcessorType for a list of possible values.
FullNameBuffer
Receives the full name of the processor type. If FullNameBuffer is NULL, this information is not returned.
FullNameBufferSize
Specifies the size, in characters, of the buffer that FullNameBuffer specifies.
FullNameSize
Receives the size in characters of the full name of the processor type. If FullNameSize is NULL, this information is not returned.
AbbrevNameBuffer
Receives the abbreviated name of the processor type. If AbbrevNameBuffer is NULL, this information is not returned.
AbbrevNameBufferSize
Specifies the size, in characters, of the buffer that AbbrevNameBuffer specifies.
AbbrevNameSize
Receives the size in characters of the abbreviated name of the processor type. If AbbrevNameSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, at least one of FullNameBuffer or AbbrevNameBuffer was too small for the corresponding name, so the name was truncated.
This method may also return error values. See Return Values for more details.
Interface Version
GetProcessorTypeNames is available in all versions of IDebugControl. GetProcessorTypeNamesWide is available in IDebugControl4 and later versions.
Comments
For more information, see Target Information.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetSupportedProcessorTypes
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputPrompt
The OutputPrompt and OutputPromptWide methods format and send a user prompt to the output callback objects.
HRESULT
IDebugControl::OutputPrompt(
IN ULONG OutputControl,
IN OPTIONAL PCSTR Format,
...
);
HRESULT

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1307 of 1651

IDebugControl4::OutputPromptWide(
IN ULONG OutputControl,
IN OPTIONAL PCWSTR Format,
...
);
#ifdef UNICODE
#define OutputPromptT OutputPromptWide
#else
#define OutputPromptT OutputPrompt
#endif
Parameters
OutputControl
Specifies an output control that determines which of the client's output callbacks will receive the output. For possible values, see DEBUG_OUTCTL_XXX.
Format
Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument
is interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers and it uses the debugger's internal
address formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space.
Pointer in the host's virtual address space.

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Address of a NULL-terminated ASCII string in

the process' virtual address space.
Address of a NULL-terminated Unicode string in The specified string.
the process's virtual address space.
Address of an ANSI_STRING structure in the
The specified string.
process's virtual address space.
Address of a UNICODE_STRING structure in the The specified string.
process's virtual address space.
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any).
Address in the process's virtual address space of String that contains the name of the specified symbol (and
an item with symbol information.
displacement, if any), as well as any available source line
information.

Any 64-bit value.

If Format is NULL, only the standard prompt text is sent to the output callbacks.
...
Specifies additional parameters that represent values to be inserted into the output during formatting.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
OutputPrompt is available in all versions of IDebugControl. OutputPromptWide is available in IDebugControl4 and later versions.
Comments
OutputPrompt and OutputPromptWide can be used to prompt the user for input.
The standard prompt will be sent to the output callbacks before the formatted text described by Format. The contents of the standard prompt is returned by the method
GetPromptText.
The prompt text is sent to the output callbacks with the DEBUG_OUTPUT_PROMPT output mask set.
For more information about prompting the user, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
OutputPromptVaList, GetPromptText, ControlledOutput, DEBUG_OUTPUT_XXX
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1308 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

OutputPromptVaList
The OutputPromptVaList and OutputPromptVaListWide methods format and send a user prompt to the output callback objects.
HRESULT
IDebugControl::OutputPromptVaList(
IN ULONG OutputControl,
IN OPTIONAL PCSTR Format,
IN va_list Args
);
HRESULT
IDebugControl4::OutputPromptVaListWide(
IN ULONG OutputControl,
IN OPTIONAL PCWSTR Format,
IN va_list Args
);
#ifdef UNICODE
#define OutputPromptVaListT OutputPromptVaListWide
#else
#define OutputPromptVaListT OutputPromptVaList
#endif
Parameters
OutputControl
Specifies an output control that determines which of the client's output callbacks will receive the output. For possible values, see DEBUG_OUTCTL_XXX.
Format
Specifies the format string, as in printf. Typically, conversion characters work exactly as they do in C. For the floating-point conversion characters, the 64-bit argument
is interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in a target's address space. It might not have any modifiers and it uses the debugger's internal
address formatting. The following additional conversion characters are supported.
Character
Argument type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,
depending on the host's architecture)
%I
ULONG64

Argument
Pointer in an address space.
Pointer in the host's virtual address space.

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Address of a NULL-terminated ASCII string in

Any 64-bit value.

If Format is NULL, only the standard prompt text is sent to the output callbacks.
Args
Specifies additional parameters that represent values to be inserted into the output during formatting. Args must be initialized using va_start. This method does not call
va_end.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
OutputPromptVaList is available in all versions of IDebugControl. OutputPromptVaListWide is available in IDebugControl4 and later versions.
Comments
OutputPromptVaList and OutputPromptVaListWide can be used to prompt the user for input.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1309 of 1651

The standard prompt will be sent to the output callbacks before the formatted text described by Format. The contents of the standard prompt is returned by the method
GetPromptText.
The prompt text is sent to the output callbacks with the DEBUG_OUTPUT_PROMPT output mask set.
For more information about prompting the user, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h. The macros va_list, va_start, and va_end are defined in Stdarg.h.
See Also
OutputPrompt, GetPromptText, ControlledOutputVaList, DEBUG_OUTPUT_XXX
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetPromptText
The GetPromptText and GetPromptTextWide methods return the standard prompt text that will be prepended to the formatted output specified in the OutputPrompt and
OutputPromptVaList methods.
HRESULT
IDebugControl::GetPromptText(
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG TextSize
);
HRESULT
IDebugControl4::GetPromptTextWide(
OUT OPTIONAL PWSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG TextSize
);
#ifdef UNICODE
#define GetPromptTextT GetPromptTextWide
#else
#define GetPromptTextT GetPromptText
#endif
Parameters
Buffer
Receives the prompt text. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size, in characters, of the Buffer buffer.
TextSize
Receives the size, in characters, of the prompt text. If TextSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the prompt text was too large to fit into the Buffer buffer and the text was truncated.
This method can also return error values. See Return Values for more details.
Interface Version
GetPromptText is available in all versions of IDebugControl. GetPromptTextWide is available in IDebugControl4 and later versions.
Comments
For more information about prompting the user, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
OutputPrompt, OutputPromptVaList

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1310 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetRadix
The GetRadix method returns the default radix (number base) used by the debugger engine when it evaluates and displays MASM expressions, and when it displays symbol
information.
HRESULT
IDebugControl::GetRadix(
OUT PULONG Radix
);
Parameters
Radix
Receives the default radix.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetRadix is available in all versions of IDebugControl.
Comments
For more information about the default radix, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
SetRadix, n (Set Number Base)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetRadix
The SetRadix method sets the default radix (number base) used by the debugger engine when it evaluates and displays MASM expressions, and when it displays symbol
information.
HRESULT
IDebugControl::SetRadix(
IN ULONG Radix
);
Parameters
Radix
Specifies the new default radix. The following table contains the possible values for the radix.
Value Description
8
Octal
10
Decimal
16
Hexadecimal
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1311 of 1651

Interface Version
SetRadix is available in all versions of IDebugControl.
Comments
When the radix is changed, the engine notifies the event callbacks by passing the DEBUG_CES_RADIX flag to the IDebugEventCallbacks::ChangeEngineState callback
method.
For more information about the default radix, see Using Input and Output.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetRadix, n (Set Number Base)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetStackTrace
The GetStackTrace method returns the frames at the top of the specified call stack.
HRESULT
IDebugControl::GetStackTrace(
IN ULONG64 FrameOffset,
IN ULONG64 StackOffset,
IN ULONG64 InstructionOffset,
OUT PDEBUG_STACK_FRAME Frames,
IN ULONG FramesSize,
OUT OPTIONAL PULONG FramesFilled
);
Parameters
FrameOffset
Specifies the location of the stack frame at the top of the stack. If FrameOffset is set to zero, the current frame pointer is used instead.
StackOffset
Specifies the location of the current stack. If StackOffset is set to zero, the current stack pointer is used instead.
InstructionOffset
Specifies the location of the instruction of interest for the function that is represented by the stack frame at the top of the stack. If InstructionOffset is set to zero, the
current instruction is used instead.
Frames
Receives the stack frames. The number of elements this array holds is FrameSize.
FrameSize
Specifies the number of items in the Frames array.
FramesFilled
Receives the number of frames that were placed in the array Frames. If FramesFilled is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
E_FAIL
No stack frames were returned.
This method may also return other error values. See Return Values for more details.
Interface Version
GetStackTrace is available in all versions of IDebugControl.
Comments
The stack trace returned to Frames can be printed using OutputStackTrace.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetContextStackTrace, GetFrameOffset2, GetInstructionOffset2, GetStackOffset2, OutputStackTrace, k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace),
StackTrace

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1312 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputStackTrace
The OutputStackTrace method outputs either the supplied stack frame or the current stack frames.
HRESULT
IDebugControl::OutputStackTrace(
IN ULONG OutputControl,
IN OPTIONAL DEBUG_STACK_FRAME *
IN ULONG FramesSize,
IN ULONG Flags
);

Frames,

Parameters
OutputControl
Specifies where to send the output. For possible values, see DEBUG_OUTCTL_XXX.
Frames
Specifies the array of stack frames to output. The number of elements in this array is FramesSize. If Frames is NULL, the current stack frames are used.
FramesSize
Specifies the number of frames to output.
Flags
Specifies bit flags that determine what information to output for each frame. Flags can be any combination of values from the following table.
Flag
Description
DEBUG_STACK_ARGUMENTS
Displays the first three pieces of stack memory at the frame of each call. On platforms where parameters are
passed on the stack, and the code for the frame uses stack arguments, these values will be the arguments to the
function.
DEBUG_STACK_FUNCTION_INFO
Displays information about the function that corresponds to the frame. This includes calling convention and
frame pointer omission (FPO) information.
DEBUG_STACK_SOURCE_LINE
Displays source line information for each frame of the stack trace.
DEBUG_STACK_FRAME_ADDRESSES
Displays the return address, previous frame address, and other relevant addresses for each frame.
DEBUG_STACK_COLUMN_NAMES
Displays column names.
DEBUG_STACK_NONVOLATILE_REGISTERS
Displays the non-volatile register context for each frame. This is only meaningful for some platforms.
DEBUG_STACK_FRAME_NUMBERS
Displays frame numbers.
DEBUG_STACK_PARAMETERS
Displays parameter names and values as given in symbol information.
DEBUG_STACK_FRAME_ADDRESSES_RA_ONLY Displays just the return address in stack frame addresses.
DEBUG_STACK_FRAME_MEMORY_USAGE
Displays the number of bytes that separate the frames.
DEBUG_STACK_PARAMETERS_NEWLINE
Displays each parameter and its type and value on a new line.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
OutputStackTrace is available in all versions of IDebugControl.
Comments
The array of stack frames can be obtained using GetStackTrace.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetContextStackTrace, GetStackTrace, k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetContextStackTrace

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1313 of 1651

The GetContextStackTrace method returns the frames at the top of the call stack, starting with an arbitrary register context and returning the reconstructed register context
for each stack frame.
HRESULT
IDebugControl4::GetContextStackTrace(
IN OPTIONAL PVOID StartContext,
IN ULONG StartContextSize,
OUT OPTIONAL PDEBUG_STACK_FRAME Frames,
IN ULONG FramesSize,
OUT OPTIONAL PVOID FrameContexts,
IN ULONG FrameContextsSize,
IN ULONG FrameContextsEntrySize,
OUT OPTIONAL PULONG FramesFilled
);
Parameters
StartContext
Specifies the register context for the top of the stack.
StartContextSize
Specifies the size, in bytes, of the StartContext register context.
Frames
Receives the stack frames. The number of elements this array holds is FrameSize. If Frames is NULL, this information is not returned.
FramesSize
Specifies the number of items in the array Frames.
FrameContexts
Receives the reconstructed register context for each frame in the stack. The entries in this array correspond to the entries in the Frames array. The type of the thread
context is the CONTEXT structure for the target's effective processor. If FrameContexts is NULL, this information is not returned.
FrameContextsSize
Specifies the size, in bytes, of the memory pointed to by FrameContexts. The number of stack frames returned equals the number of contexts returned, and
FrameContextsSize must equal FramesSize times FrameContextsEntrySize.
FrameContextsEntrySize
Specifies the size, in bytes, of each frame context in FrameContexts.
FramesFilled
Receives the number of frames that were placed in the array Frames and contexts in FrameContexts. If FramesFilled is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetContextStackTrace is available in IDebugControl4 and later versions.
Comments
The stack trace returned to Frames and FrameContexts can be printed using OutputContextStackTrace.
It is common for stack unwinds to restore only a subset of the registers. For example, stack unwinds will not always restore the volatile register state because the volatile
registers are scratch registers and code does not need to preserve them. Registers that are not restored on unwind are left as the last value restored, so care should be taken
when using the register state that might not be restored by an unwind.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h. CONTEXT is defined in Ntddk.h.
See Also
GetStackTrace, k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace), OutputContextStackTrace,
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputContextStackTrace
The OutputContextStackTrace method prints the call stack specified by an array of stack frames and corresponding register contexts.
HRESULT
IDebugControl4::OutputContextStackTrace(
IN ULONG OutputControl,
IN PDEBUG_STACK_FRAME Frames,
IN ULONG FramesSize,
IN PVOID FrameContexts,
IN ULONG FrameContextsSize,

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

IN ULONG
IN ULONG
);

Page 1314 of 1651

FrameContextsEntrySize,
Flags

Parameters
OutputControl
Specifies where to send the output. For possible values, see DEBUG_OUTCTL_XXX.
Frames
Specifies the array of stack frames to output. The number of elements in this array is FramesSize. If Frames is NULL, the current stack frame is used.
FramesSize
Specifies the number of frames to output.
FrameContexts
Specifies the register context for each frame in the stack. The entries in this array correspond to the entries in the Frames array. The type of the thread context is the
CONTEXT structure for the target's effective processor.
FrameContextsSize
Specifies the size, in bytes, of the memory pointed to by FrameContexts. The number of stack frames must equal the number of contexts, and FrameContextsSize must
equal FramesSize multiplied by FrameContextsEntrySize.
FrameContextsEntrySize
Specifies the size, in bytes, of each frame context in FrameContexts.
Flags
Specifies bit flags that determine what information to output for each frame. Flags can be any combination of values from the following table.
Flag
Description
DEBUG_STACK_ARGUMENTS
Displays the first three pieces of stack memory at the frame of each call. On platforms where arguments are
passed on the stack, and the code for the frame uses stack arguments, these values will be the arguments to the
function.
DEBUG_STACK_FUNCTION_INFO
Displays information about the function that corresponds to the frame. This includes calling convention and
frame pointer omission (FPO) information.
DEBUG_STACK_SOURCE_LINE
Displays source line information for each frame of the stack trace.
DEBUG_STACK_FRAME_ADDRESSES
Displays the return address, previous frame address, and other relevant addresses for each frame.
DEBUG_STACK_COLUMN_NAMES
Displays column names.
DEBUG_STACK_NONVOLATILE_REGISTERS
Displays the non-volatile register context for each frame. This is only meaningful for some platforms.
DEBUG_STACK_FRAME_NUMBERS
Displays frame numbers.
DEBUG_STACK_PARAMETERS
Displays parameter names and values as given in symbol information.
DEBUG_STACK_FRAME_ADDRESSES_RA_ONLY Displays just the return address in the stack frame addresses.
DEBUG_STACK_FRAME_MEMORY_USAGE
Displays the number of bytes that separate the frames.
DEBUG_STACK_PARAMETERS_NEWLINE
Displays each parameter and its type and value on a new line.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
OutputContextStackTrace is available in IdebugControl4 and later versions.
Comments
The array of stack frames can be obtained using GetContextStackTrace.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h. CONTEXT is defined in Ntddk.h.
See Also
GetContextStackTrace, k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace), OutputStackTrace
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputCurrentState
The OutputCurrentState method prints the current state of the current target to the debugger console.
HRESULT
IDebugControl::OutputCurrentState(
IN ULONG OutputControl,
IN ULONG Flags
);
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

);

Page 1318 of 1651

StringSize

#ifdef UNICODE
#define GetSystemVersionStringT GetSystemVersionStringWide
#else
#define GetSystemVersionStringT GetSystemVersionString
#endif
Parameters
Which
Specifies which version string to return. The possible values are listed in the following table.
Value
Version string
DEBUG_SYSVERSTR_SERVICE_PACK Returns a description of the service pack for the target's operating system. For example, "Service Pack 1".
DEBUG_SYSVERSTR_BUILD
Returns a description of the target's operating system build version. For example, "kernel32.dll version: 5.1.2600.1106
(xpsp1.020828-1920)".
Buffer
Receives the version string. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size, in characters, of the buffer that Buffer specifies.
StringSize
Receives the size, in characters, of the string that identifies the build. If SizeString is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the buffer was too small, so the string was truncated.
This method may also return error values. See Return Values for more details.
Interface Version
GetSystemVersionString and GetSystemVersionStringWide are available in IDebugControl4 and later versions.
Comments
For more information, see Target Information.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetSystemVersion, GetSystemVersionValues
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetSystemVersionValues
The GetSystemVersionValues method returns version number information for the current target.
HRESULT
IDebugControl4::GetSystemVersionValues(
OUT PULONG PlatformId,
OUT PULONG Win32Major,
OUT PULONG Win32Minor,
OUT OPTIONAL PULONG KdMajor,
OUT OPTIONAL PULONG KdMinor
);
Parameters
PlatformId
Receives the platform ID. PlatformId is always VER_PLATFORM_WIN32_NT for NT-based Windows.
Win32Major
Receives the major version number of the target's operating system. For Windows 2000, Windows XP, and Windows Server 2003, this number is 5. For Windows Vista,
this number is 6.
Win32Minor
Receives the minor version number for the target's operating system. For Windows 2000 this is 0; for Windows XP, 1; for Windows Server 2003, 2.
KdMajor

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1319 of 1651

Receives 0xF if the target's operating system is a free build, and 0xC if it is a checked build.
KdMinor
Receives the build number for the target's operating system.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetSystemVersionValues is available in IDebugControl4 and later versions.
Comments
For more information, see Target Information.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetSystemVersion, GetSystemVersionString
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetTextMacro
The GetTextMacro and GetTextMacroWide methods return the value of a fixed-name alias.
HRESULT
IDebugControl::GetTextMacro(
IN ULONG Slot,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUt OPTIONAL PULONG MacroSize
);
HRESULT
IDebugControl4::GetTextMacroWide(
IN ULONG Slot,
OUT OPTIONAL PWSTR Buffer,
IN ULONG BufferSize,
OUt OPTIONAL PULONG MacroSize
);
#ifdef UNICODE
#define GetTextMacroT GetTextMacroWide
#else
#define GetTextMacroT GetTextMacro
#endif
Parameters
Slot
Specifies the number of the fixed-name alias. Slot can take the values 0, 1, , 9, that represent the fixed-name aliases $u0, $u1, , $u9.
Buffer
Receives the value of the alias specified by Slot. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size, in characters, of the Buffer buffer.
MacroSize
Receives the size, in characters, of the value of the alias.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetTextMacro is available in all versions of IDebugControl. GetTextMacroWide is available in IDeubgControl4 and later versions.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Specifies the bus data type to read from. For details of allowed values see the documentation for the BUS_DATA_TYPE enumeration in the Microsoft Windows SDK.
BusNumber
Specifies the system-assigned number of the bus. This is usually zero, unless the system has more than one bus of the same bus data type.
SlotNumber
Specifies the logical slot number on the bus.
Offset
Specifies the offset in the bus data to start reading from.
Buffer
Receives the data from the bus.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be returned.
BytesRead
Receives the number of bytes read from the bus. If BytesRead is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
ReadBusData is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
The nature of the data read from the bus is system, bus, and slot dependent.
Requirements
Headers: Defined in Dgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WriteBusData
The WriteBusData method writes data to a system bus.
HRESULT
IDebugDataSpaces::WriteBusData(
IN ULONG BusDataType,
IN ULONG BusNumber,
IN ULONG SlotNumber,
IN ULONG Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
);
Parameters
BusDataType
Specifies the bus data type of the bus to write to. For details of allowed values see the documentation for the BUS_DATA_TYPE enumeration in the Microsoft Windows
SDK.
BusNumber
Specifies the system-assigned number of the bus. This is usually zero, unless the system has more than one bus of the same bus data type.
SlotNumber
Specifies the logical slot number on the bus.
Offset
Specifies the offset in the bus data to start writing to.
Buffer
Specifies the data to write to the bus.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be written.
BytesWritten
Receives the number of bytes written to the bus. If BytesWritten is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1330 of 1651

Interface Version
WriteBusData is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
The nature of the data read from the bus is system, bus, and slot dependent.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadControl
The ReadControl method reads implementation-specific system data.
HRESULT
IDebugDataSpaces::ReadControl(
IN ULONG Processor,
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
);
Parameters
Processor
Specifies the processor whose information is to be read.
Offset
Specifies the offset in the control space of the memory to read.
Buffer
Receives the data read from the control-space memory.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be read.
BytesRead
Receives the number of bytes returned in the buffer Buffer. If BytesRead is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
ReadControl is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WriteControl
The WriteControl method writes implementation-specific system data.
HRESULT
IDebugDataSpaces::WriteControl(

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1331 of 1651

IN ULONG Processor,
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
);
Parameters
Processor
Specifies the processor whose information is to be written.
Offset
Specifies the offset of the control space of the memory to write.
Buffer
Specifies the data to write to the control-space memory.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be written.
BytesWritten
Receives the number of bytes returned in the buffer Buffer. If BytesWritten is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
WriteControl is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadDebuggerData
The ReadDebuggerData method returns information about the target that the debugger engine has queried or determined during the current session. The available
information includes the locations of certain key target kernel locations, specific status values, and a number of other things.
HRESULT
IDebugDataSpaces::ReadDebuggerData(
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
);
Parameters
Index
Specifies the index of the data to retrieve. The following values are valid:
Value
Return
Description
Type
DEBUG_DATA_KernBase
ULONG64 Returns the base address of the kernel image.
DEBUG_DATA_BreakpointWithStatusAddr
ULONG64 Returns the address of the kernel function BreakpointWithStatusInstruction.
DEBUG_DATA_SavedContextAddr
ULONG64 Returns the address of saved context record during a bugcheck. It is only valid after a
bugcheck.
DEBUG_DATA_KiCallUserModeAddr
ULONG64 Returns the address of the kernel function KiCallUserMode.
DEBUG_DATA_KeUserCallbackDispatcherAddr
ULONG64 Returns the kernel variable KeUserCallbackDispatcher.
DEBUG_DATA_PsLoadedModuleListAddr
ULONG64 Returns the address of the kernel variable PsLoadedModuleList.
DEBUG_DATA_PsActiveProcessHeadAddr
ULONG64 Returns the address of the kernel variable PsActiveProcessHead.
DEBUG_DATA_PspCidTableAddr
ULONG64 Returns the address of the kernel variable PspCidTable.
DEBUG_DATA_ExpSystemResourcesListAddr
ULONG64 Returns the address of the kernel variable ExpSystemResourcesList.
DEBUG_DATA_ExpPagedPoolDescriptorAddr
ULONG64 Returns the address of the kernel variable ExpPagedPoolDescriptor.
DEBUG_DATA_ExpNumberOfPagedPoolsAddr
ULONG64 Returns the address of the kernel variable ExpNumberOfPagedPools.
DEBUG_DATA_KeTimeIncrementAddr
ULONG64 Returns the address of the kernel variable KeTimeIncrement.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1332 of 1651

DEBUG_DATA_KeBugCheckCallbackListHeadAddr
ULONG64
DEBUG_DATA_KiBugcheckDataAddr
ULONG64
DEBUG_DATA_IopErrorLogListHeadAddr
ULONG64
DEBUG_DATA_ObpRootDirectoryObjectAddr
ULONG64
DEBUG_DATA_ObpTypeObjectTypeAddr
ULONG64
DEBUG_DATA_MmSystemCacheStartAddr
ULONG64
DEBUG_DATA_MmSystemCacheEndAddr
ULONG64
DEBUG_DATA_MmSystemCacheWsAddr
ULONG64
DEBUG_DATA_MmPfnDatabaseAddr
ULONG64
DEBUG_DATA_MmSystemPtesStartAddr
ULONG64
DEBUG_DATA_MmSystemPtesEndAddr
ULONG64
DEBUG_DATA_MmSubsectionBaseAddr
ULONG64
DEBUG_DATA_MmNumberOfPagingFilesAddr
ULONG64
DEBUG_DATA_MmLowestPhysicalPageAddr
ULONG64
DEBUG_DATA_MmHighestPhysicalPageAddr
ULONG64
DEBUG_DATA_MmNumberOfPhysicalPagesAddr
ULONG64
DEBUG_DATA_MmMaximumNonPagedPoolInBytesAddr ULONG64
DEBUG_DATA_MmNonPagedSystemStartAddr
ULONG64
DEBUG_DATA_MmNonPagedPoolStartAddr
ULONG64
DEBUG_DATA_MmNonPagedPoolEndAddr
ULONG64
DEBUG_DATA_MmPagedPoolStartAddr
ULONG64
DEBUG_DATA_MmPagedPoolEndAddr
ULONG64
DEBUG_DATA_MmPagedPoolInformationAddr
ULONG64
DEBUG_DATA_MmPageSize
ULONG64
DEBUG_DATA_MmSizeOfPagedPoolInBytesAddr
ULONG64
DEBUG_DATA_MmTotalCommitLimitAddr
ULONG64
DEBUG_DATA_MmTotalCommittedPagesAddr
ULONG64
DEBUG_DATA_MmSharedCommitAddr
ULONG64
DEBUG_DATA_MmDriverCommitAddr
ULONG64
DEBUG_DATA_MmProcessCommitAddr
ULONG64
DEBUG_DATA_MmPagedPoolCommitAddr
ULONG64
DEBUG_DATA_MmExtendedCommitAddr
ULONG64
DEBUG_DATA_MmZeroedPageListHeadAddr
ULONG64
DEBUG_DATA_MmFreePageListHeadAddr
ULONG64
DEBUG_DATA_MmStandbyPageListHeadAddr
ULONG64
DEBUG_DATA_MmModifiedPageListHeadAddr
ULONG64
DEBUG_DATA_MmModifiedNoWritePageListHeadAddr ULONG64
DEBUG_DATA_MmAvailablePagesAddr
ULONG64
DEBUG_DATA_MmResidentAvailablePagesAddr
ULONG64
DEBUG_DATA_PoolTrackTableAddr
ULONG64
DEBUG_DATA_NonPagedPoolDescriptorAddr
ULONG64
DEBUG_DATA_MmHighestUserAddressAddr
ULONG64
DEBUG_DATA_MmSystemRangeStartAddr
ULONG64
DEBUG_DATA_MmUserProbeAddressAddr
ULONG64
DEBUG_DATA_KdPrintCircularBufferAddr
ULONG64
DEBUG_DATA_KdPrintCircularBufferEndAddr
ULONG64
DEBUG_DATA_KdPrintWritePointerAddr
ULONG64
DEBUG_DATA_KdPrintRolloverCountAddr
ULONG64
DEBUG_DATA_MmLoadedUserImageListAddr
ULONG64
DEBUG_DATA_PaeEnabled
BOOLEAN

Returns the address of the kernel variable KeBugCheckCallbackListHead.

Returns the kernel variable KiBugCheckData.
Returns the address of the kernel variable IopErrorLogListHead.
Returns the address of the kernel variable ObpRootDirectoryObject.
Returns the address of the kernel variable ObpTypeObjectType.
Returns the address of the kernel variable MmSystemCacheStart.
Returns the address of the kernel variable MmSystemCacheEnd.
Returns the address of the kernel variable MmSystemCacheWs.
Returns the address of the kernel variable MmPfnDatabase.
Returns the kernel variable MmSystemPtesStart.
Returns the kernel variable MmSystemPtesEnd.
Returns the address of the kernel variable MmSubsectionBase.
Returns the address of the kernel variable MmNumberOfPagingFiles.
Returns the address of the kernel variable MmLowestPhysicalPage.
Returns the address of the kernel variable MmHighestPhysicalPage.
Returns the address of the kernel variable MmNumberOfPhysicalPages.
Returns the address of the kernel variable MmMaximumNonPagedPoolInBytes.
Returns the address of the kernel variable MmNonPagedSystemStart.
Returns the address of the kernel variable MmNonPagedPoolStart.
Returns the address of the kernel variable MmNonPagedPoolEnd.
Returns the address of the kernel variable MmPagedPoolStart.
Returns the address of the kernel variable MmPagedPoolEnd.
Returns the address of the kernel variable MmPagedPoolInfo.
Returns the page size.
Returns the address of the kernel variable MmSizeOfPagedPoolInBytes.
Returns the address of the kernel variable MmTotalCommitLimit.
Returns the address of the kernel variable MmTotalCommittedPages.
Returns the address of the kernel variable MmSharedCommit.
Returns the address of the kernel variable MmDriverCommit.
Returns the address of the kernel variable MmProcessCommit.
Returns the address of the kernel variable MmPagedPoolCommit.
Returns the address of the kernel variable MmExtendedCommit..
Returns the address of the kernel variable MmZeroedPageListHead.
Returns the address of the kernel variable MmFreePageListHead.
Returns the address of the kernel variable MmStandbyPageListHead.
Returns the address of the kernel variable MmModifiedPageListHead.
Returns the address of the kernel variable MmModifiedNoWritePageListHead.
Returns the address of the kernel variable MmAvailablePages.
Returns the address of the kernel variable MmResidentAvailablePages.
Returns the address of the kernel variable PoolTrackTable.
Returns the address of the kernel variable NonPagedPoolDescriptor.
Returns the address of the kernel variable MmHighestUserAddress.
Returns the address of the kernel variable MmSystemRangeStart.
Returns the address of the kernel variable MmUserProbeAddress.
Returns the kernel variable KdPrintDefaultCircularBuffer.
Returns the address of the end of the array KdPrintDefaultCircularBuffer
Returns the address of the kernel variable KdPrintWritePointer.
Returns the address of the kernel variable KdPrintRolloverCount.
Returns the address of the kernel variable MmLoadedUserImageList.
Returns TRUE when the target system has PAE enabled.
Returns FALSE otherwise.

DEBUG_DATA_SharedUserData

ULONG64 Returns the address in the target of the shared user-mode structure,
KUSER_SHARED_DATA. The KUSER_SHARED_DATA structure is defined in ntddk.h (in
the Windows Driver Kit) and ntexapi.h (in the Windows SDK).
Some of the information contained in this structure is displayed by the debugger extension !
kuser.

DEBUG_DATA_ProductType

ULONG

Returns the value of the NtProductType field in the shared user-mode page.
This value should be interpreted the same way as the wProductType field of the structure
OSVERSIONINFOEX, which is documented in the Windows SDK.

DEBUG_DATA_SuiteMask

ULONG

Returns the value of the SuiteMask field in the shared user-mode page.
This value should be interpreted the same way as the wSuiteMask field of the structure
OSVERSIONINFOEX, which is documented in the Windows SDK.

DEBUG_DATA_DumpWriterStatus

ULONG

Returns the status of the writer of the dump file. This value is operating system and dump file
type specific.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1333 of 1651

The following values are valid for Windows XP and later versions of Windows:
Value
Return Type
Description
DEBUG_DATA_NtBuildLabAddr
ULONG64 Returns the address of the kernel variable NtBuildLab.
DEBUG_DATA_KiNormalSystemCall
ULONG64 (Itanium only) Returns the address of the kernel function KiNormalSystemCall.
DEBUG_DATA_KiProcessorBlockAddr
ULONG64 Returns the kernel variable KiProcessorBlock.
DEBUG_DATA_MmUnloadedDriversAddr
ULONG64 Returns the address of the kernel variable MmUnloadedDrivers.
DEBUG_DATA_MmLastUnloadedDriverAddr
ULONG64 Returns the address of the kernel variable MmLastUnloadedDriver.
DEBUG_DATA_MmTriageActionTakenAddr
ULONG64 Returns the address of the kernel variable VerifierTriageActionTaken.
DEBUG_DATA_MmSpecialPoolTagAddr
ULONG64 Returns the address of the kernel variable MmSpecialPoolTag.
DEBUG_DATA_KernelVerifierAddr
ULONG64 Returns the address of the kernel variable KernelVerifier.
DEBUG_DATA_MmVerifierDataAddr
ULONG64 Returns the address of the kernel variable MmVerifierData.
DEBUG_DATA_MmAllocatedNonPagedPoolAddr
ULONG64 Returns the address of the kernel variable MmAllocatedNonPagedPool.
DEBUG_DATA_MmPeakCommitmentAddr
ULONG64 Returns the address of the kernel variable MmPeakCommitment.
DEBUG_DATA_MmTotalCommitLimitMaximumAddr ULONG64 Returns the address of the kernel variable MmTotalCommitLimitMaximum.
DEBUG_DATA_CmNtCSDVersionAddr
ULONG64 Returns the address of the kernel variable CmNtCSDVersion.
DEBUG_DATA_MmPhysicalMemoryBlockAddr
ULONG64 Returns the address of the kernel variable MmPhysicalMemoryBlock.
DEBUG_DATA_MmSessionBase
ULONG64 Returns the address of the kernel variable MmSessionBase.
DEBUG_DATA_MmSessionSize
ULONG64 Returns the address of the kernel variable MmSessionSize.
DEBUG_DATA_MmSystemParentTablePage
ULONG64 (Itanium only) Returns the address of the kernel variable MmSystemParentTablePage.
The following values are valid for Windows Server 2003 and later versions of Windows:
Value

Return
Type
DEBUG_DATA_MmVirtualTranslationBase
ULONG64
DEBUG_DATA_OffsetKThreadNextProcessor
USHORT
DEBUG_DATA_OffsetKThreadTeb
USHORT
DEBUG_DATA_OffsetKThreadKernelStack
USHORT
DEBUG_DATA_OffsetKThreadInitialStack
USHORT
DEBUG_DATA_OffsetKThreadApcProcess
USHORT
DEBUG_DATA_OffsetKThreadState
USHORT
DEBUG_DATA_OffsetKThreadBStore
USHORT
DEBUG_DATA_OffsetKThreadBStoreLimit
USHORT
DEBUG_DATA_SizeEProcess
USHORT
DEBUG_DATA_OffsetEprocessPeb
USHORT
DEBUG_DATA_OffsetEprocessParentCID
USHORT
DEBUG_DATA_OffsetEprocessDirectoryTableBase USHORT
DEBUG_DATA_SizePrcb
USHORT
DEBUG_DATA_OffsetPrcbDpcRoutine
USHORT
DEBUG_DATA_OffsetPrcbCurrentThread
USHORT
DEBUG_DATA_OffsetPrcbMhz
USHORT
DEBUG_DATA_OffsetPrcbCpuType
USHORT

Description
Returns the address of the kernel variable MmVirtualTranslationBase.
Returns the offset of the NextProcessor field in the KTHREAD structure.
Returns the offset of the Teb field in the KTHREAD structure.
Returns the offset of the KernelStack field in the KTHREAD structure.
Returns the offset of the InitialStack field in the KTHREAD structure.
Returns the offset of the ApcState.Process field in the KTHREAD structure.
Returns the offset of the State field in the KTHREAD structure.
(Itanium only) Returns the offset of the InitialBStore field in the KTHREAD structure.
(Itanium only) Returns the offset of the BStoreLimit field in the KTHREAD structure.
Returns the size of the EPROCESS structure.
Returns the offset of the Peb field in the EPROCESS structure.
Returns the offset of the InheritedFromUniqueProcessId field in the EPROCESS structure.
Returns the offset of the DirectoryTableBase field in the EPROCESS structure.
Returns the size of the KPRCB structure.
Returns the offset of the DpcRoutineActive field in the KPRCB structure.
Returns the offset of the CurrentThread field in the KPRCB structure.
Returns the offset of the MHz field in the KPRCB structure.
For Itanium processors: Returns the offset of the ProcessorModel field in the KPRCB structure.
For all other processors: Returns the offset of the CpuType field in the KPRCB structure.

DEBUG_DATA_OffsetPrcbVendorString

USHORT

For Itanium processors: Returns the offset of the ProcessorVendorString field in the KPRCB
structure.
For all other processors: Returns the offset of the VendorString field in the KPRCB structure.

DEBUG_DATA_OffsetPrcbProcessorState
DEBUG_DATA_OffsetPrcbNumber
DEBUG_DATA_SizeEThread
DEBUG_DATA_KdPrintCircularBufferPtrAddr
DEBUG_DATA_KdPrintBufferSizeAddr

USHORT
USHORT
USHORT
ULONG64
ULONG64

Returns the offset of the ProcessorState.ContextFrame field in the KPRCB structure.

Returns the offset of the Number field in the KPRCB structure.
Returns the size of the ETHREAD structure.
Returns the address of the kernel variable KdPrintCircularBuffer.
Returns the address of the kernel variable KdPrintBufferSize.

Buffer
Receives the value of the specified debugger data. The Return Type column in the above table specifies the data type that is returned. The data can be accessed by
casting Buffer to a pointer to that type.
BufferSize
Specifies the size in bytes of the buffer Buffer.
DataSize
Receives the number of bytes used in the buffer Buffer. If DataSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
ReadDebuggerData is available in all versions of IDebugDataSpaces.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1334 of 1651

Comments
Some or all of the values may be unavailable in certain debugging sessions. For example, some of the values are only available for particular versions of the operating system.
For details on the different values returned by ReadDebuggerData, see Microsoft Windows Internals by David Solomon and Mark Russinovich, the Microsoft Windows
SDK, and the Windows Driver Kit (WDK).
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadHandleData
The ReadHandleData method retrieves information about a system object specified by a system handle.
HRESULT
IDebugDataSpaces2::ReadHandleData(
IN ULONG64 Handle,
IN ULONG DataType,
OUT OPTIONAL PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
);
Parameters
Handle
Specifies the system handle of the object whose data is requested. See Handles for information about system handles.
DataType
Specifies the data type to return for the system handle. The following table contains the valid values, along with the corresponding return type:
Value
Description
DEBUG_HANDLE_DATA_TYPE_BASIC
Returns basic information about the system object.
In this case, the argument Buffer can be considered to have type PDEBUG_HANDLE_DATA_BASIC.
DEBUG_HANDLE_DATA_TYPE_TYPE_NAME

Returns the name of the object type. For example, "Process" or "Thread".
In this case, the argument Buffer can be considered to have type PSTR.

DEBUG_HANDLE_DATA_TYPE_OBJECT_NAME

Returns the name of the object. This includes its location in the object directory.
In this case, the argument Buffer can be considered to have type PSTR.

DEBUG_HANDLE_DATA_TYPE_HANDLE_COUNT

Returns the number of handles held by the object. This is similar to the field
DEBUG_HANDLE_DATA_BASIC.HandleCount.
In this case, the argument Buffer can be considered to have type PULONG.

DEBUG_HANDLE_DATA_TYPE_TYPE_NAME_WIDE

Returns the name of the object type.

In this case, the argument Buffer can be considered to have type PWSTR

DEBUG_HANDLE_DATA_TYPE_OBJECT_NAME_WIDE Returns the name of the object.

In this case, the argument Buffer can be considered to have type PWSTR.

Buffer
Receives the object data. Upon successful completion of the method, the contents of this buffer may be accessed by casting Buffer to the type specified in the above table.
If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be returned.
DataSize
Receives the size of the data in bytes. If DataSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1335 of 1651

Interface Version
ReadHandleData is available in IDebugDataSpaces2 and later versions.
Comments
This method is only available in user-mode debugging.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
Handles
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadImageNtHeaders
The ReadImageNtHeaders method returns the NT headers for the specified image loaded in the target.
HRESULT
IDebugDataSpaces3::ReadImageNtHeaders(
IN ULONG64 ImageBase,
OUT IMAGE_NT_HEADERS64 * Headers
);
Parameters
ImageBase
Specifies the location in the target's virtual address space of the image whose NT headers are being requested.
Headers
Receives the NT headers for the specified image.
Return Value
S_OK
The method was successful.
E_INVALIDARG
No NT headers were found for the specified image.
This method can also return error values. See Return Values for more details.
Interface Version
ReadImageNtHeaders is available in IDebugDataSpaces3 and later versions.
Comments
If the image's NT headers are 32-bit, they are automatically converted to 64-bit for consistency. To determine if the headers were originally 32-bit, look at the value of
Headers.OptionalHeader.Magic. If the value is IMAGE_NT_OPTIONAL_HDR32_MAGIC, the NT headers were originally 32-bit; otherwise the value is
IMAGE_NT_OPTIONAL_HDR64_MAGIC, indicating the NT headers were originally 64-bit.
This method will not read ROM headers.
IMAGE_NT_HEADERS64, IMAGE_NT_OPTIONAL_HDR32_MAGIC, and IMAGE_NT_OPTIONAL_HDR64_MAGIC appear in the Microsoft Windows SDK header
file winnt.h. IMAGE_NT_HEADERS64 is the 64-bit equivalent of IMAGE_NT_HEADERS, which is described in the Windows SDK documentation.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadIo
The ReadIo method reads from the system and bus I/O memory.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

This method can also return error values. See Return Values for more details.
Interface Version
ReadPhysical is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadPhysical2
The ReadPhysical2 method reads the target's memory from the specified physical address.
HRESULT
IDebugDataSpaces4::ReadPhysical2(
IN ULONG64 Offset,
IN ULONG Flags,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
);
Parameters
Offset
Specifies the physical address of the memory to read.
Flags
Specifies the properties of the physical memory to be read. This must match the way the physical memory was advertised to the operating system on the target. Possible
values are listed in the following table.
Value
Description
DEBUG_PHYSICAL_DEFAULT
Use the default memory caching.
DEBUG_PHYSICAL_CACHED
The physical memory is cached.
DEBUG_PHYSICAL_UNCACHED
The physical memory is uncached.
DEBUG_PHYSICAL_WRITE_COMBINED The physical memory is write-combined.
Buffer
Receives the memory that is read.
BufferSize
Specifies the size, in bytes, of the Buffer buffer. This is the maximum number of bytes that will be read.
BytesRead
Receives the number of bytes read from the target's memory. If BytesRead is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
ReadPhysical2 is available in IDebugDataSpaces4 and later versions.
Comments
This method is only available in kernel-mode debugging.
The flags DEBUG_PHYSICAL_CACHED, DEBUG_PHYSICAL_UNCACHED, and DEBUG_PHYSICAL_WRITE_COMBINED can only be used when the target is a
live kernel target that is being debugged in the standard way (using a COM port, 1394 bus, or named pipe).
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
ReadPhysical, WritePhysical2

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1342 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WritePhysical
The WritePhysical method writes data to the specified physical address in the target's memory.
HRESULT
IDebugDataSpaces::WritePhysical(
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
);
Parameters
Offset
Specifies the physical address of the memory to write the data to.
Buffer
Specifies the data to write.
BufferSize
Specifies the size in bytes of the buffer Buffer. This is the maximum number of bytes that will be written.
BytesWritten
Receives the number of bytes written to the target's memory. If BytesWritten is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
WritePhysical is available in all versions of IDebugDataSpaces.
Comments
This method is only available in kernel-mode debugging.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WritePhysical2
The WritePhysical2 method writes data to the specified physical address in the target's memory.
HRESULT
IDebugDataSpaces4::WritePhysical2(
IN ULONG64 Offset,
IN ULONG Flags,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
);
Parameters
Offset
Specifies the physical address of the memory to write the data to.
Flags
Specifies the properties of the physical memory to be written to. This must match the way the physical memory was advertised to the operating system on the target.
Possible values are listed in the following table.
Value
Description
DEBUG_PHYSICAL_DEFAULT
Use the default memory caching.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1343 of 1651

DEBUG_PHYSICAL_CACHED
The physical memory is cached.
DEBUG_PHYSICAL_UNCACHED
The physical memory is uncached.
DEBUG_PHYSICAL_WRITE_COMBINED The physical memory is write-combined.
Buffer
Specifies the data to write.
BufferSize
Specifies the size, in bytes, of the Buffer buffer. This is the maximum number of bytes that will be written.
BytesWritten
Receives the number of bytes written to the target's memory. If BytesWritten is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
WritePhysical2 is available in IDebugDataSpaces4 and later versions.
Comments
This method is only available in kernel-mode debugging.
The flags DEBUG_PHYSICAL_CACHED, DEBUG_PHYSICAL_UNCACHED, and DEBUG_PHYSICAL_WRITE_COMBINED can only be used when the target is a
live kernel target that is being debugged in the standard way (using a COM port, 1394 bus, or named pipe).
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
WritePhysical, WritePhysical2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadProcessorSystemData
The ReadProcessorSystemData method returns data about the specified processor.
HRESULT
IDebugDataSpaces::ReadProcessorSystemData(
IN ULONG Processor,
IN ULONG Index,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG DataSize
);
Parameters
Processor
Specifies the processor whose data is to be read.
Index
Specifies the data type to read. The following table contains the valid values. After successful completion, the data returned in the buffer Buffer has the type specified by
the middle column.
Value
Description
DEBUG_DATA_KPCR_OFFSET
Returns the virtual address of the processor's Processor Control Region (PCR).
In this case, the argument Buffer can be considered to have type PULONG64.
DEBUG_DATA_KPRCB_OFFSET

Returns the virtual address of the processor's Processor Control Block (PRCB).
In this case, the argument Buffer can be considered to have type PULONG64.

FillVirtual

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1347 of 1651

The FillVirtual method writes a pattern of bytes to the target's virtual memory. The pattern is written repeatedly until the specified memory range is filled.
HRESULT
IDebugDataSpaces2::FillVirtual(
IN ULONG64 Start,
IN ULONG Size,
IN PVOID Pattern,
IN ULONG PatternSize,
OUT OPTIONAL PULONG Filled
);
Parameters
Start
Specifies the location in the target's virtual address space at which to start writing the pattern.
Size
Specifies how many bytes to write to the target's memory.
Pattern
Specifies the memory location of the pattern.
PatternSize
Specifies the size in bytes of the pattern.
Filled
Receives the number of bytes written. If it is set to NULL, this information isn't returned.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.
Interface Version
FillVirtual is available in IDebugDataSpaces2 and later versions.
Comments
This method writes the pattern to the target's memory as many times as will fit in Size bytes.
If the final copy of the pattern will not completely fit into the memory range, it will only be partially written. This includes the case where the size of the pattern is larger than
the value of Size, and the extra bytes in the pattern are ignored.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
WriteVirtual
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

QueryVirtual
The QueryVirtual method provides information about the specified pages in the target's virtual address space.
HRESULT
IDebugDataSpaces2::QueryVirtual(
IN ULONG64 Offset,
OUT MEMORY_BASIC_INFORMATION64 *
);

Info

Parameters
Offset
Specifies the location in the target's virtual address space of the pages whose information is requested.
Info
Receives the information about the memory page.
Return Value
S_OK
The method was successful.
This method can also return error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Specifies the size in bytes of the buffer. This is also the number of bytes requested to be written.
BytesWritten
Receives the number of bytes that were written. If it is set to NULL, this information is not returned.
Return Value
S_OK
The method was at least partially successful. BytesWritten indicates the number of bytes successfully written, which may be less than BufferSize.
This method can also return error values. See Return Values for more details.
Interface Version
WriteVirtual is available in all versions of IDebugDataSpaces.
Comments
This method writes the buffer to the memory in the target's virtual address space.
This method may only write to a cache of memory data when storing data. To avoid caching, use WriteVirtualUncached instead.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
ReadVirtual, WriteVirtualUncached
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadVirtualUncached
The ReadVirtualUncached method reads memory from the target's virtual address space.
HRESULT
IDebugDataSpaces::ReadVirtualUncached(
IN ULONG64 Offset,
OUT PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesRead
);
Parameters
Offset
Specifies the location in the target's virtual address space to be read.
Buffer
Specifies the buffer to read the memory into.
BufferSize
Specifies the size in bytes of the buffer. This is also the number of bytes being requested.
BytesRead
Receives the number of bytes that were read. If it is set to NULL, this information is not returned.
Return Value
S_OK
The method was successful. It is possible that BytesRead is less than BufferSize, but at least one byte of data is being returned.
This method can also return error values. See Return Values for more details.
Interface Version
ReadVirtualUncached is available in all versions of IDebugDataSpaces.
Comments
This method fills the buffer with the contents of the memory in the target's virtual address space.
This method behaves identically to ReadVirtual, except that it avoids using the virtual memory cache. It is therefore useful for reading inherently volatile virtual memory,
such as memory-mapped device areas, without contaminating or invalidating the cache.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1352 of 1651

See Also
ReadVirtual, WriteVirtualUncached
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WriteVirtualUncached
The WriteVirtualUncached method writes data to the target's virtual address space.
HRESULT
IDebugDataSpaces::WriteVirtualUncached(
IN ULONG64 Offset,
IN PVOID Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG BytesWritten
);
Parameters
Offset
Specifies the location in the target's virtual address space to be written.
Buffer
Specifies the buffer to write the memory from.
BufferSize
Specifies the size in bytes of the buffer. This is also the number of bytes requested to be written.
BytesWritten
Receives the number of bytes that were actually written. If it is set to NULL, this information is not returned.
Return Value
S_OK
The method was at least partially successful. BytesWritten indicates the number of bytes successfully written, which may be less than BufferSize.
This method can also return error values. See Return Values for more details.
Interface Version
WriteVirtualUncached is available in all versions of IDebugDataSpaces.
Comments
This method writes the buffer to the memory in the target's virtual address space.
This method behaves identically to WriteVirtual, except that it avoids using the virtual memory cache. It is therefore useful for reading inherently volatile virtual memory,
such as memory-mapped device areas, without contaminating or invalidating the cache.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
WriteVirtual, ReadVirtualUncached
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadPointersVirtual
The ReadPointersVirtual method is a convenience method for reading pointers from the target's virtual address space.
HRESULT
IDebugDataSpaces::ReadPointersVirtual(
IN ULONG Count
IN ULONG64 Offset
OUT PULONG64 Ptrs
);
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

GetPseudoDescription
GetPseudoIndexByName
GetNumberPseudoRegisters
GetPseudoValues
SetPseudoValues
OutputRegisters
OutputRegisters2
GetNumberRegisters
GetValue
GetValues
GetValues2
SetValue
SetValues
SetValues2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetDescription
The GetDescription and GetDescriptionWide methods return the description of a register.
HRESULT
IDebugRegisters::GetDescription(
IN ULONG Register
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PDEBUG_REGISTER_DESCRIPTION Desc
);
HRESULT
IDebugRegisters2::GetDescriptionWide(
IN ULONG Register
OUT OPTIONAL PWSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PDEBUG_REGISTER_DESCRIPTION Desc
);
#ifdef UNICODE
#define GetDescriptionT GetDescriptionWide
#else
#define GetDescriptionT GetDescription
#endif
Parameters
Register
Specifies the index of the register for which the description is requested.
NameBuffer
Specifies the buffer in which to store the name of the register. If NameBuffer is NULL, this information is not returned.
NameBufferSize
Specifies the size, in characters, of the buffer that NameBuffer specifies.
NameSize
Receives the size, in characters, of the register's name in NameBuffer buffer. If NameSize is NULL, this information is not returned.
Desc
Receives the description of the register. See DEBUG_REGISTER_DESCRIPTION for more details.
Return Value
S_OK
The method was successful.
S_FALSE

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

See Also
GetStackOffset
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetPseudoDescription
The GetPseudoDescription and GetPseudoDescriptionWide methods return a description of a pseudo-register, including its name and type.
HRESULT
IDebugRegisters2::GetPseudoDescription(
IN ULONG Register,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 TypeModule,
OUT OPTIONAL PULONG TypeId
);
HRESULT
IDebugRegisters2::GetPseudoDescriptionWide(
IN ULONG Register,
OUT OPTIONAL PWSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize,
OUT OPTIONAL PULONG64 TypeModule,
OUT OPTIONAL PULONG TypeId
);
#ifdef UNICODE
#define GetPseudoDescriptionT GetPseudoDescriptionWide
#else
#define GetPseudoDescriptionT GetPseudoDescription
#endif
Parameters
Register
Specifies the index of the pseudo-register whose description is requested. The index is always between zero and the number of pseudo-registers (returned by
GetNumberPseudoRegisters) minus one.
NameBuffer
Receives the name of the pseudo-register. If NameBuffer is NULL, this information is not returned.
NameBufferSize
Specifies the size, in characters, of the buffer that NameBuffer specifies.
NameSize
Receives the size in characters of the name of the pseudo-register. If NameSize is NULL, this information is not returned.
TypeModule
Receives the base address of the module to which the register's type belongs. If the type of the register is not known, zero is returned. If TypeModule is NULL, no
information is returned.
TypeId
Receives the type ID of the type within the module returned in TypeModule. If the type ID is not known, zero is returned. If TypeId is NULL, no information is returned.
Return Value
S_OK
The method was successful.
E_FAIL
The description for the register was not available
This list does not contain all the errors that might occur. For a list of possible errors, see HRESULT Values.
Interface Version
GetPseudoDescription and GetPseudoDescriptionWide are available in IDebugRegisters2 and later versions.
Comments
Descriptions are not always available for all registers. If a pseudo-register does not have a value - for example, $eventip will not have a value before an event has
occurred - or a type cannot be determined for a pseudo-register, this method will return E_FAIL.
For an overview of the IDebugRegisters interface and other register-related methods, see Registers.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1367 of 1651

See Also
GetNumberPseudoRegisters, GetPseudoIndexByName
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetPseudoIndexByName
The GetPseudoIndexByName and GetPseudoIndexByNameWide methods return the index of a pseudo-register.
HRESULT
IDebugRegisters2::GetPseudoIndexByName(
IN PCSTR Name,
OUT PULONG Index
);
HRESULT
IDebugRegisters2::GetPseudoIndexByNameWide(
IN PCWSTR Name,
OUT PULONG Index
);
#ifdef UNICODE
#define GetPseudoIndexByNameT GetPseudoIndexByNameWide
#else
#define GetPseudoIndexByNameT GetPseudoIndexByName
#endif
Parameters
Name
Specifies the name of the pseudo-register whose index is requested. The name includes the leading dollar sign ( $ ), for example, "$frame".
Index
Receives the index of the pseudo-register.
Return Value
S_OK
The method was successful.
This list does not contain all the errors that might occur. For a list of possible errors, see HRESULT Values.
Interface Version
GetPseudoIndexByName and GetPseudoIndexByNameWide are available in IDebugRegisters2 and later versions.
Comments
For the names of all the pseudo-registers, see Pseudo-Register Syntax.
For an overview of the IDebugRegisters interface and other register-related methods, see Registers.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also
GetPseudoDescription
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetNumberPseudoRegisters
The GetNumberPseudoRegisters method returns the number of pseudo-registers that are maintained by the debugger engine.
HRESULT
IDebugRegisters2::GetNumberPseudoRegisters(
OUT PULONG Number

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1368 of 1651

SetValue
The SetValue method sets the value of one of the target's registers.
HRESULT
IDebugRegisters::GetValue(
IN ULONG Register,
IN PDEBUG_VALUE Value
);
Parameters
Register
Specifies the index of the register whose value is to be set.
Value
Specifies the value to which to set the register. See DEBUG_VALUE for a description of this parameter type.
Return Value

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1375 of 1651

S_OK
The method was successful.
E_UNEXPECTED
The target is not accessible, or the register could not be accessed.
E_INVALIDARG
The value of Register is greater than the number of registers on the target machine.
This list does not contain all the errors that might occur. For a list of possible errors, see HRESULT Values.
Interface Version
SetValue is available in all versions of IDebugRegisters.
Comments
The engine does its best to coerce the value of Value into the type of the register; this coercion is the same as that performed by CoerceValue. If the value is larger than what
the register can hold, the least significant bits are dropped. Floating-point and integer conversions will also be performed if necessary.
When a subregister is altered, the register containing it is also altered.
To set the values of multiple registers, use the SetValues method instead.
For an overview of the IDebugRegisters interface and other register-related methods, see Registers.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also
SetValues, SetValues2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetValues
The SetValues method sets the value of several of the target's registers.
HRESULT
IDebugRegisters::SetValues(
IN ULONG Count,
IN OPTIONAL PULONG Indices,
IN ULONG Start,
IN PDEBUG_VALUE Values
);
Parameters
Count
Specifies the number of registers for which to set the values.
Indices
Specifies an array that contains the indices of the registers for which to set the values. The number of elements in this array is Count. If Indices is NULL, Start is used
instead.
Start
If Indices is NULL, the registers will be set consecutively starting at this index. Otherwise it is ignored.
Values
Specifies the array that contains values to which to set the registers. The number of elements this array holds is Count. See DEBUG_VALUE for a description of this
parameter type.
Return Value
S_OK
The method was successful.
E_UNEXPECTED
The target is not accessible, or one or more of the registers could not be accessed.
E_INVALIDARG
The value of the index of one or more of the registers is greater than the number of registers on the target machine.
This list does not contain all the errors that might occur. For a list of possible errors, see HRESULT Values.
Interface Version
SetValues is available in all versions of IDebugRegisters.
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1376 of 1651

The engine does its best to coerce the values in Values into the type of the registers; this coercion is the same as that performed by CoerceValue. If the value is larger than
what the register can hold, the least significant bits are dropped. Floating-point and integer conversions will also be performed if necessary.
If the return value is not S_OK, some of the registers still might have been set.
When a subregister is altered, the register containing it is also altered.
To set the value of only a single register, use the SetValue method instead.
The method SetValues2 performs the same task as this method but also allows the register source to be specified.
For an overview of the IDebugRegisters interface and other register-related methods, see Registers.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also
SetValue, SetValues2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetValues2
The SetValues2 method sets the value of several of the target's registers.
HRESULT
IDebugRegisters2::SetValues2(
IN ULONG Source,
IN ULONG Count,
IN PULONG Indices,
IN ULONG Start,
IN PDEBUG_VALUE Values
);
Parameters
Source
Specifies the register source to query.
The possible values are listed in the following table.
Value
Register source
DEBUG_REGSRC_DEBUGGEE Fetch register information from the target.
DEBUG_REGSRC_EXPLICIT Fetch register information from the current explicit register context.
DEBUG_REGSRC_FRAME
Fetch register information from the current scope's register context.
Note Stack unwinding does not guarantee accurate updating of the register context, so the scope frame's register context might not be
accurate in all cases.
Count
Specifies the number of registers for which to set the values.
Indices
Specifies an array that contains the indices of the registers for which to set the values. The number of elements in this array is Count. If Indices is NULL, Start is used
instead.
Start
If Indices is NULL, the registers will be set consecutively starting at this index. Otherwise, it is ignored.
Values
An array that contains the values to which to set the registers. The number of elements that this array holds is Count. See DEBUG_VALUE for a description of this
parameter type.
Return Value
S_OK
The method was successful.
This list does not contain all the errors that might occur. For a list of possible errors, see HRESULT Values.
Interface Version
SetValues2 is available in IDebugRegisters2 and later versions.
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1377 of 1651

The engine does its best to cast the values in Values into the type of the registers; this conversion is the same as that performed by CoerceValue. If the value is larger than
what the register can hold, the least significant bits are dropped. Floating-point and integer conversions will also be performed if necessary.
If the return value is not S_OK, some of the registers still might have been set.
When a subregister is altered, the register that contains it is also altered.
The method SetValues performs the same task as this method but always uses the target as the register source.
For an overview of the IDebugRegisters interface and other register-related methods, see Registers.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also
SetValue, SetValues
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugSymbols
The IDebugSymbols interface includes the following methods:
GetConstantName
ReadTypedDataPhysical
OutputTypedDataPhysical
WriteTypedDataPhysical
ReadTypedDataVirtual
OutputTypedDataVirtual
WriteTypedDataVirtual
GetFieldName
GetFieldOffset
GetFieldTypeAndOffset
GetFunctionEntryByOffset
AppendImagePath
GetImagePath
SetImagePath
GetLineByOffset
GetOffsetByLine
IsManagedModule
GetModuleByIndex
GetModuleByModuleName
GetModuleByModuleName2
GetModuleNames
GetModuleNameString
GetNumberModules
GetModuleByOffset
GetModuleByOffset2
GetModuleParameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1378 of 1651

AddSyntheticModule
RemoveSyntheticModule
GetModuleVersionInformation
GetNameByOffset
GetNearNameByOffset
GetOffsetByName
Reload
GetScope
ResetScope
SetScope
SetScopeFrameByIndex
GetCurrentScopeFrameIndex
SetScopeFromJitDebugInfo
SetScopeFromStoredEvent
GetScopeSymbolGroup
FindSourceFile
GetSourceFileLineOffsets
AppendSourcePath
GetSourcePath
SetSourcePath
GetSourcePathElement
GetSourceEntriesByLine
GetSourceEntriesByOffset
GetSourceEntryOffsetRegions
GetSourceEntryBySourceEntry
GetSourceEntryString
GetSymbolEntryInformation
GetSymbolEntriesByName
GetSymbolEntriesByOffset
GetSymbolEntryOffsetRegions
GetSymbolEntryString
GetSymbolEntryBySymbolEntry
GetSymbolEntryByToken
CreateSymbolGroup
EndSymbolMatch
GetNextSymbolMatch
StartSymbolMatch
GetSymbolModule
OutputSymbolByOffset
AddSymbolOptions
GetSymbolOptions
RemoveSymbolOptions

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1379 of 1651

SetSymbolOptions
AppendSymbolPath
GetSymbolPath
SetSymbolPath
AddSyntheticSymbol
RemoveSyntheticSymbol
GetTypeId
GetOffsetTypeId
GetSymbolTypeId
GetTypeName
GetTypeSize
AddTypeOptions
GetTypeOptions
RemoveTypeOptions
SetTypeOptions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetConstantName
The GetConstantName and GetConstantNameWide methods return the name of the specified constant.
HRESULT
IDebugSymbols2::GetConstantName(
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG64 Value,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
);
HRESULT
IDebugSymbols3::GetConstantName(
IN ULONG64 Module,
IN ULONG TypeId,
IN ULONG64 Value,
OUT OPTIONAL PWSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
);
#ifdef UNICODE
#define GetConstantNameT GetConstantNameWide
#else
#define GetConstantNameT GetConstantName
#endif
Parameters
Module
Specifies the base address of the module in which the constant was defined.
TypeId
Specifies the type ID of the constant.
Value
Specifies the value of the constant.
NameBuffer
Receives the constant's name. If NameBuffer is NULL, this information is not returned.
NameBufferSize
Specifies the size in characters of the buffer NameBuffer.
NameSize
Receives the size in characters of the constant's name.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

IDebugSymbols::GetModuleByModuleNameWide(
IN PCWSTR Name,
IN ULONG StartIndex,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
);
#ifdef UNICODE
#define GetModuleByModuleNameT GetModuleByModuleNameWide
#else
#define GetModuleByModuleNameT GetModuleByModuleName
#endif
Parameters
Name
Specifies the name of the desired module.
StartIndex
Specifies the index to start searching from.
Index
Receives the index of the first module with the name Name. If Index is NULL, this information is not returned.
Base
Receives the location in the target's memory address space of the base of the module. If Base is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
E_INVALIDARG
One of the arguments passed in was invalid.
This method may also return other error values. See Return Values for more details.
Interface Version
GetModuleByModuleName is available in all versions of IDebugSymbols. GetModuleByModuleNameWide is available in IDebugSymbols3 and later versions.
Comments
Starting at the specified index, these methods return the first module they find with the specified name. If the target has more than one module with this name, then subsequent
modules can be found by repeated calls to these methods with higher values of StartIndex.
For more information about modules, see Modules.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetModuleByModuleName2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetModuleByModuleName2
The GetModuleByModuleName2 and GetModuleByModuleName2Wide methods search through the process's modules for one with the specified name.
HRESULT
IDebugSymbols3::GetModuleByModuleName2(
IN PCSTR Name,
IN ULONG StartIndex,
IN ULONG Flags,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
);
HRESULT
IDebugSymbols3::GetModuleByModuleName2Wide(
IN PCWSTR Name,
IN ULONG StartIndex,
IN ULONG Flags,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1394 of 1651

#ifdef UNICODE
#define GetModuleByModuleName2T GetModuleByModuleName2Wide
#else
#define GetModuleByModuleName2T GetModuleByModuleName2
#endif
Parameters
Name
Specifies the name of the desired module.
StartIndex
Specifies the index to start searching from.
Flags
Specifies a bit-set containing options used when searching for the module with the specified name. Flags may contain the following bit-flags:
Flag
Effect
DEBUG_GETMOD_NO_LOADED_MODULES
Do not search the loaded modules.
DEBUG_GETMOD_NO_UNLOADED_MODULES Do not search the unloaded modules.
Index
Receives the index of the first module with the name Name. If Index is NULL, this information is not returned.
Base
Receives the location in the target's memory address space of the base of the module. If Base is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
E_INVALIDARG
One of the arguments passed in was invalid.
This method may also return other error values. See Return Values for more details.
Interface Version
GetModuleByModuleName2 and GetModuleByModuleName2Wide are available in IDebugSymbols3 and later versions.
Comments
Starting at the specified index, these methods return the first module they find with the specified name. If the target has more than one module with this name, then subsequent
modules can be found by repeated calls to these methods with higher values of StartIndex.
For more information about modules, see Modules.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetModuleByModuleName
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetModuleNames
The GetModuleNames method returns the names of the specified module.
HRESULT
IDebugSymbols::GetModuleNames(
IN ULONG Index,
IN ULONG64 Base,
OUT OPTIONAL PSTR ImageNameBuffer,
IN ULONG ImageNameBufferSize,
OUT OPTIONAL PULONG ImageNameSize,
OUT OPTIONAL PSTR ModuleNameBuffer,
IN ULONG ModuleNameBufferSize,
OUT OPTIONAL PULONG ModuleNameSize,
OUT OPTIONAL PSTR LoadedImageNameBuffer,
IN ULONG LoadedImageNameBufferSize,
OUT OPTIONAL PULONG LoadedImageNameSize
);
Parameters
Index

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1395 of 1651

Specifies the index of the module whose names are requested. If it is set to DEBUG_ANY_ID, the module is specified by Base.
Base
Specifies the base address of the module whose names are requested. This parameter is only used if Index is set to DEBUG_ANY_ID.
ImageNameBuffer
Receives the image name of the module. If ImageNameBuffer is NULL, this information is not returned.
ImageNameBufferSize
Specifies the size in characters of the buffer ImageNameBuffer in characters.
ImageNameSize
Receives the size in characters of the image name. If ImageNameSize is NULL, this information is not returned.
ModuleNameBuffer
Receives the module name of the module. If ModuleNameBuffer is NULL, this information is not returned.
ModuleNameBufferSize
Specifies the size in characters of the buffer ModuleNameBuffer.
ModuleNameSize
Receives the size in characters of the module name. If ModuleNameSize is NULL, this information is not returned.
LoadedImageNameBuffer
Receives the loaded image name of the module. If LoadedImageNameBuffer is NULL, this information is not returned.
LoadedImageNameBufferSize
Specifies the size in characters of the buffer LoadedImageNameBuffer.
LoadedImageNameSize
Receives the size in characters of the loaded image name. If LoadedImageNameSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, at least one of ImageNameBuffer, ModuleNameBuffer, or LoadedImageNameBuffer was too small for the corresponding name, so
it was truncated.
E_NOINTERFACE
The specified module was not found.
This method may also return other error values. See Return Values for more details.
Interface Version
GetModuleNames is available in all versions of IDebugSymbols.
Comments
For more information about modules, see Modules.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetModuleNameString
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Headers: Defined in Dbgeng.h. Include Dbgeng.h.

See Also
GetModuleByOffset2, GetModuleByIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetModuleByOffset2
The GetModuleByOffset2 method searches through the process's modules for one whose memory allocation includes the specified location.
HRESULT
IDebugSymbols3::GetModuleByOffset2(
IN ULONG64 Offset,
IN ULONG StartIndex,
IN ULONG Flags,
OUT OPTIONAL PULONG Index,
OUT OPTIONAL PULONG64 Base
);
Parameters
Offset
Specifies a location in the target's virtual address space which is inside the desired module's memory allocation for example, the address of a symbol belonging to the
module.
StartIndex
Specifies the index to start searching from.
Flags
Specifies a bit-set containing options used when searching for the module with the specified location. Flags may contain the following bit-flags:
Flag
Effect
DEBUG_GETMOD_NO_LOADED_MODULES
Do not search the loaded modules.
DEBUG_GETMOD_NO_UNLOADED_MODULES Do not search the unloaded modules.
Index
Receives the index of the module. If Index is NULL, this information is not returned.
Base
Receives the location in the target's memory address space of the base of the module. If Base is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetModuleByOffset2 is available in IDebugSymbols3 and later versions.
Comments
Starting at the specified index, this method returns the first module it finds whose memory allocation address range includes the specified location. If the target has more than
one module whose memory address range includes this location, then subsequent modules can be found by repeated calls to this method with higher values of StartIndex.
For more information about modules, see Modules.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetModuleByOffset, GetModuleByIndex
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Headers: Defined in Dbgeng.h. Include Dbgeng.h.

See Also
GetNameByOffset
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetCurrentScopeFrameIndex
The GetCurrentScopeFrameIndex method returns the index of the current stack frame in the call stack.
HRESULT
IDebugSymbols3::GetCurrentScopeFrameIndex(
OUT PULONG Index
);
Parameters
Index
Receives the index of the stack frame corresponding to the current scope. The index counts the number of frames from the top of the call stack. The frame at the top of
the stack, representing the current call, has index zero.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetCurrentScopeFrameIndex is available in IDebugSymbols3 and later versions.
Comments
If the current scope was set using SetScope, Index receives the value of the FrameNumber member of the DEBUG_STACK_TRACE structure passed to the ScopeFrame
parameter of SetScope.
For more information about scopes, see Scopes and Symbol Groups.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
.frame (Set Local Context), SetScopeFrameByIndex, GetScope

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1409 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetScopeFromStoredEvent
The SetScopeFromStoredEvent method sets the current scope to the scope of the stored event.
HRESULT
IDebugSymbols3::SetScopeFromStoredEvent(
);
Parameters
None
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
SetScopeFromStoredEvent is available in IDebugSymbols3 and later versions.
Comments
Currently only user-mode Minidumps can contain a stored event.
The new scope is printed to the debugger console.
For more information about scopes, see Scopes and Symbol Groups.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
.ecxr (Display Exception Context Record), SetScopeFrameByIndex, SetScope, GetStoredEventInformation
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetScopeSymbolGroup
The GetScopeSymbolGroup and GetScopeSymbolGroup2 methods return a symbol group containing the symbols in the current target's scope.
HRESULT
IDebugSymbols::GetScopeSymbolGroup(
IN ULONG Flags,
IN OPTIONAL IDebugSymbolGroup * Update,
OUT IDebugSymbolGroup * * Symbols
);
HRESULT
IDebugSymbols3::GetScopeSymbolGroup2(
IN ULONG Flags,
IN OPTIONAL IDebugSymbolGroup2 * Update,
OUT IDebugSymbolGroup2 * * Symbols
);
Parameters
Flags
Specifies a bit-set used to determine which symbols to include in the symbol group. To include all symbols, set Flags to DEBUG_SCOPE_GROUP_ALL. The following
bit-flags determine which symbols are included.
Flag
Description
DEBUG_SCOPE_GROUP_ARGUMENTS Include the function arguments for the current scope.

GetSourcePath, SetSourcePath, GetSourcePathElement

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetSourcePath
The GetSourcePath and GetSourcePathWide methods return the source path.
IDebugSymbols::GetSourcePath(
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
);
IDebugSymbols3::GetSourcePathWide(
OUT OPTIONAL PCWSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG PathSize
);
#ifdef UNICODE
#define GetSourcePathT GetSourcePathWide
#else
#define GetSourcePathT GetSourcePath
#endif
Parameters
Buffer
Receives the source path. This is a string that contains source path elements separated by semicolons (;). Each source path element can specify either a directory or a
source server. If Buffer is NULL, this information is not returned.
BufferSize
Specifies the size, in characters, of the Buffer buffer.
PathSize
Receives the size, in characters, of the source path.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the buffer was not large enough to hold the source path and the path was truncated.
This method can also return error values. See Return Values for more details.
Interface Version
GetSourcePath is available in all versions of IDebugSymbols. GetSourcePathWide is available in IDebugSymbols3 and later versions.
Comments
The source path is used by the engine when searching for source files.
For more information about manipulating the source path, see Using Source Files. For an overview of the source path and its syntax, see Source Path.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
AppendSourcePath, SetSourcePath, GetSourcePathElement
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetSourcePath
The SetSourcePath and SetSourcePathWide methods set the source path.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1429 of 1651

AddSyntheticSymbol
The AddSyntheticSymbol and AddSyntheticSymbolWide methods add a synthetic symbol to a module in the current process.
HRESULT
IDebugSymbols3::AddSyntheticSymbol(
IN ULONG64 Offset,
IN ULONG Size,
IN PCSTR Name,
IN ULONG Flags,
OUT OPTIONAL PDEBUG_MODULE_AND_ID
);

HRESULT
IDebugSymbols3::AddSyntheticSymbolWide(
IN ULONG64 Offset,
IN ULONG Size,
IN PCSTR Name,
IN ULONG Flags,
OUT OPTIONAL PDEBUG_MODULE_AND_ID Id
);
#ifdef UNICODE
#define AddSyntheticSymbolT AddSyntheticSymbolWide
#else
#define AddSyntheticSymbolT AddSyntheticSymbol
#endif
Parameters
Offset
Specifies the location in the process's virtual address space of the synthetic symbol.
Size
Specifies the size in bytes of the synthetic symbol.
Name
Specifies the name of the synthetic symbol.
Flags
Set to DEBUG_ADDSYNTHSYM_DEFAULT.
Id
Receives the DEBUG_MODULE_AND_ID structure that identifies the synthetic symbol. If Id is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
AddSyntheticSymbol and AddSyntheticSymbolWide are available in IDebugSymbols3 and later versions.
Comments
The location of the synthetic symbol must not be the same as the location of another symbol.
If the module containing a synthetic symbol is reloaded - for example, by calling Reload with the Module parameter set to the name of the module - the synthetic symbol
will be discarded.
For more information about synthetic symbols, see Synthetic Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
RemoveSyntheticSymbol, AddSyntheticModule
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

RemoveSyntheticSymbol
The RemoveSyntheticSymbol method removes a synthetic symbol from a module in the current process.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1430 of 1651

HRESULT
IDebugSymbols3::RemoveSyntheticSymbol(
IN PDEBUG_MODULE_AND_ID Id
);
Parameters
Id
Specifies the synthetic symbol to remove. This must be the same value returned in the Id parameter of AddSyntheticSymbol. See DEBUG_MODULE_AND_ID for
details about the type of this parameter.
Return Value
S_OK
The method was successful.
E_INVALIDARG
No synthetic symbol was found at the specified location. This is returned if a synthetic symbol at this location was previously removed or discarded.
This method may also return error values. See Return Values for more details.
Interface Version
RemoveSyntheticSymbol is available in IDebugSymbols3 and later versions.
Comments
If the module containing a synthetic symbol is reloaded - for example, by calling Reload with the Module parameter set to the name of the module - the synthetic symbol
will be discarded.
For more information about synthetic symbols, see Synthetic Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
AddSyntheticSymbol, RemoveSyntheticModule
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetTypeId
The GetTypeId and GetTypeIdWide methods look up the specified type and return its type ID.
HRESULT
IDebugSymbols::GetTypeId(
IN ULONG64 Module,
IN PCSTR Name,
OUT PULONG TypeId
);
HRESULT
IDebugSymbols3::GetTypeIdWide(
IN ULONG64 Module,
IN PCWSTR Name,
OUT PULONG TypeId
);
#ifdef UNICODE
#define GetTypeIdT GetTypeIdWide
#else
#define GetTypeIdT GetTypeId
#endif
Parameters
Module
Specifies the base address of the module to which the type belongs. For more information, see Modules. If Name contains a module name, Module is ignored.
Name
Specifies the name of the type whose type ID is desired. If Name is a module-qualified name (for example mymodule!main), the Module parameter is ignored.
TypeId
Receives the type ID of the symbol.
Return Value

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1431 of 1651

S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetTypeId is available in all versions of IDebugSymbols. GetTypeIdWide is available in IDebugSymbols3 and later versions.
Comments
If the specified symbol is a type, these methods return the type ID for that type; otherwise, they return the type ID for the type of the symbol.
A variable whose type was defined using typedef has a type ID that identifies the original type, not the type created by typedef. In the following example, the type ID of
MyInstance corresponds to the name MyStruct (this correspondence can be seen by passing the type ID to GetTypeName):
struct MyStruct { int a; };
typedef struct MyStruct MyType;
MyType MyInstance;
Moreover, calling these methods for MyStruct and MyType yields type IDs corresponding to MyStruct and MyType, respectively.
For more information about symbols and symbol names, see Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetOffsetTypeId, GetSymbolTypeId
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetOffsetTypeId
The GetOffsetTypeId method returns the type ID of the symbol closest to the specified memory location.
HRESULT
IDebugSymbols::GetOffsetTypeId(
IN ULONG64 Offset,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
);
Parameters
Offset
Specifies the location in the target's memory for the symbol. The symbol closest to this location is used.
TypeId
Receives the type ID of the symbol.
Module
Specifies the location in the target's memory address space of the base of the module to which the symbol belongs. For more information, see Modules. If Module is
NULL, this information is not returned.
Return Value
S_OK
The method was successful
This method may also return error values. See Return Values for more details.
Interface Version
GetOffsetTypeId is available in all versions of IDebugSymbols.
Comments
For more information about symbols, see Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1432 of 1651

GetTypeId, GetSymbolTypeId
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetSymbolTypeId
The GetSymbolTypeId and GetSymbolTypeIdWide methods return the type ID and module of the specified symbol.
HRESULT
IDebugSymbols::GetSymbolTypeId(
IN PCSTR Symbol,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
);
HRESULT
IDebugSymbols3::GetSymbolTypeIdWide(
IN PCWSTR Symbol,
OUT PULONG TypeId,
OUT OPTIONAL PULONG64 Module
);
#ifdef UNICODE
#define GetSymbolTypeIdT GetSymbolTypeIdWide
#else
#define GetSymbolTypeIdT GetSymbolTypeId
#endif
Parameters
Symbol
Specifies the expression whose type ID is requested. See the Comments section for details on the syntax of this expression.
TypeId
Receives the type ID.
Module
Receives the base address of the module containing the symbol. For more information, see Modules. If Module is NULL, this information is not returned.
Return Value
S_OK
The method was successful
This method may also return error values. See Return Values for more details.
Interface Version
GetSymbolTypeId is available in all versions of IDebugSymbols. GetSymbolTypeIdWide is available in IDebugSymbols3 and later versions.
Comments
The Symbol expression may contain structure fields, pointer dereferencing, and array dereferencing for example my_struct.some_field[0].
For more information about symbols, see Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetTypeId, GetSymbolTypeId
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetTypeName
The GetTypeName and GetTypeNameWide methods return the name of the type symbol specified by its type ID and module.
HRESULT

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1433 of 1651

IDebugSymbols::GetTypeName(
IN ULONG64 Module,
IN ULONG TypeId,
OUT OPTIONAL PSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
);
HRESULT
IDebugSymbols3::GetTypeNameWide(
IN ULONG64 Module,
IN ULONG TypeId,
OUT OPTIONAL PWSTR NameBuffer,
IN ULONG NameBufferSize,
OUT OPTIONAL PULONG NameSize
);
#ifdef UNICODE
#define GetTypeNameT GetTypeNameWide
#else
#define GetTypeNameT GetTypeName
#endif
Parameters
Module
Specifies the base address of the module to which the type belongs. For more information, see Modules.
TypeId
Specifies the type ID of the type.
NameBuffer
Receives the name of the type. If NameBuffer is NULL, this information is not returned.
NameBufferSize
Specifies the size in characters of the buffer NameBuffer.
NameSize
Receives the size in characters of the type's name. If NameSize is NULL, this information is not returned.
Return Value
S_OK
The method was successful.
S_FALSE
The method was successful. However, the buffer was not large enough to hold the name of the type and it was truncated.
E_FAIL
The specified type could not be found in the specified module.
This method may also return other error values. See Return Values for more details.
Interface Version
GetTypeName is available in all versions of IDebugSymbols. GetTypeNameWide is available in IDebugSymbols3 and later versions.
Comments
For more information about symbols, see Symbols.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetTypeSize
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetTypeSize
The GetTypeSize method returns the number of bytes of memory an instance of the specified type requires.
HRESULT
IDebugSymbols::GetTypeSize(
IN ULONG64 Module,
IN ULONG TypeId,
OUT PULONG Size
);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

GetCurrentThreadDataOffset
The GetCurrentThreadDataOffset method returns the location of the system data structure for the current thread.
HRESULT
IDebugSystemObjects::GetCurrentThreadDataOffset(
OUT PULONG64 Offset
);
Parameters
Offset
Receives the location of the system data structure for the current thread.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetCurrentThreadDataOffset is available in all versions of IDebugSystemObjects.
Comments
In user-mode debugging, the location returned is of the thread environment block (TEB) for the current thread. This is the same location returned by GetCurrentThreadTeb.
In kernel-mode debugging, the location returned is of the KTHREAD structure of the system thread that was executing on the processor represented by the current thread
when the last event occurred.
Note In kernel mode debugging, the current thread is always a virtual thread the debugger engine created for a processor in the target computer. Because events may occur in
different system threads, the KTHREAD location for a virtual thread may change.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1449 of 1651

For more information about threads, see Threads and Processes. For details on the KTHREAD and TEB structures, see Microsoft Windows Internals by David Solomon and
Mark Russinovich.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetThreadIdByHandle
The GetThreadIdByHandle method returns the engine thread ID for the specified thread. The thread is specified by its system handle.
HRESULT
IDebugSystemObjects::GetThreadIdByHandle(
IN ULONG64 Handle,
OUT PULONG Id
);
Parameters
Handle
Specifies the system handle of the thread whose thread ID is requested.
Id
Receives the engine thread ID.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetThreadIdByHandle is available in all versions of IDebugSystemObjects.
Comments
In kernel-mode debugging, because the handle is an artificial handle for a processor, this method returns the engine thread ID for the virtual thread representing that processor.
For more information about threads, see Threads and Processes. For details on system handles, see Handles.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetCurrentThreadHandle
The GetCurrentThreadHandle method returns the system handle for the current thread.
HRESULT
IDebugSystemObjects::GetCurrentThreadHandle(
OUT PULONG64 Handle
);
Parameters
Handle
Receives the current thread's system handle.
Return Value
S_OK
The method was successful.
This method may also return other error values. See Return Values for more details.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1450 of 1651

Interface Version
GetCurrentThreadHandle is available in all versions of IDebugSystemObjects.
Comments
In kernel-mode debugging, an artificial handle is created because the threads are virtual threads.
For more information about threads, see Threads and Processes. For details on system handles, see Handles.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetCurrentThreadId
The GetCurrentThreadId method returns the engine thread ID for the current thread.
HRESULT
IDebugSystemObjects::GetCurrentThreadId(
OUT PULONG Id
);
Parameters
Id
Receives the engine thread ID.
Return Value
S_OK
The method was successful.
This method may also return error values. See Return Values for more details.
Interface Version
GetCurrentThreadId is available in all versions of IDebugSystemObjects.
Comments
For more information about threads, see Threads and Processes.
Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetCurrentThreadId
The SetCurrentThreadId method makes the specified thread the current thread.
HRESULT
IDebugSystemObjects::SetCurrentThreadId(
IN ULONG Id
);
Parameters
Id
Specifies the engine thread ID of the thread that is to become the current thread.
Return Value
S_OK
The method was successful.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1461 of 1651

Requirements
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
Threads and Processes
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Callback COM Interfaces

This section includes:
IDebugEventCallbacks
IDebugInputCallbacks
IDebugOutputCallbacks
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks
The IDebugEventCallbacks interface includes the following methods:
IDebugEventCallbacks::Breakpoint
IDebugEventCallbacks::ChangeDebuggeeState
IDebugEventCallbacks::ChangeEngineState
IDebugEventCallbacks::Exception
IDebugEventCallbacks::GetInterestMask
IDebugEventCallbacks::LoadModule
IDebugEventCallbacks::UnloadModule
IDebugEventCallbacks::CreateProcess
IDebugEventCallbacks::ExitProcess
IDebugEventCallbacks::SessionStatus
IDebugEventCallbacks::ChangeSymbolState
IDebugEventCallbacks::SystemError
IDebugEventCallbacks::CreateThread
IDebugEventCallbacks::ExitThread
The IDebugEventCallbacksWide interface includes Unicode versions of these methods; the Unicode methods share the same names as those used by the methods in
IDebugEventCallbacks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks::Breakpoint
The Breakpoint callback method is called by the engine when the target issues a breakpoint exception.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1462 of 1651

HRESULT
IDebugEventCallbacks::Breakpoint(
IN IDebugBreakpoint * Bp
);
HRESULT
IDebugEventCallbacksWide::Breakpoint(
IN IDebugBreakpoint2 * Bp
);
#ifdef UNICODE
#define IDebugEventCallbacksT IDebugEventCallbacksWide
#else
#define IDebugEventCallbacksT IDebugEventCallbacks
#endif
Parameters
Bp
Specifies a pointer to the IDebugBreakpoint object corresponding to the breakpoint that was triggered.
Return Value
This method returns a DEBUG_STATUS_XXX value, which indicates how the execution of the target should proceed after the engine processes this event. For details on how
the engine treats this value, see Monitoring Events.
Comments
If the breakpoint has an associated command, the engine executes that command before calling this method.
The engine will only call this method if an IDebugBreakpoint object corresponding to the breakpoint exists in the engine, andif the breakpoint is a private breakpoint
this IDebugEventCallbacks object was registered with the client that added the breakpoint.
The engine calls this method only if the DEBUG_EVENT_BREAKPOINT flag is set in the mask returned by IDebugEventCallbacks::GetInterestMask.
Because the engine deletes the corresponding IDebugBreakpoint object when a breakpoint is removed (for example, by using RemoveBreakpoint), the value of Bp might be
invalid after Breakpoint returns. Therefore, implementations of IDebugEventCallbacks should not access Bp after Breakpoint returns.
For more information about handling events, see Monitoring Events. For information about managing breakpoints, see Breakpoints.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks::ChangeDebuggeeState
The ChangeDebuggeeState callback method is called by the engine when it makes or detects changes to the target.
HRESULT
IDebugEventCallbacks::ChangeDebuggeeState(
IN ULONG Flags,
IN ULONG64 Argument
);
HRESULT
IDebugEventCallbacks::ChangeDebuggeeState(
IN ULONG Flags,
IN ULONG64 Argument
);
#ifdef UNICODE
#define IDebugEventCallbacksT IDebugEventCallbacksWide
#else
#define IDebugEventCallbacksT IDebugEventCallbacks
#endif
Parameters
Flags
Specifies the type of changes made to the target. Flags may take one of the following values:
Value
Description
DEBUG_CDS_ALL
A general change in the target has occurred. For example, the target has been executing, or the engine has just attached to the target.
DEBUG_CDS_REGISTERS The processor's register for the target have changed.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

DEBUG_CDS_DATA

Page 1463 of 1651

The target's data space has changed.

Argument
Provides additional information about the change in the target. The interpretation of the value of Argument depends on the value of Flags:
DEBUG_CDS_ALL
The value of Argument is zero.
DEBUG_CDS_REGISTERS
If a single register has changed, the value of Argument is the index of that register. Otherwise, the value of Argument is DEBUG_ANY_ID.
DEBUG_CDS_DATA
The value of Argument specifies which data space was changed. The following table contains the possible values of Argument.
Value
Description
DEBUG_DATA_SPACE_VIRTUAL The target's virtual memory has changed.
DEBUG_DATA_SPACE_PHYSICAL The target's physical memory has changed.
DEBUG_DATA_SPACE_CONTROL The target's control memory has changed.
DEBUG_DATA_SPACE_IO
The target's I/O ports have received input or output.
DEBUG_DATA_SPACE_MSR
The target's Model-Specific Registers (MSRs) have changed.
DEBUG_DATA_SPACE_BUS_DATA The target's bus memory has changed.
Return Value
The return value is ignored by the engine unless it indicates a remote procedure call error; in this case the client, with which this IDebugEventCallbacks object is registered,
is disabled.
Comments
The engine calls ChangeDebuggeeState only if the DEBUG_EVENT_CHANGE_DEBUGGEE_STATE flag is set in the mask returned by
IDebugEventCallbacks::GetInterestMask.
For more information about handling events, see Monitoring Events. For information about managing the target's memory, including registers and data spaces, see Memory
Access. For information about the target's virtual and physical memory, see Virtual and Physical Memory. For information about the target's control memory, I/O ports, MSR,
and bus memory, see Other Data Spaces.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks::ChangeSymbolState
The ChangeSymbolState callback method is called by the engine when the symbol state changes.
HRESULT
IDebugEventCallbacks::ChangeSymbolState(
IN ULONG Flags,
IN ULONG64 Argument
);
HRESULT
IDebugEventCallbacksWide::ChangeSymbolState(
IN ULONG Flags,
IN ULONG64 Argument
);
#ifdef UNICODE
#define IDebugEventCallbacksT IDebugEventCallbacksWide
#else
#define IDebugEventCallbacksT IDebugEventCallbacks
#endif
Parameters
Flags
Specifies a bit-set indicating the nature of the change to the symbol state. The following bit flags might be set.
Value
Description
DEBUG_CSS_LOADS
The engine has loaded some module symbols.
DEBUG_CSS_UNLOADS
The engine has unloaded some module symbols.
DEBUG_CSS_SCOPE
The current symbol scope has changed.
DEBUG_CSS_PATHS
The executable image, source , or symbol search paths have changed.
DEBUG_CSS_SYMBOL_OPTIONS The symbol options have changed.
DEBUG_CSS_TYPE_OPTIONS
The type options have changed.
Argument
Provides additional information about the change to the symbol state. If more than one bit flag is set in the Flags parameter, the Argument parameter is not used.
Otherwise, the value of Argument depends on the value of Flags:
DEBUG_CSS_LOADS
The value of Argument is the base location (in the target's memory address space) of the module image that the engine loaded symbols for.
DEBUG_CSS_UNLOADS
The value of Argument is the base location (in the target's memory address space) of the module image that the engine unloaded symbols for. If the engine unloaded
symbols for more than one image, the value of Argument is zero.
DEBUG_CSS_SCOPE
The value of Argument is zero.
DEBUG_CSS_PATHS
The value of Argument is zero.
DEBUG_CSS_SYMBOL_OPTIONS
The value of Argument is the symbol options.
DEBUG_CSS_TYPE_OPTIONS
The value of Argument is zero.
Return Value
The return value is ignored by the engine unless it indicates a remote procedure call error; in this case the client, with which this IDebugEventCallbacks object is registered,
is disabled.
Comments
This method is only called by the engine if the DEBUG_EVENT_CHANGE_SYMBOL_STATE flag is set in the mask returned by
IDebugEventCallbacks::GetInterestMask.
For more information about handling events, see Monitoring Events.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1471 of 1651

Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks::SystemError
The SystemError callback method is called by the engine when a system error occurs in the target.
HRESULT
IDebugEventCallbacks::SystemError(
IN ULONG Error,
IN ULONG Level
);
HRESULT
IDebugEventCallbacksWide::SystemError(
IN ULONG Error,
IN ULONG Level
);
#ifdef UNICODE
#define IDebugEventCallbacksT IDebugEventCallbacksWide
#else
#define IDebugEventCallbacksT IDebugEventCallbacks
#endif
Parameters
Error
Specifies the error that caused the event.
Level
Specifies the severity of the error.
Return Value
This method returns a DEBUG_STATUS_XXX value, which indicates how the execution of the target should proceed after the engine processes this event. For details on how
the engine treats this value, see Monitoring Events.
Comments
This method is only called by the engine if the DEBUG_EVENT_SYSTEM_ERROR flag is set in the mask returned by IDebugEventCallbacks::GetInterestMask.
For more information about handling events, see Monitoring Events.
Requirements
Headers: Defined in dbgeng.h. Include dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IDebugEventCallbacks::CreateThread
The CreateThread callback method is called by the engine when a create-thread debugging event occurs in the target.
HRESULT
IDebugEventCallbacks::CreateThread(
IN ULONG64 Handle,
IN ULONG64 DataOffset,
IN ULONG64 StartOffset
);
HRESULT
IDebugEventCallbacksWide::CreateThread(
IN ULONG64 Handle,
IN ULONG64 DataOffset,
IN ULONG64 StartOffset
);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1472 of 1651

Page 1479 of 1651

Versions: Available in all versions of IDebugBreakpoint.

Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

RemoveFlags
The RemoveFlags method removes flags from a breakpoint.
HRESULT
IDebugBreakpoint::RemoveFlags(
IN ULONG Flags
);
Parameters
Flags
Flags to remove from the breakpoint. Flags is a bit field. Tthe new value of the flags in the engine is the old value and not the value of Flags. For more information about
the flag bit field and an explanation of each flag, see Controlling Breakpoint Flags and Parameters. You cannot modify the DEBUG_BREAKPOINT_DEFERRED flag in
the engine. This bit in Flags must always be zero.
Return Value
RemoveFlags might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
For more information about breakpoint properties, see Controlling Breakpoint Flags and Parameters.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetFlags
The SetFlags method sets the flags for a breakpoint.
HRESULT
IDebugBreakpoint::SetFlags(
IN ULONG Flags
);
Parameters
Flags
The new flags for the breakpoint. Flags is a bit field. It replaces the existing flag bits. For more information about the flag bit field and an explanation of each flag, see
Controlling Breakpoint Flags and Parameters. You cannot change the DEBUG_BREAKPOINT_DEFERRED flag in the engine. This bit in Flags must always be zero.
Return Value
SetFlags might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1480 of 1651

For more information about breakpoint properties, see Controlling Breakpoint Flags and Parameters.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetId
The GetId method returns a breakpoint ID, which is the engine's unique identifier for a breakpoint.
HRESULT
IDebugBreakpoint::GetId(
OUT PULONG Id
);
Parameters
Id
The breakpoint ID.
Return Value
GetId might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
The breakpoint ID remains fixed as long as the breakpoint exists. However, after the breakpoint has been removed, you can use its ID for another breakpoint.
The GetParameters method also returns the breakpoint ID.
For more information about how to use breakpoints, see Using Breakpoints.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetOffset
The GetOffset method returns the location that triggers a breakpoint.
HRESULT
IDebugBreakpoint::GetOffset(
OUT PULONG64 Offset
);
Parameters
Offset
The location on the target that triggers the breakpoint.
Return Value
GetOffset might return one of the following values:
S_OK
The method was successful.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1481 of 1651

E_NOINTERFACE
The breakpoint is deferred and does not currently specify a location in the target's memory address space. To determine the breakpoint location in this case, call
GetOffsetExpression.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
The GetParameters method also returns the location that triggers a breakpoint.
For more information about how to use breakpoints, see Using Breakpoints.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetOffset
The SetOffset method sets the location that triggers a breakpoint.
HRESULT
IDebugBreakpoint::SetOffset(
IN ULONG64 Offset
);
Parameters
Offset
The location on the target that triggers the breakpoint.
Return Value
SetOffset might return one of the following values:
S_OK
The method was successful.
E_UNEXPECTED
The breakpoint is deferred.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
For more information about how to use breakpoints, see Using Breakpoints.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetOffsetExpression
The GetOffsetExpression and GetOffsetExpressionWide methods return the expression string that evaluates to the location that triggers a breakpoint.
HRESULT
IDebugBreakpoint::GetOffsetExpression(
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ExpressionSize
);
HRESULT

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1482 of 1651

IDebugBreakpoint2::GetOffsetExpressionWide(
OUT OPTIONAL PWSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG ExpressionSize
);
#ifdef UNICODE
#define GetOffsetExpressionT GetOffsetExpressionWide
#else
#define GetOffsetExpressionT GetOffsetExpression
#endif
Parameters
Buffer
The expression string that evaluates to the location on the target that triggers the breakpoint. If Buffer is NULL, this information is not returned.
BufferSize
The size, in characters, of the buffer that Buffer points to.
ExpressionSize
The size, in characters, of the expression string. If ExpressionSize is NULL, this information is not returned.
Return Value
GetOffsetExpression and GetOffsetExpressionWide might return one of the following values:
S_OK
The method was successful.
S_FALSE
The method was successful, but the buffer was not large enough to hold the expression string and so the string was truncated to fit.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
The expression is evaluated every time that a module is loaded or unloaded. If the debugger cannot evaluate the expression (for example, if the expression contains a symbol
that cannot be interpreted), the breakpoint is flagged as deferred. (For more information about deferred breakpoints, see Controlling Breakpoint Flags and Parameters.)
The GetParameters method also returns the size of the expression string that specifies the location that triggers the breakpoint, ExpressionSize.
For more information about how to use breakpoints, see Using Breakpoints.
Requirements
Versions: GetOffsetExpression is available in all versions of IDebugBreakpoint. GetOffsetExpressionWide is available in IDebugBreakpoint2 and later versions.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SetOffsetExpression
The SetOffsetExpression and SetOffsetExpressionWide methods set an expression string that evaluates to the location that triggers a breakpoint.
HRESULT
IDebugBreakpoint::SetOffsetExpression(
IN PCSTR Expression
);
HRESULT
IDebugBreakpoint2::SetOffsetExpressionWide(
IN PCSTR Expression
);
#ifdef UNICODE
#define SetOffsetExpressionT SetOffsetExpressionWide
#else
#define SetOffsetExpressionT SetOffsetExpression
#endif
Parameters
Expression
The expression string that evaluates to the location on the target that triggers the breakpoint. If the engine icannot evaluate the expression (for example, if the expression
contains a symbol that cannot be interpreted), the breakpoint is flagged as deferred. (For more information about deferred breakpoints, see Controlling Breakpoint Flags
and Parameters.) For more information about the expression syntax, see Using Breakpoints.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1483 of 1651

Return Value
SetOffsetExpression and SetOffsetExpressionWide might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
For more information about how to use breakpoints, see Using Breakpoints.
Requirements
Versions: SetOffsetExpression is available in all versions of IDebugBreakpoint. SetOffsetExpressionWide is available in IDebugBreakpoint2 and later versions.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetParameters
The GetParameters method returns the parameters for a breakpoint.
HRESULT
IDebugBreakpoint::GetParameters(
OUT PDEBUG_BREAKPOINT_PARAMETERS
);

Params

Parameters
Params
The breakpoint's parameters. For more information about the parameters, see DEBUG_BREAKPOINT_PARAMETERS.
Return Value
GetParameters might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
The GetParameters method is a convenience method that returns most of the parameters that the other IDebugBreakpoint methods return.
For a list of the parameters and flags that this method retrieves, and for other ways to read and write these parameters and flags, see Controlling Breakpoint Flags and
Parameters and Using Breakpoints.
Requirements
Versions: Available in all versions of IDebugBreakpoint.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetDataParameters
The GetDataParameters method returns the parameters for a processor breakpoint.
HRESULT
IDebugBreakpoint::GetDataParameters(
OUT PULONG Size,
OUT PULONG AccessType
);

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

GetNumberSymbols
GetSymbolOffset
OutputSymbols
GetSymbolParameters
GetSymbolRegister
RemoveSymbolByIndex
RemoveSymbolByName
GetSymbolSize
GetSymbolTypeName
GetSymbolValueText
WriteSymbol
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

OutputAsType
The OutputAsType and OutputAsTypeWide methods change the type of a symbol in a symbol group. The symbol's entry is updated to represent the new type.
HRESULT
IDebugSymbolGroup::OutputAsType(
IN ULONG Index,
IN PCSTR Type
);
HRESULT
IDebugSymbolGroup2::OutputAsTypeWide(
IN ULONG Index,
IN PCWSTR Type
);
#ifdef UNICODE
#define OutputAsTypeT OutputAsTypeWide
#else
#define OutputAsTypeT OutputAsType
#endif
Parameters
Index
The index of the entry in this symbol group. The index of a symbol is an identification number. The index ranges from zero through the number of symbols in the symbol
group minus one.
Type
Tthe name of the type of the symbol that you want. If the name begins with an exclamation mark (!), the name is treated as an extension. For more information about how
to use an extension as a type, see the Comments section.
Return Value
OutputAsType and OutputAsTypeWide might return one of the following values:
S_OK
The method was successful.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
Because the children of the new entry type might differ from the children of the old entry type, the OutputAsType method removes all of the children of the entry from the
symbol group. You can add the children back by using the ExpandSymbol method.
If Type is an extension, the address of the symbol is passed to the extension. Every line of output from the extension becomes a child symbol of the specified symbol. These
child symbols are text and you cannot manipulate them in any way. For example, if the name of a variable is @$teb, you can change its type to !teb.
For more information about symbol groups, see Scopes and Symbol Groups.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Comments
For more information about symbol groups, see Scopes and Symbol Groups.
Requirements
Versions: Available in IDebugSymbolGroup2 and later versions.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.
See Also
GetNumberSymbols, IDebugSymbols::GetTypeName
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetSymbolValueText
The GetSymbolValueText and GetSymbolValueTextWide methods return a string that represents the value of a symbol.
HRESULT
IDebugSymbolGroup2::GetSymbolValueText(
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG NameSize
);
HRESULT
IDebugSymbolGroup2::GetSymbolValueTextWide(
IN ULONG Index,
OUT OPTIONAL PSTR Buffer,
IN ULONG BufferSize,
OUT OPTIONAL PULONG NameSize
);
#ifdef UNICODE
#define GetSymbolValueTextT GetSymbolValueTextWide
#else
#define GetSymbolValueTextT GetSymbolValueText
#endif
Parameters
Index
The index of the symbol whose value you want. The index of a symbol is an identification number. The index ranges from zero through the number of symbols in the
symbol group minus one.
Buffer
The value of the symbol as a string. If Buffer is NULL, this information is not returned.
BufferSize
The size, in characters, of the Buffer buffer.
NameSize
The size, in characters, of the value of the symbol. If NameSize is NULL, this information is not returned.
Return Value
GetSymbolValueText and GetSymbolValueTextWide might return one of the following values:
S_OK
The method was successful.
S_FALSE
The method was successful. However, the value of the symbol would not fit in the Buffer buffer, so a truncated value was returned.
This method might also return error values. For more information about possible return values, see Return Values.
Comments
If you added the symbol to the symbol group by using the AddSymbol method, the string that is returned to Buffer is the name of the symbol that is passed to AddSymbol.
For more information about symbol groups, see Scopes and Symbol Groups.
Requirements
Versions: Available in IDebugSymbolGroup2 and later versions.
Headers: Defined in Dbgeng.h. Include Dbgeng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

DEBUG_ASMOPT_XXX
The assembly and disassembly options affect how the debugger engine assembles and disassembles processor instructions for the target.
The options are represented by a bitset with the following bit flags.
Value
DEBUG_ASMOPT_VERBOSE

Description
When this bit is set, additional information is included in the disassembly.
This is equivalent to the verbose option in the .asm command.

DEBUG_ASMOPT_NO_CODE_BYTES

When this bit is set, the raw bytes for an instruction are not included in the disassembly.
This is equivalent to the no_code_bytes option in the .asm command.

DEBUG_ASMOPT_IGNORE_OUTPUT_WIDTH When this bit is set, the debugger ignores the width of the output display when formatting instructions during
disassembly.
This is equivalent to the ignore_output_width option in the .asm command.
DEBUG_ASMOPT_SOURCE_LINE_NUMBER When this bit is set, each line of the disassembly output is prefixed with the line number of the source code provided by
symbol information.
This is equivalent to the source_line option in the .asm command.

Comments
Additionally, the value DEBUG_ASMOPT_DEFAULT represents the default set of assembly and disassembly options. This means that all the options in the preceding table
are turned off.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also
GetAssemblyOptions, SetAssemblyOptions, AddAssemblyOptions, RemoveAssemblyOptions, Assemble, Disassemble, .asm (Change Disassembly Options)
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_ATTACH_XXX
The DEBUG_ATTACH_XXX bit-flags described in this topic control how the debugger engine attaches to a user-mode process. For the DEBUG_ATTACH_XXX options
used when attaching to a kernel target, see AttachKernel.
The following table describes the possible flag values.
Value
DEBUG_ATTACH_NONINVASIVE

Description
Attach to the target noninvasively. For more information about noninvasive debugging, see Noninvasive
Debugging (User Mode).

If this flag is set, then the flags DEBUG_ATTACH_EXISTING,

DEBUG_ATTACH_INVASIVE_NO_INITIAL_BREAK, and
DEBUG_ATTACH_INVASIVE_RESUME_PROCESS must not be set.
DEBUG_ATTACH_EXISTING

Re-attach to an application to which a debugger has already attached (and possibly abandoned). For more
information about re-attaching to targets, see Re-attaching to the Target Application.

If this flag is set, then the other DEBUG_ATTACH_XXX flags must not be set.
DEBUG_ATTACH_NONINVASIVE_NO_SUSPEND

Do not suspend the target's threads when attaching noninvasively.

If this flag is set, then the flag DEBUG_ATTACH_NONINVASIVE must also be set.
DEBUG_ATTACH_INVASIVE_NO_INITIAL_BREAK (Windows XP and later) Do not request an initial break-in when attaching to the target.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1503 of 1651

If this flag is set, then the flags DEBUG_ATTACH_NONINVASIVE and DEBUG_ATTACH_EXISTING must
not be set.
DEBUG_ATTACH_INVASIVE_RESUME_PROCESS Resume all of the target's threads when attaching invasively.

If this flag is set, then the flags DEBUG_ATTACH_NONINVASIVE and DEBUG_ATTACH_EXISTING must
not be set.

Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_BREAKPOINT_PARAMETERS
The DEBUG_BREAKPOINT_PARAMETERS structure contains most of the parameters for describing a breakpoint.
typedef struct _DEBUG_BREAKPOINT_PARAMETERS {
ULONG64 Offset;
ULONG Id;
ULONG BreakType;
ULONG ProcType;
ULONG Flags;
ULONG DataSize;
ULONG DataAccessType;
ULONG PassCount;
ULONG CurrentPassCount;
ULONG MatchThread;
ULONG CommandSize;
ULONG OffsetExpressionSize;
} DEBUG_BREAKPOINT_PARAMETERS, * PDEBUG_BREAKPOINT_PARAMETERS;
Members
Offset
The location in the target's memory address space that will trigger the breakpoint. If the breakpoint is deferred (see GetFlags), Offset is DEBUG_INVALID_OFFSET.
See GetOffset.
Id
The breakpoint ID. See GetId.
BreakType
Specifies if the breakpoint is a software breakpoint or a processor breakpoint. See GetType.
ProcType
The processor type for which the breakpoint is set. See GetType.
Flags
The flags for the breakpoint. See GetFlags.
DataSize
The size, in bytes, of the memory block whose access will trigger the breakpoint. If the type of the breakpoint is not a data breakpoint, this is zero. See
GetDataParameters.
DataAccessType
The type of access that will trigger the breakpoint. If the type of the breakpoint is not a data breakpoint, this is zero. See GetDataParameters.
PassCount
The number of times the target will hit the breakpoint before it is triggered. See GetPassCount.
CurrentPassCount
The remaining number of times that the target will hit the breakpoint before it is triggered. See GetCurrentPassCount.
MatchThread
The engine thread ID of the thread that can trigger this breakpoint. If any thread can trigger this breakpoint, MatchThread is DEBUG_ANY_ID. See
GetMatchThreadId.
CommandSize
The size, in characters, of the command string that will be executed when the breakpoint is triggered. If no command is set, CommandSize is zero. See GetCommand.
OffsetExpressionSize
The size, in characters, of the expression string that evaluates to the location in the target's memory address space where the breakpoint is triggered. If no expression
string is set, OffsetExpressionSize is zero. See GetOffsetExpression.
Comments
For an overview of how to use breakpoints, and a description of all breakpoint-related methods, see Breakpoints.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1504 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_CREATE_PROCESS_OPTIONS
The DEBUG_CREATE_PROCESS_OPTIONS structure specifies the process creation options to use when creating a new process.
typedef struct _DEBUG_CREATE_PROCESS_OPTIONS
{
ULONG CreateFlags;
ULONG EngCreateFlags;
ULONG VerifierFlags;
ULONG Reserved;
} DEBUG_CREATE_PROCESS_OPTIONS, *PDEBUG_CREATE_PROCESS_OPTIONS;
Members
CreateFlags
The flags to use when creating the process. In addition to the flags described in the "Process Creation Flags" topic in the Platform SDK documentation, the debugger
engine uses the following flags when creating a process.
Values
Description
DEBUG_CREATE_PROCESS_NO_DEBUG_HEAP (Microsoft Windows Server 2003 and later) Prevents the debug heap from being used in the new process.
DEBUG_CREATE_PROCESS_THROUGH_RTL The native NT RTL process creation routines should be used instead of Win32. This is only meaningful for
special processes that run as NT native processes. No Win32 process can be created with this flag.
When creating and attaching to a process through the debugger engine, set one of the Platform SDK's process creation flags: DEBUG_PROCESS or
DEBUG_ONLY_THIS_PROCESS.
EngCreateFlags
The engine specific flags used when creating the process. EngCreateFlags is a combination of the following bit-flags:
Value
Description
DEBUG_ECREATE_PROCESS_INHERIT_HANDLES
The new process will inherit system handles from the debugger or process server.
DEBUG_ECREATE_PROCESS_USE_VERIFIER_FLAGS
(Windows Vista and later) Use Application Verifier flags in the VerifierFlags field.
DEBUG_ECREATE_PROCESS_USE_IMPLICIT_COMMAND_LINE Use the debugger's or process server's implicit command line to start the process instead of a
supplied command line.
VerifierFlags
The Application Verifier flags. Only used if DEBUG_ECREATE_PROCESS_USE_VERIFIER_FLAGS is set in the EngCreateFlags field. For possible values, see the
Application Verifier documentation.
Reserved
Set to zero.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_DUMP_XXX
The DEBUG_DUMP_XXX constants are used by the methods WriteDumpFile, WriteDumpFile2, and WriteDumpFileWide to specify the type of crash dump file to create.
The possible values include the following.
Value
Type of Dump File Created
DEBUG_DUMP_SMALL Small Memory Dump (kernel-mode) or Minidump (user-mode).
DEBUG_DUMP_DEFAULT Full User-Mode Dump (user-mode) or Kernel Summary Dump (kernel-mode).
DEBUG_DUMP_FULL
(kernel-mode only) Complete Memory Dump.
Moreover, the following aliases are available for kernel-mode debugging.
Alias
Value
DEBUG_KERNEL_SMALL_DUMP DEBUG_DUMP_SMALL
DEBUG_KERNEL_DUMP
DEBUG_DUMP_DEFAULT
DEBUG_KERNEL_FULL_DUMP DEBUG_DUMP_FULL
Additionally, the following aliases are available for user-mode debugging.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1505 of 1651

Alias
Value
DEBUG_USER_WINDOWS_SMALL_DUMP DEBUG_DUMP_SMALL
DEBUG_USER_WINDOWS_DUMP
DEBUG_DUMP_DEFAULT
Comments
For a description of kernel-mode dump files, see Varieties of Kernel-Mode Dump Files. For a description of user-mode dump files, see Varieties of User-Mode Dump Files.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_ENGOPT_XXX
The following global options affect the behavior of the debugger engine.
Value
DEBUG_ENGOPT_IGNORE_DBGHELP_VERSION
DEBUG_ENGOPT_IGNORE_EXTENSION_VERSIONS
DEBUG_ENGOPT_ALLOW_NETWORK_PATHS

Effect when set

The debugger engine generates a warning instead of an error if the version of the DbgHelp DLL does not
match the version of the debugger engine.
Disable version checking for extensions. This suppresses the debugger engine's call to CheckVersion.
Network shares can be used for loading symbols and extensions. This option prevents the engine from
disallowing network paths when debugging some system processes and should be used with caution.
This option cannot be set if DEBUG_ENGOPT_DISALLOW_NETWORK_PATHS is set.

DEBUG_ENGOPT_DISALLOW_NETWORK_PATHS

Network shares cannot be used for loading symbols and extensions. The engine attempts to set this option
when debugging some system processes.
This option cannot be set if DEBUG_ENGOPT_ALLOW_NETWORK_PATHS is set.

DEBUG_ENGOPT_IGNORE_LOADER_EXCEPTIONS

Ignore expected first-chance exceptions that are generated by the loader in certain versions of Windows.
For example, this option allows Windows 3.51 binaries to run when debugging Windows 3.1 and 3.5
systems.

DEBUG_ENGOPT_INITIAL_BREAK
DEBUG_ENGOPT_INITIAL_MODULE_BREAK
DEBUG_ENGOPT_FINAL_BREAK
DEBUG_ENGOPT_NO_EXECUTE_REPEAT
DEBUG_ENGOPT_FAIL_INCOMPLETE_INFORMATION

Break into the debugger at the target's initial event.

Break into the debugger when the target loads its first module.
Break into the debugger at the target's final event. In a live user-mode target, this is when the process exits.
It has no effect in kernel mode.
When given an empty command, the debugger engine does not repeat the last command.
Prevent the debugger from loading modules whose images cannot be mapped.
The debugger attempts to load images when debugging minidumps that do not contain images.

DEBUG_ENGOPT_ALLOW_READ_ONLY_BREAKPOINTS Allow the debugger engine to manipulate page protections on the target to allow for setting software
breakpoints in a read-only section of memory.
When setting software breakpoints, the engine transparently alters the target's memory to insert an interrupt
instruction.
DEBUG_ENGOPT_SYNCHRONIZE_BREAKPOINTS

In live user-mode debugging, the engine performs extra work when inserting and removing breakpoints to
ensure that all threads in the target have a consistent breakpoint state at all times.
This option is useful when multiple threads can use the code for which the breakpoint is set. However, it can
introduce the possibility of deadlocks.

DEBUG_ENGOPT_DISALLOW_SHELL_COMMANDS

Disallow executing shell commands through the debugger.

After this option has been set, it cannot be unset.

Turn on quiet mode. For more information, see sq (Set Quiet Mode).
Disables debugger engine support for managed code. If support for managed code is already in use, this
option has no effect.
DEBUG_ENGOPT_DISABLE_MODULE_SYMBOL_LOAD The debugger does not load symbols for modules that are loaded while this flag is set.
DEBUG_ENGOPT_DISABLE_EXECUTION_COMMANDS Prevents any commands that would cause the target to begin executing.
DEBUG_ENGOPT_KD_QUIET_MODE
DEBUG_ENGOPT_DISABLE_MANAGED_SUPPORT

Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
See Also

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1506 of 1651

AddEngineOptions, GetEngineOptions, RemoveEngineOptions, SetEngineOptions

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_OUTCTL_XXX

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1511 of 1651

The DEBUG_OUTCTL_XXX constants are used for output control. The constants form a bit field that specifies the current policy of where to send output. The bit field is
divided into two sections.
The lower bits must be exactly one of the following values.
Value
Description
DEBUG_OUTCTL_THIS_CLIENT
Output generated by methods called by this client will be sent only to this client's output callbacks.
DEBUG_OUTCTL_ALL_CLIENTS
Output will be sent to all clients.
DEBUG_OUTCTL_ALL_OTHER_CLIENTS Output will be sent to all clients (except to the client that generated the output).
DEBUG_OUTCTL_IGNORE
Output will be discarded immediately and will not be logged or sent to callbacks.
DEBUG_OUTCTL_LOG_ONLY
Output will be logged but not sent to callbacks.
The higher bits of the bit field may contain the following values:
Value
Description
DEBUG_OUTCTL_NOT_LOGGED
Do not place output from this client in the global log file.
DEBUG_OUTCTL_OVERRIDE_MASK Send output to clients regardless of whether the client's output mask allows it or not.
To create a valid output control bit-field, take exactly one value from the first table, along with zero, one, or more values from the second table, and combine them using the
bitwise-OR operator. Alternatively, when setting the output control, the value DEBUG_OUTCTL_AMBIENT can be used to set the new output control to the same value as
the current output control.
The default value of the output control bit-field is DEBUG_OUTCTL_ALL_CLIENTS.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_OUTPUT_XXX
The DEBUG_OUTPUT_XXX constants are output flags. The output flags form a bit field that indicates the type of the output that accompanies them.
The possible values include the following.
Value
Description
DEBUG_OUTPUT_NORMAL
Normal output.
DEBUG_OUTPUT_ERROR
Error output.
DEBUG_OUTPUT_WARNING
Warnings.
DEBUG_OUTPUT_VERBOSE
Additional output.
DEBUG_OUTPUT_PROMPT
Prompt output.
DEBUG_OUTPUT_PROMPT_REGISTERS Register dump before prompt.
DEBUG_OUTPUT_EXTENSION_WARNING Warnings specific to extension operation.
DEBUG_OUTPUT_DEBUGGEE
Debug output from the target (for example, OutputDebugString or DbgPrint).
DEBUG_OUTPUT_DEBUGGEE_PROMPT Debug input expected by the target (for example, DbgPrompt).
DEBUG_OUTPUT_SYMBOLS
Symbol messages (for example, !sym noisy).
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DEBUG_STATUS_XXX
The DEBUG_STATUS_XXX status codes have two purposes. They instruct the engine on how execution in the target should proceed, and they are used by the engine to
report the execution status of the target.
After an event occurs, the engine can receive several instructions that tell it how execution in the target should proceed. In this case, it acts on the instruction with the highest
precedence. Typically, the higher precedence status codes represent less execution for the target.
The values in the following table are reverse ordered by precedence; the values that appear earlier in the table have higher precedence.
Status Code
DEBUG_STATUS_NO_DEBUGGEE
DEBUG_STATUS_BREAK

When reporting
No debugging session is active.
The target is suspended.

DEBUG_STATUS_STEP_INTO

The target is executing a single

instruction.
DEBUG_STATUS_STEP_BRANCH
The target is executing until the next
branch instruction.
DEBUG_STATUS_STEP_OVER
The target is executing a single
instruction orif that instruction is a
subroutine callsubroutine.
DEBUG_STATUS_GO_NOT_HANDLED
N/A
DEBUG_STATUS_GO_HANDLED
N/A
DEBUG_STATUS_GO
The target is executing normally.
DEBUG_STATUS_IGNORE_EVENT
N/A
DEBUG_STATUS_RESTART_REQUESTED The target is restarting.
DEBUG_STATUS_NO_CHANGE
N/A

When instructing
N/A
Suspend the target.

Precedence
Highest
precedence

Continue execution of the target for a single instruction.

Continue execution of the target until the next branch instruction.
Continue execution of the target for a single instruction. If the
instruction is a subroutine call, the call is entered and the target is
allowed to run until the subroutine returns.
Continue execution of the target, flagging the event as not handled.
Continue execution of the target, flagging the event as handled.
Continue normal execution of the target.
Continue previous execution of the target, ignoring the event.
Restart the target.
No instruction. This value is returned by an event callback method Lowest
precedence
when it does not wish to instruct the engine how to proceed with
execution in the target.

9/18/2010

Introduction

Page 1520 of 1651

UCHAR F128Bytes[16];
UCHAR VI8[16];
USHORT VI16[8];
ULONG VI32[4];
ULONG64 VI64[2];
float VF32[4];
double VF64[2];
struct {
ULONG LowPart;
ULONG HighPart;
} I64Parts32;
struct {
ULONG64 LowPart;
LONG64 HighPart;
} F128Parts64;
UCHAR RawBytes[24];
};
...
ULONG Type;
} DEBUG_VALUE, *PDEBUG_VALUE;
The Type field specifies the value type that is being held by the structure. This also specifies which field in the structure is valid. The possible values of the Type field, and
the corresponding field specified as valid in the structure, include the following.
Type Name
Type
Valid DEBUG_VALUE Field
DEBUG_VALUE_INT8
8-bit signed integer
I8
DEBUG_VALUE_INT16
16-bit signed integer
I16
DEBUG_VALUE_INT32
32-bit signed integer
I32
DEBUG_VALUE_INT64
64-bit signed integer
I64
DEBUG_VALUE_FLOAT32
32-bit floating point number F32
DEBUG_VALUE_FLOAT64
64-bit floating point number F64
DEBUG_VALUE_FLOAT80
80-bit floating point number F80Bytes
DEBUG_VALUE_FLOAT128 128-bit floating point number F128Bytes
DEBUG_VALUE_VECTOR64 64-bit vector
VI8[8], VI16[4], VI32[2], VI64[1], VF32[2], VF64[1]
DEBUG_VALUE_VECTOR128 128-bit vector
VI8[16], VI16[8], VI32[4], VI64[2], VF32[4], VF64[2]
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TDOP
The EXT_TDOP enumeration is used in the Operation member of the EXT_TYPED_DATA structure to specify which suboperation the
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation will perform.
typedef enum _EXT_TDOP {
EXT_TDOP_COPY,
EXT_TDOP_RELEASE,
EXT_TDOP_SET_FROM_EXPR,
EXT_TDOP_SET_FROM_U64_EXPR,
EXT_TDOP_GET_FIELD,
EXT_TDOP_EVALUATE,
EXT_TDOP_GET_TYPE_NAME,
EXT_TDOP_OUTPUT_TYPE_NAME,
EXT_TDOP_OUTPUT_SIMPLE_VALUE,
EXT_TDOP_OUTPUT_FULL_VALUE,
EXT_TDOP_HAS_FIELD,
EXT_TDOP_GET_FIELD_OFFSET,
EXT_TDOP_GET_ARRAY_ELEMENT,
EXT_TDOP_GET_DEREFERENCE,
EXT_TDOP_GET_TYPE_SIZE,
EXT_TDOP_OUTPUT_TYPE_DEFINITION,
EXT_TDOP_GET_POINTER_TO,
EXT_TDOP_SET_FROM_TYPE_ID_AND_U64,
EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64,
EXT_TDOP_COUNT
} EXT_TDOP;
Values
Value

Operation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1521 of 1651

EXT_TDOP_COPY
Makes a copy of a typed data description.
EXT_TDOP_RELEASE
Releases a typed data description.
EXT_TDOP_SET_FROM_EXPR
Returns the value of an expression.
EXT_TDOP_SET_FROM_U64_EXPR
Returns the value of an expression. An optional address can be provided as a parameter to the expression.
EXT_TDOP_GET_FIELD
Returns a member of a structure.
EXT_TDOP_EVALUATE
Returns the value of an expression. An optional value can be provided as a parameter to the expression.
EXT_TDOP_GET_TYPE_NAME
Returns the type name for typed data.
EXT_TDOP_OUTPUT_TYPE_NAME
Prints the type name for typed data.
EXT_TDOP_OUTPUT_SIMPLE_VALUE
Prints the value of typed data.
EXT_TDOP_OUTPUT_FULL_VALUE
Prints the type and value for typed data.
EXT_TDOP_HAS_FIELD
Determines whether a structure contains a specified member.
EXT_TDOP_GET_FIELD_OFFSET
Returns the offset of a member within a structure.
EXT_TDOP_GET_ARRAY_ELEMENT
Returns an element from an array.
EXT_TDOP_GET_DEREFERENCE
Dereferences a pointer, returning the value it points to.
EXT_TDOP_GET_TYPE_SIZE
Returns the size of the specified typed data.
EXT_TDOP_OUTPUT_TYPE_DEFINITION
Prints the definition of the type for the specified typed data.
EXT_TDOP_GET_POINTER_TO
Returns a new typed data description that represents a pointer to specified typed data.
EXT_TDOP_SET_FROM_TYPE_ID_AND_U64
Creates a typed data description from a type and memory location.
EXT_TDOP_SET_PTR_FROM_TYPE_ID_AND_U64 Creates a typed data description representing a pointer to a specified memory location with specified type.
The remaining value, EXT_TDOP_COUNT, does not specify an operation. Instead, it represents the number of suboperations defined in the EXT_TDOP enumeration.
Requirements
Headers: Defined in WbgExts.h. Include WdbgExts.h before including DbgEng.h.
See Also
EXT_TYPED_DATA, DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, Request
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

EXT_TYPED_DATA
The EXT_TYPED_DATA structure is passed to and returned from the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation. It contains the input and output
parameters for the operation as well as specifying which particular suboperation to perform.
typedef struct _EXT_TYPED_DATA {
IN EXT_TDOP Operation;
IN ULONG Flags;
IN DEBUG_TYPED_DATA InData;
OUT DEBUG_TYPED_DATA OutData;
IN ULONG InStrIndex;
IN ULONG In32;
OUT ULONG Out32;
IN ULONG64 In64;
OUT ULONG64 Out64;
OUT ULONG StrBufferIndex;
IN ULONG StrBufferChars;
OUT ULONG StrCharsNeeded;
IN OUT ULONG DataBufferIndex;
IN ULONG DataBufferBytes;
OUT ULONG DataBytesNeeded;
OUT HRESULT Status;
ULONG64 Reserved[8];
} EXT_TYPED_DATA, *PEXT_TYPED_DATA;
Members
Operation
Specifies which suboperation the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation should perform. The interpretation of some of the other
members depends on Operation. For a list of possible suboperations, see EXT_TDOP.
Flags
Specifies the bit flags describing the target's memory in which the data resides. If no flags are present, the data is considered to be in virtual memory. One of the
following flags may be present:
Flag
Description
EXT_TDF_PHYSICAL_DEFAULT
The typed data is in physical memory, and this physical memory uses the default memory caching.
EXT_TDF_PHYSICAL_CACHED
The typed data is in physical memory, and this physical memory is cached.
EXT_TDF_PHYSICAL_UNCACHED
The typed data is in physical memory, and this physical memory is uncached.
EXT_TDF_PHYSICAL_WRITE_COMBINED The typed data is in physical memory, and this physical memory is write-combined.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1522 of 1651

InData
Specifies typed data to be used as input to the operation. For details about this structure, see DEBUG_TYPED_DATA.
The interpretation of InData depends on the value of Operation.
OutData
Receives typed data as output from the operation. Any suboperation that returns typed data to OutData initially copies the contents of InData to OutData, then modifies
OutData in place, so that the input parameters in InData are also present in OutData. For details about this structure, see DEBUG_TYPED_DATA.
The interpretation of OutData depends on the value of Operation.
InStrIndex
Specifies the position of an ANSI string to be used as input to the operation. InStrIndex can be zero to indicate that the input parameters do not include an ANSI string.
The position of the string is relative to the base address of this EXT_TYPED_DATA structure. The string must follow this structure, so InStrIndex must be greater than
the size of this structure. The string is part of the input to the operation and InStrIndex must be smaller than InBufferSize, the size of the input buffer passed to Request.
The interpretation of the string depends on the value of Operation.
In32
Specifies a 32-bit parameter to be used as input to the operation.
The interpretation of In32 depends on the value of Operation.
Out32
Receives a 32-bit value as output from the operation.
The interpretation of Out32 depends on the value of Operation.
In64
Specifies a 64-bit parameter to be used as input to the operation.
The interpretation of In64 depends on the value of Operation.
Out64
Receives a 64-bit value as output from the operation.
The interpretation of Out64 depends on the value of Operation.
StrBufferIndex
Specifies the position to return an ANSI string as output from the operation. StrBufferIndex can be zero if no ANSI string is to be received from the operation.
The position of the string is relative to the base address of the returned EXT_TYPED_DATA structure. The string must follow the structure, so StrBufferIndex must be
greater than the size of this structure. The string is part of the output from the suboperation, and StrBufferIndex plus StrBufferChars must be smaller than
OutBufferSize, the size of the output buffer passed to Request.
The interpretation of the string depends on the value of Operation.
StrBufferChars
Specifies the size in characters of the ANSI string buffer specified by StrBufferIndex.
StrCharsNeeded
Receives the number of characters needed by the string buffer specified by StrBufferIndex.
DataBufferIndex
Set to zero.
DataBufferBytes
Set to zero.
DataBytesNeeded
Set to zero,
Status
Receives the status code returned by the operation. This is the same value returned by Request.
Reserved
Set to zero.
Comments
The members of this structure are used as the input and output parameters to the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation. The interpretation of
most of the parameters depends on the particular suboperation being performed, as specified by the Operation member.
This structure can optionally specify additional datausing the members InStrIndex and StrBufferIndexthat is included with the structure. This additional data is
specified relative to the address of the instance of this structure. When used with the DEBUG_REQUEST_EXT_TYPED_DATA_ANSI Request operation, the additional
data is included in the InBuffer and OutBuffer (as appropriate) and should be included in the size of these two buffers.
Requirements
Headers: Defined in WbgExts.h. Include WdbgExts.h before including DbgEng.h.
See Also
DEBUG_REQUEST_EXT_TYPED_DATA_ANSI, Request, DEBUG_TYPED_DATA, EXT_TDOP
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1523 of 1651

December 09, 2009

Debugging Tools for Windows

HRESULT Values
The following is a list of common return values for functions and methods, and their usual meanings.
Successful results. These values are defined in WinError.h.
S_OK
Successful completion.
S_FALSE
Completed without error, but only partial results were obtained.
If a buffer is not large enough to hold the information that is returned to it, the returned information is often truncated to fit into the buffer and S_FALSE is returned from
the method.
Error results. These values are defined in WinError.h.
E_FAIL
The operation could not be performed.
E_INVALIDARG
One of the arguments passed in was invalid.
E_NOINTERFACE
The object searched for was not found.
E_OUTOFMEMORY
A memory allocation attempt failed.
E_UNEXPECTED
The target was not accessible, or the engine was not in a state where the function or method could be processed.
E_NOTIMPL
Not implemented.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)
The operation was denied because the debugger is in Secure Mode.
NT error results. Other error codes, such as STATUS_CONTROL_C_EXIT and STATUS_NO_MORE_ENTRIES, can sometimes occur. These results are passed to the
HRESULT_FROM_NT macro that is defined in WinError.h before being returned.
Win32 error results. Other error codes, such as ERROR_READ_FAULT and ERROR_WRITE_FAULT, can sometimes occur. These results are passed to the
HRESULT_FROM_WIN32 macro that is defined in WinError.h before being returned.
Requirements
Headers: Defined in DbgEng.h. Include DbgEng.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Specific Exceptions
The following table lists the exception codes for the specific exception filters.
Exception Code
Exception
Header file or value
STATUS_ACCESS_VIOLATION
Access violation
NtStatus.h
STATUS_ASSERTION_FAILURE
Assertion failure
NtStatus.h
STATUS_APPLICATION_HANG
Application hang
0xCFFFFFFF
STATUS_BREAKPOINT
Break instruction exception
NtStatus.h
STATUS_CPP_EH_EXCEPTION
C++ exception handling exception
0xE06D7363
STATUS_CLR_EXCEPTION
Common language runtime (CLR) exception 0xE0434f4D
DBG_CONTROL_BREAK
CTRL+Break exception
NtStatus.h
DBG_CONTROL_C
CTRL+C exception
NtStatus.h
STATUS_DATATYPE_MISALIGNMENT Data misaligned
NtStatus.h
DBG_COMMAND_EXCEPTION
Debugger command exception
NtStatus.h
STATUS_GUARD_PAGE_VIOLATION Guard page violation
NtStatus.h
STATUS_ILLEGAL_INSTRUCTION
Illegal instruction
NtStatus.h
STATUS_IN_PAGE_ERROR
In-page I/O error
NtStatus.h
STATUS_INTEGER_DIVIDE_BY_ZERO Integer divide-by-zero
NtStatus.h
STATUS_INTEGER_OVERFLOW
Integer overflow
NtStatus.h
STATUS_INVALID_HANDLE
Invalid handle
NtStatus.h
STATUS_INVALID_LOCK_SEQUENCE Invalid lock sequence
NtStatus.h
STATUS_INVALID_SYSTEM_SERVICE Invalid system call
NtStatus.h
STATUS_PORT_DISCONNECTED
Port disconnected
NtStatus.h

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

STATUS_SINGLE_STEP
STATUS_STACK_BUFFER_OVERRUN
STATUS_STACK_OVERFLOW
STATUS_VERIFIER_STOP
STATUS_WAKE_SYSTEM_DEBUGGER

Page 1524 of 1651

Single-step exception
Stack buffer overflow
Stack overflow
Application Verifier stop
Wake debugger

NtStatus.h
NtStatus.h
NtStatus.h
NtStatus.h
NtStatus.h

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Writing DbgEng Extensions

This section includes:
DbgEng Extension Design Guide
DbgEng Extension Reference
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DbgEng Extension Design Guide

This section includes:
Anatomy of a DbgEng Extension DLL
Using Clients and the Engine
Writing DbgEng Extension Code
Building DbgEng Extensions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Anatomy of a DbgEng Extension DLL

A DbgEng extension DLL exports a number of callback functions, some of which may be implementations of extension commands.
These extension DLLs are loaded by the debugger engine and can provide extra functionality or automation of tasks while performing user-mode or kernel-mode debugging
on Microsoft Windows.
If you performed a full install of Debugging Tools for Windows, a sample DbgEng extension called "exts" can be found in the sdk\samples\exts subdirectory of the
installation directory.
Extension Commands
An extension DLL may export any number of functions that are used to execute extension commands. Each function is explicitly declared as an export in the .def file, and its
name must consist entirely of lowercase letters.
Functions used to implement extension commands must match the prototype PDEBUG_EXTENSION_CALL.
These functions are named according to the standard C++ convention, except that uppercase letters are not permitted. The exported function name and the extension command
name are identical, except that the extension command begins with an exclamation point ( ! ). For example, when you load myextension.dll into the debugger and then type !
stack into the Debugger Command window, the debugger looks for an exported function named stack in myextension.dll.
If myextension.dll is not already loaded, or if there may be other extension commands with the same name in other extension DLLs, you can type !myextension.stack into the
Debugger Command window to indicate the extension DLL and the extension command in that DLL.
Other Exported Functions
A DbgEng extension DLL must export DebugExtensionInitialize. This will be called when the DLL is loaded, to initialize the DLL. It may be used by the DLL to initialize
global variables.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1525 of 1651

An extension DLL may export DebugExtensionUninitialize. If this is exported, it will be called before the extension DLL is unloaded. It may be used by the DLL to clean up
before it is unloaded.
An extension DLL may export DebugExtensionNotify. If this is exported, it will be called when a session begins or ends, and when a target starts or stops executing. These
notifications are also provided to IDebugEventCallbacks objects registered with a client.
An extension DLL may export KnownStructOutput. If this is exported, it will be called when the DLL is loaded. This function returns a list of structures that the DLL
knows how to print on a single line. It may be called later to format instances of these structures for printing.
Engine Procedure for Loading a DbgEng Extension DLL
When an extension DLL is loaded, the callback functions are called by the engine in the following order:
1. DebugExtensionInitialize is called so the extension DLL can initialize.
2. If exported, DebugExtensionNotify is called if the engine has an active session, and called again if the session is suspended and accessible.
3. If exported, KnownStructOutput is called to request a list of structures the DLL knows how to print on a single line.
See Loading Debugger Extension DLLs for information about how to use the debugger to load and unload an extension DLL, and see Using Debugger Extension Commands
for information about executing an extension command.
The debugger engine will place a try / except block around a call to an extension DLL. This protects the engine from some types of bugs in the extension code; but, since the
extension calls are executed in the same thread as the engine, they can still cause it to crash.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using Clients and the Engine

A DbgEng extension interacts with the debugger engine through a client object.
When an extension function is called, it is passed a client. The extension function should use this client for all its interaction with the debugger engine, unless it has a specific
reason to use another client.
An extension library may create its own client object upon initialization by using DebugCreate. This client can be used to register callback objects from the DLL.
Note Care should be taken when modifying the client passed to an extension function. In particular, registering callbacks with this client could disrupt the input, output, or
event handling of the debugger. It is recommended that a new client be created to register callbacks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Writing DbgEng Extension Code

DbgEng extension commands can include any standard C++ code. They can also include the C++ interfaces that appear in the dbgeng.h header file, in addition to the C
functions that appear in the wdbgexts.h header file.
If you intend to use functions from wdbgexts.h, you need to define KDEXT_64BIT before wdbgexts.h is included. For example:
#define KDEXT_64BIT
#include wdbgexts.h
#include dbgeng.h
For a full list of interfaces in dbgeng.h that can be used in an extension command, see Debugger Engine Reference.
For a full list of functions in wdbgexts.h that can be used in an extension command, see WdbgExts Functions. A number of these functions appear in 32-bit versions and 64-bit
versions. Typically, the 64-bit versions end in "64" and the 32-bit versions have no numerical ending for example, ReadIoSpace64 and ReadIoSpace. When calling a
wdbgexts.h function from a DbgEng extension, you should always use the function name ending in "64". This is because the debugger engine always uses 64-bit pointers
internally, regardless of the target platform.
If you include wdbgexts.h in your DbgEng extension, you should call GetWindbgExtensionApis64 during the initialization of your extension DLL (see
DebugExtensionInitialize).
Note You must not attempt to call any DbgHelp or ImageHlp routines from any debugger extension. Calling these routines is not supported and may cause a variety of
problems.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1526 of 1651

Debugging Tools for Windows

Building DbgEng Extensions

All debugger extensions should be compiled and built by using the Build utility. The Build utility is included in the Windows Driver Kit (WDK), as well as earlier versions of
the Windows DDK.
For documentation on the Build utility, open the WDK documentation, select the Index tab, and type Build utility.
Note the following points:

The WDK has several different build environment windows. Each of these has a corresponding shortcut placed in the Start menu when the WDK is installed. To build
a debugger extension, you must use the Windows Server 2003 build environment regardless of what platform you will be running the extension on.
The Build utility is usually not able to compile code that is located in a directory path containing spaces. Your extension code should be located in a directory whose
full path contains no spaces. (In particular, this means that if you install Debugging Tools for Windows to the default location Program Files\Debugging Tools for
Windows you will not be able to build the sample extensions.)

To build an extension, use the following procedure:

To build a debugger extension
1. Open the Windows 2003 Server Build Environment window. (You can choose either the "free" version or the "checked" version they will give identical results
unless you have put #ifdef DBG statements in your code, because DBG is set to TRUE in the checked build environments.)
2. Set the %DBGSDK_INC_PATH% and %DBGSDK_LIB_PATH% environment variables to specify the paths to the debugger SDK headers and the debugger SDK
libraries, respectively. If %debuggers% represents the root of your Debugging Tools for Windows installation, these variables should be set as follows:
set DBGSDK_INC_PATH=%debuggers%\sdk\inc
set DBGSDK_LIB_PATH=%debuggers%\sdk\lib
If you have moved these headers and libraries to a different location, specify that location instead.
3. Change the current directory to the directory containing your extension's dirs file or sources file.
4. Run the Build utility:
build -cZMg
For a full explanation of these steps, and for a description of how to create a dirs file and a sources file, see the Build utility documentation in the WDK.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DbgEng Extension Reference

This section includes:
Extension Callback Functions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Extension Callback Functions

This section includes:
DebugExtensionInitialize
DebugExtensionNotify
DebugExtensionUninitialize
KnownStructOutput
PDEBUG_EXTENSION_CALL
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1527 of 1651

Debugging Tools for Windows

DebugExtensionInitialize
The DebugExtensionInitialize callback function is called by the engine after loading a DbgEng extension DLL.
HRESULT
CALLBACK
DebugExtensionInitialize(
OUT PULONG Version,
OUT PULONG Flags
);
Parameters
Version
Receives the version of the extension. The high 16 bits contain the major version number, and the low 16 bits contain the minor version number.
Flags
Set this to zero. (Reserved for future use.)
Return Value
S_OK
The extension was successfully initialized.
Any other value indicates that the extension DLL was unable to initialize and the engine will unload it.
Comments
The engine looks for this function by name in each extension DLL. This function must be exported by a DbgEng extension DLL.
The version number can be set by using the macro DEBUG_EXTENSION_VERSION found in dbgeng.h, for example:
*Version = DEBUG_EXTENSION_VERSION(Major, Minor)
Implementations of this function should initialize any global variables required by the extension DLL.
There may or may not be a session active when this function is called, so the extension should not assume that it is able to query session information.
Requirements
Headers: The function type is defined as PDEBUG_EXTENSION_INITIALIZE in dbgeng.h.
See Also
DebugExtensionUninitialize, DebugExtensionNotify, KnownStructOutput
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugExtensionNotify
The engine calls the DebugExtensionNotify callback function to inform the extension DLL when a session changes its active or accessible status.
void
CALLBACK
DebugExtensionNotify(
IN ULONG Notify,
IN ULONG64 Argument
);
Parameters
Notify
Can be any of the following values:
Value
Description
DEBUG_NOTIFY_SESSION_ACTIVE
A debugging session is active. The session may not necessarily be suspended.
DEBUG_NOTIFY_SESSION_INACTIVE
No debugging session is active.
DEBUG_NOTIFY_SESSION_ACCESSIBLE The debugging session has suspended and is now accessible.
DEBUG_NOTIFY_SESSION_INACCESSIBLE The debugging session has started running and is now inaccessible.
Argument
Set to zero. (Reserved for future use.)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1528 of 1651

Return Value
None
Comments
This function is optional. A DbgEng extension DLL only needs to export DebugExtensionNotify if it wants to be notified when the session state changes. The engine looks
for this function by name in the extension DLL.
This function allows the extension DLL to cache information about the session without needing to register explicit callbacks. It is called at the beginning and end of a session,
and each time a target starts or stops executing.
After the extension DLL is initialized, the engine will use this function to notify the DLL if it has started a session. If the current session is suspended, the engine will call this
function a second time to notify the DLL that the session is accessible.
Requirements
Headers: The function type is defined as PDEBUG_EXTENSION_NOTIFY in dbgeng.h.
See Also
DebugExtensionInitialize
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugExtensionProvideValue
The DebugExtensionProvideValue function sets pseudo-register values.
HRESULT CALLBACK
DebugExtensionProvideValue (
__in PDEBUG_CLIENT Client,
__in ULONG Flags,
__in PCWSTR Name,
__out PULONG64 Value,
__out PULONG64 TypeModBase,
__out PULONG TypeId,
__out PULONG TypeFlags
);
Parameters
Client
A client to use if the extension needs DbgEng functions.
Flags
Provides behavioral flags. This parameter is currently reserved.
Name
The name of the value to return. This name might be one of the names that the DebugExtensionQueryValueNames function returned or a name that the caller might
already be aware of.
Value
A pointer to the value to be set.
TypeModBase
The base starting address for Client.
TypeId
A pointer to the ID for the type of Value.
TypeFlags
A parameter that you can use to return one of the following flags:
DEBUG_EXT_PVTYPE_IS_VALUE
The value that is pointed to by Value is not a pointer.
DEBUG_EXT_PVTYPE_IS_POINTER
The value that is pointed to by Value is an address for a pointer to data of the type that TypeModBase and TypeId specify.
Return Value
DebugExtensionProvideValue might return one of the following values:
S_OK
The function was successfully completed.
This function might also return error values. For more information about possible return values, see Return Values.
Comments
The name that the Name parameter specifies must start with $$ and have a terminating NULL character.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1529 of 1651

Headers: The Dbgeng.h header file has the definitions of the callback prototypes.
See Also
DebugExtensionInitialize, DebugExtensionNotify, DebugExtensionQueryValueNames, DebugExtensionUninitialize, KnownStructOutput
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugExtensionQueryValueNames
The DebugExtensionQueryValueNames callback function recovers pseudo-register values.
HRESULT CALLBACK
DebugExtensionQueryValueNames (
__in PDEBUG_CLIENT Client,
__in ULONG Flags,
__out_ecount(BufferChars) PWSTR
__in ULONG BufferChars,
__out PULONG BufferNeeded
);

Buffer,

Parameters
Client
A client to use if the extension needs DbgEng functions.
Flags
Provides behavioral flags. This parameter is currently reserved.
Buffer
A string buffer that the caller provides, to be filled with the set of value names that the client wants to expose.
BufferChars
The count of wide characters in Buffer.
BufferNeeded
The number of wide characters that this function needs to complete successfully.
Return Value
DebugExtensionQueryValueNames might return one of the following values:
S_OK
The function was successfully completed.
S_FALSE
The function completed without error, but it obtained only partial results.
This function might also return error values. For more information about possible return values, see Return Values.
Comments
Value names must start with $$ and have a terminating NULL character. The Buffer string must also be NULL-terminated. For example, Buffer could be $$myval1\0
$$myval2\0\0.
Requirements
Headers: The Dbgeng.h header file has the definitions of the callback prototypes.
See Also
DebugExtensionInitialize, DebugExtensionNotify, DebugExtensionProvideValue, DebugExtensionUninitialize, KnownStructOutput
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

DebugExtensionUninitialize
The DebugExtensionUninitialize callback function is called by the engine to uninitialize the DbgEng extension DLL before it is unloaded.
void

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1530 of 1651

CALLBACK
DebugExtensionUninitialize(
void
);
Parameters
None
Return Value
None
Comments
This function is optional. A DbgEng extension DLL only needs to export DebugExtensionUninitialize if it needs to be notified before it is unloaded. The engine looks for
this function by name in the extension DLL.
This function can be used by the extension DLL to clean up before it is unloaded.
There may or may not be a session active when this function is called, so the extension should not assume that it is able to query session information.
Requirements
Headers: The function type is defined as PDEBUG_EXTENSION_UNINITIALIZE in dbgeng.h.
See Also
DebugExtensionInitialize
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

KnownStructOutput
The engine calls the KnownStructOutput callback function once after the DLL is initialized to obtain a list of structures the DLL can print, and again each time the engine
wants to print a summary of one of these structures.
HRESULT
CALLBACK
KnownStructOutput (
IN ULONG Flag,
IN ULONG64 Address,
IN PSTR StructName,
OUT PSTR Buffer,
IN OUT PULONG BufferSize
);
Parameters
Flag
Can be either of the following values, depending on which action the engine wants the function to perform.
Value
Description
DEBUG_KNOWN_STRUCT_GET_NAMES
Get a list of names of known structures.
DEBUG_KNOWN_STRUCT_GET_SINGLE_LINE_OUTPUT Format a structure for printing on a single line.
Address
When getting names: Unused.
When printing a structure: Specifies the location in the target's memory address space of the structure to be printed.
StructName
When getting names: Unused.
When printing a structure: Specifies the name of the structure to be printed. This is one of the names returned from the DEBUG_KNOWN_STRUCT_GET_NAMES
query.
Buffer
When getting names: Receives a list of the names of each structure that the extension knows how to print. One null character must appear between each pair of names.
The list must be terminated with two null characters.
When printing a structure: Receives a representation of the structure, identified by StructName and Address, as a string.
In each case, the number of characters written to this buffer must not exceed the value of BufferSize.
BufferSize

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1531 of 1651

Specifies the size in characters of the buffer Buffer.

When getting names: If the buffer is too small to contain the list of names, this should return the required size of the buffer.
Return Value
S_OK
Buffer contains the requested information.
S_FALSE
When getting names: BufferSize was too small. Its new value is the size required to hold the list of structure names. The engine will call the function again passing in a
new buffer of this size.
All other return values indicate that the function failed. The engine will continue ignoring the contents of Buffer.
Comments
This function is optional. An extension DLL only needs to export KnownStructOutput if it has the ability to format special structures for printing on a single line. The
engine looks for this function by name in the extension DLL.
After initializing the extension DLL, the engine calls this function to query the DLL for the list of structure names it knows how to print. Then, whenever the engine prints a
summary of one of the structures whose name is in the list, it calls this function to format the structure for printing.
Requirements
Headers: The function type is defined as PDEBUG_EXTENSION_KNOWNSTRUCT in dbgeng.h.
See Also
DebugExtensionInitialize
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

PDEBUG_EXTENSION_CALL
Callback functions of the type PDEBUG_EXTENSION_CALL are called by the engine to execute extension commands. You can give these functions any name you want, as
long as it contains no uppercase letters.
HRESULT
CALLBACK
(* PDEBUG_EXTENSION_CALL)(
IN IDebugClient * Client
IN OPTIONAL PCSTR Args
);
Parameters
Client
Specifies an interface pointer to the client. This can be used to interact with the engine. Typically, this is the client through which the extension command was issued.
Args
Specifies the arguments passed to the extension command. In particular, if the extension command was called from a command line, Args contains the rest of the
command line. It can be NULL or empty.
Return Value
S_OK
The function was successful.
DEBUG_EXTENSION_CONTINUE_SEARCH
Indicates that the function cannot handle the command, or that other implementations of the same command in other extension DLLs should also run. The engine should
continue searching other extension DLLs for another function to handle the command. For example, this can be used to have all help functions run if each one returns
CONTINUE_SEARCH.
All other return values are ignored by the engine.
Comments
The name of the function becomes the name of the extension command. When executing an extension command, the engine searches through each of the loaded extension
DLLs in turn, looking for an exported function that has the same name as the command. For example, when executing the command !stack, the engine will look for an
exported function named stack in each loaded extension DLL. For information about the order in which extension DLLs are searched, see Using Debugger Extension
Commands.
The extension function should use the client that was passed to it in Client for all interaction with the engine, unless it has a specific reason to use another client. The
extension function should not maintain the pointer to the client object after it has finished.
Requirements
Headers: The function type is defined in dbgeng.h.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

For a full list of interfaces in dbgeng.h that can be used in an extension command, see Debugger Engine Reference.
For a full list of functions in wdbgexts.h that can be used in an extension command, see WdbgExts Functions. A number of these functions appear in 32-bit versions and 64-bit
versions. Typically, the 64-bit versions end in "64" and the 32-bit versions have no numerical ending for example, ReadIoSpace64 and ReadIoSpace. When calling a
wdbgexts.h function from a DbgEng extension, you should always use the function name ending in "64". This is because the debugger engine always uses 64-bit pointers
internally, regardless of the target platform. When including wdbgexts.h, engextcpp.h selects the 64-bit version of the API. The ExtensionApis global variable used by the
WDbgExts API is automatically initialized on entry to a EngExtCpp method and cleared on exit.
When an EngExtCpp extension is used with remote DbgEng interfaces, the WDbgExts interfaces will not be available and the ExtensionApis structure can be zeroed. If an
EngExtCpp extension is expected to function in such an environment, it should avoid using the WDbgExts API.
Note You must not attempt to call any DbgHelp or ImageHlp routines from any debugger extension. Calling these routines is not supported and may cause a variety of
problems.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Building ExtEngCpp Extensions

The ExtEngCpp extension libraries are built almost the same way as the DbgEng extension libraries (for details, see Building DbgEng Extensions).
In addition, ExtEngCpp extension libraries usually must be statically linked with the library engextcpp.lib. This can be accomplished by adding the following line in the
sources file:
LINKLIBS = $(DBGLIB_LIB_PATH)\engextcpp.lib
The EngExtCpp implementation is also available in Debugging Tools for Windows package for situations where linking with the static library is inappropriate or if the static
library was built with different options than the ones needed for the extension code.
Because the ExtEngCpp extension framework is built on top of the DbgEng extension framework, an EngExtCpp extension DLL should export the same functions as a
DbgEng extension DLL.
Each extension should be exported. When you use the EXT_COMMAND macro to define an extension function, this macro also creates a C function with the same name as
the extension. This function should be exported from the DLL.
The following functions are provided by the engextcpp.lib library and should be exported from the ExtEngCpp DLL.

DebugExtensionInitialize so that the Initialize method can be called to initialize the library.
DebugExtensionUnitialize so that the Uninitialize method can be called to uninitialize the library.
KnownStructOutputEx so that the engine can call the ExtKnownStructMethod methods to format known structures for output.
DebugExtensionNotify so that the engine can call the OnSessionActive, OnSessionInactive, OnSessionAccessible, and OnSessionInaccessible methods to notify
the extension library of changes to the debugging session's state.
help so that the EngExtCpp extension framework can automatically provide a !help extension.

These functions can be exported even if the functionality they provide is not needed. Moreover, if they are not exported, the functionality they provide will be lost.
DebugExtensionInitialize must be exported in order for the debugger engine to recognize the DLL as a valid DbgEng extension DLL.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Parsing Extension Arguments

The EngExtCpp extension framework provides methods to aid in parsing the command-line arguments passed to an extension. To take advantage of these methods, the
extension must first declare the format of the command-line arguments in the EXT_COMMAND macro.
To bypass the command-line argument parsing done by the framework and let the extension itself parse the arguments, set the command-line description to "{{custom}}"
and use the method GetRawArgStr to get the command-line arguments for parsing.
Command-line description strings will automatically be wrapped when printed, to fit the column width of the display. However, newline characters can be embedded in the
description strings using '\n' to start new lines.
The command-line description can be NULL or the empty string. If either occurs, it indicates that the extension command does not take any arguments.
Command-Line Description
The description of the command-line arguments is a sequence that contains two types of components: directives and arguments. The description can optionally contain one of
each directive and can contain up to 64 arguments.
Directives

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1535 of 1651

Directives specify how the arguments are parsed. They are enclosed by double braces ('{{' and '}}'). Each directive can optionally appear zero or one times in the string
that describes the arguments.
The following directives are available:
custom
Turns off the parsing done by the extension framework and lets the extension perform its own parsing.
l:str
Overrides the default long description of the command-line arguments. The extension framework will use str for the full description of all the arguments.
opt:str
Overrides the default prefix characters for named commands. The default value is "/-", allowing '/' or '-' to be used as the prefix that identifies named arguments.
s:str
Overrides the default short description of the command-line arguments. The extension framework will use str for the short description of all the arguments.
Here are some examples of directives. The following string is used by an extension command that parses its own arguments. It also provides short and long descriptions for
use with the automatic !help extension command:
{{custom}}{{s:<arg1> <arg2>}}{{l:arg1 - Argument 1\narg2 - Argument 2}}
The following string changes the argument option prefix characters to '/' or '-'. With this directive, the arguments will be specified using '+arg' and ':arg' instead of '/arg'
and '-arg':
{{opt:+:}}
Arguments
Arguments can be of two types: named and unnamed. Unnamed arguments are read positionally. Both types of argument also have a display name, used by the help
command.
Argument descriptions are enclosed by single braces ('{' and '}').
Each argument description has the following syntax:
{[optname];[type[,flags]];[argname];[argdesc]}
where:
optname
The name of the argument. This is the name used in commands and in methods that fetch arguments by name. This name is optional. If it is present, the argument
becomes a "named argument"; it can appear anywhere on the command-line and is referenced by name. If it is not present, the argument becomes an "unnamed
argument"; its position on the command-line is important and it is referenced by its position relative to the other unnamed arguments.
type
The type of the argument. This affects how the argument is parsed and how it is retrieved. The type parameter can have one of the following values:
b
Boolean type. The argument is either present or not present. Named Boolean arguments can be retrieved using HasArg.
e[d][s][bits]
Expression type. The argument has a numeric value. Named expression arguments can be retrieved using GetArgU64 and unnamed expression arguments can be
retrieved using GetUnnamedArgU64.
d
The expression is limited to the next space character in the argument string. If this is not present, the expression evaluator will consume characters from the
command line until it determines that it reached the end of the expression.
s
The value of the expression is signed. Otherwise, the value of the expression is unsigned.
bits
The number of bits in the value of the argument. The maximum value for bits is 64.
s
String type. The string is limited to the next space character. Named string arguments can be retrieved using GetArgStr and unnamed string arguments can be
retrieved using GetUnnamedArgStr.
x
String type. The argument is the rest of the command line. The argument is retrieved using GetArgStr or GetUnnamedArgStr, as with the s string type.
flags
The argument flags. These determine how the argument will be treated by the parser. The flags parameter can have one of the following values:
d=expr
The default value of the argument. If the argument is not present on the command line, then the argument is set to expr. The default value is a string that is parsed
according to the type of the argument.
ds
The default value will not be displayed in the argument description provided by the help.
o
The argument is optional. This is the default for named arguments.
r
The argument is required. This is the default for unnamed arguments.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1536 of 1651

argname
The display name of the argument. This is the name used by the automatic !help extension command and by the automatic /? or -? command-line arguments. Used when
printing a summary of the command-line options.
argdesc
A description of the argument. This is the description printed by the automatic !help extension and by the automatic "/?" or "-?" command-line arguments.
Here are some examples of argument descriptions. The following expression defines a command which takes a single optional expression argument. The argument must fit in
32bits. If the argument isn't present on the command line, the default value of 0x100 will be used.
{;e32,o,d=0x100;flags;Flags to control command}
The following expression defines a command with an optional Boolean "/v" argument and a required unnamed string argument.
{v;b;;Verbose mode}{;s;name;Name of object}
The following expression defines a command that has an optional named expression argument /oname expr and an optional named string argument /eol str. If /eol
is present, its value will be set to the remainder of the command line and no further arguments will be parsed.
{oname;e;expr;Address of object}{eol;x;str;Commands to use}
Command Line
The following is a list of some ways that arguments are parsed on the command line:

The values of named expression and string arguments follow the name on the command line. For example, /name expr or /name str.
For named Boolean arguments, the value is true if the name appears on the command line; false otherwise.
Multiple single-character-named Boolean options can be grouped together on the command line. For example, "/a /b /c" can be written using the shorthand
notation "/abc" (unless there is already an argument named "abc").
If the command line contains the named argument "?" for example, "/?" and "-?" the argument parsing ends, and the help text for the extension is displayed.

Parsing Internals
Several methods are used by the argument parser to set arguments.
The method SetUnnamedArg will change the value of an unnamed argument. And, for convenience, the methods SetUnnamedArgStr and SetUnnamedArgU64 will set
unnamed string and expression arguments respectively.
Similar methods exist for named arguments. SetArg is used to change the value of any named argument and SetArgStr and SetArgU64 are used for named string and
expression arguments respectively.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Typed Data
The EngExtCpp extension framework provides a few classes to help manipulate the target's memory. The ExtRemoteData class describes a small piece of the target's
memory. If the type of this memory is known, it is referred to as typed data and is described by ExtRemoteTyped objects.
Windows lists can be iterated over by using ExtRemoteList and, if the type of the objects in the list is known, ExtRemoteTypedList.
Note Like the client objects in ExtExtension, instances of these classes are only valid while the extension library is used to execute an extension command or format a
structure for output. In particular, they should not be cached. For more information about when client objects are valid, see Client Objects and the Engine, .
Remote Data
Remote data should be handled using the class ExtRemoteData. This class is a wrapper around a small section of a target's memory. ExtRemoteData automatically retrieves
the memory and wraps other common requests with throwing methods.
Remote Typed Data
If the type of the remote data is known, it should be handled using the ExtRemoteTyped class. This class is an enhanced remote data object that understands data typed with
type information from symbols. It is initialized to a particular object by symbol or cast, after which it can be used like an object of the given type.
Remote Lists
To handle remote lists, use the ExtRemoteList class. This class can be used for either a singly linked or doubly linked list. If the list is doubly linked, it is assumed that the
previous pointer immediately follows the next pointer. The class contains methods that can iterate over the list and retrieve nodes both forward and backward. ExtRemoteList
can be used with either null-terminated or circular lists also.
Remote Typed Lists
To handle remote lists when the type of the nodes in the list is known, use the ExtRemoteTypedList class. This is an enhanced version of ExtRemoteList. In addition to the
basic functionality of ExtRemoteList, ExtRemoteTypedList automatically determines link offsets from type information.
2009 Microsoft Corporation

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1537 of 1651

Send feedback on this topic

Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Page 1540 of 1651

IsExtensionRemote
AreOutputCallbacksDmlAware
RequireUserMode
RequireKernelMode
GetNumUnnamedArgs
GetUnnamedArgStr
GetUnnamedArgU64
HasUnnamedArg
GetArgStr
GetArgU64
HasArg
HasCharArg
SetUnnamedArg
SetUnnamedArgStr
SetUnnamedArgU64
SetArg
SetArgStr
SetArgU64
GetRawArgStr
GetRawArgCopy
Out
Warn
Err
Verb
Dml
DmlWarn
DmlErr
DmlVerb
DmlCmdLink
DmlCmdExec
RefreshOutputCallbackFlags
WrapLine
OutWrapStr
OutWrapVa
OutWrap
DemandWrap
AllowWrap
TestWrap
RequestCircleString
CopyCircleString
PrintCircleStringVa
PrintCircleString

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1541 of 1651

SetAppendBuffer
AppendBufferString
AppendStringVa
AppendString
IsAppendStart
SetCallStatus
GetCachedSymbolTypeId
GetCachedFieldOffset
GetCachedFieldOffset
AddCachedSymbolInfo
GetExpr64
GetExprU64
GetExprS64
ThrowCommandHelp
ThrowInterrupt
ThrowOutOfMemory
ThrowContinueSearch
ThrowReloadExtension
ThrowInvalidArg
ThrowRemote
ThrowStatus
ThrowLastError
The ExtExtension class also contains the following fields that can be used by the subclass:
class ExtExtension
{
public:
USHORT m_ExtMajorVersion;
USHORT m_ExtMinorVersion;
ULONG m_ExtInitFlags;
ExtKnownStruct * m_KnownStructs;
ExtProvidedValue * m_ProvidedValues;
ExtCheckedPointer<IDebugAdvanced> m_Advanced;
ExtCheckedPointer<IDebugClient> m_Client;
ExtCheckedPointer<IDebugControl> m_Control;
ExtCheckedPointer<IDebugDataSpaces> m_Data;
ExtCheckedPointer<IDebugRegisters> m_Registers;
ExtCheckedPointer<IDebugSymbols> m_Symbols;
ExtCheckedPointer<IDebugSystemObjects> m_System;
ExtCheckedPointer<IDebugAdvanced2> m_Advanced2;
ExtCheckedPointer<IDebugAdvanced3> m_Advanced3;
ExtCheckedPointer<IDebugClient2> m_Client2;
ExtCheckedPointer<IDebugClient3> m_Client3;
ExtCheckedPointer<IDebugClient4> m_Client4;
ExtCheckedPointer<IDebugClient5> m_Client5;
ExtCheckedPointer<IDebugControl2> m_Control2;
ExtCheckedPointer<IDebugControl3> m_Control3;
ExtCheckedPointer<IDebugControl4> m_Control4;
ExtCheckedPointer<IDebugDataSpaces2> m_Data2;
ExtCheckedPointer<IDebugDataSpaces3> m_Data3;
ExtCheckedPointer<IDebugDataSpaces4> m_Data4;
ExtCheckedPointer<IDebugRegisters2> m_Registers2;
ExtCheckedPointer<IDebugSymbols2> m_Symbols2;
ExtCheckedPointer<IDebugSymbols3> m_Symbols3;
ExtCheckedPointer<IDebugSystemObjects2> m_System2;
ExtCheckedPointer<IDebugSystemObjects3> m_System3;
ExtCheckedPointer<IDebugSystemObjects4> m_System4;
ULONG m_OutputWidth;
ULONG m_ActualMachine;
ULONG m_Machine;
ULONG m_PageSize;

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Introduction

Page 1547 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetNumUnnamedArgs
The GetNumUnnamedArgs method returns the number of unnamed arguments in the command line used to invoke the current extension command.
ULONG
ExtExtension::GetNumUnnamedArgs(
void
)
Parameters
None.
Return Value
GetNumUnnamedArgs returns the number of unnamed arguments.
Comments
The indices of the unnamed arguments returned by GetNumUnnamedArgs range from zero to the number of unnamed arguments minus one (unnamed args - 1).
For an overview of argument parsing in the EngExtCpp extensions framework, see Parsing Extension Arguments.
This method should only be called during the execution of an extension command provided by this class.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetUnnamedArgStr
The GetUnnamedArgStr method returns an unnamed string argument from the command line used to invoke the current extension command.
PCSTR
ExtExtension::GetUnnamedArgStr(
IN ULONG Index
) throw(...)
Parameters
Index
Specifies the index of the argument. The command-line description used in EXT_COMMAND must specify that the type of this argument is string. The value of Index
should be between zero and the number of unnamed arguments returned by GetNumUnnamedArgs minus one (unnamed arguments - 1).
Return Value
GetUnnamedArgStr returns the unnamed string argument.
Comments
For an overview of argument parsing in the EngExtCpp extensions framework, see Parsing Extension Arguments.
The string returned by GetUnnamedArgStr is only meaningful during the execution of the current extension command.
This method should only be called during the execution of an extension command provided by this class.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
EXT_COMMAND, GetNumUnnamedArgs

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1548 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Debugging Tools for Windows

GetRawArgStr
The GetRawArgStr method returns a string that represents the arguments passed to the extension command.
PCSTR
ExtExtension::GetRawArgStr(
void
)
Parameters
None
Return Value
GetRawArgStr returns a string that represents the arguments passed to the extension command. In particular, if the extension command was called from a command line, this
string contains the portion of the command line that follows the extension command. The return value can be NULL or empty.
Comments
For an overview of argument parsing in the EngExtCpp extensions framework, see Parsing Extension Arguments.
The string returned by this method is only meaningful during the execution of the current extension command.
This method should only be called during the execution of an extension command provided by this class.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtKnownStruct
The ExtKnownStruct structure is used to specify how a target's structure can be formatted for output.
struct ExtKnownStruct
{
PCSTR TypeName;
ExtKnownStructMethod Method;
bool SuppressesTypeName;
};
Members
TypeName
The name of the structure type.
Method
The ExtKnownStructMethod callback function that can be called to format an instance of the structure specified in TypeName.
SuppressesTypeName
A Boolean flag that specifies whether the formatted output includes the name of the structure's type. If FALSE, the name is included in the formatted output; otherwise,
the name is not included.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtKnownStructMethod
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtKnownStructMethod

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1556 of 1651

The ExtKnownStructMethod callback method is called by the engine to format an instance of a structure for output on a single line.
typedef void
(ExtExtension::*ExtKnownStructMethod)(
IN PCSTR TypeName,
IN ULONG Flags,
IN ULONG64 Offset
)
Parameters
TypeName
Specifies the name of the type of the structure pointed to by Offset. This is the same as the TypeName field of the ExtKnownStruct structure used to register this
callback method.
Flags
Specifies bit flags that indicate how the output should be formatted. Currently, this is set to DEBUG_KNOWN_STRUCT_GET_SINGLE_LINE_OUTPUT, which
indicates that the output should be formatted for output on a single line.
Offset
Specifies the location in the target's memory of the instance of the structure to be formatted for output.
Return Value
None
Comments
The debugger engine expects the output to be formatted for printing on a single line, hence it does not expect the formatted structure to have any line breaks.
The formatted output from this method should be placed in the buffer m_AppendBuffer a member of ExtExtension.
Instances of this callback method are registered with the engine by using an instance of the ExtKnownStruct structure that is placed into the array m_KnownStructs (a
member of ExtExtension) by the Initialize method. The ExtKnownStruct structure also specifies the name of the type of structure this method formats.
When the debugger engine calls a known structure method, it wraps the call in a try / except block. This protects the engine from some types of bugs in the extension code;
but, because the extension calls are executed in the same thread as the engine, they can still cause it to crash.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtExtension, ExtKnownStruct, Initialize
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData
The ExtRemoteData class provides a wrapper around a small section of a target's memory. ExtRemoteData automatically retrieves the memory and provides a number of
convenience methods.
The ExtRemoteData class includes the following constructors and methods:
ExtRemoteData
Set
Read
Write
GetData
GetChar
GetUchar
GetBoolean
GetStdBool
GetW32Bool
GetShort
GetUshort

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1557 of 1651

GetLong
GetUlong
GetLong64
GetUlong64
GetFloat
GetDouble
GetLongPtr
GetUlongPtr
GetPtr
ReadBuffer
WriteBuffer
GetString
class ExtRemoteData
{
public:
PCSTR m_Name;
ULONG64 m_Offset;
bool m_ValidOffset;
ULONG m_Bytes;
ULONG64 m_Data;
bool m_ValidData;
bool m_Physical;
ULONG m_SpaceFlags;
};
Members
m_Name
The name given to this instance of ExtRemoteData. This name is used to provide meaningful error messages and is set by the constructor,
ExtRemoteData::ExtRemoteData.
m_Offset
The location in the target's memory (virtual or physical) of the region of memory represented by this instance of ExtRemoteData. It can be set by the
ExtRemoteData::ExtRemoteData constructor or by the ExtRemoteData::Set method.
m_ValidOffset
Indicates whether the m_Offset location is valid. If m_ValidOffset is false, the location is not valid and most of the methods for this object will not work. In this case,
the ExtRemoteData::Set method can be called to change m_Offset to a valid location.
m_Bytes
The size, in bytes, of the region of memory represented by this object. It can be set by the ExtRemoteData::ExtRemoteData constructor or by the ExtRemoteData::Set
method.
m_Data
The cached contents of the region of memory specified by this instance of ExtRemoteData. Setting this member is optional. If the region of memory is large, it will not
be cached.
m_ValidData
Indicates whether the m_Data cached data is valid. If m_ValidData is false, the cached data is not valid and most of the methods for this object will not work. In this
case, the ExtRemoteData::Read method can be called to refresh the cached data.
m_Physical
Indicates whether the m_Offset location is in the target's virtual address space or in its physical address space. If m_Physical is true, the m_Offset location is in the
target's physical address space. If m_Physical is false, the m_Offset location is in the target's virtual address space.
m_SpaceFlags
The DEBUG_PHYSICAL_XXX flags used for accessing physical memory on the target. These flags are only used if m_Physical is true. For a description of these
flags, see the ReadPhysical2 method.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData::ExtRemoteData, ExtRemoteData::Read, ExtRemoteData::Set, ReadPhysical2
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::ExtRemoteData

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1558 of 1651

The ExtRemoteData constructors create a new instance of the ExtRemoteData class.

ExtRemoteData::ExtRemoteData(
void
)
ExtRemoteData::ExtRemoteData(
IN ULONG64 Offset,
IN ULONG Bytes
) throw(...)
ExtRemoteData::ExtRemoteData(
IN OPTIONAL PCSTR Name,
IN ULONG64 Offset,
IN ULONG Bytes
) throw(...)
Parameters
Name
Name of the memory region. Name can be used to help identify the region and will be inserted into any error messages generated by the new object.
Offset
Location of the beginning of the memory region in the target's virtual address space.
Bytes
Number of bytes in the memory region.
Comments
If a memory region is specified, the contents of the region are read from the target and cached. The data can be retrieved using ExtRemoteData::GetData or one of the
ExtRemoteTyped::GetXxx methods.
The constructor is called by the ExtRemoteData::Set method and the ExtRemoteData::GetData method.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData::GetData, ExtRemoteData::Set
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::Set
The Set method sets the region of the target's memory represented by the ExtRemoteData object.
void
ExtRemoteData::Set(
IN ULONG64 Offset,
IN ULONG Bytes
) throw(...)
void
ExtRemoteData::Set(
IN const DEBUG_TYPED_DATA *
)

Typed

Parameters
Offset
Location of the beginning of the memory region in the target's virtual address space.
Bytes
Number of bytes in the memory region.
Typed
Specifies the region of memory by using a DEBUG_TYPED_DATA structure.
Return Value
None
Comments
The Set method will read the contents of the specified region of memory and cache the data. The data can be retrieved using ExtRemoteData::GetData or one of the
ExtRemoteTyped::GetXxx methods.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1559 of 1651

Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData::ExtRemoteData, ExtRemoteData::GetData
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

) throw (...)
Parameters
None
Return Value
GetLongPtr returns a signed integer version of the ExtRemoteData object, extended to LONG64.
Comments
The size of the memory represented by the ExtRemoteData object must be the same as the size of a pointer on the target, ExtExtension::m_PtrSize.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData, ExtRemoteData::GetData, ExtRemoteData::GetLong, ExtRemoteData::GetLong64, ExtRemoteData::GetUlongPtr
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::GetUlongPtr
The GetUlongPtr method returns an unsigned integer version (extended to ULONG64) of the ExtRemoteData object, which represents the contents of the target's memory.
The size of the unsigned integer from the target is the same size as a pointer on the target.
ULONG64
ExtRemoteData::GetUlongPtr(
void
) throw (...)
Parameters
None
Return Value
GetUlongPtr returns an unsigned integer version of the ExtRemoteData object, extended to ULONG64.
Comments
The size of the memory represented by the ExtRemoteData object must be the same as the size of a pointer on the target, ExtExtension::m_PtrSize.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData, ExtRemoteData::GetData, ExtRemoteData::GetLongPtr, ExtRemoteData::GetUlong, ExtRemoteData::GetUlong64
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::GetPtr
The GetPtr method returns a pointer from the target's memory version of the ExtRemoteData object, which represents the contents of the target's memory. The size of the
unsigned integer from the target is the same size as a pointer on the target.
ULONG64
ExtRemoteData::GetPtr(
void
) throw (...)
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1568 of 1651

None
Return Value
GetPtr returns a pointer from the target's memory. As with all pointers, if the target uses 32-bit pointers, it is sign-extended to 64-bits.
Comments
The size of the memory represented by the ExtRemoteData object must be the same as the size of a pointer on the target, ExtExtension::m_PtrSize.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData, ExtRemoteData::GetData, ExtRemoteData::GetLongPtr, ExtRemoteData::GetUlong, ExtRemoteData::GetUlong64
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::ReadBuffer
The ReadBuffer method reads data from the target's memory. The data is located in the beginning of the region represented by the ExtRemoteData object. However, the size
of the data can be different.
ULONG
ExtRemoteData::ReadBuffer(
OUT PVOID Buffer,
IN ULONG Bytes,
IN bool MustReadAll = true
) throw(...);
Parameters
Buffer
Pointer that receives the data read from the target.
Bytes
Specifies the number of bytes to read. The Buffer buffer must be at least this size.
MustReadAll
Specifies what happens if the debugger engine is unable to read all the data from the target. If MustReadAll is true and the debugger engine is unable to read Bytes
bytes from the target, an ExtRemoteException will be thrown. If MustReadAll is false, no exception will be thrown if the engine is unable to read the requested
number of bytes from the target.
Return Value
ReadBuffer returns the number of bytes read from the target and copied into the Buffer buffer. If MustReadAll is true, the value of Bytes will be returned (unless an
exception is thrown).
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData, ExtRemoteData::WriteBuffer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::WriteBuffer
The WriteBuffer method writes data to the target's memory. The data is located in the beginning of the region represented by the ExtRemoteData object. However, the size
of the data can be different.
ULONG
ExtRemoteData::WriteBuffer(
IN PVOID Buffer,
IN ULONG Bytes,
IN bool MustReadAll = true

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1569 of 1651

) throw(...);
Parameters
Buffer
Specifies the data to write to the target.
Bytes
Specifies the number of bytes to write. The Buffer buffer must be at least this size.
MustReadAll
Specifies what happens if the debugger engine is unable to write all the data to the target. If MustReadAll is true and the debugger engine is unable to write Bytes bytes
to the target, an ExtRemoteException will be thrown. If MustReadAll is false, no exception will be thrown if the engine is unable to write the requested number of
bytes to the target.
Return Value
WriteBuffer returns the number of bytes written to the target from the Buffer buffer. If MustReadAll is true, the value of Bytes will be returned (unless an exception is
thrown).
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteData, ExtRemoteData::ReadBuffer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteData::GetString
The GetString method reads a null-terminated string from the target's memory. The string is located in the beginning of the region represented by the ExtRemoteData object.
PSTR
GetString(
OUT PSTR Buffer,
IN ULONG BufferChars,
IN ULONG MaxChars = 1024,
IN bool MustFit = false
) throw(...);
PWSTR
GetString(
OUT PWSTR Buffer,
IN ULONG BufferChars,
IN ULONG MaxChars = 1024,
IN bool MustFit = false
) throw(...);
Parameters
Buffer
Receives the null-terminated string read from the target. The type of Buffer must be the same as the type of the string on the target. If the string is a Unicode string, the
type of Buffer must be PWSTR. If the string is a multibyte string, the type of Buffer must be PSTR.
Note the remainder of the Buffer buffer, after the string, can be overwritten by this method.
BufferChars
Specifies the size, in characters, of the Buffer buffer.
MaxChars
Specifies the maximum number of characters to read from the target.
MustFit
Specifies what happens if the string is larger than BufferChars characters. If MustFit is true and the string is larger than BufferChars characters, an
ExtRemoteException will be thrown. If MustFit is false and the string is larger than BufferChars characters, the string will be truncated and null-terminated to fit
inside the Buffer buffer.
Return Value
GetString returns the null-terminated string that was read from the target. This is Buffer.
Comments
This method can only be used if the region represented by the ExtRemoteData object is in virtual memory. It will not work if the region specifies physical memory.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1570 of 1651

See Also
ExtRemoteData, ExtRemoteData::ReadBuffer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped
The ExtRemoteTyped class provides the ability to manipulate typed data on the target. An instance of this class represents a small region of memory on the target. This
region is interpreted as a specific type. This class provides methods for manipulating the memory according to the type and for accessing the object hierarchy on the target.
ExtRemoteTyped is a subclass of ExtRemoteData.
The ExtRemoteTyped class includes the following constructors, operators, and methods:
ExtRemoteTyped
operator=
Copy
Set
SetPrint
HasField
GetTypeSize
GetFieldSize
GetFieldOffset
Field
ArrayElement
Dereference
GetPointerTo
Eval
operator[]
operator*
GetTypeName
OutTypeName
OutSimpleValue
OutFullValue
OutTypeDefinition
Release
GetTypeFieldOffset
class ExtRemoteTyped : public ExtRemoteData
{
public:
DEBUG_TYPED_DATA m_Typed;
bool m_Release;
};
Members
m_Typed
The DEBUG_TYPED_DATA structure that describes the typed data represented by this instance of ExtRemoteTyped.
m_Release
Indicates whether or not the destructor for this instance of ExtRemoteTyped needs to release the DEBUG_TYPED_DATA structure that is specified in m_Typed.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1571 of 1651

Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.

See Also
DEBUG_TYPED_DATA, ExtRemoteData
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::ExtRemoteTyped
The ExtRemoteTyped constructors create a new instance of the ExtRemoteTyped class.
ExtRemoteTyped(
void
)
ExtRemoteTyped(
IN PCSTR Expr
) throw(...)
ExtRemoteTyped(
IN const DEBUG_TYPED_DATA *
) throw(...)
ExtRemoteTyped(
IN const ExtRemoteTyped &
) throw(...)

Typed

ExtRemoteTyped(
IN PCSTR Expr,
IN ULONG64 Offset
) throw(...)
ExtRemoteTyped(
IN PCSTR Type,
IN ULONG64 Offset,
IN bool PtrTo,
IN OUT OPTIONAL PULONG64 CacheCookie = NULL,
IN OPTIONAL PCSTR LinkField = NULL
) throw(...)
Parameters
Expr
An expression that evaluates to the desired symbol. This expression is evaluated by the default expression evaluator.
Offset
When used with Expr, specifies an additional parameter that can be used when evaluating the Expr expression. This additional parameter is available in the expression as
the $extin pseudo-register. For example, to specify a process environment block (PEB) at a particular location, you could set Expr to the C++ expression (ntdll!_PEB
*)@$extin. This casts the pseudo-register $extin to a pointer to a PEB. Then, set Offset to the location of the PEB structure.
When used with Type, Offset specifies the location of the data in the target's virtual address space.
Typed
The typed data represented by the RemoteExtTyped. This can be either a DEBUG_TYPED_DATA structure that describes the data and type to be represented by this
object, or, for the copy constructor, an existing ExtRemoteTyped object.
Type
The type name of the type. Type can include a module qualifier (for example, mymodule!mytype). The module qualifier can be omitted, but it is recommended that it be
included if the module is known.
PtrTo
Specifies whether or not to set the ExtRemoteTyped instance to the specified typed data, or to a pointer to the specified typed data. If PtrTo is true, the
ExtRemoteTyped instance will contain a pointer to the typed data.
CacheCookie
The cache cookie to use for caching type information. If CacheCookie is NULL, the debugger engine will search for type information each time.
For more information about CacheCookie, see ExtRemoteTyped::Set.
LinkField
The name of a field in the typed data that contains the pointer to the next item in a list. LinkField should be set if CacheCookie is being used for the first time and will
later be used with ExtRemoteTypedList.
Comments
The typed data can also be set or changed using the ExtRemoteTyped::Set method.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1572 of 1651

Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.

See Also
DEBUG_TYPED_DATA, ExtRemoteData, ExtRemoteTyped::Set, ExtRemoteTypedList
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::operator=
The operator= overloaded assignment operator sets the typed data represented by the ExtRemoteTyped object by copying the information from another object.
ExtRemoteTyped &
operator=(
IN const DEBUG_TYPED_DATA *
) throw(...)
ExtRemoteTyped &
operator=(
IN const ExtRemoteTyped &
) throw(...)

Typed

Parameters
Typed
The typed data description to copy. This becomes the typed data represented by this object. Typed can be either a DEBUG_TYPED_DATA structure that describes the
data and type to be represented by this object, or an existing ExtRemoteTyped object.
Return Value
operator= returns the ExtRemoteTyped object.
Comments
The typed data can also be copied using the ExtRemoteTyped::Copy method.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
For other methods used to set the initial values of ExtRemoteTyped, see
DEBUG_TYPED_DATA, ExtRemoteTyped, t
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::Copy
The Copy method sets the typed data represented by the ExtRemoteTyped object by copying the information from another object.
void
Copy(
IN const DEBUG_TYPED_DATA *
) throw(...)
void
Copy(
IN const ExtRemoteTyped &
) throw(...)

Typed

Parameters
Typed
The typed data description to copy. Tthis becomes the typed data represented by this object. Typed can be either a DEBUG_TYPED_DATA structure that describes the
data and type to be represented by this object, or an existing ExtRemoteTyped object.
Return Value

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1573 of 1651

None
Comments
The typed data can also be copied using the ExtRemoteTyped::Copy method.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
DEBUG_TYPED_DATA, ExtRemoteTyped, ExtRemoteTyped::operator=
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::Set
The Set method sets the typed data represented by the ExtRemoteTyped object.
void
Set(
IN PCSTR
) throw(...)

Expr

void
Set(
IN PCSTR Expr,
IN ULONG64 Offset
) throw(...)
void
Set(
IN bool PtrTo,
IN ULONG64 TypeModBase,
IN ULONG TypeId,
IN ULONG64 Offset
) throw(...)
void
Set(
IN PCSTR Type,
IN ULONG64 Offset,
IN bool PtrTo,
IN OUT OPTIONAL PULONG64 CacheCookie = NULL,
IN OPTIONAL PCSTR LinkField = NULL
) throw(...)
Parameters
Expr
An expression that evaluates to the desired symbol. This expression is evaluated by the default expression evaluator.
Offset
When used with Expr, specifies an additional parameter that can be used when evaluating the Expr expression. This additional parameter is available in the expression as
the $extin pseudo-register. For example, to specify a process environment block (PEB) at a particular location, you could set Expr to the C++ expression (ntdll!_PEB
*)@$extin. This casts the pseudo-register $extin to a pointer to a PEB. Then, set Offset to the location of the PEB instance.
When used with Type or TypeId, Offset specifies the location of the data in the target's memory.
PtrTo
Specifies whether or not to set the ExtRemoteTyped instance to the specified typed data, or to a pointer to the specified typed data. If PtrTo is true, the
ExtRemoteTyped instance will be a pointer to the typed data.
TypeModBase
The base address of the module to which the type belongs.
TypeId
The type ID of the type.
Type
The type name of the type. Type can include a module qualifierfor example, mymodule!mytype. The module qualifier can be omitted, but it is recommended that it be
included if the module is known.
CacheCookie
A cache cookie used for caching the type information. If CacheCookie is NULL, the debugger engine will search for the type information each time.
A cache cookie is a pointer to a ULONG64. It is associated with a particular symbol that is uniquely identified by the symbol's type ID and the address of the module that
contains the symbol. The first time it is used, the ULONG64 that cache cookie points to must be set to 0. In this case, the debugger engine will search for the symbol
information and cache it, then it will set the cookie so that the symbol information can be easily retrieved later. Whenever you use a subsequent method that will need
information about the same symbol, use the cache cookie. The debugger engine will then be able to retrieve the symbol information from the cache instead of searching

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1574 of 1651

for it. Each cache cookie should only be used with a single type. If a cache cookie is used in conjunction with a different symbol, the cache cookie might be corrupted.
LinkField
The name of a field in the typed data structure which contains the pointer to the next item in a list. LinkField should be set if CacheCookie is being used for the first time
and will later be used with ExtRemoteTypedList.
Return Value
None
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteTyped, ExtRemoteTyped::SetPrint, ExtRemoteTypedList
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::SetPrint
The SetPrint method sets the typed data represented by the ExtRemoteTyped object by formatting an expression and then evaluating that expression.
void
ExtRemoteData::SetPrint(
IN PCSTR Format,
...
) throw(...)
Parameters
Format
The format string used to create the expression. This is the same as the format string used by the C printf function.
Note While other methods and functions in the debugger engine API provide additional, debugger-specific conversion characters, SetPrint only supports the conversion
characters used by printf.

The arguments for the format string, as in printf. The arguments should match the conversion characters in Format.
Return Value
None
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteTyped, ExtRemoteTyped::Set
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::HasField
The HasField method determines if the type of the data represented by this object contains the specified member.
bool
ExtRemoteData::HasField(
IN PCSTR Field
)
Parameters
Field
The name of the member. The name of the member is a dot-separated path and can contain sub-members (for example, mymember.mysubmember). Pointers on this
dot-separated path will automatically be dereferenced. However, a dot operator (.) should still be used here instead of the usual C pointer dereference operator (->).

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1575 of 1651

Return Value
HasField returns true if the typed data contains the member; false otherwise.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::operator[]
The operator[] overloaded operator returns the typed data in the specified array element of the typed data represented by this object.
ExtRemoteTyped
ExtRemoteData::operator[](
IN LONG Index
)
ExtRemoteTyped
ExtRemoteData::operator[](
IN ULONG Index
)
ExtRemoteTyped
ExtRemoteData::operator[](
IN LONG64 Index
)
ExtRemoteTyped
ExtRemoteData::operator[](
IN ULONG64 Index
)
Parameters
Index
The index of the array element.
Return Value
The operator[] operator returns a new ExtRemoteTyped object that represents the typed data for the specified element of the array.
Comments
If the typed data represented by this object is a pointer and not an array, the pointer is treated like an array.
The ExtRemoteTyped::ArrayElement performs a similar function.
Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
See Also
ExtRemoteTyped::ArrayElement
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtRemoteTyped::operator*
The operator* overloaded operator returns the typed data that is pointed to by the typed data represented by this object.
ExtRemoteData
ExtRemoteData::operator*(
void
)
Parameters
None
Return Value
The operator* operator returns a new ExtRemoteData object that represents the typed data pointed to by the typed data represented by this object.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Introduction

Requirements
Headers: Defined in Engextcpp.hpp. Include Engextcpp.hpp.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Writing WdbgExts Extensions

WdbgExts extensions are the original kind of debugger extensions. They are less powerful than DbgEng extensions, but they still offer a wide range of functionality when
performing user-mode or kernel-mode debugging on Microsoft Windows.
If you performed a full install of Debugging Tools for Windows, a sample WdbgExts extension called "simplext" can be found in the sdk\samples\simplext subdirectory of the
installation directory.
This section includes:
WdbgExts Extension Design Guide
WdbgExts Extension Reference
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Extension Design Guide

This section includes:
WdbgExts Extension API Overview
32-Bit Pointers and 64-Bit Pointers
Using WdbgExts Extension Callbacks
Using the DECLARE_API Macro
Writing WdbgExts Extension Code
Building WdbgExts Extensions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Extension API Overview

Each WdbgExts extension DLL exports one or more functions that are used to implement extension commands. These functions are named according to the standard C
convention, except that upper-case letters are not permitted.
The function name and the extension command name are identical, except that the extension command begins with an exclamation point ( ! ). For example, when you load
Myextension.dll into the debugger and then type !stack into the Debugger Command window, the debugger looks for an exported function named stack in Myextension.dll.
If Myextension.dll is not already loaded, or if there are other extension commands with the same name in other extension DLLs, you can type !myextension.stack into the
Debugger Command window to indicate the extension DLL and the extension command in that DLL.
Each WdbgExts extension DLL also exports a number of callback functions. These functions are called by the debugger when the DLL is loaded and when extension
commands are used.
The debugger engine will place a try / except block around a call to an extension DLL. This protects the engine from some types of bugs in the extension code. However,
since the extension calls are executed in the same thread as the engine, they can still cause the engine to crash.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1590 of 1651

Debugging Tools for Windows

32-Bit Pointers and 64-Bit Pointers

The WdbgExts.h header file supports both 32-bit and 64-bit pointers. To use 64-bit pointers, simply include the following two lines in your code, in the following order:
#define KDEXT_64BIT
#include wdbgexts.h
It is recommended that you always use 64-bit pointers in your code. This allows your extension to work on any platform, because the debugger will automatically cast 64-bit
pointers to 32 bits when the target is 32-bit.
If you intend to use your extension only on 32-bit platforms, you can write a 32-bit extension instead. In that case, you only need to include the following line in your code:
#include wdbgexts.h

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using WdbgExts Extension Callbacks

Every WdbgExts extension DLL can export certain callback functions. Two of these are required; the third is optional:
1. You must export a function named WinDbgExtensionDllInit. When the debugger loads an extension DLL, it first calls WinDbgExtensionDllInit and passes it several
parameters, including a pointer to a WINDBG_EXTENSION_APIS64 structure. This structure contains the callbacks to functions that are exported by wdbgexts.h. This
pointer should be saved in a global variable named ExtensionApis. The debugger also passes information about the Windows version to the WinDbgExtensionDllInit
function.
2. You must export a function called ExtensionApiVersion. The debugger calls this function and expects back a pointer to an API_VERSION structure that contains the
version number of the extension DLL. The debugger uses this version number when executing commands like .chain and version that display the extension version
number.
3. You can optionally export a function called CheckVersion. The debugger calls this routine every time you use an extension command from DLL. This is used to print
out version mismatch warnings when your DLL is of a slightly different version than the debugger, but not different enough to prevent it from running.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Using the DECLARE_API Macro

Each extension command in a WdbgExts extension DLL is declared using the DECLARE_API macro. This macro is defined in wdbgexts.h.
The basic format of the code for an extension command is:
DECLARE_API( myextension )
{
code for myextension
}
The DECLARE_API macro sets up a standard interface for extension commands. For example, if the user passed any arguments to the extension command, the entire
argument string will be stored as a string, and a pointer to this string (PCSTR) will be passed to the extension function as args.
If you are using 64-bit pointers, the DECLARE_API macro is defined as follows:
#define DECLARE_API(s)
CPPMOD VOID
s(
HANDLE
HANDLE
ULONG64
ULONG
PCSTR
)

hCurrentProcess,
hCurrentThread,
dwCurrentPc,
dwProcessor,
args

\
\
\
\
\
\
\
\

If you are using 32-bit pointers, DECLARE_API remains the same, except that dwCurrentPc will be of the type ULONG instead of ULONG64. However, 64-bit pointers are
recommended for any extension that you are writing. See 32-Bit Pointers and 64-Bit Pointers for details.
2009 Microsoft Corporation
Send feedback on this topic

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1591 of 1651

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

Writing WdbgExts Extension Code

WdbgExts extension commands can call any standard C function, as well as the debugger-related functions that appear in the WdbgExts.h header file.
The WdbgExts functions are intended for use in debugger extension commands only. They are useful for controlling and inspecting the computer or application that is being
debugged. The WdbgExts.h header file should be included by any code that is calling these WdbgExts functions.
A number of these functions have 32-bit versions as well as 64-bit versions. Typically, the names of the 64-bit WdbgExts functions end in "64," for example ReadIoSpace64.
The 32-bit versions have no numerical ending, for example, ReadIoSpace. If you are using 64-bit pointers, you should use the function name ending in "64"; if you are using
32-bit pointers, you should use the "undecorated" function name. 64-bit pointers are recommended for any extension that you are writing. See 32-Bit Pointers and 64-Bit
Pointers for details.
WdbgExts extensions cannot use the C++ interfaces that appear in the DbgEng.h header file. If you wish to use these interfaces, you should write a DbgEng extension or an
EngExtCpp extension instead. Both DbgEng extensions and EngExtCpp extensions can use all the interfaces in DbgEng.h as well as those in WdbgExts.h. For details, see
Writing DbgEng Extensions and Writing EngExtCpp Extensions.
Note You must not attempt to call any DbgHelp or ImageHlp routines from a debugger extension. This is not supported and may cause a variety of problems.
The following topics give an overview of various categories of WdbgExts functions:
WdbgExts Input and Output
WdbgExts Memory Access
WdbgExts Threads and Processes
WdbgExts Symbols
WdbgExts Target Information
For a full list of these functions, see WdbgExts Functions.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Input and Output

This topic provides a brief overview of how input and output can be performed using the WdbgExts API. For an overview of the input and output streams in the debugger
engine, see Input and Output in the Debugger Engine Overview section of this documentation.
The function dprintf works in a way similar to the standard C printf function and prints a formatted string to the Debugger Command window or, more precisely, the
formatted string is sent to the output callbacks. To read a line of input from the debugger engine, use the function GetInputLine.
To check for a user-initiated interrupt, use CheckControlC. This function should be used in loops to determine if the user has attempted to cancel execution of an extension.
For a more powerful input and output API, see Using Input and Output in the Using the Debugger Engine API section of this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Memory Access

This topic provides a brief overview of how memory access can be performed using the WdbgExts API. For an overview of memory access in the debugger engine, see
Memory in the Debugger Engine Overview section of this documentation.
Virtual Memory
The virtual memory of the target can be read by using the ReadMemory function and written using the WriteMemory function. Pointers in the target's memory can be read
and written by using the ReadPointer, ReadPtr, and WritePointer functions.
To search the virtual memory for a pattern of bytes, use the SearchMemory function.
The TranslateVirtualToPhysical function can be used to convert a virtual memory address to a physical memory address.
The Disasm function can be used to disassemble a single assembly instruction on the target.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1592 of 1651

To check the low 4 GB of memory for corruption when using physical address extension (PAE), use the Ioctl operation IG_LOWMEM_CHECK.
Physical Memory
Physical memory can only be directly accessed in kernel-mode debugging.
The physical memory on the target can be read by using the ReadPhysical and ReadPhysicalWithFlags functions, and written by using the WritePhysical and
WritePhysicalWithFlags functions.
To search the physical memory for pointers to locations within a specified range, use the Ioctl operation IG_POINTER_SEARCH_PHYSICAL.
Other Data Spaces
In kernel-mode debugging, it is possible to read and write data to a variety of data spaces in addition to the main memory. The following data spaces can be accessed:
Control-Space Memory
The functions ReadControlSpace, ReadControlSpace64, ReadTypedControlSpace32, and ReadTypedControlSpace64 will read data from a control space. The
WriteControlSpace function will write data to a control space.
I/O Memory
The functions ReadIoSpace, ReadIoSpace64, ReadIoSpace64, ReadIoSpaceEx64 will read data from system I/O memory and bus I/O memory. The functions
WriteIoSpace, WriteIoSpace64, WriteIoSpaceEx, and WriteIoSpaceEx64 will write data to system I/O memory and bus I/O memory.
Model Specific Register (MSR)
The functions ReadMsr and WriteMsr read and write MSRs.
System Bus
The Ioctl operations IG_GET_BUS_DATA and IG_SET_BUS_DATA read and write system bus data.
Additional Information
For a more powerful memory access API, see Memory Access in the Using the Debugger Engine API section of this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Threads and Processes

This topic provides a brief overview of how threads and processes can be manipulated using the WdbgExts API. For an overview of threads and processes in the debugger
engine, see Threads and Processes in the Debugger Engine Overview section of this documentation.
Threads
To get the address of the thread environment block (TEB) that describes the current thread, use the method GetTebAddress. In kernel-mode debugging, the KTHREAD
structure is also available to describe a thread. This structure is returned by GetCurrentThreadAddr (in user-mode debugging, GetCurrentThreadAddr returns the address
of the TEB).
The thread context is the state preserved by Windows when switching threads; it is represented by the CONTEXT structure. This structure varies with the operating system
and platform and care should be taken when using the CONTEXT structure. The thread context is returned by the GetContext function and can be set using the SetContext
function.
To examine the stack trace for the current thread, use the StackTrace function. To temporarily change the thread used for examining the stack trace, use the
SetThreadForOperation or SetThreadForOperation64 functions. See Examining the Stack Trace in the Using the Debugger Engine API section of this documentation for
additional methods for examining the stack.
To get information about an operating system thread in the target, use the Ioctl operation IG_GET_THREAD_OS_INFO.
Processes
To get the address of the process environment block (PEB) that describes the current process use the method GetPebAddress. In kernel-mode debugging, the KPROCESS
structure is also available to describe a process. This structure is returned by GetCurrentProcessAddr (in user-mode debugging, GetCurrentProcessAddr returns the
address of the PEB).
The method GetCurrentProcessHandle returns the system handle for the current process.
Additional Information
For a more powerful thread manipulation and process manipulation API, see Controlling Threads and Processes in the Using the Debugger Engine API section of this
documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Symbols

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1593 of 1651

This topic provides a brief overview of how symbols can be manipulated using the WdbgExts API. For an overview of using symbols in the debugger engine, see Symbols in
the Debugger Engine Overview section of this documentation.
To evaluate a MASM or C++ expression, use the functions GetExpression or GetExpressionEx.
To read the value of a member in a structure, use the GetFieldData function or, if, the member contains a primitive value, GetFieldValue can be used. To determine the size
of an instance of a symbol in the target's memory, use the GetTypeSize function.
To locate the offset of a member in a structure, use the GetFieldOffset function.
To read multiple members in a structure, first use the InitTypeRead function to initialize the structure. Then, you can use the ReadField function to read the members with
size less than or equal to 8 bytes one at a time. For structure addresses in physical memory, use the InitTypeReadPhysical function instead of InitTypeRead.
There are two functions that you can use for iterating over linked lists. For doubly-linked lists that use the LIST_ENTRY32 or LIST_ENTRY64 structures, the function
ReadListEntry can be used to find the next and previous entries. The function ListType will iterate over all the entries in a linked list and call a callback function for each
entry.
To locate a symbol near a specified address in the target's memory, use the GetSymbol function.
To delete all the symbol information from the debugger engine's cache, use the ReloadSymbols function. To read or change the symbol path, which is used to search for
symbol files, use the GetSetSympath function.
Almost all symbol operations provided by the debugger engine can be executed using the Ioctl operation IG_DUMP_SYMBOL_INFO. However, while being a very
flexible function, it is advanced and we recommend that you use the above simpler functions where applicable.
Additional Information
For a more powerful symbols API, see Using Symbols in the Using the Debugger Engine API section of this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Target Information

To determine if the target uses 32-bit or 64-bit pointers for memory addresses, use the function IsPtr64.
For information about the target's operating system, use the Ioctl operation IG_GET_KERNEL_VERSION. To get the total number of processors on the target and find out
which one is the current processor, use the function GetKdContext.
The GetDebuggerData function returns a KDDEBUGGER_DATA64 or KDDEBUGGER_DATA32 structure that contains information about the target that the debugger
engine has queried or determined during the current session. This information includes certain key target locations and specific status values.
The debugger caches some information obtained from the target. The function GetDebuggerCacheSize will return the size of this cache.
Additional Information
For a more powerful target API, see Target Information in the Using the Debugger Engine API section of this documentation.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Building WdbgExts Extensions

All debugger extensions should be compiled and built with the Build utility. The Build utility is included in the Windows Driver Kit (WDK) and in earlier versions of the
Windows DDK.
For more information on the Build utility, see the WDK documentation.
Note the following points:

The WDK has several different build environment windows. Each of these has a corresponding shortcut placed in the Start menu when the WDK is installed. To build
a debugger extension, you must use the latest Windows build environment, regardless of what platform you will be running the extension on.
The Build utility is usually not able to compile code that is located in a directory path that contains spaces. Your extension code should be located in a directory whose
full path contains no spaces. (In particular, this means that if you install Debugging Tools for Windows to the default location Program Files\Debugging Tools for
Windows you will not be able to build the sample extensions.)

To build a debugger extension

1. Open the window for the latest Windows build environment. (You can choose either the "free" version or the "checked" version they will give identical results unless
you have put #ifdef DBG statements in your code.)
2. Set the variable _NT_TARGET_VERSION to indicate the oldest version of Windows on which you want to run the extension. _NT_TARGET_VERSION can be set to

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1594 of 1651

the following values.

Value
Versions of Windows
_NT_TARGET_VERSION_WIN2K
Windows 2000 and later.
_NT_TARGET_VERSION_WINXP
Windows XP and later.
_NT_TARGET_VERSION_WS03
Windows Server 2003 and later.
_NT_TARGET_VERSION_LONGHORN Windows Vista and later.
If _NT_TARGET_VERSION is not set, the extension will only run on the version of Windows for which the build window was opened (and later versions). For
example, putting the following line in your Sources file will build an extension that will run on Windows XP and later versions of Windows:
_NT_TARGET_VERSION = $(_NT_TARGET_VERSION_WINXP)
3. 3.Set the DBGSDK_INC_PATH and DBGSDK_LIB_PATH environment variables to specify the paths to the debugger SDK headers and the debugger SDK libraries,
respectively. If %debuggers% represents the root of your Debugging Tools for Windows installation, these variables should be set as follows:
set DBGSDK_INC_PATH=%debuggers%\sdk\inc
set DBGSDK_LIB_PATH=%debuggers%\sdk\lib
If you have moved these headers and libraries to a different location, specify that location instead.
4. 4.Change the current directory to the directory that contains your extension's Dirs file or Sources file.
5. 5.Run the Build utility:
build -cZMg
For a full explanation of these steps, and for a description of how to create a Dirs file and a Sources file, see the Build utility documentation in the WDK.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Extension Reference

This section includes:
WdbgExts Extension Callback Functions
WdbgExts Functions
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Extension Callback Functions

This section includes:
WinDbgExtensionDllInit
ExtensionApiVersion
CheckVersion
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WinDbgExtensionDllInit
The WinDbgExtensionDllInit callback function is used to load and initialize the extension module.
VOID
WinDbgExtensionDllInit(
PWINDBG_EXTENSION_APIS64
USHORT MajorVersion
USHORT MinorVersion

lpExtensionApis

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1595 of 1651

);
Parameters
lpExtensionApis
Receives a pointer to a WINDBG_EXTENSION_APIS64 structure. This structure contains the callbacks to functions that you can use to do standard operations. Save the
pointer in a global variable named ExtensionApis.
MajorVersion
Specifies the Microsoft Windows build type. A value of 0xC indicates the checked build of Windows; a value of 0xF indicates the free build of Windows. Save this value
in a global variable named SavedMajorVersion.
MinorVersion
Specifies the Windows build number of the target system. For example, 2600. Save this value in a global variable named SavedMinorVersion.
Return Value
None
Headers
You must define this function in your code using the prototype above. Include wdbgext.h.
Comments
WinDbgExtensionDllInit is called by the debugger when the extension DLL is loaded.
It is recommended that you always use 64-bit pointers in your code, since the debugger will automatically resize these pointers when necessary. See 32-Bit Pointers and 64Bit Pointers for details. However, if you choose to use 32-bit pointers, the first parameter of WinDbgExtensionDllInit will have the type PWINDBG_EXTENSION_APIS
instead of PWINDBG_EXTENSION_APIS64.
Additional Information
For more details, see Using WdbgExts Extension Callbacks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ExtensionApiVersion
The ExtensionApiVersion callback function returns version information about the extension DLL.
LPEXT_API_VERSION
ExtensionApiVersion(
VOID
);
Parameters
None
Return Value
This function must return a pointer to an API_VERSION structure.
Headers
You must define this function in your code using the prototype above. Include wdbgext.h.
Comments
ExtensionApiVersion is called by the debugger when the extension DLL is loaded.
The debugger uses the MajorVersion and MinorVersion fields of the returned API_VERSION structure when executing commands like .chain and version that display the
extension version number. The debugger does not perform any "version checking" the extension DLL will be loaded regardless of what version numbers are present in
these fields.
The Revision field of the returned API_VERSION structure should be EXT_API_VERSION_NUMBER64 if you are using 64-bit pointers in your code, or
EXT_API_VERSION_NUMBER32 if you are using 32-bit pointers. It is recommended that you always use 64-bit pointers in your code, since the debugger will
automatically resize these pointers when necessary. See 32-Bit Pointers and 64-Bit Pointers for details.
Additional Information
For more details, see Using WdbgExts Extension Callbacks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1596 of 1651

December 09, 2009

Debugging Tools for Windows

CheckVersion
The CheckVersion callback function verifies that the extension module version matches the debugger version, and outputs an warning message if there is a mismatch.
VOID
CheckVersion(
VOID
);
Parameters
None
Return Value
None
Headers
You must define this function in your code using the prototype above. Include wdbgext.h.
Comments
CheckVersion is an optional callback function. If it exists, it will be called by the debugger the first time an extension function exported by the extension DLL is used.
The purpose of this function is to allow you to print out a version mismatch warning when the extension DLL is used. This is an optional feature, which should not be
confused with the version number used by ExtensionApiVersion.
If the .noversion command is used, version checking is disabled and the debugger will not call CheckVersion.
Additional Information
For more details, see Using WdbgExts Extension Callbacks.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WdbgExts Functions
The wdbgexts.h header file contains prototypes for the following functions. These functions use the same prototype for both 32-bit and 64-bit extensions:
GetContext
SetContext
CheckControlC
GetCurrentProcessAddr
GetCurrentProcessHandle
GetCurrentThreadAddr
GetDebuggerCacheSize
GetDebuggerData
Disasm
dprintf
GetExpression
GetExpressionEx
GetInputLine
Ioctl
GetKdContext
ReadMemory

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1597 of 1651

SearchMemory
WriteMemory
ReadMsr
WriteMsr
GetPebAddress
ReadPhysical
ReadPhysicalWithFlags
WritePhysical
WritePhysicalWithFlags
GetTebAddress
StackTrace
GetSymbol
ReloadSymbols
GetSetSympath
TranslateVirtualToPhysical
The wdbgexts.h header file contains prototypes for the following functions. These functions have different prototypes for 32-bit and 64-bit extensions:
ReadControlSpace
ReadControlSpace64
ReadTypedControlSpace32
ReadTypedControlSpace64
WriteControlSpace
ReadIoSpace
ReadIoSpace64
ReadIoSpaceEx
ReadIoSpaceEx64
WriteIoSpace
WriteIoSpace64
WriteIoSpaceEx
WriteIoSpaceEx64
SetThreadForOperation
SetThreadForOperation64
The wdbgexts.h header file contains prototypes for the following functions. These functions can be used only in 64-bit extensions:
GetFieldData
GetFieldOffset
GetFieldValue
GetShortField
ReadField
ReadListEntry
ReadPointer
WritePointer
IsPtr64
ReadPtr

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1598 of 1651

GetTypeSize
InitTypeRead
InitTypeReadPhysical
ListType
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Specifies the size of the data block, including the header.

Return Value
If the data block is found, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers:
Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include wdbgexts.h before
dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Disasm
The Disasm function disassembles the instruction pointed to by lpOffset and places the printable string into lpBuffer.
ULONG
Disasm (
PULONG lpOffset,
PCSTR lpBuffer,
ULONG fShowEffectiveAddress
);
Parameters
lpOffset
Points to the instruction to be disassembled.
lpBuffer
Receives the disassembled instruction.
fShowEffectiveAddress
Specifies whether or not to print the effective address.
Return Value
If the routine succeeds, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

dprintf
The dprintf function prints a formatted string to the Debugger Command window. It works like the C-language routine printf.
VOID
dprintf (
PCSTR format
. . . . [arguments]
);
Parameters
format
Specifies the format string, as in printf. In general, conversion characters work exactly as in C. For the floating-point conversion characters the 64-bit argument is
interpreted as a 32-bit floating-point number unless the l modifier is used.
The %p conversion character is supported, but it represents a pointer in the target's virtual address space. It may not have any modifiers and it uses the debugger's
internal address formatting. The following additional conversion characters are supported:
Character
Argument Type
%p
ULONG64
%N
DWORD_PTR (32 or 64 bits,

Argument
Pointer in the target's virtual address space
Pointer in the host's virtual address space

Text printed
The value of the pointer.
The value of the pointer. (This is equivalent to the standard C %p

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

depending on the host's architecture)

ULONG64

%ma

ULONG64

%mu

ULONG64

%msa

ULONG64

%msu

ULONG64

%ly

ULONG64

Page 1603 of 1651

Any 64-bit value

Address of a NULL-terminated ASCII string in

the target's virtual address space
Address of a NULL-terminated Unicode string in
the target's virtual address space
Address of an ANSI_STRING structure in the
target's virtual address space
Address of a UNICODE_STRING structure in
the target's virtual address space
Address of a debugger symbol in the target's
virtual address space
Address of a debugger symbol in the target's
virtual address space

character.)
The specified value. If this is greater than 0xFFFFFFFF it is
printed as a 64-bit address, otherwise it is printed as a 32-bit
address.
The specified string.
The specified string.
The specified string.
The specified string.
String containing the name of the specified symbol (and
displacement, if any).
String containing the name of the specified symbol (and
displacement, if any), as well as any available source line
information.

arguments
Specifies arguments for the format string, as in printf. The number of arguments specified should match the number of conversion characters in FormatString. Each
argument is an expression that will be evaluated by the default expression evaluator (MASM or C++). For details, see Numerical Expression Syntax.
Return Value
None
Comments
When generating very large output strings, it is possible the limits of the debugger engine or operating system may be reached. For example, some versions of the debugger
engine have a 16K character limit for a single piece of output. If you find that very large output is getting truncated, you may need to split your output into multiple requests.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetExpression
The GetExpression function returns the value of expression. The expression is evaluated using the current expression evaluator, and can contain aliases.
ULONG
GetExpression (
PCSTR expression
);
Parameters
expression
Specifies the expression to evaluate.
Return Value
The value of the expression passed to GetExpression.
Comments
The expression is evaluated by the current expression evaluator (either the MASM or C++ expression evaluator); see Numerical Expression Syntax for details. Aliases will be
properly understood; see Using Aliases for details.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1604 of 1651

GetExpressionEx
The GetExpressionEx function evaluates an expression. The expression is evaluated using the MASM evaluator, and can contain aliases.
BOOL
GetExpressionEx(
PCSTR Expression,
ULONG64 * Value,
PCSTR * Remainder
);
Parameters
Expression
Specifies the expression to evaluate. The expression uses the MASM syntax. For details of this syntax, see MASM Numbers and Operators.
Value
Receives the value of the expression.
Remainder
Receives a pointer to the first character in the expression Expression that was not used in the evaluation of the expression.
Return Value
GetExpressionEx returns one of the following values:
TRUE
The expression was evaluated successfully.
FALSE
An error occurred while attempting to evaluate the expression.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
GetExpression
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetInputLine
The GetInputLine function requests an input string from the debugger.
ULONG
GetInputLine(
PCSTR Prompt,
PSTR Buffer,
ULONG BufferSize
);
Parameters
Prompt
Specifies a prompt to indicate what input is being requested. The prompt is printed to the debugger's output before the input is gathered. If Prompt is NULL, no prompt is
printed.
Buffer
Specifies the buffer to receive the input.
BufferSize
Specifies the size, in characters, of the buffer Buffer.
Return Value
GetInputLine returns the size, in characters, of the input returned to the Buffer buffer, or zero, if no input was returned.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1605 of 1651

Debugging Tools for Windows

Ioctl
The Ioctl function performs a variety of different operations. Much of its functionality mirrors the functionality of other functions in wdbgexts.h.
ULONG
Ioctl (
USHORT IoctlType,
PVOID lpvData,
ULONG cbSizeOfContext
);
Parameters
IoctlType
Specifies which Ioctl operation to perform. For a list of possible IoctlType values, see the Comments section.
lpvData
Points to the address of a data structure. The type of structure that is required depends on the value of IoctlType.
cbSizeOfContext
Specifies the size of the structure that lpvData points to.
Return Value
The meaning of return value depends on IoctlType. See the page for the corresponding Ioctl operation for the meaning of the return value.
Comments
The Ioctl function is the entry point for many of the functionalities supplied for WdbgExts extensions. Many of the other functions in wdbgexts.h are simply wrappers for calls
to Ioctl.
The following table lists the possible IoctlType values. If the IoctlType corresponds to another function, that function is provided; otherwise, a link to the page describing the
Ioctl operation is provided.
IoctlType constant
IG_KD_CONTEXT
IG_READ_CONTROL_SPACE

Equivalent function
GetKdContext
ReadControlSpace
ReadControlSpace64

IG_WRITE_CONTROL_SPACE
IG_READ_IO_SPACE

WriteControlSpace
ReadIoSpace
ReadIoSpace64

IG_WRITE_IO_SPACE

WriteIoSpace
WriteIoSpace64

IG_READ_PHYSICAL
IG_WRITE_PHYSICAL
IG_READ_IO_SPACE_EX

ReadPhysical
WritePhysical
ReadIoSpaceEx
ReadIoSpaceEx64

IG_WRITE_IO_SPACE_EX

WriteIoSpaceEx
WriteIoSpaceEx64

IG_SET_THREAD

SetThreadForOperation
SetThreadForOperation64

IG_READ_MSR
IG_WRITE_MSR
IG_GET_DEBUGGER_DATA
IG_GET_KERNEL_VERSION
IG_RELOAD_SYMBOLS
IG_GET_SET_SYMPATH
IG_GET_EXCEPTION_RECORD
IG_IS_PTR64
IG_GET_BUS_DATA
IG_SET_BUS_DATA
IG_DUMP_SYMBOL_INFO
IG_LOWMEM_CHECK
IG_SEARCH_MEMORY

ReadMsr
WriteMsr
GetDebuggerData
ReloadSymbols
GetSetSympath
IsPtr64

SearchMemory

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1606 of 1651

IG_GET_CURRENT_THREAD
GetCurrentThreadAddr
IG_GET_CURRENT_PROCESS
GetCurrentProcessAddr
IG_GET_TYPE_SIZE
GetTypeSize
IG_GET_CURRENT_PROCESS_HANDLE
GetCurrentProcessHandle
IG_GET_INPUT_LINE
GetInputLine
IG_GET_EXPRESSION_EX
GetExpressionEx
IG_TRANSLATE_VIRTUAL_TO_PHYSICAL TranslateVirtualToPhysical
IG_GET_CACHE_SIZE
GetDebuggerCacheSize
IG_READ_PHYSICAL_WITH_FLAGS
ReadPhysicalWithFlags
IG_WRITE_PHYSICAL_WITH_FLAGS
WritePhysicalWithFlags
IG_POINTER_SEARCH_PHYSICAL
IG_GET_THREAD_OS_INFO
IG_GET_CLR_DATA_INTERFACE
IG_GET_TEB_ADDRESS
GetTebAddress
IG_GET_PEB_ADDRESS
GetPebAddress
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IG_DUMP_SYMBOL_INFO
The IG_DUMP_SYMBOL_INFO Ioctl operation provides information about the type of a symbol. When calling Ioctl with IoctlType set to IG_DUMP_SYMBOL_INFO,
IpvData should contain an instance of the SYM_DUMP_PARAM structure.
typedef struct _SYM_DUMP_PARAM {
ULONG size;
PUCHAR sName;
ULONG Options;
ULONG64 addr;
PFIELD_INFO listLink;
union {
PVOID Context;
PVOID pBuffer;
};
PSYM_DUMP_FIELD_CALLBACK CallbackRoutine;
ULONG nFields;
PFIELD_INFO Fields;
ULONG64 ModBase;
ULONG TypeId;
ULONG TypeSize;
ULONG BufferSize;
ULONG fPointer:2;
ULONG fArray:1;
ULONG
fStruct:1;
ULONG fConstant:1;
ULONG Reserved:27;
} SYM_DUMP_PARAM, *PSYM_DUMP_PARAM;
Members
size
Specifies the size, in bytes, of this structure. It should be set to sizeof(SYM_DUMP_PARAM).
sName
Specifies the name of the symbol to lookup.
Options
Specifies the flags that determine the behavior of this Ioctl operation. For a description of these flags, see DBG_DUMP_XXX.
addr
Specifies the address of the symbol.
listLink
Specifies the field that contains the next item in a linked list. If the symbol is an entry in a linked list, this Ioctl operation can iterate over the items in the list using the
field specified here as the pointer to the next item in the list. The type of this structure is FIELD_INFO.
The callback function specified in the fieldCallBack member of this structure is called, during this Ioctl operation, for each item in the list. When it is called, it is passed
this linkList structure with the members filled in for the list entry along with the contents of the Context member.
DBG_DUMP_LIST should be set in Options to tell this Ioctl to iterate over the list.
Context
Specifies a pointer that is passed to the callback function in the CallbackRoutine member and to the callback functions in the fieldCallBack member of the linkList and

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1607 of 1651

IG_DUMP_SYMBOL_INFO, Ioctl, FIELD_INFO

2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

PSYM_DUMP_FIELD_CALLBACK
The PSYM_DUMP_FIELD_CALLBACK callback function is called by the debugger engine during the IG_DUMP_SYMBOL_INFO Ioctl operation with information about
a member in the specified symbol.
typedef
ULONG
(WDBGAPI * PSYM_DUMP_FIELD_CALLBACK)(
struct _FIELD_INFO * pField,
PVOID UserContext
);
Parameters
pField
Specifies the field for which this callback function is being called. The debugger engine fills in the contents of this parameter before making the call. See FIELD_INFO
for details about the members of this parameter.
UserContext
Specifies the user context object passed to the Ioctl operation in the Context member of the SYM_DUMP_PARAM structure.
Return Value
If the function is successful, it should return STATUS_SUCCESS. Otherwise, it should return an appropriate error code.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that uses this function prototype,
include wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details). STATUS_SUCCESS and other status and error codes are defined in ntstatus.h.
See Also
IG_DUMP_SYMBOL_INFO, Ioctl, FIELD_INFO
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IG_DUMP_SYMBOL_INFO Error Codes

The following error codes can be returned by IG_DUMP_SYMBOL_INFO and related functions and macros.
Successful result. A successful result always returns zero.
Error results. Nonzero return values represent errors. These values are defined in WDbgExts.h.
MEMORY_READ_ERROR
An error occurred while reading memory.
SYMBOL_TYPE_INDEX_NOT_FOUND
The internal index containing symbol type information was not found.
SYMBOL_TYPE_INFO_NOT_FOUND
Information about a specific symbol type was not found.
FIELDS_DID_NOT_MATCH
Mismatched parameters were passed to this routine.
NULL_SYM_DUMP_PARAM
NULL_FIELD_NAME
INCORRECT_VERSION_INFO
A version mismatch occurred.
EXIT_ON_CONTROLC
The user pressed CTRL+C or CTRL+BREAK before the routine completed.
CANNOT_ALLOCATE_MEMORY
A memory allocation error occurred.
INSUFFICIENT_SPACE_TO_COPY
A memory write error occurred.
ADDRESS_TYPE_INDEX_NOT_FOUND
A problem occurred when attempting to access the internal index containing type information.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1611 of 1651

Headers: Defined in WDbgExts.h. Include WDbgExts.h.

See Also
IG_DUMP_SYMBOL_INFO, Ioctl
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IG_GET_BUS_DATA
The IG_GET_BUS_DATA Ioctl operation reads data from a system bus and the IG_SET_BUS_DATA Ioctl operation writes data to a system bus. When calling Ioctl with
IoctlType set to IG_GET_BUS_DATA or IG_SET_BUS_DATA, IpvData should contain an instance of the BUSDATA structure.
typedef struct _GETSETBUSDATA {
ULONG BusDataType;
ULONG BusNumber;
ULONG SlotNumber;
PVOID Buffer;
ULONG Offset;
ULONG Length;
} BUSDATA, *PBUSDATA;
Members
BusDataType
Specifies the bus data type to use. For details of allowed values, see the documentation for the BUS_DATA_TYPE enumeration in the Platform SDK.
BusNumber
Specifies the system-assigned number of the bus. This is usually zero, unless the system has more than one bus of the same bus data type.
SlotNumber
Specifies the logical slot number on the bus.
Buffer
Specifies the buffer that contains the memory to write to the bus, or to receive the memory that is read from the bus.
The size of Buffer must be at least the value of Length.
Offset
Specifies the offset in the bus data to start reading from or writing to.
Length
Specifies the number of bytes to read from or write to the bus when the Ioctl operation is called. Upon returning, Length is set to the number of bytes actually read or
written.
Return Value
If this Ioctl operation succeeds, the return value from Ioctl is TRUE; otherwise, it is FALSE.
Comments
The parameters for the IG_GET_BUS_DATA and IG_SET_BUS_DATA Ioctl operations are the members of the BUSDATA structure.
This operation is only available in kernel-mode debugging.
The properties of the data in the bus depends on the system, bus, and slot.
Requirements
Headers: Declared in wdbgexts.h. If you are writing a DbgEng extension that uses this Ioctl operation, include wdbgexts.h before dbgeng.h (see Writing DbgEng Extension
Code for details).
See Also
Ioctl
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Comments
The parameters for the IG_POINTER_SEARCH_PHYSICAL Ioctl operation are the members of the POINTER_SEARCH_PHYSICAL structure.
Requirements
Headers: Declared in wdbgexts.h. If you are writing a DbgEng extension that uses this Ioctl operation, include wdbgexts.h before dbgeng.h (see Writing DbgEng Extension
Code for details).
See Also
Ioctl
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetKdContext
The GetKdContext function returns the total number of processors and the number of the current processor in the structure ppi points to.
ULONG
GetKdContext (
PPROCESSORINFO ppi
);
Parameters
ppi
Points to the following structure:
typedef struct _tagPROCESSORINFO {
USHORT Processor;
// current processor
USHORT NumberProcessors;
// total number of processors
} PROCESSORINFO, *PPROCESSORINFO;
Return Value
The total number of processors.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadMemory
The ReadMemory function works like the Win32 ReadProcessMemory function. It reads memory from the process being debugged. The entire area to be read must be
accessible, or the operation fails.
ULONG
ReadMemory (
ULONG_PTR offset,
PVOID lpBuffer,
ULONG cb,
PULONG lpcbBytesRead
);
Parameters
offset
Specifies the base address of the memory to be read in the process that is being debugged.
lpBuffer
Points to the buffer to receive the memory read.
cb
Specifies the number of bytes that you want ReadMemory to read.
lpcbBytesRead
Receives the actual number of bytes that ReadMemory transferred into the buffer. This parameter is optional; if it is NULL, it is ignored.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1616 of 1651

Return Value
If the routine succeeds, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

SearchMemory
The SearchMemory function searches the target's virtual memory for a specified pattern of bytes.
VOID
SearchMemory(
ULONG64 SearchAddress,
ULONG64 SearchLength,
ULONG PatternLength,
PVOID Pattern,
PULONG64 FoundAddress
);
Parameters
SearchAddress
Specifies the address in the target's virtual memory from which to start the search.
SearchLength
Specifies the size, in bytes, of the memory to search. For a successful match, the pattern must be found before SearchLength bytes have been examined.
PatternLength
Specifies the size, in bytes, of the pattern to search for.
Pattern
Specifies the pattern to search for.
FoundAddress
Receives the location of the pattern, found in the target's virtual memory. If the pattern was not found, the value in FoundAddress is unchanged by this function.
Return Value
None
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WriteMemory
The WriteMemory function works like the Win32 WriteProcessMemory routine. It writes memory to the process being debugged. The entire area to be written must be
accessible, or the operation fails.
ULONG
WriteMemory (
ULONG_PTR offset,
LPCVOID lpbuffer,
ULONG cb,
PULONG lpcbBytesWritten
);
Parameters
offset
Specifies the base address of the memory to be written in the process that is being debugged.
lpbuffer
Points to the buffer that contains the data to be written.
cb
Specifies the number of bytes that WriteMemory should write.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1617 of 1651

lpcbBytesWritten
Receives the actual number of bytes that WriteMemory transferred from the buffer. This parameter is optional; if it is NULL, it is ignored.
Return Value
If the routine succeeds, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

The actual number of frames written to the buffer pointed to by StackFrames.

GetSymbol
The GetSymbol function locates the symbol nearest to address.
VOID
GetSymbol (
PVOID offset,
PUCHAR pchBuffer,
PULONG pDisplacement
);
Parameters
offset
Specifies an address near the symbol you want located.
pchBuffer
Receives the name of the symbol found.
pDisplacement
Specifies the displacement from the beginning of the symbol.
Return Value
None
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReloadSymbols
The ReloadSymbols function deletes symbol information from the debugger so that it can be reloaded as needed. This function behaves the same way as the debugger
command .reload.
VOID
ReloadSymbols(
IN OPTIONAL PSTR
);

Arg

Parameters
Arg
Specifies the arguments for the debugger command .reload. For example, setting Arg to /u ntdll.dll has the same effect as the command .reload /u ntdll.dll.
Return Value
None
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
.reload (Reload Module)

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1623 of 1651

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

2009 Microsoft Corporation

Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WriteControlSpace
The WriteControlSpace function writes to the processor-specific control space of the current target.
VOID
WriteControlSpace(
USHORT processor,
ULONG address,
PVOID buf,
ULONG size
);
Parameters
processor
Specifies the index of the processor whose control space is to be written.
address
Specifies the address of the control space.
buf
Specifies the data to be written to the control space.
size
Specifies the number of bytes to be written. This is the number of bytes in the buf buffer.
Return Value
None
Comments
This function can only be called in kernel-mode debugging.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
ReadControlSpace, ReadControlSpace64
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadIoSpace
The ReadIoSpace function reads from the system I/O locations.
VOID
ReadIoSpace (
ULONG address,
PULONG data,
PULONG size
);
Parameters
address
Specifies the I/O address to read from.
data
Specifies the address of a variable to hold the data read. This must be at least the number of bytes contained in size.
size
Specifies the address of a variable that contains the number of bytes to read (1, 2, or 4 only). After the data is read, size will contain the number of bytes actually read.
Return Value
None
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1627 of 1651

If you are writing 64-bit code, you should use ReadIoSpace64 instead. See 32-Bit Pointers and 64-Bit Pointers for details.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadIoSpace64
The ReadIoSpace64 function reads from the system I/O locations.
VOID
ReadIoSpace (
ULONG64 address,
PULONG data,
PULONG size
);
Parameters
address
Specifies the I/O address to read from.
data
Specifies the address of a variable to hold the data read. This must be at least the number of bytes contained in size.
size
Specifies the address of a variable that contains the number of bytes to read. Size must be 1, 2, or 4. After the data is read, size will contain the number of bytes actually
read.
Return Value
None
Comments
If you are writing 32-bit code, you should use ReadIoSpace instead. See 32-Bit Pointers and 64-Bit Pointers for details.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadIoSpaceEx
The ReadIoSpaceEx function is an extended version of ReadIoSpace. It reads not only the system I/O locations, but also I/O locations on a bus. ReadIoSpace works like
ReadIoSpaceEx, except that it defaults interfacetype to ISA, busnumber to zero, and addressspace to 1.
VOID
ReadIoSpaceEx (
ULONG address,
PULONG data,
PULONG size,
ULONG interfacetype,
ULONG busnumber,
ULONG addressspace
);
Parameters
address
Specifies the I/O address to read from.
data
Specifies the address of a variable to hold the data read. This must be at least the number of bytes contained in size.
size
Specifies the address of a variable that contains the number of bytes to read. Size must be 1, 2, or 4. After the data is read, size will contain the number of bytes actually
read.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1628 of 1651

interfacetype
Specifies the type of interface on which the extended I/O space exists. Possible values include ISA, EISA, and MCA. For more information, see ntddk.h, which is
available as part of Windows Driver Kit.
busnumber
Specifies the number of the bus on which the extended I/O space exists. This is typically zero, unless there is more than one bus of a given type.
addressspace
This is typically 1.
Return Value
None
Comments
If you are writing 64-bit code, you should use ReadIoSpaceEx64 instead. See 32-Bit Pointers and 64-Bit Pointers for details.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadIoSpaceEx64
The ReadIoSpaceEx64 function is an extended version of ReadIoSpace64. It reads not only the system I/O locations, but also I/O locations on a bus. ReadIoSpace64 works
like ReadIoSpaceEx64, except that it defaults interfacetype to ISA, busnumber to zero, and addressspace to 1.
VOID
ReadIoSpaceEx (
ULONG64 address,
PULONG data,
PULONG size,
ULONG interfacetype,
ULONG busnumber,
ULONG addressspace
);
Parameters
address
Specifies the I/O address to read from.
data
Specifies the address of a variable to hold the data read. This must be at least the number of bytes contained in size.
size
Specifies the address of a variable that contains the number of bytes to read. Size must be 1, 2, or 4. After the data is read, size will contain the number of bytes actually
read.
interfacetype
Specifies the type of interface on which the extended I/O space exists. Possible values include ISA, EISA, and MCA. For more information, see ntddk.h, which is
available as part of Windows Driver Kit.
busnumber
Specifies the number of the bus on which the extended I/O space exists. This is typically zero, unless there is more than one bus of a given type.
addressspace
This is typically 1.
Return Value
None
Comments
If you are writing 32-bit code, you should use ReadIoSpaceEx instead. See 32-Bit Pointers and 64-Bit Pointers for details.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

TypeAddress
The meaning of this parameter depends on the value of StoreAddress.
If StoreAddress is non-zero:
Specifies the address of the structure in the target's memory. This address is used for subsequent calls when StoreAddress is zero.
If StoreAddress is zero:
TypeAddress is ignored. The value of TypeAddress from the last call when StoreAddress was non-zero is used to specify the address of the structure in the target's
memory.
Name
The meaning of this parameter depends on the value of StoreAddress.
If StoreAddress is non-zero:
Specifies the name of the type of the structure at TypeAddress.
If StoreAddress is zero:
Specifies the name of the member in the structure to read. The address and type of the structure are remembered from a previous call to this function with
StoreAddress not equal to zero. Submembers can be specified by using a period-separated path, for example, "myfield.mysubfield".
StoreAddress
Specifies the mode of this function.
If StoreAddress is non-zero:
Causes this function to initialize a structure for reading its members. The address and type name for the structure is remembered.
If the bit value 0x2 is set in StoreAddress, the address TypeAddress is considered a physical address; otherwise, it is considered a virtual address.
If StoreAddress is zero:
Causes this function to read a member from a previously initialized structure.
Return Value
If StoreAddress is non-zero:
If the function succeeds, it returns the value zero. If the function fails because the caller passed a zero value as TypeAddress, it returns the value
MEMORY_READ_ERROR (defined in Wdbgexts.h). If the function fails for any other reason, it returns an IG_DUMP_SYMBOL_INFO error code.
If StoreAddress is zero:
If the function succeeds, it returns the value of the specified field in the previously initialized structure. The structure is the one initialized in a previous call to
GetShortField. The field is the one specified by the Name parameter of the current call to GetShortField. The return value is cast to ULONG64. If the function fails, it
returns the value zero.
Comments
When GetShortField is called with a nonzero StoreAddress value, it initializes the structure located at the address specified by TypeAddress. Only one structure can be
initialized at a time. If GetShortField is called more than once with a nonzero StoreAddress value, only the structure specified in the most recent call is initialized. When
GetShortField is called with StoreAddress equal to zero, it accesses the most recently initialized structure, reads in that structure the field specified by Name, and returns the
value of that field.
This function does not need to be called directly. The macros InitTypeRead and InitTypeReadPhysical call this function with StoreAddress non-zero to prepare a structure
for reading its members. The macro ReadField calls this function with StoreAddress (and TypeAddress) equal to zero, to read members from the structure.
Note because this function stores the TypeAddress and Name by using static local variables, and because this function is defined in WdbgExts.h, the C pre-processor will
create a new instance of this function for each DLL, and TypeAddress and Name will only be available within a single source file. In other words, the structure must be
initialized in the same source file from which the members are read.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
InitTypeRead, InitTypeReadPhysical, ReadField
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadField
The ReadField and ReadFieldStr macros read a field whose size is less than 8 bytes from a structure initialized with InitTypeRead or InitTypeReadPhysical.
#define ReadField(Field) \
GetShortField(0, #Field, 0)
#define ReadFieldStr(FieldStr) \
GetShortField(0, FieldStr, 0)
Parameters
Field
Specifies the name of the field. The C-preprocessor will turn Field into a string.
FieldStr
Specifies the name of the field. FieldStr is expected to be an ASCII string.
Return Value

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1635 of 1651

If this macro succeeds, it returns the value of the specified field in the previously initialized structure. The structure is the one initialized in a previous call to InitTypeRead,
InitTypeStrRead, InitTypeReadPhysical, InitTypeStrReadPhysical, or GetShortField. The field is the one specified by the Field or FieldStr parameter of ReadField.
The return value is cast to ULONG64. If the function fails, it returns the value zero.
Comments
The parameter Field is the name of the member. For ReadField, the C pre-processor will turn the parameter into a string. For ReadFieldStr, Field is expected to already be
an ASCII string. For example, the following two commands are identical and read the same member from a previously initialized structure:
ReadField( myField );
ReadFieldStr( "myField" );
Submembers can be read by using a period-separated path, for example, "myField.mySubfield".
Note Because these macros use the GetShortField function, they must be called from the same source code file as the macros that initialize the structure for reading. For
more details, see GetShortField.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that uses this macro, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
InitTypeRead, InitTypeReadPhysical, GetShortField
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadListEntry
The ReadListEntry function reads a doubly-linked list entry from the target's memory.
ULONG
ReadListEntry(
ULONG64 Address,
PLIST_ENTRY64 List
);
Parameters
Address
Specifies the address of the list entry in the target. If the target uses 32-bit pointers, this should be the address of a LIST_ENTRY32 structure. If the target uses 64-bit
pointers, this should be the address of a LIST_ENTRY64 structure.
List
Receives a LIST_ENTRY64 structure that contains pointers to the previous and next entries in the list. If the target uses 32-bit pointers, they are sign-extended to 64 bits.
Return Value
If the function succeeds, the return value is TRUE; otherwise, it is FALSE.
Comments
For more information about the LIST_ENTRY structures, see the Windows Driver Kit (WDK) documentation.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
LIST_ENTRY64 and LIST_ENTRY32 are defined in winnt.h.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadPointer
The ReadPointer function reads a pointer from the target.
ULONG
ReadPointer(

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1636 of 1651

ULONG64 Address,
PULONG64 Pointer
);
Parameters
Address
Specifies the address of the pointer to read.
Pointer
Receives the value of the pointer. If the target uses 32-bit pointers, the pointer is sign-extended to 64 bits.
Return Value
If the function succeeds, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
WritePointer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

WritePointer
The WritePointer function writes a pointer to the target.
ULONG
WritePointer(
ULONG64 Address,
ULONG64 Pointer
);
Parameters
Address
Specifies the address to write the pointer to.
Pointer
Specifies the value of the pointer. If the target uses 32-bit pointers, Pointer is a 32-bit value that has been sign-extended to 64-bits.
Return Value
If the function succeeds, the return value is TRUE; otherwise, it is FALSE.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
ReadPointer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

IsPtr64
The IsPtr64 function determines if the target uses 64-bit pointers.
ULONG
IsPtr64(
void
);
Parameters

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1637 of 1651

None
Return Value
The function returns TRUE if the target uses 64-bit pointers; FALSE, otherwise.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ReadPtr
The ReadPtr function reads a pointer from the target. ReadPointer should be used instead of this function as the return value of ReadPointer is more consistent with the rest
of the WdbgExts API.
ULONG
ReadPtr(
ULONG64 Addr,
PULONG64 pPointer
);
Parameters
Addr
Specifies the address of the pointer to read.
pPointer
Receives the value of the pointer. If the target uses 32-bit pointers, the pointer is sign-extended to 64 bits.
Return Value
If the function succeeds, the return value is FALSE; otherwise, it is TRUE.
Comments
This function is identical to ReadPointer, except the meaning of the return value is reversed.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
ReadPointer
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

GetTypeSize
The GetTypeSize function returns the size in the target's memory of an instance of the specified type.
ULONG
GetTypeSize (
IN LPCSTR Type
);
Parameters
Type
Specifies the type to return the size of.
Return Value
This function returns the size of an instance of the specified type.
Requirements

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1638 of 1651

InitTypeRead
The InitTypeRead and InitTypeStrRead macros initialize a structure so that its members can be read using ReadField.
#define InitTypeRead(Addr, Type) \
GetShortField(Addr, #Type, 1)
#define InitTypeStrRead(Addr, TypeStr) \
GetShortField(Addr, TypeStr, 1)
Parameters
Addr
Specifies the address of the structure in the target's virtual memory.
Type
Specifies the name of the type of the structure. The C pre-processor will turn Type into a string.
TypeStr
Specifies the name of the type of the structure. TypeStr is expected to be an ASCII string.
Return Value
If this macro succeeds, it returns the value zero. If it fails because the caller passed a zero value as Addr, it returns the value MEMORY_READ_ERROR (defined in
Wdbgexts.h). If it fails for any other reason, it returns an IG_DUMP_SYMBOL_INFO error code.
Comments
Note Because these macros use the GetShortField function, ReadField must be used in the same source code file as these macros. For more details, see GetShortField.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that uses this macro, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
InitTypeReadPhysical, ReadField, GetShortField
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

InitTypeReadPhysical
The InitTypeReadPhysical and InitTypeStrReadPhysical macros initialize a structure in physical memory so that its members can be read using ReadField.
#define InitTypeReadPhysical(Addr, Type) \
GetShortField(Addr, #Type, 3)
#define InitTypeStrReadPhysical(Addr, TypeStr) \
GetShortField(Addr, TypeStr, 3)
Parameters
Addr
Specifies the address of the structure in the target's physical memory.
Type
Specifies the name of the type of the structure. The C pre-processor will turn Type into a string.
TypeStr
Specifies the name of the type of the structure. TypeStr is expected to be an ASCII string.
Return Value
If this macro succeeds, it returns the value zero. If it fails because the caller passed a zero value as Addr, it returns the value MEMORY_READ_ERROR (defined in
Wdbgexts.h). If it fails for any other reason, it returns an IG_DUMP_SYMBOL_INFO error code.
Comments

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1639 of 1651

Note Because these macros use the GetShortField function, ReadField must be used in the same source code file as these macros. For more details, see GetShortField.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that uses this macro, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
See Also
InitTypeRead, ReadField, GetShortField
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

ListType
The ListType function calls a specified callback function for every element in a linked list.
ULONG
ListType (
IN LPCSTR Type,
IN ULONG64 Address,
IN USHORT ListByFieldAddress,
IN LPCSTR NextPointer,
IN PVOID Context,
IN PSYM_DUMP_FIELD_CALLBACK CallbackRoutine
);
Parameters
Type
Specifies the name of the type of each entry in the linked list.
Address
If ListByFieldAddress is zero:
Specifies the address in the target's memory of the first entry in the linked list.
If ListByFieldAddress is 1:
Specifies the address in the target's memory of the member of the first entry that points to the next entry.
ListByFieldAddress
Specifies whether Address contains the base address of the first entry, or if it contains the address of the member of the first entry that points to the next entry.
NextPointer
Specifies the name of the member in the structure of type Type that contains a pointer to the next entry in the linked list. NextPointer can be a period-separated path, for
example, if Type is "nt!_ETHREAD", NextPointer could be "Tcb.ThreadListEntry.Flink".
Context
Specifies a pointer that is passed to the callback function specified by CallbackRoutine each time the callback function is called.
CallbackRoutine
Specifies a function that is called for each entry in the linked list. The parameters passed to the function are the Context pointer and a FIELD_INFO structure; the address
of the entry is found in the address member of this structure.
Return Value
This function returns TRUE on success and FALSE on failure.
Requirements
Headers: Defined in wdbgexts.h. If you are writing a WdbgExts extension, include wdbgexts.h. If you are writing a DbgEng extension that calls this function, include
wdbgexts.h before dbgeng.h (see Writing DbgEng Extension Code for details).
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

Glossary
This glossary contains terms and acronyms related to the Microsoft Debugging Tools for Windows.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Debugging Tools for Windows

December 09, 2009
Debugging Tools for Windows

K
KD connection server
A proxy used during some forms of kernel-mode remote debugging. It listens for connections from smart client and performs memory, processor, or Windows operations
as requested by these remote clients. .
See also debugging server.
For more information, see KD Connection Servers (Kernel Mode).
kernel
The kernel is the portion of the Windows operating system that manages and controls access to hardware resources. It performs thread scheduling and dispatching,
interrupt and exception handling, and multiprocessor synchronization.
kernel error
See bug check.
kernel mode
Kernel-mode code has permission to access any part of the system, and is not restricted like user-mode code. It can gain access to any part of any other process running in
either user mode or kernel mode.
Performance-sensitive operating system components run in kernel mode. In this way they can interact with the hardware and with each other without the overhead of
context switch. All the kernel-mode components are fully protected from applications running in user mode. They can be grouped as follows:

Executive.
This contains the base operating system components such as memory management, process and thread management, security, I/O, interprocess communication.

Kernel.
This performs low-level functions such as thread scheduling, interrupt and exception dispatching, and multiprocessor synchronization. It also provides a set of
routines and basic objects used by the Executive to implement higher-level semantics.

Hardware Abstraction Layer (HAL).

This handles all direct interface to hardware. It thus isolates the Windows Kernel, device drivers, and Windows Executive from platform-specific hardware
differences.

Window and Graphics Subsystem.

This implements the graphical user interface (GUI) functions.

When a process erroneously accesses a portion of memory that is in use by another application or by the system, the lack of restrictions on kernel-mode processes forces
Windows to stop the entire system. This is referred to as a bug check.
Malfunctioning hardware devices or device drivers, which reside in kernel mode, are often the culprits in bug checks.
kernel-mode target
See target computer.
kernel-mode debugging
A debugger session in which the target is running in kernel mode.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

L
live kernel-mode debugging
Kernel-mode debugging using live targets.
See also live user-mode debugging.
live target
A target application or target computer that is currently operational (as opposed to a dump target).
live user-mode debugging
User-mode debugging using live targets.
See also live kernel-mode debugging.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1647 of 1651

local context
See scope.
local debugging
This refers to a debugging session in which the debugger and the application to be debugged reside on the same computer.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

M
module
An image in a target process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

N
nonpaged pool
A portion of system memory that will not be paged to disk.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

O
output callback objects
Instances of the IDebugOutputCallbacks interface which have been registered with a client object. All output from the debugger engine is sent to the output callbacks.
For more information, see Output Callbacks.
output callbacks
See output callback objects.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

P
page table
A process-specific table that maps virtual memory addresses to physical memory addresses.
Page Table Entry (PTE)
An item in the page table.
paged pool
A portion of system memory that can be paged to disk.
Note that this term does not only refer to memory that actually has actually been paged out to the disk it includes any memory that the operating system is permitted to
page.
paging
A virtual memory operation in which the memory manager transfers pages from memory to disk when physical memory becomes full. A page fault occurs when a thread
accesses a page that is not in memory.
parent symbol
A symbol that is contains in other symbols, for example, a structure contains its member.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1648 of 1651

Page 1649 of 1651

smart client
An instance of the debugger engine acting as a host. The smart client is connected to a process server. or a KD connection server.
See also debugging client.
For more information, see Process Servers (User Mode), KD Connection Servers (Kernel Mode), and Process Server and Smart Client.
specific exception filter
An event filter for an exception for which the engine has a built-in filter. Most specific exception filters refer to specific types of exceptions (identified by exception
code), but the default exception filter also qualifies as a specific exception filter.
See also arbitrary exception filter, specific event filter, specific filter, exception filter.
For more information, see Event Filters.
specific event filter
An event filter for an event which is not an exception. The specific event filters are listed in DEBUG_FILTER_XXX.
See also specific exception filter, specific filter.
For more information, see Event Filters.
specific filter
An event filter for an event for which the engine has a built-in filter.
See also specific event filter, specific exception filter.
software breakpoint
A breakpoint that is implemented by the debugger engine temporarily modifying the target's executable code. The breakpoint is triggered when the code is executed. The
code modification is invisible to users of the debugger or the debugger engine API.
See also processor breakpoint.
For more information, see Using Breakpoints or Breakpoints.
stack
See call stack.
stack frame
The memory in the call stack containing the data for a single function call. This includes the return address, parameters passed to the function, and local variables.
stop code
See bug check code.
stop error
See bug check.
stop screen
See blue screen.
subregister
A register that is contained within another register. When the subregister changes, the portion of the register that contains the subregister also changes.
suspended
A target, process, or thread is suspended if it has been blocked it from executing.
symbol
A unit of debugging information which provides interpretive information about the target in a debugging session. Examples of symbols include variables (local and
global), functions, types and function entries. Information about symbols can include the name, type (if applicable), and the address or register where it is stored, as well
as any parent or child symbols. This information is stored in symbol files and is typically not available in the module itself.
The debugger engine can synthesize certain symbols when symbol files are not available (for example, exported symbols), but these symbols generally provide only
minimal information.
symbol file
A supplemental file created when an application, library, driver, or operating system is built. A symbol file contains data which is not actually needed when running the
binaries, but which is very useful in the debugging process.
For more information, see Symbol Files: Overview.
symbol group
A group of symbols, typically representing all the local variables in a scope.
For more information, see Scopes and Symbol Groups.
symbol type
Descriptive information about a symbols representation, such as its layout in memory. This is part of the information a compiler uses to generate code to manipulate the
symbol. It is also used by the debugger engine to manipulate symbols. The symbol type is distributed in symbol files.
synthetic module
A region of memory that the engine treats like a module. A synthetic module may contain synthetic symbols.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1650 of 1651

For more information, see Modules.

synthetic symbol
A memory address that the engine treats like a symbol.
For more information, see Symbols.
system crash
See bug check.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

T
target
A target application, target computer, or dump target.
Sometimes referred to as the debuggee.
target application
An application that is being debugged in user-mode.
target computer
A computer that is being debugged in kernel-mode.
target ID
The unique identifier for a target.
target process
In user-mode debugging, an operating system process that is part of the target application.
In kernel-mode debugging, the virtual process representing the kernel.
target thread
In user-mode debugging, an operating system thread in the target application.
In kernel-mode debugging, a virtual thread representing a processor.
thread context
The state preserved by Windows when switching threads. This is similar to the register context, except that there is some extra kernel-only processor state that is part of
the register context but not the thread context. This extra state is available as registers during kernel-mode debugging.
For more information, see Scopes and Symbol Groups.
transport layer
This controls communication between the host and target computers during remote debugging.
trap
See bug check.
type
See symbol type.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

U
user mode
Applications and subsystems run within Windows in user mode. Processes that run in user mode do so within their own virtual address spaces. They are restricted from
gaining direct access to many parts of the system, including system hardware, memory that was not allocated for their use, and other portions of the system that might
compromise system integrity. Because processes that run in user mode are effectively isolated from the system and other user-mode processes, they cannot interfere with
these resources.
User-mode processes can be grouped in the following categories:

System Processes.
These perform important functions and are integral part of the operating system. System processes include such items as the logon process and the session manager
process.

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Introduction

Page 1651 of 1651

Server Processes.
These are operating system services such as the Event Log and the Scheduler. They can be configured to start automatically at boot time.

Environment Subsystems.
These are used to create a complete operating system environment for the applications. Windows provides the following three environments: Win32, POSIX, and
OS/2.

User Applications.
There are five types: Win32, Windows 3.1, Microsoft MS-DOS, POSIX, and OS/2.

user-mode debugging
A debugger session in which the target is running in user mode.
user-mode target
See target application.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

V
virtual process
In kernel-mode debugging the debugger engine creates a single virtual process to represent the target's kernel.
See also virtual thread.
virtual thread
In kernel-mode debugging the debugger engine creates a virtual thread for each processor in the target computer.
See also virtual process.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009
Debugging Tools for Windows

W
WdbgExts API
An interface exposed by the debugger engine for extensions. It contains a subset of the functionality of the debugger engine API and can only be used by extensions.
WdbgExts extension
An extension based on the prototypes in the wdbgexts.h header file. These extensions use the WdbgExts API.
See also DbgEng extension.
For more information, see Writing WdbgExts Extensions.
WOW64
An emulation layer in 64-bit Windows that can run 32-bit Windows applications. When debugging a 32-bit application running on 64-bit Windows, it is important to
distinguish between the application itself and the WOW64 subsystem.
For more information on 32-bit and 64-bit debugging, see Choosing a 32-bit or 64-bit Debugger Package.
2009 Microsoft Corporation
Send feedback on this topic
Debugging Tools for Windows
December 09, 2009

file://C:\Users\joy.CAMSYS\AppData\Local\Temp\~hhCDEB.htm

9/18/2010

Learn Stock Market in Telugu
63% (24)
Learn Stock Market in Telugu
31 pages
MSDN - Debugging Guide
No ratings yet
MSDN - Debugging Guide
4,176 pages
UndocumentedNT PDF
100% (1)
UndocumentedNT PDF
222 pages
ESP8266 Artnet To DMX
100% (1)
ESP8266 Artnet To DMX
13 pages
C++ Beej's Guide To Network Programming Using Internet Sockets (Brian "Beej Jorgensen" Hall)
No ratings yet
C++ Beej's Guide To Network Programming Using Internet Sockets (Brian "Beej Jorgensen" Hall)
92 pages
NT Logon
No ratings yet
NT Logon
38 pages
A Crash Course On The Depths of Win32
100% (1)
A Crash Course On The Depths of Win32
33 pages
052 Iczelions - Win32 - Assembly - Tutorials PDF
100% (1)
052 Iczelions - Win32 - Assembly - Tutorials PDF
273 pages
Windbg Quick Reference
No ratings yet
Windbg Quick Reference
2 pages
Common WinDbg Commands (Thematically Grouped)
100% (2)
Common WinDbg Commands (Thematically Grouped)
16 pages
Introduction To M V VM
No ratings yet
Introduction To M V VM
24 pages
Windbg Usefull Commands
No ratings yet
Windbg Usefull Commands
2 pages
NET - Debugging With WinDbg
No ratings yet
NET - Debugging With WinDbg
153 pages
Programming Windows With MFC
100% (2)
Programming Windows With MFC
12 pages
Boot Loaders
100% (1)
Boot Loaders
54 pages
Misra C 2004
No ratings yet
Misra C 2004
4 pages
Lab Exercise 1: Boot Loader
100% (1)
Lab Exercise 1: Boot Loader
15 pages
GUID Partition Table
No ratings yet
GUID Partition Table
58 pages
Advanced Debugging of STM32-Based Devices
No ratings yet
Advanced Debugging of STM32-Based Devices
11 pages
Windows Socket Programming in C - Biniam Fisseha
100% (1)
Windows Socket Programming in C - Biniam Fisseha
18 pages
IDA Pro Shortcuts
100% (2)
IDA Pro Shortcuts
1 page
Introduction To Linux Kernel
No ratings yet
Introduction To Linux Kernel
22 pages
Win 32 Dasm
No ratings yet
Win 32 Dasm
1 page
Unix & Shell Programming Manual
100% (1)
Unix & Shell Programming Manual
48 pages
WindowsService PDF
100% (1)
WindowsService PDF
36 pages
SFML 2.2 - Tutorials
No ratings yet
SFML 2.2 - Tutorials
136 pages
Windows NT Startup Process
100% (1)
Windows NT Startup Process
4 pages
File System Interface
No ratings yet
File System Interface
108 pages
Linux Booting
No ratings yet
Linux Booting
7 pages
AbendAid Debugging Tool
No ratings yet
AbendAid Debugging Tool
3 pages
Simics User Guide For Linux
No ratings yet
Simics User Guide For Linux
166 pages
Essential Perl One-Liners
No ratings yet
Essential Perl One-Liners
92 pages
System Programming Notes
100% (1)
System Programming Notes
15 pages
Bash Programming For Linux
No ratings yet
Bash Programming For Linux
172 pages
Visual Studio 2013 Cookbook
From Everand
Visual Studio 2013 Cookbook
Richard Banks
No ratings yet
Esc - 1991 - Vol2 - Page710 - Ward - Manipulating Hardware With C
100% (1)
Esc - 1991 - Vol2 - Page710 - Ward - Manipulating Hardware With C
6 pages
Guide To Using Assembly in Visual Studio
100% (1)
Guide To Using Assembly in Visual Studio
7 pages
Vim Advanced
No ratings yet
Vim Advanced
171 pages
Notepad Internals: Extern Labs Pvt. Ltd. 22/2/2022
No ratings yet
Notepad Internals: Extern Labs Pvt. Ltd. 22/2/2022
7 pages
Eclipse - Platform Plug-In Developer Guide
No ratings yet
Eclipse - Platform Plug-In Developer Guide
150 pages
Visual Studio 2010 Package Development Fundamentals
50% (2)
Visual Studio 2010 Package Development Fundamentals
99 pages
X86 Assembly Language C Fundamentals
100% (1)
X86 Assembly Language C Fundamentals
3 pages
Mark Russinovich - Memory - A Must
No ratings yet
Mark Russinovich - Memory - A Must
60 pages
Programming Languages (OOP)
100% (1)
Programming Languages (OOP)
27 pages
Introduction To Assembly Language (With New Lessons)
100% (2)
Introduction To Assembly Language (With New Lessons)
106 pages
Scott Hanselman's 2014 Ultimate Developer and Power Users Tool List For Wind
No ratings yet
Scott Hanselman's 2014 Ultimate Developer and Power Users Tool List For Wind
67 pages
0344-Generating A UUID Using A Java Transformation
No ratings yet
0344-Generating A UUID Using A Java Transformation
3 pages
C++ in One Day - The Ultimate Beginners Guide To C++ With 7 Awesome Projects
No ratings yet
C++ in One Day - The Ultimate Beginners Guide To C++ With 7 Awesome Projects
112 pages
Vala Tutorial
50% (2)
Vala Tutorial
56 pages
Communicating With A Device Using Linux and RS-232
100% (8)
Communicating With A Device Using Linux and RS-232
11 pages
Brief Introduction To The C Programming Language: Washington
100% (1)
Brief Introduction To The C Programming Language: Washington
51 pages
Reverse Engineering Cheat Sheet
No ratings yet
Reverse Engineering Cheat Sheet
3 pages
MFC Programming With Visual.C++ 6 Unleashed
No ratings yet
MFC Programming With Visual.C++ 6 Unleashed
1,377 pages
Clamav Signatures
No ratings yet
Clamav Signatures
35 pages
USB Flash Drive Forensics: Philip A. Polstra, Sr. University of Dubuque
No ratings yet
USB Flash Drive Forensics: Philip A. Polstra, Sr. University of Dubuque
38 pages
BBB Embedded Linux Systems 6
No ratings yet
BBB Embedded Linux Systems 6
39 pages
The Linux File System Structure Explained
No ratings yet
The Linux File System Structure Explained
5 pages
Parted Magic User Guide v1.0
No ratings yet
Parted Magic User Guide v1.0
30 pages
Programming ASP.NET
From Everand
Programming ASP.NET
Nino Paiotta
No ratings yet
Scripting with Objects: A Comparative Presentation of Object-Oriented Scripting with Perl and Python
From Everand
Scripting with Objects: A Comparative Presentation of Object-Oriented Scripting with Perl and Python
Avinash C. Kak
No ratings yet
Unix / Linux FAQ: with Tips to Face Interviews
From Everand
Unix / Linux FAQ: with Tips to Face Interviews
Prof. N.B. Venkateswarlu
No ratings yet
EMC Sourceone PDF
No ratings yet
EMC Sourceone PDF
40 pages
UPS Network Interface
No ratings yet
UPS Network Interface
88 pages
Notation
No ratings yet
Notation
2 pages
Date: Saturday, April 05, 2014: I Would Be Highly Thankful To You
No ratings yet
Date: Saturday, April 05, 2014: I Would Be Highly Thankful To You
1 page
Train No Train Name Runs From Source Runs On
No ratings yet
Train No Train Name Runs From Source Runs On
1 page