Bcdedit Tips and Tricks For Debugging Part 1

Hello everyone, my name is Sean Walker, and I am on the Platforms OEM team in Washington. This article is for those people who have had a hard time switching from the old boot.ini configuration to the new BCD store (myself included). Doing the simple tasks such as enabling kernel debugging over com1 are easy to do with bcdedit.exe or the msconfig GUI, you just enable them and reboot the computer. However, if you need to do something more advanced such as break into the early boot process during resume from hibernation, things get a lot more complicated.

This article has some samples for enabling and disabling debug settings that you may not be familiar with, and a list of bcdedit debug settings for Windows Vista/Server 2008 and Windows 7/Server 2008 R2. This information has been helpful to me for quickly and accurately getting to the debug at hand rather than fumbling around with bcdedit. Much of the following information has been taken from various sources, including the windbg help files, the OEM team blog, the MSDN bcdedit reference, and the WHDC debugger site.

NOTE: For the examples below, you will need to run bcdedit.exe from an administrator (UAC-elevated) command prompt. To output a summary view of the current state of the BCD store, just run "bcdedit.exe" from the command prompt. To get detailed information about all of the store(s) that Windows knows about, use the following command:

bcdedit /enum all

What is a BCD store?

A BCD store is a binary file that contains boot configuration data for Windows, basically it is a small registry file. Boot applications use the system BCD store, located on the system partition, during the boot process. You can also create additional BCD stores in separate files but only one store at a time can be designated as the system store.

NOTE: The "/store" switch can be used to specify a particular BCD store for bcdedit commands (instead of the default store). To enumerate all the settings in another BCD store, in this case e:\bcd_store\BCD, use the following command:

bcdedit /store e:\bcd_store\BCD /enum all

This will show you which options are currently set, and what their values are. When /store switch is omitted, the system store is used.

Using bootdebug

To enable debugging for early boot problems, you may need to enable the bootdebug switch. This is easy to do with bcdedit:

bcdedit /set bootdebug on

However, this only sets bootdebug for the current "boot application", which is generally winload.exe, so it does not break into the very early boot process. There are multiple applications used for booting, hibernating, and resuming (bootmgr.exe, winload.exe and winresume.exe are examples of these). Each application (called BCD Objects) has its own settings (called BCD Elements) in the BCD store and each can be modified globally and/or individually.

So, to deal with different (or multiple) debug scenarios, you just enable boot debugging based on the boot application you are concerned with. For early debugging, you can enable bootdebug for bootmgr:

bcdedit /set {bootmgr} bootdebug on

To set bootdebug for winload.exe (which will most often be your current, and default, boot object) all three of the following will give you the same result:

bcdedit /set bootdebug on

bcdedit /set {current} bootdebug on

bcdedit /set {default} bootdebug on

If you are modifying the settings in another store, or are booted into another OS on the same computer (such as WinPE), you need to specify the location of the BCD store:

bcdedit /store d:\Boot\BCD /set {default} bootdebug on

Not all of the boot objects have "friendly" names, so you may need to specify the full GUID (Globally Unique ID) to modify it. As an example, if you wanted to enable bootdebug on resume from hibernation, you would include the identifier (see figure 1) for the "Resume from Hibernate" object:

bcdedit /set {89a932d0-d5bc-11e0-a0af-00215add5ebc} bootdebug on

Figure 1: Color coded bcdedit output

Why won't my USB or 1394 debug work?

When there are multiple debug ports of a certain type in a computer Windows may not default to the correct one for your situation. This happens most commonly when there are either multiple 1394 host controllers or USB EHCI controllers. When this occurs it can range from a slight inconvenience (different port is used so the cable needs to be plugged into another port), to complete failure (internal port is used, which is not accessible). In the case of USB debugging the Intel USB 2.0 specification only provides one debug port, so debugging is not possible if the wrong host controller is used.

There are several caveats with USB debugging, not the least of which is that you need to buy a separate, expensive, debug cable. Some of the difficulties and implementation details necessary to get USB debugging to work are encompassed in the WHDC USB FAQ and in Setting Up Kernel Debugging with USB 2.0.

NOTE: A correction to the WHDC USB documentation for Windows 7/Windows 2008 R2 is that the busparams switch now takes decimal rather than hexadecimal values, and the "loadoptions" parameter is no longer required. So, to enable the busparams element (for USB or 1394 debugging) in Vista/2008, you would use something like this:

bcdedit /set {current} loadoptions busparams=0.1D.7

And the Win7/2008 R2 example would be:

bcdedit /set {current} busparams 0.29.7

In the case of loadoptions or busparams, deleting the setting is not as easy as changing a flag from yes to no. You must specifically delete the value to get rid of it, and one of the examples below can be used:

For Vista/2008:

bcdedit /deletevalue {current} loadoptions

And Windows 7/2008 R2:

bcdedit /deletevalue {current} busparams

Bcdedit settings and examples

This is just scratching the surface of using bcdedit for your troubleshooting and/or debugging needs, so there are more articles to follow. Part 2 will include some more detailed debugging scenarios, such as Hyper-V guest and host debugging. Below is a consolidated table with many of the debugging switches/settings as well as a number of different usage examples.

Table of debug-related bcdedit settings

Option

Description

bootdebug

Enables or disables the boot debugger for a specified boot entry. Although this command works for any boot entry, it is effective only for boot applications.

Enable value(s): on, 1

Disable value(s): off, 0

Bcdedit /set bootdebug on

debug

Enables or disables the kernel debugger for a specified boot entry.

Enable value(s): on, 1

Disable value(s): off, 0

/dbgsettings

Used to modify the global settings for the debug connection (does not include hypervisor).Values:

Can change all settings at once instead of using the /set command to change them individually. Usage example:

bcdedit /dbgsettings 1394 channel:30

debugport

Used to specify the debugger type.

Values:

Serial port – com1, com2, comx

1394 port – 1394

USB port - USB

channel

Specifies 1394 channel used.

Values:

Decimal integer between 0 and 62, inclusive.

baudrate

Used to specify the baud rate of a serial debug port.

Values: 9600, 19200, 38400, 57600, 115200

targetname

Specifies a string to use as the identification for the USB 2.0 connection. This string can be any value.

Usage example:

bcdedit /dbgsettings usb targetname:usbdebug

/hypervisorsettings

Used the same way as /dbgsettings to configure all settings at once.

Usage example:

bcdedit /hypervisorsettings 1394 channel:10

hypervisordebug

Enables or disables hypervisor debug mode. This is for debugging a Hyper-V host system.

Enable value(s): on, 1

Disable value(s): off, 0

Usage example:

bcdedit /set {current} hypervisordebug on

/noumex

Specifies that the kernel debugger ignores user-mode exceptions. By default, the kernel debugger breaks for certain user-mode exceptions, such as STATUS_BREAKPOINT and STATUS_SINGLE_STEP. The /noumex parameter is effective only when there is no user-mode debugger attached to the process.

/start

This option specifies the debugger start policy. If a start policy is not specified, ACTIVE is the default.

Values: active, disable, autoenable

loadoptions

Used to describe settings that are not covered by other types. One setting that is relevant here is busparams.

Values: Any value followed by the setting.

Usage example (Vista/2008):

bcdedit /set {current} loadoptions busparams=0.1d.0

busparams

A boot setting (specified with loadoptions key word) used to point to the PCI address of the debugger in use. The PCI bus, device, and function are used, in the format bb.dd.ff. This is generally used to identify the location of a 1394 or USB debug port. In Vista/2008, hexadecimal values are used, whereas decimal values are used for Win7.

Values: Decimal values between 0 and 255.

Usage example:

In Win7 - bcdedit /set busparams 0.29.0

In Vista - bcdedit /set loadoptions busparams=0.1d.0

kernel

The loadoptions parameter used to point to a different kernel binary. This can be used to test with a checked or instrumented version of the kernel without replacing the existing one. The updated binary MUST be placed in the %windir%\system32 folder to be used

Values: The 8.3 filename of the replacement kernel include the exe extension.

Usage examples:

In Win7 – bcdedit /set kernel kernchk.exe

In Vista - bcdedit /set loadoptions kernel=kernchk.exe

hal

The loadoptions parameter used to point to a different hal binary. This can be used to test with a checked or instrumented version of the kernel without replacing the existing one. The updated binary MUST be placed in the %windir%\system32 folder to be used

Values: the 8.3 filename of the replacement kernel include the .dll extension.

Usage examples:

In Win7 – bcdedit /set hal halchk.dll

In Vista - bcdedit /set loadoptions hal=halchk.dll

testsigning

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 without setting the testsigning switch

Thanks for this post, it may save me in the future. I would like to ask if you guys can write some detailed article(s) concerning checked builds of Windows (some real world examples, differences between free and checked builds from the debugging perspective etc.).

[Thank you for the feedback, and for the suggestion.]

GoodOne

6 Oct 2011 9:30 PM

Very helpful. We mostly face issue while installtion phase. Can you also post something about how we can setup debugger in WINPE? It would be great help.