---

name: driver-debugging description: | Windows driver debugging end-to-end: WinDbg / WinDbg-Preview, KDNET kernel debugging setup over Ethernet/USB, Driver Verifier, Application Verifier (UMDF), bugcheck analysis with !analyze -v, common kernel commands (!process, !thread, !irp, !devstack, !wdfdevice, !wdfkd.wdfdriverinfo), live and post-mortem (kernel dumps), symbol setup, and WPP / ETW trace analysis.

USE WHEN: user mentions "WinDbg", "kd", "KDNET", "kernel debugger", "Driver Verifier", "verifier.exe", "Application Verifier", "appverif", "!analyze", "!irp", "bugcheck", "0x9f DRIVER_POWER_STATE_FAILURE", "kernel dump", "MEMORY.DMP", "DebugView", "tracefmt", "tracerpt", "WPP decode"

DO NOT USE FOR: Visual Studio managed/.NET debugging, web app debugging allowed-tools: Read, Grep, Glob, Write, Edit

Windows Driver Debugging - Quick Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: driver-debugging. Authoritative source: learn.microsoft.com/en-us/windows-hardware/drivers/debugger/.

Setup checklist (one-time per test machine pair)

1. Two machines: HOST (debugger, WinDbg) + TARGET (the machine running the driver)
2. Same OS bitness, both on the same private network (or USB 3 debug cable, or serial — Ethernet via KDNET is the modern default)
3. On TARGET, enable kernel debugging:

   bcdedit /debug on
   bcdedit /dbgsettings net hostip:<HOST_IP> port:50000 key:1.2.3.4
   bcdedit /set testsigning on        ; if loading test-signed drivers
   

   bcdedit prints the debug key — copy it to HOST.
4. Reboot TARGET — it now waits for HOST early in boot (or run live)
5. On HOST: WinDbg → File → Attach to Kernel → Net → port 50000, paste key
6. Symbols: set _NT_SYMBOL_PATH=srv*c:\symbols*https://msdl.microsoft.com/download/symbols (and add your driver's .pdb path)

Driver Verifier (use this every dev/test session)

Configure on TARGET:

verifier /standard /driver MyDriver.sys
verifier /flags 0x209BB /driver MyDriver.sys     ; common production-like set
verifier /query                                   ; show current state
verifier /reset                                   ; turn off

Standard rules catch: pool corruption, IRQL violations, low resources simulation, leaked references, deadlock detection, DMA verification.

Cost: ~10–20% perf hit, occasional artificial low-memory failures. Worth it — the bugs Verifier finds are bugs that ship.

WinDbg essentials

Command	Purpose
g / gu / t / p	go / step out / step in / step over
bp <addr> / bm <pat>	software / module breakpoint
bc *	clear all breakpoints
k / kn / kp	call stack / numbered / with parameters
!analyze -v	bugcheck root-cause first stop
!process 0 0	list every process
!process 0 7 myapp.exe	dump all threads + stacks of myapp.exe
!thread <addr>	inspect a _KTHREAD
!irp <addr>	decode an IRP (driver stack, status, params)
!devstack <devobj>	show device stack for a _DEVICE_OBJECT
!devnode 0 1	the entire PnP devnode tree
!wdfkd.wdfdriverinfo MyDriver	WDF metadata about your driver (load wdfkd.dll)
!wdfkd.wdfdevice <wdfdevice>	WDF device internals (queues, refs, callbacks)
!locks / !qlocks	held kernel locks
!pool <addr>	identify a pool block (tag, size)
!poolused 4 <tag>	who allocated under this pool tag
dt nt!_EPROCESS <addr>	typed structure dump

Bugcheck analysis flow

1. !analyze -v — get the proposed culprit, parameters, faulting stack
2. Cross-check with bugcheck reference (e.g. 0xC4 = Driver Verifier detected violation, 0x9F = power state failure, 0xD1 = DRIVER_IRQL_NOT_LESS_OR_EQUAL)
3. kP for full stack with parameters
4. !irp <faulting irp> if an IRP is involved (very common for 0xD1)
5. Inspect the suspect driver:
   • lm vm MyDriver — module info, build time
   • !for_each_module .if (...) to script
6. Reproduce with Driver Verifier if not already on — it often changes a wild crash into a precise assertion

Common bugchecks tied to driver mistakes

Code	Name	Usual cause
0xA	IRQL_NOT_LESS_OR_EQUAL	Touched paged data at DISPATCH_LEVEL or freed memory
0x1E	KMODE_EXCEPTION_NOT_HANDLED	Unhandled SEH in kernel; often null deref
0x9F	DRIVER_POWER_STATE_FAILURE	Driver didn't complete a Pnp/Power IRP within timeout
0xC2	BAD_POOL_CALLER	Wrong pool free, double-free, wrong tag
0xC4	DRIVER_VERIFIER_DETECTED_VIOLATION	Verifier rule fired — read parameter 1 for the rule
0xC9	DRIVER_VERIFIER_IOMANAGER_VIOLATION	I/O misuse caught by Verifier (most common: incomplete IRP)
0xD1	DRIVER_IRQL_NOT_LESS_OR_EQUAL	Pageable code/data at DISPATCH_LEVEL
0x139	KERNEL_SECURITY_CHECK_FAILURE	Stack canary / CFG / control-flow integrity violation
0x1AA	EXCEPTION_ON_INVALID_STACK	Stack corruption

Live remote inspection (no break)

.reload /f                         ; refresh symbols
!process 0 17                       ; very verbose process list
!thread <tid>                       ; current thread
.dump /ma C:\target.dmp              ; full memory dump for offline analysis

Post-mortem (MEMORY.DMP)

Configure TARGET to write a kernel/full dump:

• System Properties → Advanced → Startup and Recovery → Write debugging information → Kernel memory dump (or Complete for big repros)
• After bugcheck, %SystemRoot%\MEMORY.DMP is created — open with WinDbg → Open Crash Dump

Application Verifier (UMDF)

For UMDF drivers (and the user-mode services that talk to them), use appverif.exe:

appverif /verify WUDFHost.exe                  ; full UMDF host coverage
appverif /verify mytestapp.exe /faults          ; with fault injection

Catches handle leaks, heap corruption, double-frees, lock-order issues — the user-mode equivalent of Driver Verifier.

WPP trace decoding

:: Start a session against the driver's WPP GUID
tracelog -start mytrace -guid GuidFile.txt -f trace.etl -flag 0xFFFF -level 5

:: Repro the bug

tracelog -stop mytrace

:: Decode using the .pdb of the driver (TMF embedded)
tracefmt -p C:\symbols\MyDriver.pdb trace.etl -o trace.txt

Or use traceview.exe (legacy GUI) for live decoding.

ETW (modern alternative for UMDF / general)

• Define an ETW provider with <instrumentationManifest> or TraceLoggingProvider.h
• Capture: wpr -start GeneralProfile && repro && wpr -stop trace.etl
• Open in Windows Performance Analyzer (WPA) for graphs, or tracerpt trace.etl -of XML

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Debug only with DbgPrint	No filtering, no offline replay	WPP / ETW with structured fields
Disable Driver Verifier "to ship faster"	Bugs ship	Keep it on for all dev/test boots
Trust the first !analyze -v answer absolutely	Heuristic, sometimes wrong	Cross-check with kP, !irp, the actual code
Stale symbols	Wrong stacks, wrong line numbers	.reload /f and pin the build's .pdb next to .sys
Debugging via Hyper-V quick-create + screen-staring	Slow loop	KDNET to a real (or VM) target, scripted repro
Saving only minidumps	Often missing the data you need	Set Kernel or Complete dump for driver bugs
Capturing ETW without a clear provider list	Massive noise	Filter by your driver's GUID + the kernel providers you actually need