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)
- Two machines: HOST (debugger, WinDbg) + TARGET (the machine running the driver)
- Same OS bitness, both on the same private network (or USB 3 debug cable, or serial — Ethernet via KDNET is the modern default)
- 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.
- Reboot TARGET — it now waits for HOST early in boot (or run live)
- On HOST: WinDbg → File → Attach to Kernel → Net → port
50000, paste key
- 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
!analyze -v — get the proposed culprit, parameters, faulting stack- Cross-check with bugcheck reference (e.g.
0xC4 = Driver Verifier detected violation, 0x9F = power state failure, 0xD1 = DRIVER_IRQL_NOT_LESS_OR_EQUAL)
kP for full stack with parameters!irp <faulting irp> if an IRP is involved (very common for 0xD1)- Inspect the suspect driver:
lm vm MyDriver — module info, build time!for_each_module .if (...) to script
- 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 |
1---2name: driver-debugging3description: 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 debugging4---5# Windows Driver Debugging - Quick Reference67> **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `driver-debugging`. Authoritative source: `learn.microsoft.com/en-us/windows-hardware/drivers/debugger/`.89## Setup checklist (one-time per test machine pair)10111. **Two machines**: HOST (debugger, WinDbg) + TARGET (the machine running the driver)122. **Same OS bitness**, both on the same private network (or USB 3 debug cable, or serial — Ethernet via KDNET is the modern default)133. On TARGET, enable kernel debugging:14 ```15 bcdedit /debug on16 bcdedit /dbgsettings net hostip:<HOST_IP> port:50000 key:1.2.3.417 bcdedit /set testsigning on ; if loading test-signed drivers18 ```19 `bcdedit` prints the **debug key** — copy it to HOST.204. Reboot TARGET — it now waits for HOST early in boot (or run live)215. On HOST: WinDbg → File → Attach to Kernel → Net → port `50000`, paste key226. Symbols: set `_NT_SYMBOL_PATH=srv*c:\symbols*https://msdl.microsoft.com/download/symbols` (and add your driver's `.pdb` path)2324## Driver Verifier (use this every dev/test session)2526Configure on TARGET:27```cmd28verifier /standard /driver MyDriver.sys29verifier /flags 0x209BB /driver MyDriver.sys ; common production-like set30verifier /query ; show current state31verifier /reset ; turn off32```3334Standard rules catch: pool corruption, IRQL violations, low resources simulation, leaked references, deadlock detection, DMA verification.3536> **Cost**: ~10–20% perf hit, occasional artificial low-memory failures. **Worth it** — the bugs Verifier finds are bugs that ship.3738## WinDbg essentials3940| Command | Purpose |41|---------|---------|42| `g` / `gu` / `t` / `p` | go / step out / step in / step over |43| `bp <addr>` / `bm <pat>` | software / module breakpoint |44| `bc *` | clear all breakpoints |45| `k` / `kn` / `kp` | call stack / numbered / with parameters |46| `!analyze -v` | bugcheck root-cause first stop |47| `!process 0 0` | list every process |48| `!process 0 7 myapp.exe` | dump all threads + stacks of `myapp.exe` |49| `!thread <addr>` | inspect a `_KTHREAD` |50| `!irp <addr>` | decode an IRP (driver stack, status, params) |51| `!devstack <devobj>` | show device stack for a `_DEVICE_OBJECT` |52| `!devnode 0 1` | the entire PnP devnode tree |53| `!wdfkd.wdfdriverinfo MyDriver` | WDF metadata about your driver (load `wdfkd.dll`) |54| `!wdfkd.wdfdevice <wdfdevice>` | WDF device internals (queues, refs, callbacks) |55| `!locks` / `!qlocks` | held kernel locks |56| `!pool <addr>` | identify a pool block (tag, size) |57| `!poolused 4 <tag>` | who allocated under this pool tag |58| `dt nt!_EPROCESS <addr>` | typed structure dump |5960## Bugcheck analysis flow61621. `!analyze -v` — get the proposed culprit, parameters, faulting stack632. Cross-check with **bugcheck reference** (e.g. `0xC4` = Driver Verifier detected violation, `0x9F` = power state failure, `0xD1` = DRIVER_IRQL_NOT_LESS_OR_EQUAL)643. `kP` for full stack with parameters654. `!irp <faulting irp>` if an IRP is involved (very common for `0xD1`)665. Inspect the suspect driver:67 - `lm vm MyDriver` — module info, build time68 - `!for_each_module .if (...)` to script696. Reproduce with **Driver Verifier** if not already on — it often changes a wild crash into a precise assertion7071## Common bugchecks tied to driver mistakes7273| Code | Name | Usual cause |74|------|------|-------------|75| `0xA` | IRQL_NOT_LESS_OR_EQUAL | Touched paged data at DISPATCH_LEVEL or freed memory |76| `0x1E` | KMODE_EXCEPTION_NOT_HANDLED | Unhandled SEH in kernel; often null deref |77| `0x9F` | DRIVER_POWER_STATE_FAILURE | Driver didn't complete a Pnp/Power IRP within timeout |78| `0xC2` | BAD_POOL_CALLER | Wrong pool free, double-free, wrong tag |79| `0xC4` | DRIVER_VERIFIER_DETECTED_VIOLATION | Verifier rule fired — **read parameter 1** for the rule |80| `0xC9` | DRIVER_VERIFIER_IOMANAGER_VIOLATION | I/O misuse caught by Verifier (most common: incomplete IRP) |81| `0xD1` | DRIVER_IRQL_NOT_LESS_OR_EQUAL | Pageable code/data at DISPATCH_LEVEL |82| `0x139` | KERNEL_SECURITY_CHECK_FAILURE | Stack canary / CFG / control-flow integrity violation |83| `0x1AA` | EXCEPTION_ON_INVALID_STACK | Stack corruption |8485## Live remote inspection (no break)8687```88.reload /f ; refresh symbols89!process 0 17 ; very verbose process list90!thread <tid> ; current thread91.dump /ma C:\target.dmp ; full memory dump for offline analysis92```9394## Post-mortem (`MEMORY.DMP`)9596Configure TARGET to write a kernel/full dump:97- System Properties → Advanced → Startup and Recovery → Write debugging information → **Kernel memory dump** (or **Complete** for big repros)98- After bugcheck, `%SystemRoot%\MEMORY.DMP` is created — open with WinDbg → Open Crash Dump99100## Application Verifier (UMDF)101102For UMDF drivers (and the user-mode services that talk to them), use `appverif.exe`:103```cmd104appverif /verify WUDFHost.exe ; full UMDF host coverage105appverif /verify mytestapp.exe /faults ; with fault injection106```107108Catches handle leaks, heap corruption, double-frees, lock-order issues — the user-mode equivalent of Driver Verifier.109110## WPP trace decoding111112```cmd113:: Start a session against the driver's WPP GUID114tracelog -start mytrace -guid GuidFile.txt -f trace.etl -flag 0xFFFF -level 5115116:: Repro the bug117118tracelog -stop mytrace119120:: Decode using the .pdb of the driver (TMF embedded)121tracefmt -p C:\symbols\MyDriver.pdb trace.etl -o trace.txt122```123124Or use `traceview.exe` (legacy GUI) for live decoding.125126## ETW (modern alternative for UMDF / general)127128- Define an ETW provider with `<instrumentationManifest>` or `TraceLoggingProvider.h`129- Capture: `wpr -start GeneralProfile && repro && wpr -stop trace.etl`130- Open in **Windows Performance Analyzer (WPA)** for graphs, or `tracerpt trace.etl -of XML`131132## Anti-Patterns133134| Anti-Pattern | Why It's Bad | Correct Approach |135|--------------|--------------|------------------|136| Debug only with `DbgPrint` | No filtering, no offline replay | WPP / ETW with structured fields |137| Disable Driver Verifier "to ship faster" | Bugs ship | Keep it on for all dev/test boots |138| Trust the first `!analyze -v` answer absolutely | Heuristic, sometimes wrong | Cross-check with `kP`, `!irp`, the actual code |139| Stale symbols | Wrong stacks, wrong line numbers | `.reload /f` and pin the build's `.pdb` next to `.sys` |140| Debugging via Hyper-V quick-create + screen-staring | Slow loop | KDNET to a real (or VM) target, scripted repro |141| Saving only minidumps | Often missing the data you need | Set Kernel or Complete dump for driver bugs |142| Capturing ETW without a clear provider list | Massive noise | Filter by your driver's GUID + the kernel providers you actually need |
claude-dev-suite