The second installment of a beginner’s guide to debugging with NDISKD

Last time we set up the debugger, looked at !ndiskd.help, and dumped out a table of active miniports.  Today we’ll continue our laboratory by examining a specific miniport.  As before, we use !ndiskd.miniports to get the table of active miniports:

kd> !ndiskd.miniport
    MiniDriver         Miniport            Name                                _
    fffffa800acf4640   fffffa800ad051a0    WAN Miniport (SSTP)
    fffffa800ac8f020   fffffa800ac911a0    Microsoft Virtual Machine バス ネットワーク アダプター

Suppose we want to get more information about the VM NIC named "Microsoft Virtual Machine バス ネットワーク アダプター".  (It’s a Japanese target OS; this example showcases ndiskd’s newfound Unicode support).  To pull up the details page on the Miniport, click the link in the second column.  On my machine, the link is labeled fffffa800ac911a0, although it will be different for your machine.

When you click the link, the debugger displays a screenful of information.  To keep things simple, we’ll dissect the output in sections.  The first section displays basic information about the miniport.

MINIPORT
    Microsoft Virtual Machine バス ネットワーク アダプター
    Ndis Handle        fffffa800ac911a0
    Ndis API Version   v6.0
    Adapter Context    fffffa800ad7e000
    Miniport Driver    fffffa800ac8f020 - netvsc60.sys  v6.0
    Ndis Verifier      [No flags set]
    Media Type         802.3
    Physical Medium    NdisPhysicalMediumUnspecified
    Device Path        \??\VMBUS#{9df4aa68-e174-46f3-b4d1-716969be9559}#5&296c0f0e&0&{9df4aa68-e174-46f3-b4d1-716969be9559}#{ad498944-762f-11d0-8dcb-00c04fc3358c}\{42C420A8-067B-41DC-B746-114BAA3FB84A}
    Device Object      fffffa800ac91050
    MAC Address        00-15-5d-1e-25-09

There’s a lot of information there—let’s consider one row at a time.  The Ndis Handle shows the miniport handle that we just clicked on.  Every NDIS object (miniport instances, miniport drivers, filter instances, etc.) has a handle that uniquely identifies it to NDIS.  If you are manually typing ndiskd commands, you’ll usually have to include a NDIS Handle value to specify which object you’re manipulating.  Of course, clicking the Windbg hyperlinks is easier than copying and pasting handle values; then you don’t need to know the handle value at all.

The NDIS API Version identifies which version of the NDIS contract the miniport is written to.  There is an exhaustive table of versions here.

The Adapter Context is a pointer to the driver-specific information.  For example, if you are using the XFrameII sample miniport, it is a pointer to an xmpNicCtx_t structure.

Miniport Driver is, not surprisingly, a NDIS handle to the MiniDriver.  Click on it to get more information about the driver.

The Ndis Verifier row shows you any Ndis Verifier settings that might be enabled for this miniport.  NDISTest manipulates Verifier settings on your behalf, so don’t be surprised if you see some flags set on your miniport during testing.  But in the output above, we see that there are not any verifier flags set on my miniport instance.

The Media Type and Physical Medium rows show what type of network interface this miniport is.  If you’re a networking nerd, you might recall that 802.3 is the IEEE name for Ethernet.  But if you didn’t remember that, it’s still okay, since you can click on it to pull up a definition from ndiskd’s built-in help database.

The Device Path shows the device instance ID.  The Device Object shows WDM’s underlying DEVICE_OBJECT.

Finally, the MAC address should hopefully need no introduction.

STATE
    Miniport           Running
    Device PnP         Started
    Datapath           Normal
    Interface          Up
    Media              Connected
    Power              D0
    References         8
    User Handles       0
    Total Resets       0
    Pending OID        None
    Flags              2c452000
        ↑ NOT_BUS_MASTER, DEFAULT_PORT_ACTIVATED, SUPPORTS_MEDIA_SENSE,
        DOES_NOT_DO_LOOPBACK, MEDIA_CONNECTED
    PnPFlags           00210000          ← RECEIVED_START, HARDWARE_DEVICE

The next section shows the current state of the miniport.  As you might notice, everything is printed in green text—green is supposed to hint that "packets can be sent".  If you are trying to figure out why network packets aren’t getting through, the first thing you’ll want to do is scan this section for status that isn’t green.  (Colored text is not available in kd.exe by default, so kd users can instead compare the text output to the 'good' text printed in the example above).

There are also a number of flags printed here.  The flags are useful in advanced debugging situations; you don’t usually need to worry about them too much.  If you do see a suspicious-looking flag, you can always click it to see the explanation from ndiskd’s built-in help database.

BINDINGS
    Filter List        Filter              Filter Driver      Context          _
    WFP LightWeight Filter-0000
                       fffffa800b3068d0    fffffa800ab682d0   fffffa800b2e9630
    Buggy Filter Driver 1-0000
                       fffffa800b2e3540    fffffa800ac207b0   fffffa800b2e44b0
    Open List          Open                Protocol           Context          _
    RSPNDR             fffffa800b91b8d0    fffffa800b920010   fffffa800b926010
    NDISUIO            fffffa800b9236b0    fffffa800b90f910   fffffa800b921e00
    LLTDIO             fffffa800b90c8d0    fffffa800b90d760   fffffa800b90c010
    TCPIP6             fffffa800b3018d0    fffffa800a997010   fffffa800aaff290
    TCPIP              fffffa800b3082a0    fffffa800a996540   fffffa800b3089e0

The next section shows you the binding stack.  The first table shows you the filter drivers that are bound to the miniport.  The filters are listed in the order of their binding altitude.  The second table shows the protocols that are bound to the miniport.  (Note that in NDIS terminology, an instance of a protocol is called an Open—see this post.)  You can get more information about a filter or open by clicking the corresponding entry in the table.

MORE INFORMATION
     → Driver handlers                      → Task offloads
     → Power management                     → PM protocol offloads
     → Pending OIDs                         → Timers
     → Pending NBLs                         → Receive Side Throttling
     → Wake-on-LAN (WoL)                    → Packet filter
     → Receive queues                       → Receive filtering
     → NDIS ports                           → NIC switch

Finally, the last section is a list of links to more information.  The first three links (Driver Handlers, Power management, and Pending OIDs) are the most useful.  When debugging issues in miniports, I will often click on Driver Handlers so I can set a breakpoint in the miniport driver and catch the bug in action.  Note that because we give you the same ndiskd that we use internally to debug NDIS itself, not all of the other links will work properly with NDIS's public symbols.

Phew, that was a lot of material to cover.  Next time we’ll put this material to use as we diagnose a real network problem using ndiskd.