Kernel debugging over the network

  • Article

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).

Comments

  • Anonymous
    September 21, 2016
    If I do not see "Microsoft Kernel Debug Network Adapter" under Network Adapters in Device Manager, what could be the reason? I am using Windows 10 Pro and do not see this enlisted, and hence I am unable to do kernel debug. The actual physical NIC is installed and I am able to browse the Internet (I am not able to browse the internet when I do bcdedit /debug on, because it says this device is used for Kernel Debug). So, why should the machine not have the kernel debug network adapter installed, and how do I get it?
    • Anonymous
      February 12, 2017
      Device Manager hides the kernel debug adapter by default. You can click a checkbox to show hidden devices.
      • Anonymous
        March 29, 2017
        Same issue, even after I check "show hidden devices" the windows kernel debug adapter still not shown. I uninstalled the adapter before because my host machine cannot connect to target machine over kernel debugger. (they can ping each other no problem) On the other hand my target machine can kernel debug host machine. So I'm pretty sure the issue is on target machine side. I have all bcdedit stuff setup correctly, also tried setup busparams, still host cannot kernel debug target. So I want to try reinstall Kernel Debug Network Addapter driver, but I cannot find it anywhere from Microsoft. (Even though I'm sure the driver was not deleted from my target machine because I didn't check "also delete driver file" when uninstall the adapter). All in all, I guess my question is same with Sankar, how do I get the adapter installer? Appreciate for any help!