Debugging Network Drivers

Overview

This guide provides practical steps for debugging Windows network drivers using WinDbg, Microsoft Message Analyzer, and related tools. It covers setup, common pitfalls, and troubleshooting strategies.

Prerequisites

  • Windows 10/11 (or Windows Server 2019/2022) with the driver installed.
  • Admin privileges on the test machine.
  • Microsoft Visual Studio (optional for source-level debugging).
  • Debugging Tools for Windows (WinDbg) latest version.
  • Network driver source code with symbols (.pdb) available.

Tools

WinDbg

Use WinDbg for kernel-mode debugging. Install it from the Debugging Tools for Windows page.

Microsoft Message Analyzer (Legacy) / Network Monitor

Capture network traffic to correlate driver behavior with actual packets.

VM/Debugging Host

Set up a virtual machine or separate host for a stable debugging environment.

Setting Up Debugging

  1. Enable kernel debugging on the target machine: 
    bcdedit /debug on
bcdedit /dbgsettings serial debugport:1 baudrate:115200
  2. Connect a null-modem cable (or use a virtual COM port) between the host and target.
  3. Start WinDbg on the host and attach to the target: 
    File → Open Remote Session → COM1, Baud Rate 115200
  4. Load symbols for the network driver: 
    .sympath+ C:\Drivers\MyNetDriver\symbols
.reload /f MyNetDriver.sys

Common Issues & Solutions

Driver fails to load (STATUS_INVALID_PARAMETER)

Check the INF file for correct hardware IDs and make sure the driver’s DriverEntry returns STATUS_SUCCESS.

!analyze -v
Network traffic not captured

Verify that the filter driver is correctly attached to the miniport. Use netsh trace start capture=yes to confirm packets are flowing.

netsh trace start capture=yes tracefile=c:\temp\nettrace.etl
System hangs after sending a packet

Enable page fault analysis and check for deadlocks with !locks and !analyze -v.

!locks

Sample Debug Session

Below is a recorded sequence of commands used to debug a packet drop issue.

// Set up breakpoints
bp MyNetDriver!SendPacket
bp MyNetDriver!ReceivePacket

g // Continue execution

// When breakpoint hits
kv // View call stack
!analyze -v // Detailed analysis

// Check NDIS queue length
dx (MyNetDriver!g_NdisQueue)->Count

References