NDIS Driver Tips and Guidelines

Updated: December 4, 2001

NOTE: NDIS 5.0 is deprecated and will be removed in future versions of Windows. Refer to NDIS 6.x.

On This Page

  Driver Initialization
  General Guidelines for Writing NDIS Miniport Drivers
  Recommended Solutions for NDIS Driver Problems
  Tips for Driver Initialization and Performance
  Testing Network Adapter Drivers with Driver Verifier

Driver Initialization

Driver initialization times can have significant impact when a system is starting up or waking up, affecting the end-user experience of how fast the system is and how it looks and feels. Microsoft testers discovered that, in many cases, the initialization time can be reduced several seconds by optimizing the NDIS miniport drivers.

Driver Initialization. The time spent in driver initialization can have a significant impact on the time it takes for Microsoft Windows to boot. Reducing this time is particularly important for laptops when they are not connected to a network, as well as for desktop systems that are suspended and restored. Driver initialization time should always be on the order of 10s of milliseconds.

To optimize driver initialization:

• Always perform media detection first. If it can be determined that no network cable is present, then link speed detection should be skipped.

• If the media is connected, defer link speed detection to a timer routine. The rest of the network stack comes later, and by the time it needs this data, the information should be available. Knowledge of this information is not required until the OID_GEN_MEDIA_SPEED query arrives.

Driver Shutdown. When the driver is asked to shut down, nothing else should be done except setting the hardware into an idle state.

Driver Halt. In addition to the processing done for shut down, the Halt routine must also free all resources. Please note the following additional requirements:

• If the driver uses timers, they must be cancelled. If NdisMCancelTimer() fails, this implies that the timer has already fired. In this situation, wait for the timer handler to complete. For solutions to this problem, see "Recommended Solutions for NDIS Driver Problems" later in this article.

• If packet indications using NdisMIndicateReceivePacket() are used in the driver, make sure that all outstanding packets have been returned before returning from the Halt handler. An easy way to do this is the following:
  
  while (NdisPacketPoolUsage(PacketPoolHandle) != 0) NdisMSleep(10);

Driver Interrupt Handling. Determine whether an interrupt is yours from the hardware state when the driver interrupt service routine (ISR) is called. If it is, request that a deferred procedure call (DPC) be queued, and disable the interrupt. Re-enable the interrupt when the DPC completes.

Make sure the hardware will not raise an interrupt until the driver is ready to handle it--that is, after NdisMRegisterInterrupt() completes.

 Top of page

General Guidelines for Writing NDIS Miniport Drivers

The miniport driver should make only NDIS library calls. Avoiding the use of operating system-specific kernel calls increases the portability of the code between Windows platforms. Also, to make the NDIS miniport drivers binary compatible between Windows 98/Windows Me and Windows 2000/Windows XP, the BINARY_COMPATIBLE flag must be used. If you have to call interfaces outside the NDIS library, use only the calls defined in the Wdm.h file, which can be found in the Windows DDK.

Important: The development of full MAC drivers is no longer supported or documented in the DDKs. Support for full MAC drivers will be removed from future releases of Windows operating systems.

 Top of page

Recommended Solutions for NDIS Driver Problems

Both hardware and software vendors can use the information here to avoid repeating these same problems during their own testing processes.

Problem: NDIS Driver Timers Fail during Driver Unload. Drivers can be loaded and unloaded multiple times under Windows 2000/Windows XP through calls to the MiniportHalt routine. All operations necessary to unload the driver must be completed when this routine is called, including freeing memory, deregistering interrupts and shutdown handlers, and canceling timers. Timers are cancelled by a call to NdisMCancelTimer; however, in some cases, a call to NdisMCancelTimer may fail.

If NdisMCancelTimer fails, this means that the timer has already fired. If the timer has fired, the driver cannot unload until the timer routine has been called and completed. The following options can help avoid this problem:

• Keep a reference count for the timer.

• Have the timer function trigger an event in the case of the NdisMCancelTimer call failing; the MiniportHalt handler can be set to block on that event.

• Ensure that the timer function should also detect that the driver is halting and not queue another timer.

The miniport's shutdown handler should only stop generating interrupts, DMA transfers, and so on. It should not cancel timers or de-allocate resources.

Problem: NDIS Driver Doesn't Start during Initialization. Most PCI card drivers should set the Dma32BitAddresses parameter to TRUE. The only reason for setting this flag to FALSE is if the card cannot address memory above 16 MB. If the flag is set to FALSE, the driver may not start during initialization, as memory below 16 MB can be a scarce resource. This can also cause problems with cards that are not power managed. In this case, the drivers are halted on Suspend and re-initialized on Resume. In addition, the network adapter may fail to initialize on Resume.

The NE3200 sample driver in the Windows DDK is for a PCI card that cannot address physical memory that exceeds 16 MB. Therefore, when allocating resources for DMA transfers, this sample driver calls NdisMAllocateMapRegisters with the Dma32BitAddresses parameter set to FALSE.

 Top of page

Tips for Driver Initialization and Performance

Follow these tips for driver initialization, send requests, and buffer allocation.

NDIS Driver Initialization Routine Process. A miniport driver should only call NdisMIndicateStatus after its initialize routine. Until an NDIS miniport's MiniportInitialize routine completes, NDIS is not prepared to receive and process status indications from these drivers.

NDIS Drivers Must Not Complete Requests at Device IRQL. NDIS Miniports complete send request by calling NdisMSendComplete. This should never be done at the device interrupt request level (DIRQL). Some drivers incorrectly complete send requests in a function called through NdisMSynchronizeWithInterrupt. Doing this causes the called function to execute at DIRQL. Sends should never be completed at this IRQL. (Note that an earlier version of this article stated this incorrectly; this text represents the correct information.)

Reduce Free Buffers for Drivers to Increase System Performance. Memory should be allocated dynamically where possible on an as-needed basis. When large amounts of memory are allocated for driver use, system performance can degrade. Large amounts of memory consumption in low-memory environments can also affect system performance.

The initial number of buffers typically starts at 32 to 64 and should be increased in increments of 32. The highest number of buffers allowed should be 256.

In an NDIS 3.0 model driver where the network adapter driver always owns received packets, a fixed number of buffers (scaled to the bandwidth) are all that is needed. For a 100 Mb/s system, 32 to 64 buffers are sufficient. For Gigabit Ethernet, the number of buffers could be double that of a 100 Mb/s system.

In a driver that uses the Receive Packet model, the network adapter relinquishes control of the receive buffer to the network stack. The network adapter driver is then required to manage this pool. A potential way to do this is as follows:

1. Determine the lowest number of buffers needed. When this number is reached, all receive indications are marked so that the ownership of these buffers is retained with the network adapter driver by setting status in the packet to NDIS_STATUS_RESOURCES.

2. Determine the highest number of buffers needed. The driver must never grow the pool beyond this limit. This restriction ensures that a busy server does not utilize a large amount of the available memory.

3. If the number of free buffers hits the lowest number needed and the total number of buffers is less than the highest number needed, then initiate an asynchronous allocation to grow the buffer pool. Until the allocation completes, indicate packets with NDIS_STATUS_RESOURCES.

4. If the number of free buffers is greater than that designated by the lowest number needed and has consistently stayed there for a duration of time, continue to free additional buffers.

 Top of page

Testing Network Adapter Drivers with Driver Verifier

To better ensure driver quality, the Windows test teams have extended the testing done to include the use of the Driver Verifier. Drivers are required to pass this testing to be included with Windows 2000/Windows XP, and the test tools are being modified to automatically turn on driver verification at Level 3 for all network interface card (NIC) drivers tested with these tools. The Driver Verifier is documented in the Windows DDK.

One of the best ways to ensure creation of high quality drivers is to run the Driver Verifier before submitting your driver to Microsoft for testing. The Driver Verifier should be run at Level 3 through the entire suite of NDIS tests before submission.

All drivers that are submitted for inclusion with Windows products are tested extensively by the Windows networking team. Drivers that pass this testing are verified on an ongoing basis with current builds of the operating system. A subset of the tests and tools used to verify these drivers are also part of the Microsoft Windows Hardware Compatibility Tests (HCTs) required for the Windows Logo for hardware.

Call to action for NDIS 5.0 driver writers:

• Evaluate the opportunities for reducing initialization time in your network drivers.

• Test using Driver Verifier with your drivers before you submit them for testing.

• Use the tips presented here to improve NDIS driver testing results.

• For more information about Driver Verifier, see Driver Verifier in Windows XP.

• For information about driver installation issues, INF files and formats, see the article Network INF Format for Windows.

• For guidelines related to NDIS 5.0 support for network adapters, see the Windows DDK and the Network Technology web site.

• If you have technical questions about the issues in this article, please send e-mail to ndisfb@microsoft.com with Driver initialization time in the Subject line of your message. Please include your name, title, company name, and phone and fax numbers.

 Top of page