NDIS Miniport
User-Mode Interface
Techniques

October 31, 2001 - This is preliminary information that has not been checked for accuracy and is not yet complete. It is published at this time as "food-for-thought".

If you have any input concerning this topic, please let me know at NDIS-Win32 API Feedback.

Input from members of the PCAUSA Discussion List is especially welcome.

Regards,

Thos

DISCUSSION

A frequently-asked question is:

"How can I access my NDIS miniport driver from a user-mode application?"

Unfortunately, there is no simple answer to this simple question. This is especially true if Windows® Hardware Quality Labs (WHQL) certification is a consideration.

From the perspective of the NDIS miniport there are two basic interface techniques:

Device I/O Control API

When using this technique a kernel-mode driver creates a device object and a symbolic link and then implements necessary IRP function handlers. The user-mode application uses the CreateFile and DeviceIoControl functions to communicate with the driver's IRP function handlers.

The Microsoft DDK help file and DDK samples, as well as most books on Windows NT/2000 and WDM device driver programming, provide a great deal of general information about both the user-mode and the kernel-mode aspects of a device I/O control interface.

However, NDIS miniport drivers are restricted to using functions that are exported by the NDIS wrapper. The standard NT/WDM IoCreateDevice and IoCreateSymbolicLink functions, normally used to create a device object and its Win32-visible symbolic link, are not exported by the NDIS wrapper. This means that:

True NDIS miniports should use the NdisMRegisterDevice function to create a named device object and a symbolic link between the device object and a user-visible name for that device.

The NDIS wrapper exports NDISMRegisterDevice only on specific Windows versions, as tabulated below:

NdisMRegisterDevice Availability
By Windows Version

This means that NdisMRegisterDeivce can be used to add a DeviceIoControl interface to your WHQL-certifiable NDIS 5.0 miniport on these Windows versions:

What about other Windows versions???

The standard IoCreateDevice and IoCreateSymbolicLink functions are intrinsic to Windows NT 4.0, and can be used to add a DeviceIoControl interface to your NDIS 4.0 miniport.

The Windows Driver Model (WDM) facility introduced with Windows 98 provides these functions to certain VxD-based Windows versions, as tabulated below:

IoCreateDevice/IoCreateSymbolicLink Availability
By Windows Version

This means that IoCreateDevice/IoCreateSymbolicLink can be used to add a DeviceIoControl interface to your WHQL-certifiable NDIS 4.0 miniport on these Windows versions:

What about Windows 95???

Windows 95 does not have IoCreateDevice WDM nor NdisMRegisterDevice NDIS services available, so the device I/O control methods discussed so far are not applicable.

However, this Windows version does include system VxD services that allow user-mode applications to communicate with VxD device drivers. With more creativity then I have it may be possible to develop a scheme that allows a supporting VxD to communicate with a NDIS miniport on this platform.

On the other hand, if you must support a user-mode interface to a NDIS miniport on the Windows 95 platform, you can use the NDIS Object Identifier API method and a NDIS 3.0 protocol VxD as a "relay", as described below. If you do this, then the same NDIS 3.0 protocol can (probably) be used to provide the API on the Windows 98 and Windows Millennium platforms as well.

Other Considerations

Stay away from using IRP_MJ_READ/IRP_MJ_WRITE handlers (ReadFile/WriteFile) if you are interested in using your interface on VxD-based Windows versions. VxD-based Windows versions do not support read/write to device drivers - even with WDM support.

NDIS Object Identifier (OID) API

The basic approach here is that you define custom/proprietary NDIS object identifiers (OIDs) that you use to implement the private interface to your NDIS miniport. The code in your NDIS miniport consists of appropriate SetInformation and QueryInformation handler extensions.

The challenge in using this method is to find a suitable method that your Win32 application can use to actually call your NDIS miniport at these handlers.

There are three techniques that a Win32 application can use to call a NDIS miniport's SetInformation and QueryInformation handlers:

Windows Management Instrumentation (WMI)

Windows Management Instrumentation (WMI) is a kernel-mode service that drivers can use to make measurement and instrumentation data available to user-mode applications. A driver can use WMI mechanisms to publish information, permit configuration of its device, and supply notifications and logging of events.

WMI provides a variety of very flexible mechanisms which allow a user-mode API to access information made available by drivers using WMI. In addition, WMI provides distributed access to devices that use the WMI service..

The code to support WMI in a NDIS miniport is fairly simple: just implement handlers for new OIDs.

On the other hand, the user-mode WMI API is fairly complex; if you love the methods of COM/DCOM then you will embrace WMI before you need to use it.

WMI is built in to the Windows ME (??? Not Verified...) and Windows 2000 and higher versions of Windows. It is available as a separately-installable enhancement for (Windows 95???), Windows 98 and Windows NT 4.0; if you intend to use WMI with your NDIS miniport then you must insure that WMI support is installed.

For more information see the following MSDN Topics:

In addition, the Windows XP DDK includes sample NDIS miniport drivers that illustrate some WMI support.

IOCTL_NDIS_QUERY_GLOBAL_STATS

Windows NT, Windows 2000 and Windows XP include a built-in IOCTL that user-mode applications can use to pass a NDIS query to a NDIS miniport driver. This IOCTL is IOCTL_NDIS_QUERY_GLOBAL_STATS, defined in the ntddndis.h header file. Once the adapter NDIS name is known the user-mode application uses CreateFile and DeviceIoControl to communicate with the miniport.

The Windows NT 4.0 DDK included the MACADDR sample application that illustrated the use of this method. This sample is not included in the Windows 2000 and higher DDK's.

PCAUSA provides the MACADDR II sample that illustrates use of IOCTL_NDIS_QUERY_GLOBAL_STATS on Windows NT and higher. You can download the PCAUSA MACADDR II sample executable (and sources) from the following URL:

[ MACADDR II Application And Sources ]

Here are some other considerations:

The IOCTL is predefined to use METHOD_OUT_DIRECT; this means that only the NDIS miniport QueryInformation handler can be called this way.

(With some creativity METHOD_OUT_DIRECT could be used to set NDIS data...)
 

There is no counterpart to this method on the Windows 9X or Windows ME platforms.

Access Using "Relay" NDIS Protocol Driver

With this approach the NDIS miniport writer also provides a companion NDIS protocol driver that is used as a "relay" between user-mode applications and the NDIS protocol driver.

Since the NDIS protocol driver is a NDIS-aware component, it can directly open the NDIS miniport driver and use NdsiRequest to call the SetInformation and QueryInformation handlers. The NDIS protocol driver can provide an interface using to user-mode applications using any means supported by the operating system; most frequently this interface is provided using the traditional device I/O control method.

This approach is widely used to provide private interfaces between user-mode applications and a NDIS miniport is commonly approved by WHQL.

One downside of this approach is that there are dependencies between Windows versions and NDIS protocol drivers implementation requirements. For example, a NDIS protocol driver designed and built for Windows NT 4.0 should not be used on Windows 2000.

In practice it appears that three logically similar NDIS protocol drivers are needed to provide a complete relay NDIS protocol driver suite supporting Windows versions from Windows 95 through windows XP:

This points out a second downside to this approach: both the NDIS miniport and the supporting NDIS protocol driver (the NDIS 5.0 driver) must be tested if WHQL/Driver Signing is required.

The PCAUSA Rawether for Windows product is an example of a set of NDIS protocol drivers that can be used this way. The product information for Rawether includes a brief description of how one would develop such a suite of NDIS protocol drivers; see the Rawether Tour.

Summary

Other sources of information include kernel-mode Newsgroups. One way to get potentially useful information is to perform a Google Search on the term NdisMRegisterDevice.

Status

Mailing Lists  · PCAUSA Newsletter · PCAUSA Discussion List
· Privacy Statement · 

WinDis 32 is a trademark of Printing Communications Assoc., Inc. (PCAUSA).
Rawether for Windows and Rawether .NET are trademarks of Printing Communications Assoc., Inc. (PCAUSA).
Microsoft, MS, Windows, Windows 95, Windows 98, Windows Millennium, Windows 2000, Windows XP, and Win32 are registered trademarks and Visual C++ and Windows NT are trademarks of the Microsoft Corporation.
Send mail to rawether-webmaster@pcausa.com with questions or comments about this web site.
Copyright © 1996-2008 Printing Communications Assoc., Inc. (PCAUSA).
All rights reserved.
Last modified: December 31, 2007