Home Up Search PCAUSA HomeNDIS FAQ

NDIS FAQ IM Driver FAQ TDI FAQ Win95 IFS FAQ Other Resources Consultants

 

Answers to NDIS Frequently Asked Questions

The information on this page is intended primarily for network software developers who are working on lower-level network-related NDIS device drivers for Windows 95 and Windows NT.

undercon.gif (286 bytes)This FAQ, like most others, is always under construction...

If you have useful information or corrected/improved links that you think should be added to the NDIS FAQ, please let us know at ndisfaq@pcausa.com.

Thanks!!!

Table of Contents

General Questions

What is "NDIS"?
Where can I find NDIS programming information?
What is the difference between a "Legacy" and a "Miniport" NDIS driver?
How can I find the hardware address of a NDIS MAC adapter?
How do I put a NDIS MAC adapter into promiscuous mode to receive all packets?

 

NDIS Function Notes

What is the FunctionContext parameter to NdisInitializeTimer used for?

 

Windows 2000 Questions

Why does NdisAllocatePacket fail unexpectedly on Windows 2000?

 

Windows NT Questions

Where can I find a NDIS Protocol Driver Sample For Windows NT?
DDK PACKET Driver Sample
DDK TDI Driver Sample
Lew Perin's billgPC Sources For Windows 95 And NT
What are some of the bugs in the Microsoft Windows NT Packet Driver sample?

 

NDIS Intermediate Driver Questions

The information on NDIS Intermediate (IM) drivers has been moved to its own FAQ.

NDIS Intermediate (IM) Driver FAQ

 

Windows 95 Questions

Where can I find NDIS 3.1 Protocol Driver Samples For Windows 95
PCAUSA's SNTRANS Protocol VxD Sources
Microsoft PACKET Driver Sample For Windows 95
Lew Perin's billgPC Sources For Windows 95 And NT

 

MS-DOS And Windows 3.X Questions

Where can I find the NDIS 2.0.1 Specification?
"Clarkson" (Now Crynwr) DOS Packet Driver Collection (Updated - 1/31/99)
Where can I find the API Specification for TCP/IP Applications to run over DOS packet drivers?  (Pavel Aronsky - 1/31/99)

 

 

General Questions

What is "NDIS"?

NDIS is short for the "Network Driver Interface Specification". The primary purpose of NDIS is to define a standard API for "Network Interface Cards" (NIC's). The details of a NIC's hardware implementation is wrapped by a "Media Access Controller" (MAC) device driver in such a way that all NIC's for the same media (e.g., Ethernet) can be accessed using a common programming interface.

NDIS also provides a library of functions (sometimes called a "wrapper") that can be used by MAC drivers as well as higher level protocol drivers (such as TCP/IP). The wrapper functions serve to make development of both MAC and protocol drivers easier as well as to hide (to some extent) platform dependencies.

Early versions of NDIS were jointly developed by Microsoft and the 3Com Corporation. Current NDIS versions used by Windows For Workgroups (WFW), Windows 9X and Windows NT are Microsoft proprietary specifications.

 

Where can I find NDIS programming information?

Windows NT
If you are developing NDIS drivers under the Windows NT platform, then NDIS information is found in the Windows NT DDK Help file under the highest-level topic "Network Drivers".
The Microsoft DDK documentation is available on the Microsoft Developer Network (MSDN) software subscription CD's. It is also provided as part of the free MDSN OnLine service at http://www.microsoft.com/msdn leave-site.gif (117 bytes).
Windows 95
For Windows 95, the NDIS information is found in the Windows 95 DDK Help file, which is also provided on the MSDN. If you are using VtoolsD for Windows 95 from Vireo Software leave-site.gif (117 bytes), then the VtoolsD product includes the Windows 95 DDK documentation and associated Windows 95 header files and NDIS VxD wrappers.
Back to Top

 

What is the difference between a "Legacy" and a "Miniport" NDIS driver?

The fundamental difference between "Legacy" and "Miniport" driver is:

Legacy Drivers allow the use of platform-specific functionality.
Miniport Drivers replace platform-specific functionality with platform-independent "wrapper" functions.

The writer of a "legacy" driver is free to use whatever functionality is available to develop a device driver. The penalty for this freedom is that the resulting driver is limited in that it can only be used on the operating system that provides the selected features.

A writer of a "miniport" driver is required to use a specific set of functions and other rules, dependent on the type of driver being developed. If the miniport driver is built "by the rules", then Microsoft provides the mechanism to allow the resulting driver to run on both Windows 9X and Windows NT.

Miniport drivers are usually built and debugged on the Windows NT platform.

Back to Top

 

How can I find the hardware address of a NDIS MAC adapter?

There are a variety of methods available to determine the hardware address of installed NDIS MAC adapters. Here are the methods that PCA is aware of:

Method Win 95 Win NT Limitation

Query The MAC Driver Directly From A Win32 Application

On the Windows NT platform it is possible for a Win32 application to query a NDIS MAC driver for certain types of information. The query is made using the IOCTL_NDIS_QUERY_GLOBAL_STATS DeviceIoControl call.

The Windows NT DDK MACADDR sample shows how to make this call.

No

Yes

NT Only
Query The MAC Driver Indirectly Using A Helper NDIS Protocol Driver

A NDIS protocol driver can use the NdisRequest function to query a bound adapter for it's hardware address. It is possible to develop a dynamically loadable NDIS protocol driver to assist Win32 applications in asking the NDIS MAC adapter driver for it's address. This is the method used by the NDIScope application of PCAUSA's Win32 NDIS Framework.

Yes Yes Must have protocol driver for each platform.

Use The CoCreateGuid Function

The lower six bytes of the 128-bit GUID created by the CoCreateGuid function is the Ethernet or Token-ring hardware address for the computer.

If multiple adapters are installed, then this function returns one of the adapter hardare addresses in the lower six bytes; however, it does not provide any indication that there are, in fact, multiple installed adapters nor does it provide any way to specify which adapter address is returned in the lower six bytes of the GUID.

Yes

Yes

Indeterminate result when multiple adapters are installed.

Use The NETBIOS API

If the workstation has the NETBIOS protocol installed, then adapter hardware addresses can be determined using the NETBIOS API.

Microsoft provides an example in the MSDN Knowledge Base under the title Getting the MAC Address For An Ethernet Adapter, Article ID: Q118623.

Here is a code fragment provided by David Goldberg:

Using NETBIOS To Get MAC Address

Yes

Yes

NETBIOS protocol must be installed.

 

Back to Top

 

How do I put a NDIS MAC adapter into promiscuous mode to receive all packets?

Only a NDIS Protocol driver has the capability to command a NDIS MAC adapter to enter "promiscuous" mode and receive all packets on the wire. You will need to develop your own NDIS protocol driver for this purpose - or license a NDIS protocol driver designed for this purpose.

In addition, you will need to develop a Win32 application to control your protocol driver and collect the received packets.

Here are some places to start this development effort:

Free NDIS Protocol Driver Sample For Windows NT From Microsoft And Others
Free NDIS Protocol Driver Samples For Windows 95 From PCAUSA, Microsoft And Others
PCAUSA's Licensable  Win32 NDIS Framework (WinDis 32)

 

Back to Top

 

NDIS Function Notes

What is the FunctionContext parameter to NdisInitializeTimer used for?

VOID NdisIntiializeTimer(
PNDIS_TIMER Timer,
PNDIS_TIMER_FUNCTION TimerFunction,
PVOID FunctionContext
);
VOID NdisMIntiializeTimer(
PNDIS_MINIPORT_TIMER Timer,
NDIS_HANDLE MiniportAdapterHandle,
PNDIS_TIMER_FUNCTION TimerFunction,
PVOID FunctionContext
);

In some (actually, many or most...) NDIS MAC drivers it is desirable to use common driver code to support multiple installed adapters. The driver functions to be performed for each adapter are identical; it is only the adapter "context", including it's hardware resources and instance-specific data, that is different.

The Microsoft Windows NT DDK NE32000 MAC driver sample illustrates a good use of the FunctionContext parameter when calling NdisMInitializeTimer. For the NE3200, a structure called a NE3200_ADAPTER contains most of the data specific to each installed NE3200 adapter. In the call to NdisMInitializeTimer a pointer to the NE3200_ADAPTER structure is passed as FunctionContext.  Later, when the NE3200ResetHandler MiniportTimer function is called, it can use the FunctionContext parameter to recover the correct NE3200_ADAPTER structure pointer. Since the timer function then knows the correct "context", it can perform functions appropriate to the correct adapter.

Back to Top

 

Windows 2000 Questions

Why does NdisAllocatePacket fail unexpectedly on Windows 2000?

This change in the behavior of the NDIS library may (should) effect lots of developers who have working NDIS protocol drivers built using NT 4.0 DDK.

The Problem

Basically, prior to Windows 2000 Beta 3 RC1 the NdisFreePacket MACRO defined in the NT 4.0 NDIS.H file was functionally identical to the NdisFreePacket function exported by the NDIS library. So, NdisAllocatePacket/NdisFreePacket worked correctly for NDIS protocol drivers, which use the MACRO.

The behavior changed with Windows 2000 Beta 3 RC1. With Windows 2000 B3RC1 the NdisFreePacket MACRO from NT 4.0 DDK *IS NOT* equivalent to the Windows 2000 B3RC1 NdisFreePacket function.

Calling the NdisFreePacket MACRO does not actually return the NDIS_PACKET to the free pool on Windows 2000. As a result, calls to NdisAllocatePacket will eventually fail prematurely.

Workarounds

1.) You can use NT4.0 DDK if you add this fragment after #include NDIS.H but before any reference to NdisFreePacket:

#if defined(NdisFreePacket)
#undef NdisFreePacket

VOID
NdisFreePacket(
   IN PNDIS_PACKET Packet
   );

#endif

This forces use of the NdisFreePacket exported by the NDIS library instead of using the MACRO.

2.) You can re-compile the NDIS protocol driver using the NT 5 B2 DDK.



Both 1.) and 2.) APPEAR to result in a NDIS protocol driver which runs OK on NT 4.0 and Windows 2000 through B3RC1.

Windows NT Questions

Where can I find a NDIS Protocol Driver Sample For Windows NT?

The Microsoft NT DDK includes two NDIS protocol driver samples:

PACKET Driver Sample - In the directory \NTDDK\src\network\packet
TDI Driver Sample - In the directory \NTDDK\src\network\tdi

 

Back to Top

 

What are some of the bugs in the Microsoft Windows NT Packet Driver sample?

Lewis Perin has <perin@acm.org>has put together a list of bugs in the NT DDK Packet Driver sample. Lew's list is available at http://www.panix.com/~perin/packetbugs.html

 

Back to Top

NDIS Intermediate Driver Questions

Where can I find a NDIS 4 intermediate driver sample?

The Microsoft Windows NT DDK team has a sample NDIS Intermediate (IM) Driver named "ImSamp" on their website at:

http://support.microsoft.com/support/ddk_hardware/ntddk/NTsamples/#Network Device Driver Samples

 

The Microsoft NT 5.0 Beta 2 DDK includes a different NDIS IM Driver sample "PassThru" under the directory:

\DDK\Src\Network\NDIS\SampIM

 

Back to Top

 

Implementing An Intermediate Driver that works with RAS under NT

January 6, 1999 - Andrew Zabolotny <bit@eltech.ru> has contributed a paper that includes his instructions on how to adapt a intermediate driver that works with network cards to make it work with RAS. Click the link below to view Mr. Zabolotny's paper.

Implementing An IM Driver That Works With RAS Under NT

Back to Top

How Can I Test My NDIS Intermediate Driver

February 1, 1999 - At it's upper edge an NDIS Intermediate Driver should function like an ordinary NDIS Miniport driver. This means that the Hardware Compatibility Test (HCT) tools used to test ordinary NDIS Miniport drivers can be used to test NDIS Intermediate Drivers.

NDIS Miniport drivers can be tested with the NDIS Tester, which is available from the Microsoft WHQL (Windows Hardware Quality Labs). The general WHQL web site (for all kinds of devices) is:

http://www.microsoft.com/hwtest

Go to the TEST KITS & FAQs link and check the "LAN Network Self-Test" entry in the table. There you'll find a link to the Hardware Compatibility Test (HCT) CD-ROM, which you must order for a small fee.

There are also links for download of the latest test documents.

Alternatively, e.g. if you do not want to have your driver officially certified by WHQL, download the latest NDIS Tester beta version from:

ftp://ftp.microsoft.com/services/whql/ndis

The NDIS Tester tests all of the Miniport driver's capabilities, depending if it is a NDIS3, NDIS4, or NDIS5 Miniport.

In addition, some HCT Test Tools are included with the MSDN Universal Subscription CDs.

 

Windows 95 Questions

Where can I find FREE Windows 95 NDIS protocol driver samples?

PCAUSA's SNTRANS Protocol VxD Sources

The PCAUSA SNTRANS project is an example NDIS 3.1 PROTOCOL virtual device driver for Windows 95. SNTRANS is written in the 'C' programming language specifically for VtoolsD for VxD framework, and provides a basic empty shell for developing your own protocol driver.

SNTRANS is functional only to the extent that it registers the SNTRANS protocol and automatically binds to one MAC adapter, and unbinds when the driver is unloaded. No other functionality is provided in the sample.

To compile SNTRANS specifically as an NDIS 3.1 protocol driver for Windows 95 requires the the VtoolsD for Windows 95 VxD framework V2.03 from Vireo Software, Inc. and the Microsoft C/C++ V4.2 development environment.

Note: SNTRANS V1.00.00.03 has been modified to that it can be compiled as either an NDIS 3.0 protocol driver (for Windows for Workgroups) or an NDIS 3.1 protocol driver (for Windows 95).

Download SNTRANS.ZIP V1.00.00.03 (1/19/97)

Back to Top

 

Microsoft PACKET Driver Sample For Windows 95

The Microsoft PACKET sample for Windows 95 can be downloaded from:

http://support.microsoft.com/support/ddk_hardware/

Follow the link Windows DDK to find the sample.

Back to Top

 

Lew Perin's billgPC Sources For Windows 95 And NT

Lewis Perin has <perin@acm.org>has developed billgPC: a free bootp client for Windows 95 and NT. Lew provides sources to the billgPC protocol drivers and associated applications.

The billgPC bootp client and it's sources can be downloaded from www.panix.com/~perin/

Back to Top

 

MS-DOS And Windows 3.X Questions

Where can I find the NDIS 2 Specification?

The Network Driver Interface Specification (NDIS) Version 2.0.1 was jointly developed by the 3Com Corporation and the Microsoft Corporation. It was used as the specification for development of NDIS adapter drivers for the DOS and Windows 3.10 platforms.

The Network Driver Interface Specification (NDIS), Version 2.0.1
(PDF: 173 KB/92 pages)
TEXT (Text: 215KB/92 pages)

This document, and other information of interest, may be available from the 3Com FTP site at ftp.3com.com .

Back to Top

Where can I find the "Clarkson" packet driver collection for DOS?

Go to the URL http://www.crynwr.com for the "Clarkson" (now Crynwr) packet driver collection. The site is a little confusing; click the larger-size "Crynwr Software" link to navigate to packet-related information.

Contact is Russ Nelson <nelson@crynwr.com> at Crynwr Software.

February 1, 1999 - Russ says that the current DOS packet driver specification that's in wide use is 1.09.  The only significant thing in 1.11 is PPP, and only FTP ever implemented it. DOS is alive and well in the embedded systems market.

January 31, 1999, Pavel Aronsky <pavela@my-dejanews.com> reports that the latest known packet driver specification is v 1.11, by former FTP Software, 1994. It can be found at http://www.devinfo.com/archives/simtel/msdos/pktdrvr/ in the file netzhack.zip.

Other information of interest concerning this driver collection may be available from the 3Com FTP site at ftp.3com.com .

Back to Top

 

Where can I find the API Specification for TCP/IP Applications to run over DOS packet drivers?

January 31, 1999, Pavel Aronsky <pavela@my-dejanews.com> reports that the API spec for TCP/IP applications to run over DOS packet drivers can be found on www.trumpet.com . Just in case somebody still interested...

Back to Top

 

 

WinDis 32 is a trademark of Printing Communications Assoc., Inc.
Microsoft, MS, Windows, Windows 95, Windows 98, and Win32 are registered trademarks and Visual C++ and Windows NT are trademarks of the Microsoft Corporation.
Send mail to webmaster@pcausa.com with questions or comments about this web site.
Copyright © 1996-1999 Printing Communications Assoc., Inc.
Last modified: April 12, 1999