Use Debug-WcosDevice to enable debugging
Debug-WcosDevice is a PowerShell utility included in the WSK that helps with setting up the debugger by modifying the BCD on Factory OS devices.
You can run Debug-WcosDevice to configure Factory OS devices that are accessible in the following ways:
- A VHD that's mounted on a technician PC
- Through TShell (Factory OS only)
Load the utility in PowerShell
Before you can run the Debug-WcosDevice utility, you have to make it available on your technician PC. You can import it into PowerShell every time you need it, or you can automatically load it when PowerShell launches.
Option 1: Load Debug-WcosDevice to use in a single PowerShell session
Set-Location 'D:\Program Files\Windows Kits\10\Tools\Scripts\'
Import-Module .\Debug-WcosDevice.psm1
Where D:\ is the location of the WSK
Option 2: Load Debug-WcosDevice by default
You can configure PowerShell on your technician PC to load the Debug-WcosDevice utility every time PowerShell starts by copying the following files into the PowerShell modules folder:
md "C:\Program Files\WindowsPowerShell\Modules\debug-WcosDevice"
cd /D "C:\Program Files\WindowsPowerShell\Modules\debug-WcosDevice"
copy D:\Program Files\Windows Kits\10\Tools\Scripts\Debug-WcosDevice\*ps?1
md "C:\Program Files (x86)\WindowsPowerShell\Modules\debug-WcosDevice"
cd /D "C:\Program Files (x86)\WindowsPowerShell\Modules\debug-WcosDevice"
copy D:\\Program Files\Windows Kits\10\Tools\Scripts\Debug-WcosDevice\*ps?1
Where D:\ is the root of your Windows System Kit media or installation.
Gain access to the BCD files
To run Debug-WcosDevice and configure debugging, you have to have access to you Factory OS image's BCD files. You can do this by:
Once you can access the BCD files on your Factory OS image, you can start working with Debug-WcosDevice.
Configure the BCD files to enable debugging
From an administrative PowerShell prompt, use Debug-WcosDevice to modify the BCD on your Factory OS device to enable debugging. After debugging is enabled, the debugging process is the same as any other Windows device.
Using Debug-WcosDevice
To setup the connection to the debugger, you run Debug-WcosDevice, specifying a transport (network, USB, or serial) for the debugger and any associated parameters.
The full syntax for Debug-WcosDevice is below.
Examples:
Setting up the network debugger
Debug-WcosDevice NET 10.23.78.12 AllUse an already-connected TShell connection to configure a network debugger
Debug-WcosDevice NET 10.23.78.12 All -TShellConfigure the debugger on locally-hosted virtual machine over serial connection
Debug-WcosDevice -Transport SERIAL 1 115200 -BootDebug
Once you've used Debug-WcosDevice to modify the BCD of your WCOS device, you're ready to start debugging.
Debug-WcosDevice Syntax and parameters
Syntax:
Debug-WcosDevice -Transport <NET <IpAddress> [<Bus Params>] [<HIP>] [<Port>]|USB [<Targetname>] [<Bus params>]|SERIAL <DEBUGPORT> [<BAUDRATE>|NOBAUD]|OFF|ON> <BCD Entry Target> [-TShell]
-Transport parameters
The transport switch is used to tell the script the type of debug function to perform. From configuring the debug transport to use and to turn on/off the debugger for the boot options. The following parameters can be used to change the transport settings for the individual transports.
Use debug-WcosDevice with -Transport NET, -Transport USB or -Transport SERIAL to configure the connection to your Factory OS device.
-Transport NET
Running Debug-WcosDevice.cmd with the NET transport option allows you to connect to your Factory OS device through a network connection.
Syntax:
Debug-WcosDevice -Transport NET <IpAddress> [<Bus Params>] [<HIP>] [<Port>] [<Key>] <BCD Entry Target> [-TShell]
Example:
Debug-WcosDevice -Transport NET 10.23.78.12 All
This sets the network debugger using the IP address 10.23.78.12 for HostIP and enables the debugger on all boot entries. For KDNET over EEM, use HostIP=169.254.255.255 regardless of your host's address.
| Parameter | Description |
|---|---|
| IpAddress | The HostIp address to use with the network. In the form of an IP4 address 1.1.1.1 default is to use the EEM (Ethernet Emulation Model)/IpOverUSB address of 169.254.255.255 |
| Bus Params | When using the transport type NET, you may want to specify a specific Bus, Device, and Function Number (BDN) to use. This value should be in decimal, in either 1 or 1.1.1 form. |
| HIP | If this is passed in, the script will automatically find the first IP4 ip address to use on the host. Do not put in an IpAddress if using HIP, you will get an error. |
| Port | This represents the open port on the host that should be in the range of 49152 - 65535 Default is 50000 |
| Key | Security key used to help secure the connection.
This script only accepts keys with all letters up to 4 letters per node and expects 4 nodes. ^[a-zA-Z]{1,4}\.[a-zA-Z]{1,4}\.[a-zA-Z]{1,4}\.[a-zA-Z]{1,4}$ Example:
Default is 1.2.3.4 (yes numbers, this is ok for a default) |
| BCD Entry Target | This identifies the boot entry to enable the debugger on. Select from ALL or MainOS or UpdateOS. Default is MainOS |
-Transport USB
Syntax:
Running Debug-WcosDevice.cmd with the USB transport option allows you to connect to your WCOS device through a USB connection.
Debug-WcosDevice -Transport USB [<Targetname>] [<Bus params>] <BCD Entry Target> [-TShell]
| Parameter | Description |
|---|---|
| Bus Params | When using the transport type NET, you may want to specify a specific Bus, Device, and Function Number (BDN) to use. This value should be in decimal, in either 1 or 1.1.1 form. |
| TargetName | Targetname can be up to 24 characters long
Default is WCOSTARGET |
| BCD Entry Target | This identifies the boot entry to enable the debugger on. Select from ALL or MainOS or UpdateOS. Default is MainOS |
-Transport SERIAL
Running Debug-WcosDevice.cmd with the SERIAL transport option allows you to connect to your Factory OS device through a USB connection.
Syntax:
Debug-WcosDevice -Transport SERIAL <DEBUGPORT> [<BAUDRATE>|NOBAUD] <BCD Entry Target> [-TShell]
Example:
Debug-WcosDevice -Transport SERIAL 1 115200 -BootDebug
See Debug over a serial connection to learn more.
| Parameter | Description |
|---|---|
| DEBUGPORT | The debug port can be between 1 and 99 |
| BAUDRATE | Baudrate can be 300 and up. |
| NOBAUD | This will tell the system not to set BAUD rate. |
| BCD Entry Target | This identifies the boot entry to enable the debugger on. Select from ALL or MainOS or UpdateOS. Default is MainOS |
-Transport OFF or ON
Example:
Debug-WcosDevice -Transport OFF
| Parameter | Description |
|---|---|
| None | Turns the debugger on or off based off the transport value of ON or OFF |
Non-transport parameters
Note
These parameters are preceded by a required -.
| Parameter | Description |
|---|---|
| -TShell | This tells the script you are running under TShell and that the debug configuration should be done against the device connected via the TShell connection. |
| -BootDebug | This tells the script to also make changes to the bootdebugger, including on {bootmgr} boot option. |
| -UserPaths | These are partial paths to the bcd store. The script will append efi\Microsoft\boot\bcd or boot\bcd to the path and check to see if the file exists.
Format is |