Debug over a serial connection

Article
2021-06-28

Just like other versions of Windows, you can use the Windows debugger on Factory OS devices to debug code. The process for getting setup is a little bit different, but once your Factory OS device is connected to the debugger, the debugging process is the same as in other versions of Windows.

The Windows System Kit includes a PowerShell utility that enables the debugger on Factory OS devices. This topic shows how to setup a connection to the debugger on a local VM.

If you're using the Factory OS product, instead of using Debug-WcosDevice you can enable kernel debugger features that enable the debugger on your Factory OS device.

What you need

To get started debugging, you'll need:

A technician PC
A Factory OS VM created with Hyper-V on the technician PC
- Our example below uses the name "Factory OS VM"
- Secure Boot is turned off
The Windows System Kit available on the technician PC

Setup your PC for Factory OS debugging

1. Get your Factory OS device ready to debug

Build a Factory OS image that includes features that enable the kernel debugger

If you have an image that that doesn't already have kernel debugging features enabled, add the Debug-WcosDevice utility to your technician PC:

Use an administrative PowerShell window to copy the debug-wcosdevice files from the Windows System Kit ISO to your local PC. These files are PowerShell modules that enable you to connect the debugger to your Factory OS VM.

md "C:\Program Files\WindowsPowerShell\Modules\debug-wcosdevice"
cd "C:\Program Files\WindowsPowerShell\Modules\debug-wcosdevice" 
copy "K:\Program Files\Windows Kits\10\Tools\Scripts\debug-wcosdevice.*" 

md "C:\Program Files (x86)\WindowsPowerShell\Modules\debug-wcosdevice"
cd "C:\Program Files (x86)\WindowsPowerShell\Modules\debug-wcosdevice" 
copy "K:\Program Files\Windows Kits\10\Tools\Scripts\debug-wcosdevice.*"

Where K: is the root of the WSK ISO

2. Map your serial port

In File explorer, double-click your VM's VHD to mount it.

Use your administrative PowerShell window to view the VM's serial ports:

Get-VMComPort -VMName "Factory OS VM"

You'll see output that looks like this:

VMName       Name    Path
------       ----    ----
Factory OS VM COM 1 
Factory OS VM COM 2

Map the COM1 port:
```
Set-VMComPort -VMName "Factory OS VM" -Path \\.\pipe\vmcom1  -Number 1
```
vmcom1 is the name we've given the path above, but you can choose a different name.
Check to see that the COM 1 port is mapped:
```
Get-VMComPort -VMName "Factory OS VM"
```
The output will look like this:
```
VMName       Name  Path
------       ----  ----
Factory OS VM COM 1  \\.\pipe\vmcom1
Factory OS VM COM 2 
```
The path you mapped in the previous step shows as the path assigned to COM 1

3. Connect to the device and start debugging

If you're using a VM that doesn't have kernel debugging features enabled, use Debug-WcosDevice to configure the VHDX's BCD store to enable kernel debugging:

Debug-WcosDevice -Transport  SERIAL  1   115200  -BootDebug

When -Transport is used with SERIAL, you can specify the following options:

Parameter type	Description
DEBUGPORT	The debug port can be between 1 and 99.
BAUDRATE	Baudrate can be 300 and up.
NOBAUD	This tells the system not to set BAUD rate as some systems don't want it.

Debug your device just as you would other Windows devices.

Share via