|
|
Network Driver Interface Specification (NDIS)
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
 | INFO:
Windows 2000 NDIS Kernel Debugger Extensions  |
| HOWTO:
Writing WDM/NDIS Miniports for Windows |
NDIS Function Notes
| What is the FunctionContext parameter to
NdisInitializeTimer used for? | ||||||||
| PCAUSA Knowledge
Base - NDIS General Information
| ||||||||
| Handling Receives in a Deserialized Miniport Drivers on 9x
Platforms - 10/10/00 (An advance draft of a Microsoft KB article, courtesy of Eliyas Yakub.) | ||||||||
| FYI: Q198582 - INFO: NDIS Binary-Compatibility on Windows 98 and Windows 2000
- 11/18/00 (An advance draft of a Microsoft KB article, courtesy of Eliyas Yakub.) |
Windows 2000 Questions
| Why does NdisAllocatePacket fail unexpectedly on
Windows 2000? |
| Can I Load NDIS 3.0 Full NIC Drivers on Windows
2000? |
| Can I use IOCTL_NDIS_QUERY_GLOBAL_STATS on Windows 2000? (Or: does the MACADDR application work on Windows 2000?) - 7/28/00 |
Windows NT Questions
| Where can I find a NDIS Protocol Driver Sample For Windows
NT?
|
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
|
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
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.
..
for information about NDIS 5.0, the most recent NDIS version.
, then the VtoolsD product includes the Windows 95/98 DDK
documentation and associated Windows 95/98 header files and NDIS VxD wrappers.
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.
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 | Limitation |
|---|---|
Query The MAC Driver Directly From A Win32 ApplicationOn 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. You can also see the PCAUSA MACADDR II sample, which illustrates the same technique for Windows 2000. |
NT/W2K 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. |
Must have protocol driver for each platform. |
Use The CoCreateGuid FunctionThe 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.
|
Indeterminate result when multiple adapters are installed. |
Use The NETBIOS APIIf 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: Microsoft Knowledge Base Article Q118623, "HOWTO: Get the MAC Address for an Ethernet Adapter", also discusses this technique.
|
NETBIOS protocol must be installed. |
Use the GetAdaptersInfo() functionDocumentation for GetAdaptersInfo() is not included with Microsoft Visual C++ (at least through VC++ 6.0). However, documentation for GetAdaptersInfo() and necessary import libraries can be found in the Platform SDK. |
Win98, NT4 SP4 or higher, and NT5 only. |
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) |
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.
Legacy or full NIC NDIS MAC drivers are NDIS MAC drivers that comply with NDIS 3.0.
It is possible to load NDIS 3.0 NDIS MAC drivers (and make them work) on
Windows 2000, but Windows 2000 is the last release that it will support them.
Microsoft is killing Full NIC driver support after Windows 2000.
The Microsoft NT DDK includes two NDIS protocol driver samples. In addition, an updated NT 4.0 Packet driver sample is available on the Microsoft website.
| PACKET Driver Sample - In the directory \NTDDK\src\network\packet |
| NTPacket Driver Sample - On the Microsoft website. Microsoft Updated
NT4.0 NDIS 3.0 Packet Sample. |
| TDI Driver Sample - In the directory \NTDDK\src\network\tdi |
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
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
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:
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:
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.
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 NuMega/Compuware
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).
The Microsoft PACKET sample for Windows 95 is included on the Windows 98 DDK.
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 .
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 .
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...
|
PCAUSA Home · Privacy Statement · Products · Ordering · Support · Utilities · ResourcesRawether for Windows and WinDis 32 are trademarks of Printing Communications Assoc., Inc.
(PCAUSA)
|
This FAQ, like
most others, is always under construction...
Note: This
method fails on Windows 2000 because the function has been re-defined,
for security reasons, to prevent the generated GUID from being tracable
to the adapter; the bytes of interest
are different for each call to CoCreateGuid.