Kernel debugging over the network

What just happened to my NIC?!

We’ve previously published some tips on how to use the debugger to fix your NDIS miniport driver.  But today we’re going to turn the tables and talk about how the debugger uses NDIS to break your miniport driver.

You can debug the Windows kernel through several transports.  One of the fastest transports is the NET transport, which works over common network cards connected by an ordinary Ethernet cable.  Most developers are happy to run through the setup checklist and just begin debugging.  But for those of you who work on network drivers, you might notice a few strange things happening to the network stack when NET debugging is enabled.  What’s going on?

First, let’s take a look at how the debugger works when it’s not using networking.  This diagram shows the network stack behaving normally.

The miniport driver talks to its hardware, and the debug transport is preoccupied with some other piece of hardware.  Everything is normal.  But now when we enable kernel debugging over the NIC, let’s see how the diagram changes.

In the second diagram, the debug transport has taken over the NIC hardware completely!  The miniport driver, NDIS, and even the kernel itself are excluded from talking to the NIC hardware.  That’s why, when kernel debugging is enabled, you see the NIC device getting “banged out” in Device Manager.  At boot, NDIS tried to initialize the miniport, but NDIS saw that the kernel debugger had exclusive access to the hardware, so NDIS failed the miniport’s AddDevice.  In other words, the yellow exclamation mark is by design: the vendor NIC “failed” to load because the kernel debugging is enabled.

If that were all to the story, then we’d have working kernel debugging, but completely broken networking.  Fortunately, there’s more.

When the debugger team at Microsoft planned this feature, they realized that network debugging wouldn’t be very useful if it broke your networking.  So they also planned a second piece to the architecture.  The debug transport exposes a virtual network adapter, based off of the underlying physical adapter.  This virtual adapter has a regular NDIS driver, so the rest of the OS can talk on the network.

This virtual NIC is named the “Microsoft Kernel Debug Network Adapter”.  It is pre-installed on all Windows 8 machines, but it is only enabled once kernel debugging over networking is enabled.  When it’s enabled, it carries your normal traffic (TCPIP, etc.) out to the physical NIC that is now being used for kernel debugging.

So now you can explain why there’s that additional network device hidden in Device Manager: it’s waiting for the moment that you enable kernel debugging, so it can be your main network adapter.  You can also explain why the Network Connections folder shows a different adapter when kernel debugging is enabled: TCPIP really is bound to a different adapter (as far as the OS knows).