microsoft/openvmm
Publicmirrored fromhttps://github.com/microsoft/openvmmAvailable
Guide/src/reference/dev_feats/kdnet.md
58lines · modecode
| 1 | # Kernel Debugging (KDNET) |
| 2 | |
| 3 | Kernel Debugging is available for Windows guests via KDNET over VMBus. |
| 4 | |
| 5 | ## Enabling and Starting the Debugger |
| 6 | |
| 7 | Set up KDNET on the guest and start the debugger as described on |
| 8 | [Set up KDNET network kernel debugging manually | Microsoft Learn](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-a-network-debugging-connection). |
| 9 | Setting `busparams` is not necessary. |
| 10 | |
| 11 | ```admonish warning |
| 12 | If you're using a `memdiff:` disk (the default in most examples), guest state |
| 13 | is not persisted between runs. You'll need to configure KDNET in the guest |
| 14 | each time you launch — or configure it once on the base disk image before |
| 15 | wrapping it with `memdiff:`. |
| 16 | ``` |
| 17 | |
| 18 | ## With OpenVMM and WHP as Host |
| 19 | |
| 20 | Launch the VM with UEFI and networking enabled. KDNET requires `--net consomme` |
| 21 | for the network transport: |
| 22 | |
| 23 | ```bash |
| 24 | # Without OpenHCL |
| 25 | cargo run -- --uefi --hv --net consomme --disk memdiff:file:path/to/windows.vhdx |
| 26 | |
| 27 | # With OpenHCL |
| 28 | cargo run -- --uefi --hv --vtl2 --net consomme --igvm path/to/openhcl.igvm --disk memdiff:file:path/to/windows.vhdx |
| 29 | ``` |
| 30 | |
| 31 | ### Known Issues |
| 32 | |
| 33 | - **Networking backend:** KDNET currently requires `--net consomme`. The |
| 34 | `consomme` backend creates a new network adapter in the guest on each |
| 35 | OpenVMM restart — this is harmless and can be ignored. Using |
| 36 | `--net vmnic:<switch id>` connects but hangs immediately due to an |
| 37 | undiagnosed vmbusproxy issue. |
| 38 | - **Debugger reconnection:** If you quit OpenVMM without shutting down the |
| 39 | guest first, the same WinDbg instance cannot reconnect on next boot. |
| 40 | Close and relaunch WinDbg to reconnect. |
| 41 | - **Synic warnings with OpenHCL:** When launching an OpenHCL VM with KDNET, |
| 42 | you may see a stream of `failed to signal synic` errors from |
| 43 | `virt_whp::synic` for several seconds. These do not affect VM functionality |
| 44 | and can be ignored. |
| 45 | |
| 46 | ## Debugging workflow |
| 47 | |
| 48 | Once KDNET is connected: |
| 49 | |
| 50 | 1. In WinDbg, go to **File → Kernel Debug → Net** and enter the key and port from the guest setup. |
| 51 | 2. Start the VM. WinDbg should connect during Windows boot. |
| 52 | 3. To break into the debugger: **Debug → Break** (or Ctrl+Break). |
| 53 | |
| 54 | ```admonish note |
| 55 | KDNET debugs the VTL0 (guest) Windows kernel. For debugging the VTL2 |
| 56 | (OpenHCL) side, see [Debugging OpenHCL](../openhcl/debugging.md) which covers |
| 57 | serial logs, crash dumps, and `ohcldiag-dev`. |
| 58 | ``` |