WinDbg Help

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

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



Page 1 of 1651Introduction

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

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

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.




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.


Debuggers

This section includes:

Debuggers in this Package

Installation and Setup

Debugger Operation

Symbols

Crash Dump Files

Security Considerations

Debugger Reference


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.






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.


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.





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.


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.


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


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.


Choosing a 32-Bit or 64-Bit Debugger Package

Installing from the Customer Support Diagnostics CD

Installing from the Windows SDK






Installing from the Windows Driver Kit

Installing from the Web

Installing from a Script

Customizing the Installation

Uninstalling the Debugger Package


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.


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.







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.


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.


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.


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


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:







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.


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.


Kernel-Mode Setup


Configuring Hardware for Kernel-Mode Debugging

Configuring Software on the Target Computer

Configuring Software on the Host Computer


Configuring Hardware for Kernel-Mode Debugging


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






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

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.


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







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


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.


Setting Up a USB 2.0 Debug 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 a USB 2.0 debug cable, a debug (null-modem) cable, or an IEEE 1394 ("FireWire") cable.

Kernel debugging through a USB 2.0 debug cable is not supported on all systems. The target computer must be running Windows Vista or a later version of Windows, and the host computer must be running Windows 2000 or a later version of Windows.

You must use the following hardware for this kind of debugging:

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.

Software Setup


Note Additional support can be requested by sending mail to [email protected].


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:





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> $port= new-Object System.IO.Ports.SerialPort COM1,19200,None,8,one

PS> $port.open()

PS> $port.Write("Hello, world!")

PS> $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. In the Connection Description box, enter a name for the new connection. (The name is not important.) 3. 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. 4. In the next window, accept the defaults for the COM port properties. 5. 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 pass-though 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.


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.


Introduction to Boot Options

Editing Boot Options

Boot.ini Boot Parameter Reference




BCD Boot Options Reference

Using Boot Parameters

Bypassing Boot Options

Disabling the 1394 Host Controller

Using KDbgCtrl


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.


Boot Options in a Boot.ini File

Boot Options in EFI NVRAM

Boot Options in Windows Vista and Later


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.


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.


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






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(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 command-line 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.


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.




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.


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.


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 firmware-independent 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.


Overview of Boot Options in EFI

Editing Boot Options in EFI

Backing up Boot Options in EFI






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

Default: \Device\HarddiskVolume3\WINDOWS

CurrentBootEntryID: 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 Description Example

Boot Options Contains options that apply to all boot entries. (Section heading)

Timeout Determines how long the boot menu is displayed. When this value expires, the boot loader loads the default operating system.

Timeout: 30

Default Specifies the location of the default operating system. \Device\HarddiskVolume3\WINDOWS

CurrentBootEntryID Identifies the boot entry that was used to start the current session of the operating system. CurrentBootEntryID: 1

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. A boot entry is a set of options that defines a load configuration for an operating system or bootable program.

(Section heading)

Boot entry ID Identifies the boot entry to Bootcfg. This value changes when you reorder the boot entries. This is not the EFI boot entry ID, which is a persistent identifier for the EFI components.

Boot entry ID: 1

OS Friendly Name Represents the boot entry in the boot menu. Windows Server 2003, Enterprise

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. For a list of the boot parameters that are related to driver debugging and testing, see Boot.ini Boot Parameter Reference.

OsLoadOptions: /debug

/debugport=COM1 /baudrate=57600

BootFilePath Specifies the location of the EFI boot loader for the operating system. On EFI-based systems, 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.

BootFilePath: \Device\HarddiskVolume1

\EFI\Microsoft\WINNT50\ia64ldr.efi

OsFilePath Specifies the location of the operating system. In NVRAM, this value is stored as an EFI device path that uses the GUID of the boot disk partition and the path to the directory that contains the operating system. Bootcfg uses the NT device name of the partition in its path display.

OsFilePath: \Device\HarddiskVolume3

\WINDOWS



In addition, there is an important element of an EFI boot entry that Bootcfg does not display, the EFI boot entry ID. The EFI boot entry is a unique identifier for an EFI boot entry. This identifier is assigned when the boot entry is created, and it does not change. It represents the boot entry in several lists, including the BootOrder array, and it is the name of the directory on disk in which the system stores data related to the boot entry, including backup copies of the boot entry. An EFI boot entry ID has the format, Bootxxxx, where xxxx is a hexadecimal number that reflects the order in which the boot entries are created.

Note The Boot entry ID field in Bootcfg and the boot entry number in Nvrboot do not display 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.

For a detailed description of boot options on Itanium-based systems, see the Extensible Firmware Interface Specification. You can download a copy of the specification from the Intel Extensible Firmware Interface Web site.


Editing Boot Options in EFI

To edit boot options on computers with EFI NVRAM that are running Windows Server 2003 or earlier versions of NT-based Windows, use Bootcfg (bootcfg.exe), a tool that runs on Windows, or Nvrboot (nvrboot.efi), a tool that runs in the EFI environment. Both tools are included in the Windows XP 64-Bit Edition and the 64-bit version

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 (bootcfg.exe) is a command-line tool that edits boot options on a local or remote computer Using the same Bootcfg commands and procedures, you can edit a Boot.ini file or the boot options in 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 the values of all valid boot options; however, you cannot set an indefinite 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.

On systems that store boot options in EFI NVRAM, Bootcfg can also display the boot partition table, add boot entries for mirrored drives, and update the GUIDs for a system partition.

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.

Nvrboot

Nvrboot (nvrboot.efi) is an EFI-based boot entry editor included in Windows XP 64-Bit Edition and the 64-bit version of later versions of Windows. Nvrboot runs in the EFI environment. You cannot run Nvrboot while an operating system is running.

Nvrboot edits only boot entries. You cannot use it to display or change the time-out value for the boot menu, although, you can use the push command (nvrboot p) to change the default boot entry.

Nvrboot also includes commands to export backup copies of boot entries and to import backup copies of boot entries into NVRAM. This procedure is discussed in the Backing up Boot Options in EFI section.

Nvrboot displays boot options in a user-friendly format. For example, it displays the operating system file path and the boot loader file path as a partition GUID followed by a Windows directory path.

The following procedure explains how to start Nvrboot from the EFI shell, a tool provided with many Itanium-based systems. Because the EFI shell tools vary among manufacturers, the description in this section might not accurately describe the EFI shell interface on a particular computer.

To run Nvrboot

1. Reboot the computer. 2. From the boot menu, choose EFI Shell. 3. At the shell prompt, type the drive letter or file system number of the system partition, such as C: or FSn, where n is the file system number of the system partition. 4. Type cd msutil to navigate to the Msutil directory where nvrboot.efi is located. 5. To start Nvrboot, type nvrboot.

To find instructions for Nvrboot, type h.


Backing up Boot Options in EFI

When you install a 64-bit version of Windows, Setup automatically creates a boot entry for the installation and saves a backup copy of the boot entry to a binary file named





Bootxxxx, where Bootxxxx is the NVRAM ID for the boot entry. Setup stores the boot entry backup copy in a new directory on the EFI partition, along with the EFI boot loader for the new installation.By default, the installation directory is in the \EFI\Microsoft\ subdirectory.

However, the system does not save backup copies of the boot entries that you create and it does not update backup copies of boot entries after you edit them.

To save backup copies of boot entries that you create and edit, and to save extra backup copies of the entries that Setup creates, use Nvrboot (nvrboot.efi). Nvrboot saves the entries in the binary format that Setup and the EFI components use. Then, if the boot entry for an installation is lost or corrupted, you can use the import command (nvrboot i) in Nvrboot to import the backup copy of the boot entry into NVRAM.


Exporting and Importing Boot Entries in EFI

Identifying Backup Files for Existing Boot Entries

Identifying Backup Files for Deleted Boot Entries

Recognizing Unusable Boot Entry Backup Files


Exporting and Importing Boot Entries in EFI

Use the nvrboot x (export) command to create a backup copy of a boot entry. Design a naming and storage convention that will make it easy to find the backup copy files when you need them.

Use the nvrboot i (import) command to import boot entries from the backup copies that you exported or from the Bootxxxx boot entry backup files that Setup created.

Imported boot entries always receive new EFI boot entry IDs. For example, if you export a copy of Boot0003, and then import the copy into NVRAM, the imported boot entry receives a new boot entry ID, such as Boot000A.


Identifying Backup Files for Existing Boot Entries

To search for the backup copy of a boot entry by its file name, you need the entry's EFI boot entry ID. However, neither Bootcfg nor Nvrboot display this ID.

Instead, you can find a boot entry backup copy by searching for a Bootxxxx file in the installation's directory on the EFI partition. To find the installation directory, locate the path to the boot loader file for the operating system installation. The boot entry backup file for the installation is stored in the same directory.

Use the nvrboot d (display) command or the bootcfg or bootcfg query commands to display the path to the directory in which the boot loader for the operating system is stored.

In the following example, the boot loader for a boot entry is stored on the EFI partition in the \Microsoft\WINNT50 subdirectory. The backup copy of the boot entry for this installation is a file named Bootxxxx in the same subdirectory.

Note The Boot entry ID field in Bootcfg and the boot entry number in Nvrboot do not display 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.

As shown in the following Bootcfg sample, the path to the boot loader file appears in the BootFilePath field.

Bootcfg displays the file location as the NT device name of the partition, followed by the file system path to the boot loader file.

Boot Entries

------------

Boot entry ID: 1

OS Friendly Name: Windows Server 2003, Enterprise

OsLoadOptions: /debug /debugport=COM1 /baudrate=115200

BootFilePath: \Device\HarddiskVolume1\EFI\Microsoft\WINNT50\ia64ldr.efi

OsFilePath: \Device\HarddiskVolume3\WINDOWS

In the following sample of an Nvrboot display, the path to the boot loader file for an operating system installation appears in the EFIOSLoaderFilePath field.

Nvrboot displays the file location as a partition GUID followed by the path to the boot loader file.

1. Load identifier = Windows Server 2003, Enterprise

2. OsLoadOptions = /debug /debugport=COM1 /baudrate=115209

3. EFIOSLoaderFilePath = 006F0073-0066-0074-5C00-570049004E00 :: \EFI\Microsoft\WINNT50\ia64ldr.efi

4. OSLoaderFilePath = 04000004-5D18-3F27-0000-0000205C273F :: \Windows





In both cases, the boot loader file (and the Bootxxxx boot entry backup file) for the operating system are in the WINNT50 directory of the EFI system partition (EFI\Microsoft\WINNT50).


Identifying Backup Files for Deleted Boot Entries

Typically, you need to locate a boot entry backup file when a boot entry is inadvertently deleted.

If a boot entry has been deleted from NVRAM, and the operating system is still installed, the boot loader file and the boot entry backup file for the installation still remain on the disk in the installation's directory on the EFI partition.

To find the boot entry backup file for a deleted entry, boot to the EFI shell, and search the EFI partition recursively for boot entry backup files using the command dir boot* /s. Exclude from your results boot entry backup files that are in directories associated with boot entries already in NVRAM. To display the directory for an existing boot entry, use the nvrboot d (display) command.

If there are multiple Bootxxxx files that are not associated with existing boot entries, use Nvrboot to import the entries from their backup files, and then delete the unwanted boot entries.


Recognizing Unusable Boot Entry Backup Files

Unfortunately, boot entry backup copies are not always usable.

In an EFI environment, applications and drivers identify disk partitions by a partition GUID. If the disk partition GUID changes for any reason, then the partition GUID in the boot entry backup copy is no longer valid and the EFI boot loader cannot use the backup copy to boot the system.

The following Bootcfg sample shows a boot entry that was imported with invalid partition GUIDs.

Boot entry ID: 4

OS Friendly Name: Windows Server 2003 - mydebug

OsLoadOptions: /debug /debugport=com1 /baudrate=115200

BootFilePath: (null)

OsFilePath: (null)

In this case, you must recreate the boot entry by copying another boot entry from the operating system installation, and then changing the parameters.


Boot Options in Windows Vista and Later

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.






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.


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.




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.


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




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 a

WinDbg Help

Documents

Transcript of WinDbg Help