XDP for Windows: Testing & Debugging

This skill covers everything an agent needs to execute tests on the required separate test machine, attach kd for crash analysis, and recover the machine to a known-good state after a bugcheck.

[!IMPORTANT]
All XDP testing must occur on a separate Windows test machine — never
the dev machine. Always pass -ComputerName <machine> explicitly on
every test command. Do not rely on
tools\remote-set-default.ps1 alone — the session default lives in
the PowerShell global scope and is silently lost when a new terminal
spawns (after Start-Process, kd sessions, or whenever the tool host
opens a fresh shell). A test script invoked without -ComputerName
and without an active session default will run **against the dev
machine** and may damage local state. Treat -ComputerName as
required.

When to Use

• Running any of: functional.ps1, spinxsk.ps1, prepare-machine.ps1

(non-build scenarios), check-drivers.ps1, rxfilter.ps1, rxfilterperf.ps1, ringperf.ps1, xskmaprx.ps1, xskfwdkm.ps1, pktfuzz.ps1.

• Triggering, observing, or analyzing a kernel bugcheck.
• Recovering a test machine that's stuck after a crash.
• Choosing default parameters for a test invocation.

Build-only scripts (always local, ignore -ComputerName)

build.ps1, merge-artifacts.ps1, publish-nuget.ps1, prepare-machine.ps1 -ForBuild / -ForEbpfBuild, create-test-archive.ps1, update-nuspec.ps1.

Remote-test workflow

1. Ask the user once per chat session which test machine to use:

"Which test machine should I run tests on?". Accept hostname, FQDN, or IP. Remember the value for the rest of the session and pass it as -ComputerName <machine> on every test invocation.

1. (Optional, human convenience only) set the session default. Does

not replace -ComputerName for agent-driven runs: ``powershell .\tools\remote-set-default.ps1 <machine> ``

1. Run any test script with -ComputerName — it auto-deploys

artifacts\bin\<plat>_<cfg>\ and streams output back: ``powershell .\tools\functional.ps1 -ComputerName <machine> -ListTestCases .\tools\functional.ps1 -ComputerName <machine> -TestCaseFilter "Name=GenericBinding" .\tools\spinxsk.ps1 -ComputerName <machine> -Minutes 5 ``

1. Credentials. First connect auto-adds the host to WSMan

TrustedHosts (UAC prompt) and, if WinRM rejects with auth error, prompts at the console (Read-Host, no GUI) for username and password. Credentials are cached in $global:XdpRemoteCredentialCache for the rest of the session. Do not generate Get-Credential calls or store passwords in scripts.

> [!IMPORTANT] > When run by an agent, console password prompts are invisible to > the user (the terminal is not interactive and any typed > characters would be shown in plaintext). If a test command stalls > waiting for credentials, do not send them to the terminal. > Instead, collect username and password through the chat UI > (vscode_askQuestions) and pass them to subsequent commands via > the -Credential parameter or by pre-populating > $global:XdpRemoteCredentialCache before re-running the script.

1. One-time test-machine setup (the user must run, requires

elevation): ``powershell .\tools\remote.ps1 -EnableRemoting `` If the user hasn't done this, the connection fails with "WinRM client cannot process the request" — surface this and ask them to run it.

1. Build first. Always run .\tools\build.ps1 (or rely on a

recent build) before remote test commands, since deploy pulls from artifacts\bin\<plat>_<cfg>\.

Choosing test parameters

When the user doesn't specify parameters, derive sensible defaults from the matching job in [.github/workflows/ci.yml](../../workflows/ci.yml). That file is the source of truth for which switches each test exercises in CI.

• spinxsk: `tools/spinxsk.ps1 -Verbose -Stats -Driver <XDPMP|FNMP>

-Minutes <N> -XdpmpPollProvider <NDIS|FNDIS> -SuccessThresholdPercent <pct> -EnableEbpf [-TxInspect]. Scale -Minutes` down for smoke runs as requested.

• functional: mirror -Config, -Platform, and any

-TestCaseFilter / -XdpInstaller flags from the CI job.

• perf/fuzz: copy the CI invocation verbatim, adjusting only

duration/iteration counts when the user asks for a shorter run.

Respect explicit user overrides; leave everything else at CI defaults.

Kernel debugger (kd) attach for bugcheck monitoring

Test machines typically have a kd "head" already attached and exposing a debug server over a named pipe (started on the head with .server npipe:pipe=<name>). To watch for breaks during a test run, attach a passive remote kd client from the dev machine in a separate background terminal before kicking off the test:

# Run with mode=async; <pipe-name> defaults to the same value as
# -ComputerName / Set-XdpRemoteDefault.
kd.exe -remote npipe:server=localhost,pipe=<pipe-name>

kd usage rules

• Always -remote npipe:server=localhost,pipe=<name> — never

-k com:pipe,port=... (that's the serial-pipe transport for VMs and will not connect to a kd debug server).

• Default pipe to the value of -ComputerName /

Set-XdpRemoteDefault. If that fails to connect, ask the user once for the correct pipe name.

• Run kd mode=async so test invocations stream output in parallel.
• Periodically check the kd terminal for break-in prompts (kd> after

a break) or bugcheck banners; surface them to the user, otherwise let kd run idle.

• If kd reports "Cannot connect to server" or exits immediately, no kd

head is currently attached. Inform the user and continue without kd.

• Keep kd attached across reboots. After .reboot, leave the kd

terminal running — secondary breaks (early-boot Driver Verifier hits, watchdog timeouts, follow-on bugchecks from corrupted state) often happen during the next boot.

• Issuing .reboot non-interactively from the dev machine. Use

kd.exe -cf <scriptfile> with a hidden window: ``powershell $cmd = New-TemporaryFile Set-Content -Path $cmd -Value ".rebootrnqd" Start-Process kd.exe -ArgumentList @( "-remote","npipe:server=localhost,pipe=<machine>", "-cf",$cmd.FullName) -PassThru -WindowStyle Hidden | ForEach-Object { $_.WaitForExit(60000) | Out-Null } Remove-Item $cmd.FullName -Force ` Do not try to drive an interactive kd> prompt via PowerShell's terminal stdin — that connects you to the host shell, not kd. Then poll Test-WSMan -ComputerName <machine>` until it succeeds.

• When the chat session ends or the user moves on, kill the kd

terminal.

Bugcheck recovery loop

Bugchecks frequently leave the test machine in a partially-corrupted state that prevents the next iteration from running. The recovery script is tools\check-drivers.ps1 -Force. The dev loop cannot move on until that command reports "No loaded XDP drivers found!".

Recovery doctrine

• Bugchecks can corrupt on-disk and registry state. Files written

in the seconds before the crash may be truncated, partially written, or filled with NUL bytes. Driver registry keys, INF/catalog files, PnP metadata, and Windows Installer product databases are common victims.

• Reinstall over partial state when feasible. When an

installer/MSI/INF reports the product is missing from its database but the on-disk binaries are still present, reinstall on top of the existing layout (which reseeds the database) and then run the normal uninstall. Prefer this over hand-rolled service/driver teardown.

• Recovery flags MUST be opt-in. Behaviors that downgrade errors,

reinstall over corruption, or paper over partial state belong behind a -Force switch on the recovery script (e.g. tools\check-drivers.ps1 -Force). Don't change default install/uninstall behavior — that would silently mask real bugs.

• Persist until clean. Each bugcheck tends to expose a *slightly

different* corruption (NUL-filled scripts last time, wedged eBPF service this time, something else next time). When check-drivers.ps1 fails: 1. Read the actual error and identify which component / step is stuck. 2. Improve tools\setup.ps1 (or tools\check-drivers.ps1) with a targeted fix for that specific failure mode — add a stuck service to the cleanup list, detect a specific MSI exit code, add a NUL-byte check for a specific file path, etc. 3. Re-run check-drivers.ps1 -Force and repeat until it succeeds. 4. Only then return to the build/test/deploy loop.

Do not stop at "the recovery is partially working" — partial recovery means the next test run will hit the residual broken state and waste an iteration. Avoid broad ignore-everything error handling; recovery should be targeted and understandable.

Common test commands

# Functional tests
.\tools\prepare-machine.ps1 -ComputerName <machine> -ForFunctionalTest
.\tools\functional.ps1 -ComputerName <machine> -Config Debug -Platform x64
.\tools\functional.ps1 -ComputerName <machine> -TestCaseFilter "Name=GenericBinding"
.\tools\functional.ps1 -ComputerName <machine> -ListTestCases
.\tools\log.ps1 -Convert -Name xdpfunc

# Stress tests (spinxsk)
.\tools\prepare-machine.ps1 -ComputerName <machine> -ForSpinxskTest
.\tools\spinxsk.ps1 -ComputerName <machine> -XdpmpPollProvider FNDIS -QueueCount 2 -Minutes 10
.\tools\log.ps1 -Convert -Name spinxsk

# Recovery
.\tools\check-drivers.ps1 -ComputerName <machine> -Force

See [docs/remote-testing.md](../../../docs/remote-testing.md) for the human-facing reference.