(转载)Testing Network Drivers with the NDIS Test Tool

(转载)

Testing Network Drivers with the NDIS Test Tool
July 15th, 2003
Stephan Wolf

Copyright © 2003 by Stephan Wolf. All rights reserved

Any device driver that you write has the potential risk of crashing the system. Thus, you should intensively test your driver before shipping it.

Network drivers only cause about 1% of all Windows system crashes for good reason: The official Microsoft NDISTest Tool is the acid test for all "lower edge" NDIS network drivers such as NDIS miniport and NDIS intermediate drivers.

If you write an NDIS driver, you should use NDISTest at any stage during your driver development to verify the driver's integrity and stability. Not only will NDISTest find bugs in your driver that cause system crashes, but it will also help you to write a fully NDIS conformant driver with respect to all of the following:

• Replies to get and set requests for mandatory as well as optional OIDs
• Handling of unexpected NDIS failure replies
• Indication of cable connect and disconnect events
• Driver halt/restart and unload/reload
• Adapter reset request
• Send and receive path and send packet cancellation
• Receive filter including multicast frames, promiscuous mode etc.
• Task Offload such as TCP/IP checksum offload and IPSec offload
• ...and more

Which NDIS drivers can I test with NDISTest?

NDISTest can test all of the following NDIS drivers:

• NDIS miniport drivers for the following physical network adapter types:

  • Ethernet
  • Token Ring
  • FDDI
  • ATM
  • ISDN
  • Modem
  • IrDA
  • WLAN
  • WWAN (some WWAN devices have known troubles with the send/recv and load/unload tests)
  • SAN (the SAN tests require extra scripts that are shipped in the HCT but are not part of the standalone NDISTest download)

• NDIS intermediate (IM) drivers that implement virtual network adapters

What equipment do I need to test my NDIS driver?

Although you can run NDISTest with just a single network card in one machine (see "one card tests" below), I recommend using two computers, four network cards, and two hubs to run NDISTest, as shown in Figure One.

Figure One
Recommended Full NDISTest Hardware Setup

It's a good idea to use non-intelligent hubs or repeaters instead of intelligent switches for the test network. Some tests may fail or show warnings when switches are used because they filter the network traffic. If your network adapters so permit, you can connect them back-to-back directly (using a crossover cable) and omit the switch or hub.

An easy way to setup NDISTest with only one machine and two network cards is shown in Figure Two. If you have only one network card available, you can even omit the second network adapter and still run NDISTest.

Figure Two
Simple NDISTest Hardware Setup

NDISTest offers you the following test categories, which you can combine as desired. Each test category requires some or all of the hardware I just described.

1c - one card tests

Install the "test device" network adapter that your driver requires in the client machine, and you are ready to run the one card (1c) tests. I colored the test device blue in Figures One and Two. This is the minimal test setup.

2c - two card tests

For the two card (2c) tests, install an additional "support device" network adapter in the client machine. Connect it to the test device on a private "test network". This support device is colored orange in Figure Two.

2m - two machine tests

Add a server machine for the two machine (2m) tests. Equip the server with a "support device" (orange) network adapter and connect it to the same private test network as the test device of the client as shown in Figure One. The support device in the server takes over the role of the support device in the client, so the support device is no longer required in the client machine.

For the communication channel between the server and the client add a "message device" (green) network adapter to both the client and the server machine. The two message devices can be anything that allows for TCP/IP to run on top of them. For instance, if your test and support devices are Wireless LAN adapters, the message devices can be standard Ethernet adapters.

Connect the two message devices to a "message network" that is separate from the private test network. Note that the message network does not need to be a private network and you may also connect other machines to it. If the message devices are the adapter cards that you ordinarily use to connect the client and server machines to your office LAN, and if you're using TCP/IP as the network protocol, you've already done this step.

Alternatively, you may also connect the two message devices to the test network, but I recommend that you use independent test and message networks.

In order to achieve an optimal test coverage, you should run NDISTest on two machines with all of the available 1c, 2c, and 2m tests enabled. If available, you should use a multi-processor machine as the client.

Where Do I get the NDIS Test Tool?

NDISTest is part of the Microsoft Hardware Compatibility Test (HCT). But it is also available as a stand-alone tool coming in a self-extracting archive file, which you can download from the Microsoft Windows Hardware & Driver Central (WHDC) at the NDIS Test Tool page

Note: The HCT is required to run the official WHQL tests, which qualify a device for the "Designed for Windows" logo. You can download the complete HCT in the WHQL Network Testing section (several hundred MB!). If you have MSDN Universal Subscription, then the HCT is included in your distribution CDs. After installing the HCT you will find NDISTest in "<HCT root directory>/testbin/ndistest".

Can I test on Windows 98 or Windows ME?

The current version of NDISTest (at the time of this writing) runs on Windows 2000, Windows XP, and Windows 2003. It does not run on Windows 98 or Windows ME. An older version of NDISTest does run on these older systems, namely version 3.91, and it is available from Microsoft WHQL (Windows Hardware Quality Labs) in their Network Testing section as file "ndt391.exe".

Note that you will find the term "trusted card" being used in earlier NDISTest versions, which is similar to what is now known as a "support device". However, with older NDISTest versions you need one trusted card in both the client and the server whereas newer NDISTest versions require only one support device in either the client or the server.

How do I install the NDIS Test Tool?

Installation of NDISTest is a fairly easy task: Simply run the downloaded self-extracting archive file and unzip the contained NDISTest files to a directory of your choice. Install NDISTest once on the client machine and once on the server machine.

Note: Once you extract the archived files, you can use the batch file "ndsetup.bat" to create further installation copies of NDISTest. For instance, to create the new directory "n:/ndistest" and copy a new installation of NDISTest there, open a command prompt in the current installation directory of NDISTest and enter the following command:

  ndsetup n:/ndistest

What else do I need?

I recommend connecting a debugger to your client machine for several reasons:

• NDISTest prints a lot of messages to the debugger console. They will help you better understand any failed or warned tests.
• Your driver should also print messages to the debugger when it detects any anomalies.
• When NDISTest detects some critical situation it may hit a breakpoint, which will freeze the machine until you take appropriate actions in the debugger.
• Any bugs in your driver can potentially crash the system. NDISTest usually hits those bugs, so it is a good idea to have a debugger ready that you can use to examine the bugcheck.

In very rare cases NDISTest may also hit a breakpoint in the server. So you may need to also connect a debugger to the server machine then.

The Microsoft WinDbg debugger is available for download in the Microsoft WHDC section Microsoft Debugging Tools. If you have an NDISTest server machine you can run WinDbg on the server machine and connect it to the client machine.

During installation of NDISTest, all the debug symbols for NDISTest are copied to the directory "<cpu>/symbols" under the directory where you installed NDISTest. You should add this directory to your debugger's symbol path.

If you are unable to connect a debugger to your client or server machine, you can alternatively use a tool like SysInternals' freeware tool DebugView, which you can download from their utilities section. Actually you can use any tool or debugger (e.g. SoftICE) that will display kernel debug messages.

Another useful tool is a network sniffer that allows you to watch all the traffic on the test network. The sniffer tool should not use any of the test or support devices but should use an extra network adapter also connected to the test network. You should prefer to run the sniffer on a separate third machine.

How do I configure the NDIS Test Tool?

Before you configure NDISTest, make sure to enable TCP/IP on both message devices and configure them to use the same IP subnet address. If you have DHCP enabled on the message devices, you should be ok. Check the IP addresses with the IPCONFIG command in a command prompt window if in doubt.

NDISTest will present you only those physical and virtual network adapters that are actually still available for the test, message, and support device entries. It is important to note that NDISTest will no longer show any entries that are associated with the same adapter once you select a listed adapter to be a test, message, or support device. This makes sense as you for instance cannot test an intermediate driver with a support device that is the physical adapter to which the IM is bound.

You need administrator privileges on the client and server machines in order to run NDISTest.

Start the server first

If you have a server machine, start NDISTest on the server first. Make sure you have administrator privileges on the server.

1. Run the "ndtest.bat" file from the directory where you installed NDISTest on the server.
2. Select the TESTS tab.
3. On the right, select the SERVER radio button.
4. In the MESSAGE combo box, select the message device from the list of adapters. Notice that the IP address is listed for each adapter.
   Note: The MESSAGE combo box will only show adapters that have TCP/IP bound to it.
5. Select the support device in the SUPPORT DEVICES list box.

   
   Figure Two
   Test settings for server machine

6. Hit the START button.

The server is now fully configured and waiting to participate in any tests that the client will run.

Now start the client

Make sure you have administrator privileges on the client.

1. Run the "ndtest.bat" file from the directory where you installed NDISTest on the client.
2. Select the TESTS tab.
3. On the right, select the CLIENT radio button.
4. In the TEST combo box, select your test device from the list of adapters. The test device can be the NDIS miniport or intermediate driver of any physical or virtual adapter.

   Note: If you are testing an NDIS intermediate driver, be sure to use an underlying network card that will pass NDISTest on its own. Run the tests that you intend to make on your NDIS IM driver on the "bare card" before you test your IM driver.

5. If you have a server machine, select the message device from the list of adapters in the MESSAGE combo box. Notice that the IP address is listed for each adapter. The support device(s) of the server machine will now appear in the SUPPORT DEVICES list box.
   Note: The MESSAGE combo box will only show adapters that have TCP/IP bound to it.
6. Select the support device in the SUPPORT DEVICES list box. If you have a server machine, make sure to select the support device of the server, not the client.
7. Select the MANUAL TESTS radio button.
8. You can select as many tests as you would like to run or simply hit the SELECT ALL button. Which tests can be selected depends on whether a support device is available:
   • One card (1c) tests are always available.
   • Two card (2c) tests can be selected as soon as a support device is available on the local client or on the remote server machine.
   • Two machine (2m) tests are only available when the support device is on the server machine.

   NDISTest will execute tests in the order they appear in the list.
   Note: You can change the order of the tests by selecting a test script, holding down the <Ctrl> key, and moving the test script with the <Up> and <Down> keys.

   
   Figure Three
   Test settings for client machine

9. Tests will begin as soon as you hit the START button. You can watch the status of the individual tests in the test progress window.

   Note: When you start NDISTest for the first time on the test device, a message box might appear saying that you will have to restart the machine in order to enable the Driver Verifier on the test device. NDISTest enables Driver Verifier by default on the test device and you should leave it enabled to achieve an optimal test coverage.

How long a test run takes depends on the number of tests selected, the speed of the machine(s) and the speed of the network. This can be anything from less than a minute to several hours.

Where can I see a summary of the test results?

Here is how you can get a list of the results of all individual tests:

1. On the main menu, select "Results" - "Test Logs...".
2. In the combo box on the top, select the test run for which you want to see the test results.
   Note: NDISTest creates a new test result entry for each test run and saves the results of the individual tests there.
3. The list of the selected test run's test results appear in the list box along with a short summary for each individual test.
4. Select the file "ndistest.htm" for a summary of the selected test run's test results or click on the file name of any of the individual test results to see its contents.

NDISTest will find lots of bugs and anomalies in your driver. It's really nit-picking and tests almost everything that has been specified in NDIS.

Bottom line

The quality of your NDIS miniport or intermediate driver will substantially increase when you run NDISTest against it. Do not wait to test your driver until you have added more features to it but test it as soon as you can install it for the first time. NDISTest will ensure your driver conforms to NDIS and will reveal any bugs at a very early stage.

Although available since the early 1990s, NDISTest has not become very popular amongst NDIS driver developers. Maybe because most people think NDISTest is only available in conjunction with the HCT. However, NDISTest is actually available separately from the HCT and is a great tool that will make your life easier.

Further reading

NDISTest comes with a help file that has many details about how the program works internally. You will find information about the packet structure that NDISTest uses for the packets it sends out to the test network, a list of command line options, and much more. So it's really worth reading it.

About the author:

Stephan Wolf has worked as an independent system software developer since 1988. He lives and works mainly in Germany, but sometimes abroad. His focus is on network driver development (not only) for all Windows variants (including CE). You can contact him at [e-mail] (hotmail sometimes "recognizes" serious email as spam, so try again if you get no answer).