NDIS User mode I/O Protocol

[This is preliminary documentation and subject to change.]

SUMMARY

This sample demonstrates a connection-less NDIS 5.0/5.1 protocol driver. The driver supports sending and receiving raw Ethernet frames using ReadFile/WriteFile calls from user-mode. It only receives frames with a specific (run-time configurable) EtherType field. As an NDIS protocol, it illustrates how to establish and tear down bindings to Ethernet adapters, i.e. those that export medium type NdisMedium802_3. It shows how to set a packet filter, send and receive data, and handle plug-and-play events. It also shows use of the following NDIS 5.1 features/APIs:

1. Canceling sends

2. NdisQueryPendingIOCount()

The sample works on Windows 2000, 32-bit and 64-bit platforms, and Windows XP. Both checked and free builds are available.

BUILDING THE SAMPLE

From the Free or Checked Build environment, execute build in the ndisuio directory.

INSTALLATION

This step can be omitted on Windows XP where this driver is installed by default, as a hidden protocol. NOTE that the functionality present in the in-build version of NDISUIO on Windows XP is subject to change. Developers should not assume availability of this functionality for user-mode applications on Windows XP.

The driver is installed using the INF file ndisuio.inf, which is provided in the driver directory. In Network Connections UI, select an adapter and open Properties.

Click Install, then Protocol, then Add, and then Have disk. Then point to the location of the .inf and driver.

Select NDIS Usermode I/O Protocol and click OK. After installing the protocol, copy over the test application uiotest.exe to a convenient location.

USAGE

To start the driver, type

Net start ndisuio

To stop the driver, type

Net stop ndisuio

To test the driver, run uiotest. For help on usage, run uiotest -?

usage: UIOTEST [options] <devicename>
options:
 -e: Enumerate devices
 -r: Read
 -w: Write (default)
 -l <length>: length of each packet (default: 100)
 -n <count>: number of packets (defaults to infinity)
 -m <MAC address> (defaults to local MAC)

Uiotest exercises the IOCTLs supported by NDISUIO, and sends and/or receives data on the selected device. In order to use uiotest, the user must have administrative privilege. Users should pass down a big enough buffer in order to receive the entire received data. If the length of the buffer passed down is smaller than the length of the received data, NDISUIO will only copy part of the data and discard the rest when the given buffer is full.

NOTE: On Windows XP, uiotest may fail to access devices since other processes could have open handles to NDISUIO for those devices. To work around this, stop and restart NDISUIO as shown above. You will be prompted to stop services that depend on NDISUIO as well.

Use the –e option to enumerate all devices to which NDISUIO is bound:

C:\uio>uiotest -e
 0. \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F}
 - Intel-Based 10/100 Ethernet Card

The following command sends and receives 2 packets on a device). Since these packets are sent to the local MAC address (default), both packets are received. The device name parameter to uiotest is picked up from the output of uiotest –e (see above).

C:\uio>uiotest -n 2 \DEVICE\{9273DA7D-5275-4B9A-AC56-68A49D121F1F}
DoWriteProc: finished sending 2 packets of 100 bytes each
DoReadProc finished: read 2 packets

TIPS

With a checked version of ndisuio.sys, you can control the volume of debug information generated by changing the variable ndisuioDebugLevel. Refer to debug.h for more information.

CODE TOUR

File Manifest

Directory: Test




 
 
 
 
 
File Description 
uiotest.c User-mode test application
 
 
Directory: Sys




 
 
 
 
 
File Description 
debug.c Routines to aid debugging
debug.h Debug macro definitions
macros.h Spinlock, event, referencing macros
ndisbind.c NDIS protocol entry points to handle binding/unbinding from adapters
ndisuio.h Data structure definitions
ndisuio.inf INF file for installing NDISUIO
ntdisp.c NT Entry points and dispatch routines for NDISUIO
nuiouser.h IOCTL and associated structure definitions
recv.c NDIS protocol entry points for receiving data, and IRP_MJ_READ processing
send.c NDIS protocol routines for sending data, and IRP_MJ_WRITE processing
 

Top of page

© Microsoft Corporation 2000