Configure the BCD for debugging

  • Article

You can use the Windows debugger to debug Factory OS devices. Once your Factory OS device is configured, the debugging process is the same as in other versions of Windows. Configuring the BCD files to enable debugging, however, is different because of the Storage Spaces partition layout that Factory OS uses to enable state separation.

Factory OS Boot configuration data (BCD)

BCD location

The BCD files on Factory OS devices are located on the VIRT_EFIESP volume, a virtual disk with read/write access. This is a change from other versions of Windows that use the EFI System partition to hold the BCD files.

See Partition layout for information about all of the partitions and virtual disks in the Factory OS Storage spaces partition layout.

Modifying BCD files

On other versions of Windows, you can access and modify the BCD store through the Command prompt. Since Factory OS devices don't have an interactive Command prompt, you'll have to modify the BCD files on VIRT_EFIESP in the following ways:

Because the virtual disk that contains the BCD files is read/write, once you have access to the disk you can make any changes that you could make to the BCD on any other Windows installation.

Automated ways to configure debugging

Use the Debug-WcosDevice utility

Debug-WcosDevice is a PowerShell utility included in the WSK that helps setup the debugger on Factory OS devices. You can use it against a mounted image, or an online image over TShell. See Use Debug-WcosDevice to enable debugging to learn how to use it.

Once you've used Debug-WcosDevice to modify your Factory OS's BCD files, you're ready to start debugging.

Enable debugging optional features

Factory OS has optional features that you can enable in your OEMInput file to modify the BCD to enable debugging. The optional features are:

Optional features
KDNETUSB_ON
KDNETSERIAL_ON
KDUSB_ON

If you've enabled debugging by using optional features, you're ready to start debugging.

Manually configure debugging

Before you can configure debugging, choose a method to to access the BCD files on a Factory OS device.

Connect with TShell

You can access BCD files by connecting to a running Factory OS device with TShell:

cmdd BCDEdit

Using BCDEdit, you can modify the BCD.

Connect with SSH

You can access BCD files connecting to a running Factory OS device that has SSH configured. When connected to your device through SSH:

BCDEdit

Using BCDEdit, you can modify the BCD.

On a mounted VHD

You can access BCD files in the VIRT_EFIESP partition on an offline mounted VHD by mounting a VHD on your technician PC. To mount a VHD, double-click it in File explorer. From a technician PC where the VHD is mounted. After the VHD is mounted:

BCDEdit /store <path_to_VIRT_EFIESP_bcd>

Using BCDEdit, you can modify the BCD.

Modify the BCD

If you're not using Debug-WcosDevice or the debugging optional features to modify the BCD, once you've accessed the BCD, use BCDEdit to make changes that enable debugging. To learn how to use BCDEdit for different debugging scenarios, see the following table:

Debugger type How to setup the debugger BCDEdit commands How to start debugging
Net Setting Up KDNET Network Kernel Debugging Manually BCDEdit /debug on
BCDEdit /dbgsettings net hostip:w.x.y.z port:n key:Key		 Start network debugging
USB Setting Up Kernel-Mode Debugging over a USB 3.0 Cable Manually BCDEdit /debug on
BCDEdit /dbgsettings usb targetname:targetname		 Start USB debugging
Serial Setting Up Kernel-Mode Debugging over a Serial Cable Manually BCDEdit /debug on
BCDEdit /dbgsettings serial debugport:n baudrate:rate		 Start serial debugging
Note: See Debug over a serial connection to learn how to connect to a local VM over a serial connection.

After you've modified the BCD settings on your WCOS device, you can start debugging

Start debugging

You can start debugging sessions based on the type of connection you're using to connect to your WCOS device:

Debugger type How to start debugging
Net Start network debugging
USB [Start USB debugging]/windows-hardware/drivers/debugger/setting-up-a-usb-3-0-debug-cable-connection#starting-a-debugging-session-for-the-first-time)
Serial Start serial debugging