NDIS Virtual Miniport Driver

SUMMARY

The purpose of this sample is to illustrate functionality of a deserialized NDIS miniport driver without requiring a physical network adapter. This sample is based on E100BEX sample present in the DDK. It is basically a simplified version of E100bex driver. Since the driver does not interact with any hardware, it makes it very easy to understand the miniport interface and the usage of various NDIS functions without the clutter of hardware specific code normally found in a fully functional driver. The driver can be installed either manually using Add Hardware wizard as a root enumerated virtual miniport driver or on a virtual bus (like toaster bus).

Note: This sample provides an example of minimal driver intended for education purposes. Neither the driver or it's sample test programs are intended for use in a production environment.

The driver can be built in the Windows® 2000, XP, and Server 2003 DDK build environment

The driver can be installed in the Windows® 2000, XP, and Windows Server 2003 operating system. Windows 2000 supports only NDIS 5.0 version miniport driver. Windows XP and Windows Server 2003 supports NDIS 5.0 & 5.1 versions of miniport driver.

BUILDING THE SAMPLE

Click the Free Build Environment or Checked Build Environment icon under your Development Kits program group to set basic environment variables needed by the build utility.

Change to the directory containing the device source code, such as CD Src\network\ndis\netvmini.

Run build -ceZ, or use the macro BLD. This behavior invokes the Microsoft make routines that produce log files called Buildxxx_yyy_zzz.log, and also Buildxx_yyy_zzz.wrn and Buildxx_yyy_zzz.err if there are any warnings or errors. Where xxx stands for fre or chk depending on the environment chosen, yyy stands for the OS version (W2K, WXP or Wnet), and zzz stands for platform version (x86, IA64 or AMD64).

If the build succeeds, the driver, vnetmini.sys, will be placed in a platform specific subdirectory of your %TargetPath% directory specified in the Sources file. Depending on the build environment, the driver will be either an NDIS 5.0 or NDIS 5.1 miniport driver. If you build in the Windows 2000 build enviromnet, you will get NDIS 5.0 version of miniport driver. If you build under Windows XP or Windows Server 2003 environment, you will get NDIS 5.1 versions of miniport driver.

Driver Installation

To install the driver on Windows 2000, build the driver in Win2K build environment to get NDIS5.0 version of the driver and copy that and NETVMINI.INF file to a floppy or to a directory on the target test machine. Then:

1. Double-click the Add New Hardware Wizard applet in Control Panel.
2. Click Next.
3. Select Add a new device.
4. Select No, I Want to Select the Hardware from a list.
5. Select Network Devices and then click Next.
6. Click Have Disk and point to the directory that contains NETVMINI.INF file.

1. Double-click the ‘Add Hardware’ wizard in Control Panel.
2. At the 'Welcome to the Add Hardware Wizard', click ‘Next’.
3. Select 'Yes, I have already connected the hardware', then click Next.
4. Select ‘Add a new hardware device’ from the list, then click Next.
5. Select ‘Install the hardware that I manually select from a list(Advanced),' and then click next.
6. Select ‘Network Devices’, then click Next.
7. Click 'Have Disk', make sure that 'A:\' is in the "Copy manufacturer's files from:" box, and click OK.
8. Click on the desired entry, and then click Next.
9. At 'The wizard is ready to install your hardware', click Next.
10. Click Finish at 'Completing the Add/Remove Hardware Wizard.'

Alternatively, you can use the DEVCON.EXE from the DDK to install the driver programmatically.

c:\>DEVCON.EXE   INSTALL   netvmini.inf   "root\netvmini"

The system copies the netvmini.sys file to %systemroot%\system32\drivers directory and loads the driver.

Instead of root-enumerating, you can also bus enumerate by using the virtual Toaster Bus driver from the DDK. You should first install the toaster bus driver, and then run Notify.exe to install this miniport driver. Make sure to update the Device ID in the "Plug In Device" dialog of the application to have "{b85b7c50-6a01-11d2-b841-00c04fad5171}\NetVMini". The advantage of bus enumerating the miniport is that you can test surprise-removal scenario which is not possible with root-enumerated drivers.

Testing driver

To test the miniport driver, install more than one instance of the miniport driver. You can repeat above installation steps to install more than one instance of the miniport. Then install NDIS Tester from WHQL website and run all Client tests.

You can test the ioctl interface provided by the miniport using the testapp.exe. The testapp is a PNP friendly application, in that it registers for PNP notification on the NDIS device and closes the handles at the right time to allow the device from being removed. Please note the PNP manager vetoes any request to disable or uninstall the device and pops-up a dialog to restart the machine if there are any open handles to the device.

The deviceobject registered by the miniport using NdisMRegsiterDevice is a stand-alone control deviceobject and not part of the actual miniport's PNP device stack. When the device is removed, disabled or uninstalled, the PNP notifications are sent only to the interface registered on the PNP stack and not to the control deviceobject. As a result, if an application opens an handle to the control deviceobject, it also needs to have another handle open to the PNP interface registered by NDIS using GUID_NDIS_LAN_CLASS to listen for PNP device-change notification.

The GUI application illustrates how to do this. First the application registers for interface-change notification on GUID_NDIS_LAN_CLASS. When it gets notified about an existing device-interface, it opens an handle to the device and registers for device-change notification using that handle. This is required to get notified about any kind of PNP activity on the target device. Now the user can optionally open the control deviceobject and send ioctls to it. When the application gets notified about device removal, it not only closes the handle to the NDIS device but also to the control device so that the PNP manager can remove the device.

CODE TOUR

Send & Receive Path Code Path:

RESOURCES

For the latest release of the Windows NT device driver kit, see http://www.microsoft.com/ddk/.

File Manifest