Debug Apps in Validation OS

Article
09/30/2022

We currently support debugging only using Windbg.exe, and supporting tools to debug applications on Validation OS and its kernel. Debugging tools are included in the Windows SDK. You must make the debugging tools available on the Validation OS computer by either copying them locally or using them from a share.

User-mode debugging

The easiest user-mode debugging method is to run a process server on the Validation OS computer, and connect to it by using a debugger on another computer. The process server is included with the debugging tools in the Windows SDK.

To run a process server in user-mode

Copy the Windows Debugging Process Server tool, dbgsrv.exe, from the Windows SDK debugging tools folder (C:\Program Files (x86)\Windows Kits\10.0\Debuggers\x64), to the Validation OS computer.
Start the Windows Debugging Process Server, specifying a connection method to the PC, for example, a TCP port:
```
dbgsrv.exe -t tcp:port=1234
```
Note

For more information, see Activating a Process Server (Windows Debuggers).
From the remote computer, use the process server to attach to or start processes on the Validation OS destination computer:
```
windbg -remote tcp:server=Server,port=1234
```
Important

We recommend that you perform debugging from a computer running a full version of Windows, as described in this procedure.

Kernel-mode debugging

Kernel-mode debugging can be enabled either before the system is booted or using the command prompt after booting (requires reboot). The boot configuration file has a setting for kernel mode debugging, which is enabled by using the bcdedit.exe command-line tool to modify the Boot Configuration Data (BCD) store. The tool is located in the %windir%\System32 directory of the Windows partition.

The default debugger settings are as follows

identifier              {dbgsettings} 
debugtype               Serial 
debugport               1 
baudrate                115200

Enable kernel-mode debugging

This will enable debugging on the Validation OS machine only, the support type (network, USB cable, etc.) needs to be set afterwards.

Create a BIOS or EFI partition, skip if already exist. Assign a letter to this partition (i.e. S:\). Create a BDC store using bcdboot.exe.
At the command prompt, type the following bcdedit command to set the debug flag of the BCD store used to boot the image to debug on:
- On UEFI systems
```
bcdedit /store S:\EFI\Microsoft\Boot\BCD /set {default} debug on
```
- On legacy BIOS system
```
bcdedit /store S:\Boot\BCD /set {default} debug on
```
Note

To change this setting online, remove the store parameter from the previous commands and reboot the system to save the changes.

Note

To use a symbol server from within Validation OS, use the net use command on the server’s symbols and file shares. For more information about command-line options that control debugging, see BCDEdit Command-Line Options.

Support network kernel-mode debugging

On a technician PC, run the following commands to create a Validation OS image with kernel mode debugging settings.

Enable kernel mode debugging as described previously. The S:\ drive is used as the location of the system partition for this example, update accordingly.
Run the following commands to enable network KD debugging. Update hostip with the IP address of the host PC that will run WinDbg. PORT can be set from 50000 to 50039. The key will be autogenerated if not set (recommended) or you can set a custom one, for more info see Encryption key:
- On UEFI systems
```
bcdedit /store S:\EFI\Microsoft\Boot\BCD /dbgsettings NET HOSTIP:xxx.xxx.xxx.xxx PORT:500xx key:x.x.x.x
```
- On legacy BIOS system
```
bcdedit /store S:\Boot\BCD /dbgsettings NET HOSTIP:xxx.xxx.xxx.xxx PORT:500xx key:x.x.x.x
```
- Run the following command in host PC and start the target PC:
```
windbg.exe -k net:port=500xx,key=x.x.x.x
```
Note

For more information on network debugging please check Setting Up KDNET Network Kernel Debugging Manually

Support kernel-mode debugging over USB cable